The x402 protocol is gaining traction as a lightweight, on-chain micropayment standard designed specifically for agent payments in decentralized systems. Using x402, developers can enforce pay-per-call semantics on APIs that autonomous agents consume. In this guide, I’ll show how to integrate x402 payment handling into a Python FastAPI server, creating a robust gateway that enforces HTTP 402 payment-required responses.
Why FastAPI? Besides its excellent async support and developer ergonomics, it’s popular among Python devs building blockchain tooling and AI agent endpoints. Combined with x402, you craft a micropayments API that’s ready for on-chain agent use cases involving USDC stablecoin or other ERC-20 tokens.
If you’re unfamiliar with x402 or want a step-by-step to the protocol in Python, this guide complements the broader x402 protocol tutorial and the Node.js-focused x402 Node.js Express example.
Before starting, make sure you have:
web3.py (v6.x), fastapi (v0.95+), uvicorn, and httpx installedpip install fastapi uvicorn web3 httpx
The example demo uses local Ganache or a testnet with faucets for USDC.
The core structure includes a FastAPI app with a middleware that intercepts requests to check for valid x402 payments. If payment is missing or insufficient, it replies with HTTP 402 Payment Required and a payment invoice.
Here’s the minimal FastAPI setup:
from fastapi import FastAPI, Request, HTTPException
from starlette.responses import JSONResponse
app = FastAPI()
@app.get("/public")
async def public_endpoint():
return {"message": "No payment needed here."}
@app.get("/protected")
async def protected_endpoint():
# Placeholder for payment validation
return {"message": "Here is your paid content."}
Nothing special so far. However, the next step is middleware that enforces agent pay-per-API-call.
x402 protocol specifies a RESTful payment pattern: clients send partial payment info in headers, and servers respond with 402 status code plus a payment request in the body.
The middleware checks the payment header, validates it against the expected cost (in token units), and conditionally allows the call or replies 402.
Example middleware:
from fastapi import Request
from starlette.middleware.base import BaseHTTPMiddleware
from web3 import Web3
class X402PaymentMiddleware(BaseHTTPMiddleware):
def __init__(self, app, web3: Web3, price_per_call_wei: int, token_address: str):
super().__init__(app)
self.web3 = web3
self.price_per_call = price_per_call_wei
self.token_address = token_address
async def dispatch(self, request: Request, call_next):
# Skip non-protected endpoints
if request.url.path == "/public":
return await call_next(request)
payment_header = request.headers.get("X-402-Payment")
if not payment_header:
return self._response_with_payment_request()
# Decode and check payment obligation
try:
payment_details = self._parse_payment_header(payment_header)
except Exception:
return JSONResponse(status_code=400, content={"error": "Invalid payment header format."})
if not self._is_payment_sufficient(payment_details):
return self._response_with_payment_request()
response = await call_next(request)
return response
def _parse_payment_header(self, header_value: str) -> dict:
# Simple example: parse JSON string (in prod, better serialization or JWT)
import json
return json.loads(header_value)
def _is_payment_sufficient(self, payment: dict) -> bool:
# Validate token address and amount paid >= price
return (
payment.get("token") == self.token_address
and int(payment.get("amount", 0)) >= self.price_per_call
)
def _response_with_payment_request(self):
payment_request = {
"token": self.token_address,
"amountDue": str(self.price_per_call),
"message": "API call requires micropayment via x402"
}
return JSONResponse(status_code=402, content=payment_request)
To wire it up:
from web3 import Web3
rpc_url = "https://rpc.testnet.local"
web3 = Web3(Web3.HTTPProvider(rpc_url))
PRICE_WEI = 10 ** 15 # 0.001 USDC equivalent (adjust per token decimals)
TOKEN_ADDRESS = "0x...usdcContract" # Testnet USDC
app.add_middleware(X402PaymentMiddleware, web3=web3, price_per_call_wei=PRICE_WEI, token_address=TOKEN_ADDRESS)
This setup expects the client to send a header X-402-Payment with JSON specifying token and amount. Otherwise, it returns 402 with payment invoice info.
Now let’s build a simple paid API route where an AI agent or a bot is billed per call.
The client could send this header:
{
"token": "0x...usdcContract",
"amount": "1000000000000000"
}
Here is a runnable example for a paid endpoint:
@app.get("/agent-data")
async def agent_data():
# Business logic behind paywall
return {"data": "Sensitive AI agent data or compute result."}
On the client side, if payment is sufficient, you get the data. Otherwise, HTTP 402 with the required amount.
I found when I wired up the agent's wallet, using session keys with spending limits minimized risk around overpaying. I recommend scoping agent wallet permissions tightly in production setups.
Clients must handle 402 status by parsing the response, creating a micropayment transaction (via wallet SDK or contract call), then resubmitting the request with the payment header.
Example with httpx client in Python:
import httpx
import json
async def call_paid_api():
url = "http://localhost:8000/agent-data"
async with httpx.AsyncClient() as client:
resp = await client.get(url)
if resp.status_code == 402:
payment_req = resp.json()
print(f"Payment required: {payment_req}")
# TODO: create token payment tx with agent wallet
payment_header = json.dumps({
"token": payment_req["token"],
"amount": payment_req["amountDue"]
})
headers = {"X-402-Payment": payment_header}
resp = await client.get(url, headers=headers)
print(resp.json())
# Run with asyncio
This example glosses over signing transactions but shows the general agent micropayments flow.
USDC is a popular stablecoin for micropayments due to low volatility and wide acceptance. Using USDC with x402 requires careful attention to token decimals (6 vs 18 decimals) and allowance approvals.
For example, USDC on Ethereum mainnet uses 6 decimals, so 1 USDC = 1_000_000 units.
When setting price_per_call_wei above, calculate the right token amount, e.g.:
price_usdc = 0.01 # 1 cent per call
usdc_decimals = 6
price_units = int(price_usdc * 10**usdc_decimals) # 10_000 units
In production, your middleware should verify the payment on-chain or via an MCP gateway to confirm the payment was settled. I recommend offloading this to an MCP (Model Context Protocol) server for permissionless micropayments and audit trails, as explained in the MCP server monetization tutorial.
I’ve hit gotchas running this locally with mixed token decimals and RPC timeouts. So expect some iteration before production readiness.
| Feature | Python FastAPI | Node.js Express |
|---|---|---|
| Language | Python | JavaScript/TypeScript |
| Async support | Native async/await | Callback/Promise |
| Ecosystem | Rich Python blockchain libs | Large Node/NPM ecosystem |
| Middleware pattern | BaseHTTPMiddleware | Express middleware |
| Documentation | Growing, less mature | More community examples |
| Example setup | Concise, especially for Py devs | Extensive tutorials |
Both work well for x402 but Python suits teams building hybrid AI×crypto agent infrastructures.
Setting up a micropayment API gateway with x402 in Python FastAPI is straightforward but requires careful handling of payment validation and token specifics. This setup is ideal for agent pay-per-API-call models where USDC stablecoin payments need enforcement.
From here, you can extend by integrating on-chain payment verification, MCP servers, or agent wallet session keys to harden your payment pipeline. Also, check out our agent-payments-protocol-comparisons page for understanding alternatives and their trade-offs.
Try this setup with your AI agent endpoints, and watch for real-world issues like fee spikes or key management.
Happy building!
For further details on x402 integrations and agent payment tutorials, see: