What Is x402? How the HTTP 402 Payment Protocol Works, With a Real 402 Offer Decoded

HTTP has had a status code for payment since the 1990s and never a way to use it. The current HTTP semantics standard, RFC 9110, still defines it in one line: "The 402 (Payment Required) status code is reserved for future use." Paywalls and APIs therefore built payment outside HTTP: an account, a subscription, an API key tied to a card. That works for humans and fails for software agents, which cannot fill in a signup form, pass an email check or enter a card.

x402 fills the gap with a small, chain-agnostic contract. The x402 Foundation repository describes it as "an open standard for internet native payments" that "aims to support all networks (both crypto & fiat) and forms of value (stablecoins, tokens, fiat)", and x402.org calls it "an open, neutral standard for internet-native payments". In practice almost every live deployment moves USDC on Base or Solana, because a stablecoin transfer can be authorized with one signature and settled for a fraction of a cent, which is what makes a $0.005 API call economical.

Who is behind it. Coinbase's developer platform introduced x402 in May 2025. On September 23, 2025 Cloudflare announced it was "partnering with Coinbase to create the x402 Foundation", proposed a deferred payment scheme for agent payments that do not need immediate settlement, and added x402 support to its Agents SDK and MCP servers (Cloudflare blog). The reference code now lives at github.com/x402-foundation/x402 (Apache-2.0); the repository's own readme no longer mentions Coinbase, though Coinbase still runs a major facilitator. The x402.org site lists Alchemy, AWS, Cloudflare, Messari, Nansen, Quicknode, Stripe, Vercel and World under "Trusted by" and states that x402 "has processed millions of transactions"; it publishes no exact figure, so we do not quote one.

What you install. The reference SDKs are on npm under the @x402 scope (@x402/core, @x402/evm, @x402/svm, the client wrappers @x402/fetch and @x402/axios, server middleware @x402/express, @x402/hono, @x402/next, and @x402/mcp for paid MCP tools), on PyPI as x402, and in Go as github.com/x402-foundation/x402/go/v2. When we checked, @x402/fetch was at version 2.30.0 and the PyPI package at 2.27.0, both on the v2 protocol.

The v2 specification names three parties: the resource server (the API that wants payment), the client (any application or agent; it holds a wallet) and the facilitator ("a service that handles payment verification and blockchain settlement"). The core cycle is four messages, and the default authorization flow verifies before the API does any work and settles after it.

1. Request. The client calls the endpoint as it would any API, with no credentials.

2. 402 challenge. The server returns 402 and a PAYMENT-REQUIRED header: base64-encoded JSON with x402Version, a resource block (URL, description, MIME type) and an accepts[] array. Each accepts entry is one way to pay: scheme (for example exact), network in CAIP-2 form, asset (the token contract), amount in the token's smallest unit, payTo (the recipient address) and maxTimeoutSeconds.

3. Sign and retry. The client picks one entry it can pay, signs a payload (on EVM chains an EIP-3009 transferWithAuthorization for USDC, which needs no gas from the payer) and repeats the request with a base64 PAYMENT-SIGNATURE header.

4. Verify, serve, settle. The server, or a facilitator on its behalf, checks the signature, amount and time window (POST /verify), runs the request, broadcasts the transfer (POST /settle) and returns 200 with the data plus a PAYMENT-RESPONSE header carrying the settlement result: success, the transaction hash, the network and the payer. A failed payment comes back as 402 with a PAYMENT-RESPONSE that carries an errorReason such as insufficient_funds.

Schemes decide how money moves. The repository defines exact ("transfers a specific amount"), upto ("authorizes up to a maximum per request; the seller settles the actual usage, up to that cap") and batch-settlement (EVM only: escrow plus off-chain vouchers that the seller redeems in batches); the spec's scheme folder also lists auth-capture. Replay protection comes from the token standard: each EIP-3009 authorization carries a unique 32-byte nonce and an explicit valid-before time, and the contract rejects a reused nonce.

