x402 Protocol: How the HTTP 402 Payment Flow Works for AI Agents

Account creation, KYC, prepaid credits, and API key rotation are human-oriented steps, and x402.org argues they do not fit how software pays for services. The x402 protocol is an open payment standard designed to remove that friction by making payments a native part of HTTP. By the end of this guide, you will know which headers move during an x402 payment, what each actor does, how the three payment schemes differ, and where to start on base-sepolia using the protocol’s documentation. This article is based on vendor and protocol documentation; it does not report hands-on testing.

What x402 Is, and Where It Came From

x402 is an open payment standard built around the HTTP 402 Payment Required status code. It allows clients to programmatically pay for APIs and content without accounts, sessions, or credential management. On the seller side, x402.org states that one line of middleware requires payment for each incoming request. The example configures an accepts array for supported networks and schemes, plus a description per endpoint. If an unpaid request arrives, the server responds with HTTP 402, prompting the client to pay and retry.

The GitHub spec README shows the same middleware pattern and frames x402 as an open standard intended to support many networks and forms of value. Provenance is documented across the sources: the x402 whitepaper (May 6, 2025, Coinbase Developer Platform) presents x402 as a Coinbase Developer Platform project; docs.x402.org describes it as a completely open standard under the Apache-2.0 license; and x402.org links to the x402 Foundation announcement under the Linux Foundation’s LF Projects. The coinbase/x402 repository notes that the canonical repo moved to x402-foundation/x402 and that coinbase/x402 is now a development fork.

The coinbase/x402 repository page fetched for this guide showed 182 stars, 298 forks, and 725 commits. Those are point-in-time counts for the development fork, not an adoption measurement.

As vendor positioning, x402.org lists “Zero protocol fees” and states that x402 is free for the customer and the merchant, with only nominal payment network fees. That is a vendor claim, not an independently verified measurement.

Why Agents Can’t Use the Old Payment Rails

The x402 homepage contrasts the old payment path with x402 in concrete steps. The old way requires: creating an account with an API provider, adding a payment method with KYC, buying prepaid credits or a subscription, managing and rotating API keys, and dealing with slower payments, chargebacks, and fees. With x402, the flow becomes: send an HTTP request, receive 402: Payment Required, pay with stablecoins, and receive access with no API keys.

The whitepaper adds the motivation behind that simplification. It argues that legacy rails are built for humans: settlement and chargeback windows are slow relative to per-call access by agents. x402.org and the whitepaper also frame stablecoins as the primary payment medium for this onchain-first design.

According to docs.x402.org, x402 is for both sellers and buyers. Sellers monetize APIs or content; buyers can be human developers or AI agents. The documented use cases include per-request APIs, agents that autonomously pay for API access, paywalls for digital content, microtransaction-monetized tooling, and proxy or reseller services that aggregate and resell API capabilities.

On the Wire: The Three Headers That Make x402 Work

The current wire format is easiest to understand by following the headers.

PAYMENT-REQUIRED (server → client): When a client requests a paid resource without payment, the server answers with 402 Payment Required and a PAYMENT-REQUIRED header. Per Cloudflare’s x402 docs, this header contains a Base64-encoded PaymentRequired object with price, accepted token, network, and merchant address. The spec README describes the same header carrying the PaymentRequired object as Base64.
PAYMENT-SIGNATURE (client → server): The client selects one of the returned PaymentRequirements, builds a PaymentPayload for that scheme and network, signs it, and retries the request with a PAYMENT-SIGNATURE header (Cloudflare, x402 spec).
PAYMENT-RESPONSE (server → client): After verification and settlement, the server returns the resource with a PAYMENT-RESPONSE header containing the settlement confirmation as Base64 JSON (Cloudflare, x402 spec).

If verification fails, the spec README states that the resource server returns another 402 Payment Required with a Payment Required Response JSON body. The spec also notes two design choices: x402 is transport-native and should avoid extra requests outside a typical client/server flow, and the initial unpaid request is optional if the client already knows the accepted payment terms.

Source drift note: The whitepaper (May 6, 2025) describes structured JSON payment fields in its examples. The current spec and Cloudflare’s docs (updated Oct 22, 2026) describe PAYMENT-REQUIRED and PAYMENT-RESPONSE as Base64-encoded headers, with the client’s signed payload sent in PAYMENT-SIGNATURE. This guide treats the header-based flow as current and uses the whitepaper for payload anatomy and rationale.

