x402 in Python

Add x402 payments to a Python API with the official SDK — gate a FastAPI route behind USDC on the server, and pay endpoints automatically on the client.

Which approach should you use?

Install

pip install x402

Server (FastAPI)

The route returns HTTP 402 until a USDC payment is made, then runs normally.

# FastAPI server that charges for a route
from fastapi import FastAPI
from x402.fastapi.middleware import require_payment

app = FastAPI()

# Gate this route behind a USDC payment
app.middleware("http")(
    require_payment(
        path="/weather",
        price="$0.01",
        pay_to_address="0xYourReceivingWalletAddress",
        network="base-sepolia",   # use "base" in production
    )
)

@app.get("/weather")
def weather():
    # Runs only after a valid payment
    return {"city": "Tokyo", "forecast": "sunny"}

Client (httpx)

Attach payment hooks and the client pays on its own — the same pattern an AI agent uses.

# A Python client that pays automatically
import httpx
from x402.clients.httpx import x402_payment_hooks
from eth_account import Account

account = Account.from_key("0xYOUR_PRIVATE_KEY")

client = httpx.Client()
client.event_hooks = x402_payment_hooks(account)

r = client.get("http://localhost:8000/weather")
print(r.json())  # {"city": "Tokyo", ...}

Async client (agents)

An autonomous agent usually wants this over the sync client — it can await a paid call inside an async loop instead of blocking the thread while payment settles.

# Same thing, but async — how an autonomous agent typically calls it
import asyncio
import httpx
from x402.clients.httpx import x402_payment_hooks
from eth_account import Account

account = Account.from_key("0xYOUR_PRIVATE_KEY")

async def main():
    async with httpx.AsyncClient(event_hooks=x402_payment_hooks(account)) as client:
        r = await client.get("http://localhost:8000/weather")
        r.raise_for_status()
        return r.json()

print(asyncio.run(main()))  # {"city": "Tokyo", ...}

Flask / no official package

There's no official Flask middleware yet, but x402 is protocol-level: a before_request hook that returns a 402 with the right JSON body works in any WSGI framework.

# Flask (or any WSGI framework) — no x402 package required.
# The protocol is just HTTP 402 + a JSON body, so you can implement it
# by hand in a before_request hook if you're not on FastAPI/ASGI.
from flask import Flask, request, jsonify

app = Flask(__name__)
PRICE_ATOMIC = "10000"  # $0.01 USDC, 6 decimals -> 10_000 base units

@app.before_request
def require_payment():
    if request.path != "/weather":
        return
    proof = request.headers.get("X-PAYMENT")
    if not proof or not verify_payment(proof, PRICE_ATOMIC):  # your verification
        return jsonify({
            "accepts": [{
                "scheme": "exact",
                "network": "base-sepolia",
                "maxAmountRequired": PRICE_ATOMIC,
                "payTo": "0xYourReceivingWalletAddress",
                "asset": "USDC",
            }]
        }), 402

@app.get("/weather")
def weather():
    return {"city": "Tokyo", "forecast": "sunny"}

You still need something to implement verify_payment() — either call a facilitator's verify endpoint or check the on-chain transfer yourself. See facilitators for hosted options.

Troubleshooting

Get amounts right with the free base-unit converter.

Real Python x402 projects

Curated from the 137 Python projects we track that reference x402 — stars live from GitHub.

Frequently asked questions

More: all SDKs · Next.js · examples