x402 Payments for an AI Agent in Python: 2026 Tutorial

A neutral, testnet-first walkthrough of the full HTTP 402 flow in Python — catch the 402, sign and pay test USDC on Base Sepolia, retry with X-PAYMENT, plus spend caps and idempotency.

What x402 payments for an AI agent in Python actually involve

Adding x402 payments to an AI agent in Python means giving the agent a wallet and an HTTP client that knows how to react to a 402 Payment Required response: read the seller’s payment requirements, sign a USDC transfer locally, and retry the same request with an X-PAYMENT header that proves payment. The agent never creates an account, never enters a card, and never holds an API key for the resource — the payment itself is the credential.

x402 is an open protocol stewarded by the x402 Foundation, which Coinbase and Cloudflare launched on September 23, 2025, to standardize value exchange over HTTP. It revives the long-dormant HTTP 402 status code and pairs it with USDC settlement, most commonly on Coinbase’s Base L2, where transactions settle in roughly two seconds at sub-cent gas cost.

Most published tutorials cover the seller side: bolt on some middleware, get paid. This one is written for the buyer — the agent. We walk the full loop end to end, entirely on the Base Sepolia testnet, so you can run every line below without spending a real cent. Then we cover what actually bites builders in production: spend caps, wallet scoping, facilitator trust, settlement latency, and replay/idempotency.

If you only remember one mental model: x402 turns ‘paying for an API call’ into an HTTP retry with a signed header. Everything else is wiring.

How the HTTP 402 payment flow works for an agent

The x402 flow is four HTTP moves: the agent requests a resource, the server answers 402 Payment Required with machine-readable payment requirements, the agent signs a gasless USDC authorization and retries with an X-PAYMENT header, and the server verifies-and-settles through a facilitator before returning the resource plus an X-PAYMENT-RESPONSE receipt. No money moves until the retry, and the signing happens entirely client-side — nothing leaves the device except a signature.

The 402 response body carries an accepts array of payment options. For the common ‘exact’ scheme on EVM, each option looks like this (values are illustrative for a $0.001 call on Base Sepolia):

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:84532",          // Base Sepolia testnet
      "maxAmountRequired": "1000",          // 1000 = $0.001 USDC (6 decimals)
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e", // testnet USDC
      "payTo": "0xSellerWalletAddress",
      "resource": "https://api.example.com/weather",
      "description": "Weather report",
      "mimeType": "application/json",
      "maxTimeoutSeconds": 300
    }
  ]
}

Step 1: Set up a Base Sepolia testnet wallet and test USDC

Before any code, create a throwaway EVM wallet, fund it with test ETH and test USDC on Base Sepolia, and store the private key in an environment variable — never in source. This wallet is the agent’s identity and its spending account, so treat it as disposable.

Generate a fresh key with eth-account, then fund it from a faucet:

# pip install eth-account
from eth_account import Account

acct = Account.create()
print("Address:    ", acct.address)
print("Private key:", acct.key.hex())  # store this in EVM_PRIVATE_KEY, never commit it

Step 2: Stand up a paywalled endpoint (so you have something to pay)

To test the buyer side you need a seller. The fastest path is a tiny FastAPI app guarded by the official x402 server middleware, priced at $0.001 and pointed at the testnet facilitator. This is the only seller-side code in the tutorial — everything after is the agent.

Install the server extras and write the app:

# pip install "x402[fastapi]" uvicorn
from fastapi import FastAPI
from x402.http import FacilitatorConfig, HTTPFacilitatorClient, PaymentOption
from x402.http.middleware.fastapi import PaymentMiddlewareASGI
from x402.http.types import RouteConfig
from x402.mechanisms.evm.exact import ExactEvmServerScheme
from x402.schemas import Network
from x402.server import x402ResourceServer

app = FastAPI()

EVM_NETWORK: Network = "eip155:84532"            # Base Sepolia
SELLER_ADDRESS = "0xYourSellerTestnetAddress"     # a second testnet wallet

facilitator = HTTPFacilitatorClient(
    FacilitatorConfig(url="https://x402.org/facilitator")
)
server = x402ResourceServer(facilitator)
server.register(EVM_NETWORK, ExactEvmServerScheme())

routes: dict[str, RouteConfig] = {
    "GET /weather": RouteConfig(
        accepts=[
            PaymentOption(
                scheme="exact",
                pay_to=SELLER_ADDRESS,
                price="$0.001",
                network=EVM_NETWORK,
            ),
        ],
        mime_type="application/json",
        description="Weather report",
    ),
}

app.add_middleware(PaymentMiddlewareASGI, routes=routes, server=server)