The Full Payment Flow, Step by Step

The x402 spec README documents a typical 12-step flow. The ordering matters because it affects how a server trades response speed for payment guarantee.

The client makes an HTTP request to a resource server. This step is optional if the client already knows the payment details.
The resource server responds with 402 Payment Required and a Base64 PaymentRequired object in the PAYMENT-REQUIRED header.
The client selects one PaymentRequirements entry and creates a signed PaymentPayload for the chosen scheme and network.
The client retries the request with the PAYMENT-SIGNATURE header.
The resource server verifies the payload locally or POSTs the payload and requirements to a facilitator’s /verify endpoint.
The facilitator verifies the payload according to its scheme and network and returns a Verification Response (spec README).
If verification is valid, the resource server performs the work to fulfill the request. If invalid, it returns 402 Payment Required again.
The resource server settles the payment directly on-chain or POSTs the payload and requirements to the facilitator’s /settle endpoint.
The facilitator submits the payment on-chain according to the payload’s scheme and network (spec README).
The facilitator waits for on-chain confirmation.
The facilitator returns a Payment Execution Response to the resource server.
The resource server returns 200 OK with the requested resource and a Base64 PAYMENT-RESPONSE header containing the settlement response.

In the documented ordering, the server performs the work after verification (step 7) and before settlement (step 8), and returns the 200 OK with PAYMENT-RESPONSE after the facilitator confirms settlement (steps 9 to 12). The spec lists “ability to trade off speed of response for guarantee of payment” as a technical goal, which is why the work-then-settle ordering is a design decision teams should make on purpose.

Client, Resource Server, Facilitator: Who Does What

The spec README defines the core terms: resource, client, facilitator, and resource server. Cloudflare’s docs describe how those roles behave in practice.

Role	Responsibilities	Holds funds?	Key detail
Client (human app or AI agent)	Requests resource, selects `PaymentRequirements`, signs `PaymentPayload`, retries with `PAYMENT-SIGNATURE`	Owns the wallet/signing key	Needs only a crypto wallet; no accounts, credentials, or session tokens
Resource server	Defines requirements in the 402, verifies payload locally or via facilitator, performs work, settles, serves resource with `PAYMENT-RESPONSE`	Receives the payment	Can verify and settle independently of any facilitator
Facilitator (optional)	`POST /verify` validates before fulfillment; `POST /settle` broadcasts the pre-signed transaction and waits for on-chain confirmation	No; verifies and broadcasts only	Cloudflare notes `https://x402.org/facilitator` is operated by Coinbase and that multiple facilitators exist

The facilitator is non-custodial: it verifies and broadcasts the client’s pre-signed transaction on the server’s behalf. The server can also verify and settle independently, as the docs.x402.org introduction describes.

For production, the spec README advises an explicit choice: use a production facilitator provider that supports your target network, run your own facilitator, or self-facilitate inside the resource server. It also states that the public x402.org facilitator should not be assumed as the default production path for mainnet EVM routes. The spec’s trust-minimizing principle requires that schemes never allow the facilitator or resource server to move funds except in accordance with client intentions.

Inside the 402 Payload

The whitepaper provides useful payload anatomy, though its examples predate the current header-based wire format. It describes fields such as maxAmountRequired, resource, description, payTo, asset, and network, and it also lists a second set of payment-request fields in its pre-header format, including assetType (for example, ERC20), assetAddress, paymentAddress, network (for example, base-mainnet), expiresAt, nonce for replay protection, and paymentId. The two field sets name the same concepts differently (payTo and asset against paymentAddress and assetAddress), so check the current spec before relying on either.

For authorization, the whitepaper describes a signed message containing the request fields, the actual amount (which must be less than or equal to maxAmountRequired), a timestamp, and the wallet’s cryptographic signature. It states that signing follows EIP-712. Servers can advertise multiple payment options: x402.org and the spec README show an accepts array that can list multiple supported networks and schemes, allowing the client to choose one.

Payment Schemes Compared

A scheme is “a logical way of moving money,” and the spec README emphasizes that each scheme’s implementation differs per chain. Clients and facilitators must explicitly support each (scheme, network) pair.

