x402 protocol explained: how HTTP 402 pays AI agents

The x402 protocol is an open standard that turns HTTP’s long-dormant 402 Payment Required status code into a working payment flow: a server rejects an unpaid request with a 402 and a machine-readable price, the client responds with a signed stablecoin payment, and the server delivers the resource in the very next request. No accounts, no API-key billing portals, no invoices — payment happens inside the HTTP exchange itself. That shape happens to be exactly what AI agents need, which is why x402 went from a Coinbase experiment to a Linux Foundation project in under a year.

HTTP 402: the status code that waited since 1997

HTTP has had a payment slot since the beginning. The original HTTP/1.1 specification defined status code 402 and labeled it “reserved for future use” — the authors expected some form of digital cash to arrive and never picked a winner. For nearly three decades, RFC 9110 and its predecessors carried 402 along as a placeholder while the web built payments around HTTP instead: card forms, OAuth-gated billing APIs, subscription dashboards.

Those workarounds all assume a human is present — someone to type a card number, click “upgrade,” or paste an API key. An autonomous agent has none of that. What it can do is read a structured error, sign a message with a wallet key, and retry a request. x402 is the protocol that closes that loop: it gives 402 a concrete body format, a payment header, and a settlement path on stablecoin rails. If you want the primer on why stablecoins are the money leg here, start with what stablecoin payments are and why they settle in seconds.

How the x402 protocol works, request by request

The whole protocol fits in four steps:

Agent                    Server                    Facilitator
  |  GET /report           |                          |
  |----------------------->|                          |
  |  402 + payment reqs    |                          |
  |<-----------------------|                          |
  |  (sign payment payload)|                          |
  |  GET /report           |                          |
  |  X-PAYMENT: <payload>  |                          |
  |----------------------->|  verify(payload)         |
  |                        |------------------------->|
  |                        |  valid -> settle         |
  |                        |<-------------------------|
  |  200 + resource        |                          |
  |<-----------------------|                          |

Step 1 — the challenge. The client requests a paid resource with no payment attached. The server responds 402 Payment Required with a JSON body listing its payment requirements: the scheme (usually exact, a fixed price), the network (say Base or Solana), the token contract, the amount, the receiving address, and an expiry.

Step 2 — the signed payload. The client picks a requirement it can satisfy and constructs a payment payload: an authorization to move exactly that amount to that address, signed with the agent’s wallet key. On EVM chains this typically uses EIP-3009 transferWithAuthorization — a signed message that lets the recipient side submit the transfer, so the agent never spends gas. The payload goes into a payment header on the retried request.

Step 3 — verify and settle. The server does not parse signatures itself. It forwards the payload to a facilitator, which checks that the signature is valid, the funds exist, and the authorization matches the requirements — then broadcasts the transfer on-chain.

Step 4 — the response. Once settlement is confirmed, the server returns 200 with the resource and a settlement receipt header. One price, one payment, one response. No session state survives the exchange unless the server wants it to.

The x402 facilitator: the least-documented, most important role

Most x402 write-ups gloss over the facilitator, but it is where all the hard work lives. The facilitator exposes two operations — verify (is this payload valid for these requirements?) and settle (broadcast it and confirm) — and the resource server outsources both. That is what keeps x402 adoption cheap: a seller adds a middleware layer and a wallet address, and never touches chain infrastructure.

You can run your own facilitator or use a hosted one; Coinbase’s x402 repository ships reference implementations, and hosted facilitators handle the chain plumbing for you. The trade-off is the usual one — self-run means you operate RPC nodes and confirmation logic; hosted means you trust a third party to report settlement honestly (the on-chain transfer itself remains verifiable by anyone).

