x402-pay 0.3.1

Pay for x402 APIs with 3 lines of Python — no wallet needed

x402-pay

Call any x402 API with one line of Python. No wallet needed.

import x402_pay

resp = x402_pay.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
print(resp.json())

Auto-provisions an API key with $0.05 trial credit on first use. Routes requests through a broker that handles on-chain payment on your behalf.

Install

pip install x402-pay

Usage

One-liner (sync)

import x402_pay

resp = x402_pay.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
print(resp.json())

resp = x402_pay.post("https://defi.hugen.tokyo/defi/simulate", json={
    "chain_id": "1", "from": "0xABC...", "to": "0xDEF...",
})

Async client

from x402_pay import PayClient

async with PayClient() as client:
    resp = await client.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
    print(resp.json())
    print(f"Balance: ${await client.balance():.2f}")

Explicit API key

from x402_pay import PayClient

async with PayClient(api_key="gw_YOUR_KEY") as client:
    resp = await client.get("https://defi.hugen.tokyo/defi/token?chain=ethereum&address=0x...")

Wallet mode (power users)

pip install x402-pay[wallet]

from x402_pay import DirectClient

async with DirectClient(private_key="0x...") as client:
    resp = await client.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")

API Key Lifecycle

1. First call auto-creates a key with $0.05 trial balance (10 calls at $0.005)
2. Key saved to ~/.x402-pay/config.json
3. After trial: top up at the URL from await client.topup_url() ($1.00 x402 payment)
4. Or bring your own key: PayClient(api_key="gw_...")

Configuration

Variable	Default	Description
X402_API_KEY	auto-created	API key for broker mode
X402_BROKER_URL	https://discovery.hugen.tokyo	Broker endpoint
X402_PAY_CONFIG_DIR	~/.x402-pay	Config directory

API Reference

Module-level (sync)

• x402_pay.get(url, **kwargs) -- sync GET through broker
• x402_pay.post(url, **kwargs) -- sync POST through broker
• x402_pay.balance(api_key="") -- check balance

PayClient (async)

• PayClient(api_key="", broker_url="", timeout=60.0)
• await client.get(url, **kwargs) -- GET through broker
• await client.post(url, **kwargs) -- POST through broker
• await client.balance() -- balance in USD
• await client.topup_url() -- URL to top up key balance

DirectClient (async, requires [wallet])

• DirectClient(private_key="0x...")
• await client.get(url) / await client.post(url) -- direct x402 payment

Exceptions

• PayError -- base exception
• InsufficientBalance -- key balance too low (.balance, .needed, .topup_url)
• NotInCatalog -- URL not in x402 catalog (.url)
• BrokerError -- upstream call failed (.refunded)

License

MIT