Most explainers show the spec's example payload with a testnet address. Here is a live production challenge instead. TwitterAPI.io accepts x402 on three GET read endpoints, so an unpaid request to one of them returns a real offer. We sent a plain curl with no key and no payment to https://api.twitterapi.io/x402/twitter/user/info?userName=x402 and got HTTP/2 402, the body {"error":"Payment required"}, cache-control: no-store, and a payment-required header of about 2,700 base64 characters. Decoded, it reads as follows (addresses shortened).

The resource.description is written for an agent to read: "Fixed price per request. Limited to 20 requests per second per paying wallet. No API key or account needed." The search endpoint /x402/twitter/tweet/advanced_search answers the same way with amount 6000 (0.006 USDC) and a description that adds "for up to 20 results; an empty result is still charged". That one header tells a wallet-equipped agent everything it needs: the price, both networks, the token contract, the recipient, the time limit and the input schema, with no documentation lookup.

We did not complete a paid call for this page (we used no wallet), so the trace stops at the challenge. A client library such as @x402/fetch or the Python x402 package handles steps 3 and 4: it reads accepts[], signs with the configured wallet, retries, and exposes the PAYMENT-RESPONSE receipt.

A facilitator is optional in principle; a resource server with its own chain node and signer can verify and settle itself. In practice nearly every x402 seller uses one, because the facilitator absorbs the chain-specific work: checking signatures, simulating the transfer, paying gas (or, on Solana, acting as feePayer), broadcasting and waiting for confirmation. The interface is three HTTP endpoints in the spec: POST /verify, POST /settle and GET /supported, which lists the scheme and network pairs, the extensions and the signer addresses a facilitator handles.

Because /supported is public, you can see exactly what a facilitator will do before you depend on it. We read two of them this year.

Two practical rules follow. First, the public x402.org facilitator is a testnet tool; the repository readme says it plainly: "Do not assume the public x402.org facilitator is the default production path for mainnet EVM routes." Second, pick the facilitator by the networks and schemes you need and by whether it indexes your endpoint for discovery. TwitterAPI.io's x402 endpoints, for example, settle through PayAI, which lists both Base and Solana mainnet and the bazaar extension, which is what the Bazaar paragraphs below rely on.

The x402 Bazaar: how agents discover paid APIs. A payment protocol does not help an agent that cannot find anything to buy. The v2 specification adds a Discovery API, "a discovery mechanism that allows clients to find and explore available x402-enabled resources. This enables the creation of marketplaces (known as 'Bazaars')". A facilitator that implements it exposes GET /discovery/resources (filterable by type, scheme, network and extensions) and GET /discovery/search; each listed resource carries its URL, type, x402Version, the accepts[] price list and a lastUpdated timestamp.