@app.get("/weather")
def weather():
    return {"city": "Lisbon", "temp_c": 21, "summary": "clear"}

# run: uvicorn seller:app --port 8000

Step 3: Build the x402 buyer — catch the 402, sign, and retry

On the buyer side, the official Python SDK wraps your HTTP client so the 402 handshake is transparent: you register an EVM signer, then call get() as usual — the wrapper catches the 402, signs the USDC authorization, retries with X-PAYMENT, and hands you the paid response. This is the core of x402 payments for an AI agent in Python.

Install the buyer extras and write the agent’s paid HTTP client. The async (httpx) version:

# pip install "x402[httpx]" eth-account
import asyncio, os
from eth_account import Account

from x402 import x402Client
from x402.http import x402HTTPClient
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client

ENDPOINT = "http://localhost:8000/weather"

async def pay_and_fetch(url: str) -> dict:
    client = x402Client()
    account = Account.from_key(os.environ["EVM_PRIVATE_KEY"])
    register_exact_evm_client(client, EthAccountSigner(account))

    http_client = x402HTTPClient(client)
    async with x402HttpxClient(client) as http:
        resp = await http.get(url)          # 402 -> sign -> retry happens here
        await resp.aread()
        if not resp.is_success:
            raise RuntimeError(f"paid request failed: {resp.status_code} {resp.text}")

        # the on-chain receipt: log this for reconciliation
        settle = http_client.get_payment_settle_response(
            lambda name: resp.headers.get(name)
        )
        print("settled:", settle)           # contains the settlement tx hash
        return resp.json()

if __name__ == "__main__":
    print(asyncio.run(pay_and_fetch(ENDPOINT)))

Step 4: Add a per-agent spend cap and scope the wallet

The single most important safeguard is a hard spend cap enforced in your own code before the signature happens — never trust the seller’s 402 to be the only limit. Read the price out of the 402’s accepts array, compare it against a per-run budget you control, and refuse to pay if it would blow the cap.

Because the SDK auto-pays, the clean place to enforce a cap is a thin gate that does a cheap unpaid probe first (to read the price), then decides whether to call the paying client. A minimal budget guard:

import httpx

class SpendCapExceeded(Exception):
    pass

class Budget:
    def __init__(self, max_total_usd: float, max_per_call_usd: float):
        self.max_total = max_total_usd
        self.max_per_call = max_per_call_usd
        self.spent = 0.0

    def authorize(self, price_usd: float):
        if price_usd > self.max_per_call:
            raise SpendCapExceeded(f"{price_usd} > per-call cap {self.max_per_call}")
        if self.spent + price_usd > self.max_total:
            raise SpendCapExceeded(f"run budget {self.max_total} exhausted")
        self.spent += price_usd

def price_of(url: str) -> float:
    """Unpaid probe: read the 402 requirements without paying."""
    r = httpx.get(url)
    if r.status_code != 402:
        return 0.0
    body = r.json()
    smallest = int(body["accepts"][0]["maxAmountRequired"])
    return smallest / 1_000_000          # USDC has 6 decimals

# usage, wrapping Step 3's pay_and_fetch:
budget = Budget(max_total_usd=0.05, max_per_call_usd=0.01)

async def guarded_fetch(url: str):
    budget.authorize(price_of(url))      # raises BEFORE we ever sign
    return await pay_and_fetch(url)

Step 5: Guard against replay with idempotency

An x402 payment authorization can be replayed to trigger multiple grants from a single payment — the arXiv ‘Five Attacks on x402’ study measured 248 grants from one payload on a live endpoint — so both sides must bind each payment to a single resource request and claim it exactly once. On the buyer side, that means making your paid calls idempotent so a retry storm or a crash-loop doesn’t sign the same intent ten times.

Attach an idempotency key to the logical operation and short-circuit if you’ve already paid for it this run:

import hashlib

_paid_cache: dict[str, dict] = {}   # in prod: Redis/DB with TTL, keyed per agent run

def idem_key(url: str, intent: str) -> str:
    return hashlib.sha256(f"{url}|{intent}".encode()).hexdigest()

async def idempotent_fetch(url: str, intent: str):
    key = idem_key(url, intent)
    if key in _paid_cache:
        return _paid_cache[key]          # already paid this run; reuse result
    result = await guarded_fetch(url)    # Step 4 gate -> Step 3 pay
    _paid_cache[key] = result
    return result

What bites real builders: facilitators, latency, and trust

The hardest x402 decisions in production aren’t about Python — they’re about which facilitator you trust, how you handle settlement latency, and how you reconcile spend. The buyer code is a dozen lines; the operational surface is where teams get hurt.

