What is x402.
x402 is an open protocol for HTTP-native payments, published by Coinbase in late 2024. It defines how a server returns 402 Payment Required with a structured JSON body - a list of acceptable payment requirements (scheme, network, chain id, recipient address, amount in USDC base units, and a payment-request id) - so that a machine client can parse the response, pay on-chain, and retry the original call with an X-Payment header, all programmatically.
HTTP 402 sat unused for thirty years. x402 made it work.
The 402 Payment Required status code was reserved in the original HTTP spec for "future use" and never received a standardized implementation. For three decades, every actual payment flow on the web was built on top of 200 / 401 / 403: a server returns 401 when authentication is missing, the client signs up via a separate UI flow, gets credentials, and re-authenticates. The signup happens out of band. None of this works for AI agents, which cannot complete signup forms.
x402 fixes this by giving 402 a usable specification. A server can return 402 with structured machine-readable payment instructions; a client can parse those instructions, pay, and retry, all without ever touching a signup form. The protocol is the missing piece between "AI agents can call APIs" and "AI agents can pay for the APIs they call". Before x402, the only practical agent payment paths were pre-paid balance accounts (with manual top-up) or proprietary integrations per API. Both broke at scale.
The strategic importance of x402 is that it sets a standard the rest of the ecosystem can build against. Wallets implement an x402 handler once, and every x402-compliant API works with that wallet. Server frameworks implement an x402 middleware once, and every x402-aware client can pay them. Facilitators (services that settle the underlying payments) compete on quality of service rather than on lock-in.
One response, one retry, one payment.
The lifecycle has three states: unpaid call, payment, retried call. Below is what the unpaid-call response actually looks like over the wire.
HTTP/1.1 402 Payment Required Content-Type: application/json { "resource": "POST /api/research-query", "accepts": [ { "scheme": "exact-usdc", "network": "mainnet", "chainId": "eip155:8453", "payToAddress": "0xAgent...", "amountWeiUsdc": "50000", "paymentRequestId": "pr_01J9...", "maxAgeSeconds": 60 } ] }
- Status code 402. Distinct from 401 (auth missing) and 403 (auth refused). The presence of 402 signals "payment is the missing input."
- resource + accepts[]. The body names the protected resource and lists one or more acceptable payment requirements. A migration can quote two requirements (e.g. mainnet and testnet) and let the client pick.
- scheme / network / chainId. The payment scheme (exact-usdc), the chain (mainnet is Base), and its CAIP-2 id. The client matches on these before paying.
- payToAddress / amountWeiUsdc. The recipient wallet and the exact amount in USDC base units (50000 = 0.05 USDC, 6 decimals). The client verifies both before paying.
- paymentRequestId + maxAgeSeconds. The id ties the payment to this quote; maxAgeSeconds is how fresh the payment must be. A payment that references a different id, or is older than the window, is rejected.
- The retry carries an X-Payment header. The client pays on-chain, then re-issues the original request with an X-Payment header proving the payment. The server verifies it and returns the real result. No response headers or hosted page are part of the x402 wire itself.
x402 in the wild.
Three concrete deployments, ordered by how mature the adoption is in each layer.
MCP server returning a 402 challenge to an unpaid tool call
A paid MCP tool receives an invocation from Claude Desktop and the caller is not yet marked paid. The server builds a requirePayment challenge - a 402 whose body carries the price and a hostedUrl - and returns it as a tool error. Claude Desktop renders the link in the chat; the user pays $0.05 USDC; the next call to the same tool succeeds.
API endpoint gating per-call billing
A research API charges $0.50 per call behind the x402 server adapter. An AI agent calls the endpoint, gets a 402 listing the amount and recipient, pays on Base from its wallet, and re-issues the request with an X-Payment header. The adapter verifies the header and returns the paid response. The whole loop completes in under 60 seconds.
Agent paying programmatically via x402-aware wallet
An agent's runtime is x402-aware (it implements the spec). When it hits a 402, it reads the payToAddress and amount from accepts[], signs a transfer from its pre-authorized wallet (within its spend permission), broadcasts on Base, and retries the original call with an X-Payment header. No human involvement; the loop completes in 5-10 seconds.
What surrounds x402 in the stack.
x402 is the protocol. These three terms cover the concepts it sits on top of and the use cases it enables.