Listings are fed by the bazaar extension. The spec says it "enables resource discovery and cataloging for x402-enabled endpoints and MCP tools": the seller puts an info block (HTTP method or MCP tool name, input parameters, output example) and a JSON schema for it into the 402 response, and a facilitator that sees the extension can index the endpoint. That is the block at the end of the live offer decoded in the previous section: method GET, query parameter userName described as "X username without @", and an example output. An agent can therefore search a Bazaar for "twitter" or "social-data" (the offer's tags), read the price, and call the endpoint with no prior integration.

"x402 marketplace" searches usually mean one of these catalogs. Besides facilitator-run Bazaars, the x402 repository readme points to community directories: x402scan.com, agentic.market, pay.sh, app.ampersend.ai/discover and x402-list.com. Treat any directory as a lead, not a guarantee: always read the live 402 from the endpoint itself before an agent spends, since the price in the challenge is the one that applies.

The specification's version history lists v0.1 (initial draft, August 2025), v0.2 (a transport-agnostic redesign, October 2025) and v2.0 on December 9, 2025: "CAIP-2 networks, restructured PaymentPayload/Required, ResourceInfo separation, extensions support". The differences you meet in code are below; we compared the v1 and v2 spec files in the repository.

CAIP-2 is the change that matters most for multi-chain work: a network is namespace:reference, so EVM chains are eip155:<chainId>, Solana is solana:<genesis hash>, and the spec encourages non-blockchain rails to follow the same shape (it gives ach:us and sepa:eu as examples). Facilitators can serve both versions at once: PayAI's /supported lists v1 pairs under the old network names next to v2 pairs under CAIP-2 IDs, so an old client keeps working while sellers move to v2.

Stripe x402. Stripe's machine payments docs ("Allow agents to pay-per-call using MPP and x402") present the Machine Payments Protocol (MPP) as the primary path and add that "Stripe also supports stablecoin payments over the x402 protocol". For x402 the rail is USDC on Base. In Stripe's x402 guide your server returns a 402 with a Stripe deposit address as payTo; mainnet payments "settle through the Coinbase Developer Platform (CDP) facilitator", and you then record the onchain transaction as a PaymentIntent so it lands in your Stripe balance and reporting. Stripe lists a 0.01 USDC minimum for stablecoin payments and stablecoin acceptance for businesses in all US states except New York. For testing it points to the public x402.org/facilitator on Base Sepolia.

Cloudflare x402. Cloudflare's contribution is distribution: the x402 Foundation it co-founded with Coinbase, x402 payments from its Agents SDK, paid tools on MCP servers, and a proposed deferred scheme for its pay per crawl beta, where a crawler is billed later instead of settling each fetch onchain.

x402 vs MPP vs L402. All three answer an unpaid request with 402; they differ in where the challenge sits and what money moves. MPP is "co-authored by Tempo and Stripe" (mpp.dev) and puts its challenge in a standard HTTP auth scheme defined by an IETF individual draft; its docs describe metered sessions and say one endpoint can "serve native MPP and x402 clients". L402, from the Lightning Network ecosystem (docs.lightning.engineering), returns 402 with a WWW-Authenticate header carrying a bearer token, recommended as a macaroon, plus a Lightning invoice; the client pays and presents the token with the payment preimage. Lightning Labs' Aperture is a reverse proxy that implements it.

Which one an agent meets is mostly a seller decision. If you sell an API and your buyers hold USDC wallets, x402 has the widest SDK and facilitator coverage; if your buyers pay by card through Stripe, MPP's card path fits; if they hold bitcoin on Lightning, L402. For checkout, mandate and card-network protocols, see the agentic payments comparison.

Here is the concrete case we can price exactly, because we sell it both ways. TwitterAPI.io accepts x402 on three GET read endpoints, paid in USDC on Base or Solana, no API key or account: /x402/twitter/tweet/advanced_search and /x402/twitter/user/last_tweets at $0.006 per request (one page of up to 20 tweets), and /x402/twitter/user/info at $0.005 per request. The price is per request and an empty result is still charged; the facilitator is PayAI; there is no MPP or ACP. The same data with an API key and prepaid credits is $0.15 per 1,000 tweets returned and $0.18 per 1,000 profiles.

Take an agent that checks 50 accounts and reads 10 pages of search results (200 posts) for a research brief.

The official X API figures use the docs.x.com pricing rate card: $0.010 per user read and $0.005 per post read. Per 1,000 tweets that is $5 against our $0.15 with a key, about 33x.

So x402 costs more per record than credits, and that is the trade it is designed for. Use x402 when the agent is ephemeral or third-party and should not hold an account key, when a run makes a handful of calls, when you want each spend to be an onchain receipt tied to a wallet with its own budget, or when an agent found the endpoint through a Bazaar and has no integration at all. Use an API key when the job is recurring or large: new accounts that pass the automatic bot check get up to $1 of free credits (at most 100,000 credits, no card, one per person or network, expiring after 31 days), purchased credits never expire, you pay only for the data returned, and the key also works with our hosted MCP server at https://mcp.twitterapi.io/mcp with the header Authorization: Bearer <your key>. Reads need no X account either way.

Rate limits differ too. The x402 offer states 20 requests per second per paying wallet; a key starts at 0.2 requests per second before the first payment and rises to 20 once paid, 50 on Scale and 500 on Business. The full plan list is on the pricing page.

To see what the x402 conversation actually covers, we collected 1,259 original posts (retweets excluded) in 2026 with /twitter/tweet/advanced_search: the newest 400 posts for x402, the 99 posts X ranks as Top for it, and up to 120 of the newest posts for each long-tail topic people search. Posts per day is the sample size divided by the hours it spans.

x402 is the HTTP 402 conversation. The bare term ran at 529.9 posts a day, about 151x the rate of L402 (3.5). Among the subtopics, facilitators get the most talk (35.9 a day), well ahead of Bazaar (4.1) and v2 (4.3), even though both shipped in the spec.

It is about agents and stablecoins, not tokens. 63.2% of the newest x402 posts mention agents, 25.2% mention USDC or stablecoins and 24.0% mention APIs; 9.2% carry a $cashtag. Base is named in 14.8% and Solana in 10.5%; every other chain we tracked stays under 3%. PayAI (6.8%) is named slightly more often than Coinbase or CDP (5.5%), and Stripe in 3.5%.

The stream and the highlights differ. Top posts reach a median of 49 likes and 3,066 views against 1 like and 37.5 views in the Latest stream, and they lean more technical: facilitators 10.1% vs 5.8%, MCP 12.1% vs 8.2%, Solana 17.2% vs 10.5%. The stream is busy but concentrated: the 10 most active authors wrote 21.5% of the newest 400 posts, and 40.0% were replies.

Each long-tail topic has its own neighbors. 46.7% of Bazaar posts name Coinbase or CDP and 40.8% name Base. Posts on x402 with Stripe name Google or AP2 in 31.2% and Coinbase in 31.2%, a sign that Stripe's x402 support is discussed as part of the wider agent-payment race. Cloudflare posts name Base in 46.2%. L402 posts almost never name a stablecoin chain (Base and Solana both 0.0%).

For a builder the takeaway is practical. If you sell an x402 endpoint, the people who will notice it are talking about agents, USDC and facilitators, mostly on Base and Solana; MCP comes up in roughly one Top post in eight, which matches the spec's choice to let bazaar index MCP tools as well as HTTP endpoints. A saved search on x402 facilitator or x402 bazaar gives a far smaller, more technical feed than the bare term.

How we collected this. Question: what does the x402 conversation on X cover, and how much attention does each long-tail topic get? Data: /twitter/tweet/advanced_search with retweets excluded for nine queries (x402 Latest and Top, then x402 facilitator, x402 bazaar, x402 v2, L402, x402 MPP, x402 stripe, x402 cloudflare, Latest). Window: the newest posts for each query at collection time in 2026 (Top: the posts X ranks highest, spanning about 410 days). Sample: 1,259 posts from 63 requests. Method: case-insensitive keyword rules (Base counts only as the capitalized word or @base, so "user base" does not match), listed in analyze.py. At our prepaid rate the collection cost $0.189; the same posts through our x402 search endpoint would have been $0.378 (63 requests at $0.006), and on the official X API rate card $6.29.

What the sample cannot show. Post counts measure attention, not adoption: they say nothing about payment volume, revenue or which facilitator settles the most. Rates come from the newest posts, so a launch or a token event inflates them. A two-word query such as x402 facilitator also matches posts where one word sits in a link or handle, and short tokens such as SOL and ETH can appear in unrelated contexts. Privacy: aggregates only; search results come from private individuals, so raw pages were not kept, the committed sample holds de-identified rows (no IDs, links, text or handles), and no individual account is named.