x402 for Developers: Stablecoin Payments over HTTP

What x402 Is

x402 is an open protocol that lets a server charge for a request by replying with HTTP 402 Payment Required, so a client or AI agent can pay in stablecoins and retry the same request automatically — no account, no card, no human checkout.

Coinbase introduced x402 in May 2025 and, as of 2026, the open spec is governed by the x402 Foundation, set up with Cloudflare. It is built for machine-to-machine payments and API monetization: the cases where a person clicking a checkout button does not scale, because the buyer is software making a call. If you want the wider map of agent payment protocols first, the agentic payments explainer covers the players and how they fit together.

Why HTTP 402

Status code 402 has been reserved in the HTTP spec since the early 1990s, labeled “Payment Required” and left for future use. For thirty years there was no agreed way to say, in a normal HTTP response, “this costs money, here is how to pay.” Servers improvised with API keys, subscriptions, and login walls, all of which assume an account set up in advance.

x402 fills the gap that 402 was reserved for. The response itself carries machine-readable payment terms, and the client can act on them without a human. It is not the only project reviving the code — Stripe's Machine Payments Protocol leans on 402 as well — which tells you the dormant status code is finally getting the job it was named for.

The Flow: Request, Pay, Retry, Serve

The whole protocol is one handshake repeated. A request gets refused with payment terms, the client pays, and the client tries again with proof. Five steps:

1. Request. The client calls the resource with no payment attached. Nothing special happens yet; it is an ordinary HTTP request.
2. 402 with requirements. Instead of the data, the server returns 402 Payment Required and advertises what it accepts: the scheme, the network, the asset, the amount, and the address that should be paid.
3. Pay. The client (or the wallet behind it) signs a stablecoin payment authorization for exactly those terms. No login, no checkout page, no card.
4. Retry with proof. The client resends the same request, this time attaching the signed payment payload in a payment header.
5. Verify, settle, serve. The server verifies the payload and settles the payment, on its own or through a facilitator, then returns 200 OK with the resource and a settlement receipt.

Here is the same exchange on the wire. Earlier drafts of x402 sent the payment proof in an X-PAYMENT header; the current spec uses the PAYMENT-* headers shown below. The shape is the same either way, and the official spec is the source of truth for exact names.

# Illustrative x402 exchange over HTTP. Header and field names follow the
# coinbase/x402 spec as of mid-2026 and have changed across versions; treat
# the official spec as canonical for the exact bytes.

# 1) Agent requests a paid resource. No payment attached yet.
GET /v1/market-data HTTP/1.1
Host: api.example.com

# 2) Server says "pay first" with a 402 and its payment requirements.
HTTP/1.1 402 Payment Required
#   The server advertises what it accepts (decoded here for readability):
#     scheme:            "exact"      -> pay one exact amount
#     network:           "base"       -> the chain to settle on
#     asset:             USDC
#     maxAmountRequired: "10000"      -> 0.01 USDC (6 decimals)
#     payTo:             0xSeller...  -> who receives the funds
#     resource:          "/v1/market-data"

# 3) Agent signs a stablecoin payment authorization for EXACTLY those terms,
#    then retries the SAME request carrying the signed payload.
GET /v1/market-data HTTP/1.1
Host: api.example.com
PAYMENT-SIGNATURE: <base64 signed payment payload>

# 4) Server verifies + settles (itself or via a facilitator), then serves.
HTTP/1.1 200 OK
PAYMENT-RESPONSE: <base64 settlement receipt>
Content-Type: application/json

{ "data": "...the thing the agent paid for..." }

Two things make this work for machines. The 402 response is structured, so a client can read the terms instead of parsing a checkout page. And the payment is a signed authorization for a specific amount to a specific payee, so retrying with proof is the natural next step rather than a separate flow.

A Worked Example

The code below is illustrative pseudocode; the real x402 SDKs and middleware handle the signing, encoding, and facilitator calls. Start on the server: you wrap one route so it cannot run until payment clears.

# Illustrative server side: gate one route behind x402 (pseudocode).
# The official x402 middleware packages wire most of this up for you.

