x402 Protocol: The Complete Developer Guide

x402 is an open payment protocol that revives the long-dormant HTTP 402 Payment Required status code, letting a server charge for a request and a client pay for it — in stablecoins, per request, with no account, subscription or human in the loop. Created by Coinbase and launched in 2025, it is now stewarded by the Linux Foundation's x402 Foundation (operational since July 2026). This guide is for developers: how the request/response flow actually works, the headers and the exact scheme, the facilitator, which chains it runs on, where adoption really stands, and how x402 fits with AP2 and ACP.

New to the space? Start with the parent guide: What is Agentic Commerce?

Why x402 exists: the web's missing payment primitive

HTTP has always had a status code reserved for this — 402 Payment Required — but for thirty years it sat unused, because the web's payment model grew up around humans: accounts, sessions, saved cards, monthly subscriptions, and a checkout page where a person clicks "pay." None of that fits an autonomous agent that wants to call an API forty times in a second, spend a fraction of a cent each time, and never see a login screen.

x402 fills that gap. It turns 402 into a real, machine-negotiable handshake: a resource server can say "this costs $0.001, pay to this address on this network," and a client — human or agent — can satisfy it programmatically and retry, all inside the normal HTTP request/response cycle. No API keys to provision, no invoices, no card on file. The unit of commerce becomes the individual request.

That is why the protocol matters to anyone building agents: it is the first widely-backed answer to how does software pay software, and it is deliberately stablecoin-native — settlement is in USDC (and other tokens), so amounts can be sub-cent and final within seconds.

How x402 works: the request/response cycle

The whole protocol is a short, four-move exchange layered on ordinary HTTP. Using the current specification's header names (coinbase/x402, main):

1. Client requests a protected resource. A normal GET/POST, no payment attached.
2. Server responds 402 Payment Required with a PAYMENT-REQUIRED header — a Base64-encoded PaymentRequired object whose accepts array lists one or more PaymentRequirements the client may satisfy (price, network, asset, destination).
3. Client pays and retries. It picks one PaymentRequirements, builds and signs a PaymentPayload, and re-sends the same request with a PAYMENT-SIGNATURE header carrying that payload.
4. Server verifies, settles, and returns the resource. It checks the payload (itself or through a facilitator's /verify), settles on-chain (directly or via the facilitator's /settle), then returns 200 OK with the resource plus a PAYMENT-RESPONSE header describing the settled payment (an on-chain receipt).

The PaymentRequirements object is where a server declares its terms:

A note on header names. The main branch spec uses PAYMENT-REQUIRED, PAYMENT-SIGNATURE and PAYMENT-RESPONSE. Earlier Coinbase Developer Platform SDKs and many tutorials use an X-PAYMENT request header and put the accepts array in the body of the 402 response. The semantics are the same; the wire format has moved. Pin the version you build against and read its spec — this is a pre-1.0 protocol.

The exact scheme: gasless stablecoin transfer

x402 is scheme-pluggable, but the first and most-used scheme is exact — pay a precise amount. On EVM chains it is built on EIP-3009 transferWithAuthorization, and this is the clever part: the client never sends a transaction itself.

Instead the client signs an authorization — a message, not a transaction — with these fields:

The PaymentPayload sent in PAYMENT-SIGNATURE is essentially that signed authorization plus the signature. Because it's a signed message, the payer needs no gas and no prior on-chain action — the facilitator submits the transferWithAuthorization call to the token contract on the client's behalf and pays the network fee. For an agent, that removes the single ugliest part of "just pay for this API call": it doesn't have to hold the chain's native gas token or build and broadcast transactions. It signs; someone else settles.

Coinbase's reference implementation uses USDC as the settlement asset, and the spec's worked example targets Base. Other chains follow the same shape with their own signing primitives.

The facilitator: who touches the chain

A facilitator is an optional-but-usual service that sits between the resource server and the blockchain, exposing two endpoints:

• /verify — given a PaymentPayload and the PaymentRequirements, confirm the signature recovers to from, the balance is sufficient, the parameters match, and the transfer would succeed.
• /settle — actually submit the transfer on-chain and return the result.

The point of the facilitator is separation of concerns: a resource server can start charging for requests without running a node, holding gas, or writing any chain code — it just calls /verify and /settle. Coinbase operates the primary facilitator through its Developer Platform, but the role is defined by the open spec, so facilitators can be self-hosted or run by third parties. That openness is deliberate — the protocol is designed not to depend on any single company sitting in the money path.

Beyond EVM: Base, Solana and Stellar

x402 started on Base (EVM + USDC) but is now multi-chain, with official SDK families for each execution environment:

• @x402/evm — Base and other EVM chains.
• @x402/svm — Solana.
• @x402/stellar — Stellar.

The chain landscape shifted fast in 2026: by reported on-chain payment counts, Solana overtook Base as the busiest x402 network (per Cointelegraph and others), and Ripple, Monad and Stellar all sit inside the new foundation's membership. For a builder this means x402 is best treated as a cross-chain settlement standard, not a Base-only one — the network field in PaymentRequirements is doing real work.

Governance: from Coinbase to the x402 Foundation

x402 has been on a deliberate path from single-vendor project to neutral standard:

