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
- First call auto-creates an API key with $0.05 trial credit
- Key saved to
~/.x402-pay/config.json - Each API call deducts from your balance ($0.005–$0.50 depending on the API)
- Low balance warning prints to stderr when you have ~1 call left
- When balance runs out,
InsufficientBalanceis 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 brokerx402_pay.post(url, **kwargs)— sync POST through brokerx402_pay.balance()— check balance in USDx402_pay.discover(query, limit=5)— search API catalogx402_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 callsawait client.balance()— balance in USDawait client.topup_url()— URL to add creditawait 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 exceptionInsufficientBalance— balance too low (.balance,.needed,.topup_url)NotInCatalog— URL not in catalog (.url)BrokerError— upstream call failed (.refunded)
License
MIT
Metadata
Release files for x402-pay 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| x402_pay-0.4.0.tar.gz | 17.9 kB | Without provenance | Details for x402_pay-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| x402_pay-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for x402_pay-0.4.0-py3-none-any.whl |
Total release size: 34.6 kB
Release files / x402_pay-0.4.0.tar.gz
| Download URL | x402_pay-0.4.0.tar.gz |
|---|---|
| Size | 17.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f275bbf10ce794b6c399cfc806a271bf570edf980f8815a3c9a2527e8e1a6754
|
|
BLAKE2b-256 checksum How to use checksums |
11af3abe9b60a722de4557e4cb1022ccdf2340837d09feb74b109d4efe141f55
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.28 {"installer":{"name":"uv","version":"0.9.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / x402_pay-0.4.0-py3-none-any.whl
| Download URL | x402_pay-0.4.0-py3-none-any.whl |
|---|---|
| Size | 16.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
01e1958963a75321aac6968a0d81a8c5a7e1ea8b6bcbbb4dcbfa3110bf691928
|
|
BLAKE2b-256 checksum How to use checksums |
9fc5dd6e88bda299c189a6661c2606c8b709a435fc2d631903fd43daa48d3f33
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.28 {"installer":{"name":"uv","version":"0.9.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for x402-pay 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.