PRICE   = "0.01 USDC"          # what this endpoint costs per call
NETWORK = "base"               # settle on Base
PAY_TO  = "0xYourSeller..."    # your receiving address

@app.get("/v1/market-data")
@require_payment(price=PRICE, network=NETWORK, pay_to=PAY_TO)
def market_data(request):
    # This body runs ONLY after payment is verified and settled.
    return {"data": load_market_data()}

On the client, the agent treats a 402 as a normal branch in its logic: read the terms, sign, retry. If your agent is the one paying, that is exactly where you want a spend limit in front of the wallet — see how to give your AI coding agent a budget so a hijacked prompt cannot drain it.

# Illustrative client side: an agent that pays on its own (pseudocode).

resp = http.get("https://api.example.com/v1/market-data")

if resp.status == 402:
    terms   = read_payment_requirements(resp)    # scheme, network, amount, payTo
    payload = wallet.sign_payment(terms)          # sign a stablecoin authorization
    resp    = http.get(                           # retry with the proof attached
        "https://api.example.com/v1/market-data",
        headers={"PAYMENT-SIGNATURE": to_base64(payload)},
    )

data = resp.json()   # 200 OK: the resource you paid for

The Facilitator and Settlement

Most servers do not want to talk to a blockchain directly, so x402 defines a facilitator: a service the resource server calls to check and execute payments. The server forwards the client's payment payload and the requirements to the facilitator's /verify endpoint to confirm the payload is valid, then to /settle to move the funds on chain. The server can also do this itself if it prefers; the facilitator is a convenience, not a gatekeeper that owns your money.

Settlement happens in stablecoins on a supported network. USDC on Base is the common default as of 2026, with Solana and Stellar also supported, and facilitators can sponsor gas so the payer does not need the chain's native token. Confirmation lands in seconds, which is what makes per-call pricing practical: the server can wait for the money before it returns the resource.

Use Cases

x402 earns its keep wherever the buyer is software and the amounts are small or frequent enough that accounts and invoices get in the way.

If you are weighing x402 against the other rails for one of these jobs, the agent payment protocols compared breakdown puts them side by side.

How x402 Relates to AP2 and MPP

x402 does not compete with Google's Agent Payments Protocol; it is AP2's stablecoin extension. AP2 defines how an agent proves it is authorized to pay — the mandate and the audit trail — across many rails. x402 is the crypto rail underneath: the A2A x402 extension, co-developed by Coinbase with the Ethereum Foundation and MetaMask, is how AP2 settles in stablecoins. The authorization layer and the settlement layer are different problems, and these two slot together.

Stripe's Machine Payments Protocol also revives the 402 code, but aims more at fiat and card-backed machine payments through Stripe's own infrastructure. So 402 is becoming a shared convention with more than one implementation behind it. Which you reach for depends on whether you want stablecoin settlement (x402) or a managed fiat rail (MPP), a trade-off we dig into in the trust layer for agent payments.

Limits and Caveats

x402 is stablecoin rails, and that comes with real constraints. Both sides need a wallet and a way to manage keys; custody is now your problem, or your provider's. You have to choose a network and live with its finality and fees, even when a facilitator sponsors gas. Holding and moving stablecoins has tax and accounting implications that a plain card charge does not.

It is also not a consumer checkout. There is no built-in chargeback the way cards have one, refunds are an application concern, and a person paying for a normal purchase is better served by a card mandate. Treat x402 as the right tool for machine-to-machine payments and API metering, not as a drop-in replacement for Stripe Checkout. And because the spec is still moving — header and field names have already changed between versions — pin to a version and read the official spec before you ship.

FAQ

Sources

• x402.org: the protocol's home and whitepaper
• GitHub: coinbase/x402 spec, SDKs, and the flow above
• Coinbase Developer Docs: x402 overview
• Coinbase: x402 as AP2's stablecoin extension
• Google Cloud: announcing the Agent Payments Protocol (AP2)
• Crossmint: agentic payments protocols compared