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

Quick Demo

python -m x402_pay demo

Walks through key creation, API call, and balance check in 10 seconds.

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...",
})

Discover APIs

import x402_pay

apis = x402_pay.discover("token security")
for api in apis:
    print(f"{api['description']} — {api['price']}")
    resp = x402_pay.get(api["url"])

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")

How Billing Works

1. First call auto-creates an API key with $0.05 trial credit
2. Key saved to ~/.x402-pay/config.json
3. Each API call deducts from your balance ($0.005–$0.50 depending on the API)
4. Low balance warning prints to stderr when you have ~1 call left
5. When balance runs out, InsufficientBalance is raised with a topup URL

Topping up

try:
    resp = x402_pay.get("https://scout.hugen.tokyo/scout/hn?q=AI")
except x402_pay.InsufficientBalance as e:
    print(f"Balance: ${e.balance:.2f}, need: ${e.needed:.2f}")
    print(f"Top up (\$1.00 USDC on Base): {e.topup_url}")

The topup URL accepts a $1.00 x402 payment (USDC on Base chain). After payment, your key is credited immediately and you can retry the call.

Check your balance anytime:

python -m x402_pay balance

Verbose Mode

See cost and balance after every call:

import x402_pay
x402_pay.set_verbose()

resp = x402_pay.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
# stderr: [x402-pay] cost=\$0.0050 balance=\$0.0450

Or via environment variable:

X402_VERBOSE=1 python my_script.py

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
X402_VERBOSE	off	Print cost/balance to stderr

CLI

python -m x402_pay demo     # live walkthrough
python -m x402_pay balance  # check credit
python -m x402_pay info     # show config details

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() — check balance in USD
• x402_pay.discover(query, limit=5) — search API catalog
• x402_pay.set_verbose(True) — enable cost/balance output

PayClient (async)

• PayClient(api_key="", broker_url="", timeout=60.0)
• await client.get(url) / await client.post(url) — API calls
• await client.balance() — balance in USD
• await client.topup_url() — URL to add credit
• await client.discover(query) — search API catalog

DirectClient (async, requires [wallet])

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

Exceptions

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

License

MIT