Facilitator trust is the big one. The facilitator sees your signed authorization and submits it on-chain on your behalf. The free x402.org testnet facilitator is fine for development; in production you choose between Coinbase’s CDP facilitator (instant, fee-free USDC settlement on Base), Cloudflare’s edge facilitator with its deferred/batched scheme, or community facilitators catalogued in awesome-x402 such as BNB Chain’s Pieverse or AsterPay (EUR off-ramp via SEPA). Treat the facilitator as a swappable dependency and read its terms — a misbehaving facilitator can stall or front-run settlement.

Latency is subtle. From the agent’s point of view the paid request feels like one slow HTTP call, because the wrapper blocks while the facilitator verifies and settles. On Base that’s roughly two seconds, but under load or on a deferred scheme it can be longer, and a timeout mid-settlement is exactly where replay bugs hide. Always log the X-PAYMENT-RESPONSE settlement tx hash — that hash is your only durable receipt for reconciliation and disputes.

Finally, x402 is a payment rail, not an authorization framework. It proves a payment happened; it does not encode ‘this user authorized this agent to spend up to $20 on data this week.’ That is AP2’s job (see the next section). Keep the two concerns separate in your architecture.

If you’d rather not hand-roll the wallet and discovery layer, community SDKs sit on top of x402: moltspay-python is LangChain-compatible, auto-creates a wallet, discovers paid services, and pays via x402, which is handy for prototyping an agent that shops across endpoints. Just apply the same spend-cap and idempotency discipline regardless of which SDK signs for you.

x402 vs AP2 and Stripe rails: which payment layer fits your agent?

x402, Google’s AP2, and Stripe’s Machine Payments Protocol (MPP) are not competitors so much as different layers — x402 moves stablecoins per HTTP call, AP2 is the authorization/mandate layer, and Stripe MPP is session-based streaming billing with fiat compliance built in. A mature 2026 agent often uses more than one.

Use x402 when an agent needs to pay per API call for infrastructure — compute, data, model inference — without accounts or cards, and you’re comfortable with onchain USDC. Use Stripe MPP (launched March 18, 2026 alongside Tempo) when you want session/streaming billing, unified fiat-and-crypto, and Stripe’s compliance stack. Use AP2 as the consent layer underneath either rail, so a human’s spending mandate persists across whatever rail actually moves the money.

For the per-API-call agent buyer this tutorial targets, x402 is the most direct fit and has the most production traction. But the moment a human’s money or recurring authorization is involved, layer AP2-style mandates on top — don’t let ‘the agent can sign a USDC transfer’ silently become ‘the agent can spend without limit.’

Builder’s take

I build agents that touch real money (Cyntr orchestrates paid data calls; Loomfeed routes machine traffic), so I read x402 less as a crypto story and more as plumbing. Here is what I tell my own team before they wire it in.

• Start testnet-only and keep it that way until your idempotency guard is proven. The arXiv ‘Five Attacks’ paper measured 248 grants from a single payment payload on a real endpoint — a replay bug here drains a hot wallet, not a Stripe balance you can claw back.
• Scope the agent’s wallet like you’d scope an API key: a dedicated key, a low on-chain balance, and a hard per-run spend cap enforced in your code BEFORE you sign. Never give an autonomous loop your treasury key.
• Trusting a facilitator is the real architectural decision, not the chain. Coinbase’s facilitator settles instantly and sponsors gas; Cloudflare’s deferred scheme batches. Pick deliberately and treat the facilitator as a dependency you can swap.
• x402 is a rail, not an authorization model. Pair it with AP2-style mandates or your own policy layer so ‘the agent can pay’ and ‘the agent is allowed to pay for this’ stay two separate decisions.
• Log the X-PAYMENT-RESPONSE tx hash for every paid call. Onchain settlement is your receipt; without it you cannot reconcile spend or debug a stuck payment.

Frequently asked questions

Primary sources

• x402 Quickstart for Buyers (official docs) — x402 Foundation
• x402 Quickstart for Sellers (official docs) — x402 Foundation
• coinbase/x402 protocol repository — Coinbase / GitHub
• HTTP 402 core concepts — Coinbase Developer Platform
• x402 Network Support (Base Sepolia) — Coinbase Developer Platform
• Launching the x402 Foundation with Coinbase — Cloudflare
• How to x402: The Complete Guide — Simplescraper
• Five Attacks on x402 Agentic Payment Protocol — arXiv
• x402 vs. Stripe MPP for AI agents in 2026 — WorkOS
• Testnet USDC faucet — Circle
• moltspay-python community SDK — GitHub
• awesome-x402 facilitator catalog — GitHub

Last updated: June 2, 2026. Related: Commerce.