Scheme	How the payment works	Networks	Best fit
`exact`	Transfers a fixed token amount, typically ERC-20 USDC on EVM, to the merchant address (for example, pay a fixed price to read an article)	EVM, Solana, Aptos, Stellar, Hedera, Sui, Algorand (Cloudflare)	Flat per-request pricing
`upto`	Authorizes a maximum amount; the actual charge is determined at settlement based on resource consumption, up to the cap	EVM (Cloudflare)	Usage-based calls priced after the work runs
`batch-settlement`	Uses escrow plus off-chain vouchers; sellers redeem many small charges on-chain in batches instead of settling every HTTP request separately	EVM (docs.x402.org)	High-volume micropayments

In practice, exact fits simple per-call pricing, upto fits workloads where the final cost is known only after execution, and batch-settlement targets high-volume EVM micropayments. Cloudflare’s scheme table lists a broad set of networks for exact and EVM only for upto; it does not cover batch-settlement, which the docs.x402.org introduction describes as EVM and the spec README describes as escrow plus off-chain vouchers.

Reproduce the Flow on Testnet

The steps below follow the documented flow. They are a reading of the spec and Cloudflare’s overview, not a record of tests the author ran. The quickstart for sellers and quickstart for buyers contain the runnable code and were not reviewed line by line for this guide.

For testnet development, the spec README says the public x402 facilitator is the easiest starting point. Cloudflare documents base-sepolia with free test USDC from the Circle Faucet.

Install the current packages. The README’s minimal commands are:

TypeScript client: npm install @x402/core @x402/evm @x402/svm @x402/fetch
TypeScript server: npm install @x402/core @x402/evm @x402/svm @x402/express
Python: pip install x402
Go: go get github.com/x402-foundation/x402/go/v2
Cloudflare Worker option: x402-hono (from Cloudflare’s docs)

On the server, the route is configured with paymentMiddleware and an accepts array plus a description, as shown on x402.org and in the spec README:

app.use(paymentMiddleware({
  "GET /weather": {
    accepts: [...],        // Supported networks / schemes
    description: "Weather data",
  },
}));

The request sequence below is reconstructed from the README’s typical flow and Cloudflare’s overview:

Fund a test wallet on base-sepolia using test USDC from the Circle Faucet.
Send GET /resource to the protected endpoint.
Receive 402 Payment Required and decode the Base64 PAYMENT-REQUIRED header to inspect price, token, network, and merchant address.
Select a matching requirement, sign a PaymentPayload, and retry with PAYMENT-SIGNATURE.
The server verifies locally or calls the facilitator’s /verify endpoint.
After valid verification, the server performs the requested work.
The server settles directly or calls the facilitator’s /settle endpoint, and the facilitator waits for on-chain confirmation.
Receive 200 OK with the resource body and a Base64 PAYMENT-RESPONSE settlement confirmation.

The whitepaper also describes a local development toolkit with preloaded test wallets, mock servers, scenario simulation, and logging; that is a vendor-described resource this guide did not evaluate.

Wiring x402 Into an Agent

For agent builders, the integration surface is not limited to plain HTTP APIs. Cloudflare’s x402 docs describe several patterns: charge for HTTP content behind a Worker proxy, charge per MCP tool call with paidTool, and pay from the Agents SDK by wrapping MCP clients with withX402Client. Cloudflare also lists coding-tool options, including an OpenCode plugin and a Claude Code hook.

On the client side, @x402/fetch is documented as a fetch wrapper with automatic payment handling, which aligns with the spec README’s goal of minimal client integration. The broader use-case menu from docs.x402.org includes per-request APIs, agents paying autonomously for API access, paywalled content, microtransaction tooling, and proxy services that aggregate or resell APIs. The whitepaper gives illustrative examples such as pay-per-article, per-second streaming, and per-request market data; those are vendor examples, not measurements from this guide.

Trade-offs: What x402 Does Not Solve

x402 simplifies the payment handshake, but it does not eliminate engineering decisions.