• September 23, 2025 — Coinbase and Cloudflare announce a foundation to steward the protocol.
• April 2026 — the intent to house it at the Linux Foundation is announced.
• July 14, 2026 — the x402 Foundation launches operationally under the Linux Foundation with 40 member organizations.

That founding roster is the real signal, because it spans every layer of the payments stack at once: Visa, Mastercard and American Express (card networks); Stripe, Adyen and Fiserv (processors); Google and AWS (cloud); Circle and Coinbase (stablecoins); and the Solana Foundation, Stellar Development Foundation and Ripple (chains), alongside Shopify, Monad, MoonPay and Cloudflare (Linux Foundation). Notably, the card networks and processors that a "crypto payment protocol" might be expected to threaten are inside the tent — a strong hint that x402 is consolidating into shared infrastructure rather than a walled garden. It's Apache-2.0 licensed and community-governed.

Adoption: where x402 actually is

The honest read as of mid-2026 is "real and growing fast, still early in absolute terms." Treat the figures below as reported by their sources, not as audited numbers:

• Coinbase reported roughly 69,000 active agents, ~165 million transactions and about $50 million in cumulative volume as of April 2026, around the launch of its Agent.market directory of x402-paywalled services.
• Solana logged record weeks in 2026 (daily x402 volume reported around the low hundreds of thousands of dollars at peak), overtaking Base in payment count.
• Ecosystem activity clustered around AI-infrastructure use cases — inference routing, scraping/data APIs (Apify, Exa) and similar — plus Cloudflare's Content Monetization Gateway, which lets sites charge AI crawlers per request via x402.
• x402scan and similar explorers track live x402 transactions and services if you want to watch the network rather than take anyone's word for it.

The through-line: the earliest real demand is machines paying machines for data and compute — exactly the workload human-shaped billing handles worst.

x402, AP2 and ACP: how the layers fit

The most common confusion in this space is treating these as competitors. They mostly aren't — they're different layers:

x402 answers how the money moves; it does not, by itself, answer was this agent allowed to spend this much. That's the authorization layer's job — and it's why the two are complementary. Google's a2a-x402 extension lets an AP2 mandate settle over x402, so the "who's allowed to pay what" (AP2) and the "actually move the USDC" (x402) slot together. A production agent stack will likely touch several of these at once. For the full map, see What is Agentic Commerce?.

Using x402 today

The developer experience is intentionally small:

• On the server, middleware wraps a route: unpaid requests get a 402 with your PaymentRequirements; paid ones pass through. SDKs exist for common web frameworks.
• On the client, a wrapper around fetch handles the 402 automatically — it reads the requirements, signs the payload, and retries — so calling a paid endpoint looks almost like calling a free one.
• Settlement goes through a facilitator, so neither side runs chain infrastructure.

Two caveats to state plainly. First, x402 is pre-1.0: the header-naming change above is a live example, and fields can still move — pin your version. Second, x402 is a settlement rail, not a control plane. It will faithfully execute every payment an agent signs, which is exactly the point — and exactly the risk.

What this means if your agents spend money

x402 makes it trivially easy for an agent to pay for things. That is its strength and its blind spot in the same breath. The protocol has no concept of a budget, an approval, an allow-list or an audit trail — it signs and settles whatever the agent decides to pay, per request, as fast as the agent can decide. Point an autonomous agent at a wallet and a set of x402 endpoints and there is nothing in the protocol standing between "the model chose to spend" and "the USDC is gone."

That missing layer — spend limits per agent and per day, human approval above a threshold, a kill switch, and an audit trail your finance team can reconcile across every provider and chain — is precisely what AgentLedger builds. It sits on top of rails like x402 (and mandate layers like AP2), governing the aggregate spend that no single protocol sees. You can watch the governance gate run on synthetic agents in the live demo.

For the wider protocol map and the latest moves, see What is Agentic Commerce? and our Agentic Commerce News roundup.

Frequently asked questions

What is x402 in simple terms?

x402 is a way for a website or API to charge for a single request and for the caller to pay instantly in stablecoins, using the HTTP 402 Payment Required status code. It's designed so software — including AI agents — can pay for things with no account, subscription, or human clicking "buy."

Is x402 free and open source?

Yes. The specification and reference implementations are open source under the Apache-2.0 license, and the protocol is governed by the neutral x402 Foundation under the Linux Foundation rather than by a single company.

What's the difference between x402 and AP2?

Different layers. x402 is settlement — actually moving money over HTTP 402, typically in USDC. AP2 is authorization — proving, with a signed mandate, that an agent is allowed to make a payment. They work together: Google's a2a-x402 extension lets an AP2 mandate settle over x402.

Which blockchains does x402 support?

It began on Base (EVM, USDC) and is now multi-chain, with SDKs for EVM (@x402/evm), Solana (@x402/svm) and Stellar (@x402/stellar). In 2026 Solana overtook Base by reported payment count. The network field in each payment requirement selects the chain.

Do I need to hold crypto or gas to use x402?

The payer needs the stablecoin being spent (e.g. USDC), but on the exact scheme they do not need the chain's native gas token: the client signs an EIP-3009 authorization and the facilitator submits the transfer and pays the network fee.

Is x402 production-ready?

It's live, open source, backed by 40 organizations including Visa, Mastercard, Stripe and Coinbase, and settling real volume — but it's pre-1.0, so the spec still changes. Build against it now; pin your version and expect churn.