Plaidly exposes a public facilitator endpoint, POST /v1/x402/facilitator, and it is worth being precise about what it does today: it validates x402 payment requirements against Plaidly’s supported chains, tokens, and networks, returning {supported, outcome, reason} — where outcome is retryable (try a different chain or token from your requirements list) or terminal (this requirement can’t be satisfied, stop). That pre-flight check saves an agent from signing payloads that can never settle. Full proof verification and settlement through the same endpoint is on the roadmap; the request and response shapes are in the API docs.

Where x402 sits in the protocol stack

x402 is frequently framed as competing with the other agentic-commerce protocols. It mostly isn’t — they occupy different layers:

• x402 is a settlement mechanism: how money actually moves for a single HTTP resource.
• ACP (Agentic Commerce Protocol, from OpenAI and Stripe) is a checkout flow: cart, order, merchant-of-record semantics for buying products inside a chat.
• AP2 (Google’s Agent Payments Protocol) is a mandate layer: cryptographic proof that a human authorized an agent to spend, portable across payment methods — cards, bank transfers, or stablecoins via its x402 extension.
• Hosted payment sessions (the Stripe-style model Plaidly uses) are an orchestration layer: a session object with a lifecycle, receipts, and webhooks wrapped around the raw transfer.

A realistic future stack uses several at once: an AP2 mandate proving the human said yes, an ACP checkout describing what’s being bought, and x402 or a payment session moving the stablecoins underneath. Complementary, not competing.

Adoption so far

x402 launched from Coinbase in May 2025 and moved to neutral governance quickly — the x402 Foundation, established with Cloudflare under the Linux Foundation, now stewards the spec. On the numbers the ecosystem publicly reports: roughly 154 million transactions to date, an annualized run rate near $600 million, and about 98.6% of volume settling in USDC. The transaction sizes are tiny and the counts are huge, which tells you what x402 is actually being used for: machine-to-machine micropayments — per-call API access, per-query data, per-task compute — not human shopping carts.

Getting an agent through a 402 paywall

Here is the recipe an agent follows when it hits a paid endpoint, as implemented in Plaidly’s paid-service-acquisition flow:

1. Parse the challenge. Decode the 402 body into a list of payment requirements. Plaidly’s SDKs ship a parse_x402_challenge helper that does this and normalizes chain/token identifiers.
2. Pre-flight the requirements. Call the facilitator endpoint to learn which requirement is actually satisfiable. A retryable outcome means try the next chain or token in the list; terminal means abandon this path and report why.
3. Create a matching payment session. The agent creates a Plaidly payment session for the required amount, token, and network with its API key, and pays it from its wallet.
4. Retry with proof. The retry_request_with_x402_proof helper re-issues the original request with the payment proof header attached, and hands back the 200 response.

The failure matrix matters more than the happy path. Unsupported chain: terminal. Expired requirements: retryable — re-request the resource for a fresh challenge. Insufficient wallet balance: terminal until funded. Encoding a clean retryable/terminal split is what lets an agent loop without a human babysitting it. We ran the session-based version of this loop end to end when six agents bought VPS servers with USDC on testnet rails — real on-chain USDC on Solana devnet, real payment sessions and MCP tools rather than raw 402 challenges, no human in the payment path.

x402 or a hosted payment session?

Raw x402 shines when the thing being sold is a single HTTP response: one price, one call, no relationship. If that’s your product, implement the middleware and you’re done.

Hosted payment sessions earn their keep when you need everything around the transfer: multi-chain choice at pay time, per-chain finality handling, a receipt object your accountant can read, and a signed webhook the moment funds clear. That’s the model Plaidly runs today — agent payments work now via payment sessions and API keys on testnet rails, across the same twenty-chain platform human checkouts use, with mainnet gated behind config. Agents that talk MCP get the same capability as tools — see how MCP payments work — and the full integration path lives on the agentic payments page and in the docs.

The honest summary: x402 gave the web’s oldest unused status code a real job, and gave agents a payment primitive that matches how they already work — structured errors, signed retries, verifiable settlement. Whether you consume it raw or through a session layer, the direction is the same: money is becoming just another header.