Facilitator trust and operations: The facilitator is non-custodial, but a server still delegates verification honesty and transaction broadcast. For production, the spec README requires an explicit facilitator decision rather than assuming the public facilitator.
Work before settlement: In the documented flow, the server performs the work after verification (step 7) and settles afterward (step 8). The spec frames the speed-versus-guarantee choice as a design goal. Teams should decide deliberately whether a given endpoint can tolerate doing the work before on-chain confirmation.
Uneven scheme coverage: Cloudflare lists broad network support, including Base, Ethereum, Polygon, Optimism, Arbitrum, Avalanche, Solana, Aptos, Stellar, Sui, and Algorand, but its table documents upto on EVM only, and the docs describe batch-settlement as EVM. The spec README also requires explicit support for every (scheme, network) pair.
Agent wallet key custody: Cloudflare’s docs state that the client needs only a crypto wallet. That shifts a critical responsibility to the agent stack: the wallet’s signing key becomes the credential that must be protected.
Onchain-first design: x402.org states that stablecoins are the primary use case and that x402 is extensible. The spec README adds that x402 will never deprioritize onchain payments in favor of fiat.
Finality without refunds: The whitepaper highlights instant settlement and the absence of chargebacks. That also means there is no in-protocol refund mechanism; refund policy must be handled at the application layer.
Gas and RPC abstraction is partial: The spec README sets a goal that clients and servers should not need to think about gas or RPC details, but that is a design goal supported by facilitators and SDKs, not something the protocol removes from the underlying system.

FAQ

Is x402 production-ready?

x402.org states that x402 is production-ready and that it has processed millions of transactions; the same FAQ also claims the protocol is open-source and audited. Those are vendor claims and were not independently verified for this guide.

Which blockchains and tokens does x402 support?

x402.org states that x402 is blockchain-agnostic and supports all EVM-compatible chains, Solana, and more, with stablecoins as the primary use case. Cloudflare’s docs list supported networks including Base, Ethereum, Polygon, Optimism, Arbitrum, Avalanche, Solana, Aptos, Stellar, Sui, and Algorand.

Do I need a facilitator?

No. Cloudflare’s docs describe the facilitator as optional but recommended, and docs.x402.org notes that a server can verify and settle independently. For production, the spec README recommends choosing a production facilitator provider, running your own, or self-facilitating; the public facilitator is a testnet starting point.

Does the facilitator custody funds?

No. Cloudflare’s docs state that the facilitator does not hold funds; it verifies and broadcasts the client’s pre-signed transaction.

What’s the difference between `exact`, `upto`, and `batch-settlement`?

exact transfers a fixed amount, upto authorizes a maximum and settles the actual usage up to that cap, and batch-settlement uses escrow and off-chain vouchers so sellers can redeem many charges in batches. See the scheme specs and batch-settlement docs.

How can I test without spending real money?

Use base-sepolia with free test USDC from the Circle Faucet, as documented by Cloudflare. The spec README suggests the public facilitator for testnet, and the whitepaper describes a local development toolkit as a vendor resource.

Who maintains x402 — is it just Coinbase?

The whitepaper documents x402’s origin at Coinbase. x402.org links to the x402 Foundation announcement under the Linux Foundation’s LF Projects. The coinbase/x402 repository states that the repo moved to x402-foundation/x402 and that coinbase/x402 is now a development fork. docs.x402.org describes x402 as an open standard under the Apache-2.0 license.

Are there fees?

x402.org states that there are zero protocol fees and only nominal payment network fees. The whitepaper also discusses low onchain costs in its comparison table; treat any such figures as whitepaper claims tied to that document’s date.

The Bottom Line

In the author’s assessment, x402 is a clean fit for machine-to-machine, per-call payments: it is HTTP-native, avoids accounts and API keys, supports non-custodial facilitation, and already documents multiple chains and schemes. The engineering questions that matter before production are less about the happy path and more about the operating model: which facilitator you trust or run, how you secure agent wallet keys, where the work sits relative to settlement, and whether the EVM-only network coverage of upto and batch-settlement matches your workload. A practical next step is to prototype on base-sepolia with the quickstart for sellers and quickstart for buyers before committing to a production facilitator path.

How This Guide Was Built

This guide is based on vendor documentation and protocol sources: x402.org, docs.x402.org, the x402 Foundation repository (the canonical repo; the README text quoted in this guide was read from the coinbase/x402 development fork), the x402 whitepaper (May 6, 2025, Coinbase Developer Platform), and Cloudflare’s developer documentation. No hands-on testing was performed. The author did not run testnet transactions, and the request sequence is reconstructed from the documented flow, not captured output. Vendor-reported figures (including production readiness, transaction volume, audit status, and fees) are attributed to their sources and were not independently verified. Where sources differ (the 2025 whitepaper versus the current spec and docs), the newer spec and docs were preferred for the current wire format.

NoCode Insider — AI workflow automation with no-code tools, agents, and APIs
ToolBrain — tool reviews, LLM comparisons, and AI workflow guides

Cross-links automatically generated from NiteAgent.

← Back to all posts