x402-pay 0.1.0

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

x402-pay

Call any x402 API with one API key. No per-API wallet integration needed.

from x402_pay import PayClient

async with PayClient(api_key="gw_your_topped_up_key") as client:
    resp = await client.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
    print(resp.json())

Routes requests through a broker that handles on-chain payment on your behalf. $0.01/call.

Install

pip install x402-pay

Modes

API Key Mode (default, no wallet)

Get a key and top it up first:

# Create key (free, gets $0.05 search credit)
curl -X POST https://discovery.hugen.tokyo/keys/create
# Top up to unlock broker ($1.00 x402 payment)
curl -X POST "https://discovery.hugen.tokyo/keys/topup?key=gw_YOUR_KEY"

Then use it:

from x402_pay import PayClient

async with PayClient(api_key="gw_YOUR_KEY") as client:
    # Any x402 API — broker pays upstream, deducts $0.01 from your key
    resp = await client.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
    print(resp.json())

    # Check remaining balance
    print(f"${await client.balance():.2f}")

Wallet Mode (power users)

pip install x402-pay[wallet]

from x402_pay import DirectClient

async with DirectClient(private_key="0x...") as client:
    # Pay upstream directly from your wallet — no broker fee
    resp = await client.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
    print(resp.json())

Configuration

API keys are stored in ~/.x402-pay/config.json. Override with environment variables:

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

PayClient

• PayClient(api_key="", broker_url="", timeout=60.0) — create client
• await client.get(url) — GET request through broker
• await client.post(url, json={...}) — POST request through broker
• await client.balance() — check key balance in USD
• client.api_key — current API key

DirectClient

• DirectClient(private_key="0x...") — create wallet client
• 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