What is x402?
x402 is an open payment protocol that lets a server answer an HTTP request with 402 Payment Required and a price, so a client can pay in a stablecoin and retry. As of November 17, 2026, the current specification is protocol version 2.
What x402 is
x402 defines how a server requests payment, how a client submits a signed payment payload, and how the server verifies and settles it. The protocol supports USDC on Base and Solana.
Coinbase created x402 and published its whitepaper on May 6, 2025. The repository uses Apache-2.0, and you need no Coinbase product to use the protocol.
The canonical specification lives in the x402 Foundation repository. It separates the payment objects from transport bindings, payment schemes and extensions, so HTTP is one transport for x402 payments.
How an x402 payment works
An x402 payment starts with a client requesting a paid resource. The server answers with HTTP 402 and a PAYMENT-REQUIRED header containing a Base64-encoded JSON PaymentRequired object.
That object contains x402Version, resource and accepts, with optional error and extensions fields. x402Version must be 2, and accepts lists the payment options the server accepts.
Each option carries scheme, network, amount, asset, payTo and maxTimeoutSeconds, plus optional extra data. amount is expressed in atomic units, network uses a CAIP-2 identifier, and payTo identifies the recipient.
The client chooses an option and creates the scheme-specific signed payment. It constructs a PaymentPayload containing x402Version, the chosen requirements in accepted, and the scheme-specific payload, with optional resource and extensions.
The client retries the request with that object encoded as Base64 JSON in PAYMENT-SIGNATURE. The resource server verifies the payment itself or submits it to a facilitator.
In the default authorization flow, verification precedes resource execution, and settlement follows it. The server returns settlement information in PAYMENT-RESPONSE, also Base64-encoded JSON, alongside the resource response.
The settlement response records success, payer, transaction, network and amount, with error and extension fields. Its transaction hash is empty if nothing was broadcast.
The v2 specification defines authorization as the default flow. The upfront flow settles payment before resource execution. The escrow flow settles payment, executes the resource, then settles again.
GET /api/report HTTP/1.1
Host: api.example.com
HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6Mi... # base64 JSON: PaymentRequired
GET /api/report HTTP/1.1
Host: api.example.com
PAYMENT-SIGNATURE: eyJ4NDAyVmVyc2lvbiI6Mi... # base64 JSON: PaymentPayload
HTTP/1.1 200 OK
PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLC... # base64 JSON: SettlementResponse
The v2 exchange over HTTP. Header values are base64-encoded JSON objects defined in the x402 v2 specification.
{
"x402Version": 2,
"resource": {
"url": "https://api.example.com/api/report",
"description": "Daily market report",
"mimeType": "application/json"
},
"accepts": [
{
"scheme": "exact",
"network": "eip155:8453",
"amount": "10000",
"asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"payTo": "0xSellerWallet...",
"maxTimeoutSeconds": 60
}
]
}
A decoded PAYMENT-REQUIRED value: one option, 0.01 USDC (10,000 atomic units, 6 decimals) on Base (CAIP-2 eip155:8453), paid to the seller's wallet.
What changed in x402 v2
x402 v2 moved payment requirements into the PAYMENT-REQUIRED response header. Tutorials that put the canonical requirements in the HTTP response body describe the v1 transport.
PAYMENT-SIGNATURE replaced X-PAYMENT, and PAYMENT-RESPONSE replaced X-PAYMENT-RESPONSE. All the v2 payment headers carry Base64-encoded JSON.
Network names became CAIP-2 identifiers, so v1's base-sepolia becomes eip155:84532. The requirements field amount replaced maxAmountRequired, whose value was already an exact amount under the v1 exact scheme.
Resource metadata moved into a separate ResourceInfo object. Its fields include url, description, mimeType, serviceName, tags and iconUrl.
V2 also formalized extensions and added multi-facilitator support and a modular SDK. The December 11, 2025 announcement states that the reference SDKs remain backward-compatible with v1.
The TypeScript HTTP client reads PAYMENT-REQUIRED for v2 and falls back to a v1 JSON body.
| Part | x402 v1 | x402 v2 (current) |
|---|---|---|
| Payment requirements | JSON body of the 402 | PAYMENT-REQUIRED header |
| Client payment | X-PAYMENT | PAYMENT-SIGNATURE |
| Settlement result | X-PAYMENT-RESPONSE | PAYMENT-RESPONSE |
| Price field | maxAmountRequired | amount |
| Network id | base-sepolia | eip155:84532 (CAIP-2) |
| Resource details | inside each requirement | resource object (ResourceInfo) |
| Packages | x402, x402-express, x402-axios | @x402/core, @x402/express, @x402/axios, @x402/evm |
Facilitators verify and settle signed payments
An x402 facilitator provides payment verification and settlement APIs for resource servers. It is optional, and a server can verify and settle payments itself.
POST /verify checks the submitted paymentPayload against paymentRequirements without executing payment. It must remain read-only and returns isValid, invalidReason and payer.
POST /settle accepts the same request structure and durably commits payment, typically by broadcasting a transaction. GET /supported reports supported protocol versions, schemes and networks, along with extensions and signer addresses.
A facilitator does not hold funds or act as a custodian. Buyer signatures constrain settlement, and an EVM exact facilitator cannot change the signed amount or destination.
Published facilitator terms as of November 17, 2026 differ. CDP includes 1,000 onchain settlements per month free, then charges $0.001 per additional settlement, while verification is always free.
CDP requires an API key and screens payer and recipient against OFAC sanctions lists and KYT risk signals at verification and settlement. Failed settlements, including compliance declines, are not billed.
CDP supports exact, upto and batch-settlement on Base, Base Sepolia, Polygon, Arbitrum, Monad, World and World Sepolia. Its Solana and Solana Devnet support covers exact and upto. Its REST settlement and verification endpoints are POST /v2/x402/settle and POST /v2/x402/verify.
PayAI lists $0.00156 per Base exact EIP-3009 settlement and $0.00093 per Solana exact settlement. It offers 1,000 introductory credits and requires no API key to start.
PayAI prices credits at $1 for 1,000 credits after the introductory allowance. Its payment charges follow network-specific rates and never take a percentage of the payment amount.
Dexter charges no facilitator fee, and Mogami advertises no fees or API key. The public x402.org facilitator supports testnets only and cannot settle Base mainnet payments.
The official facilitator directory lists 20 entries as “selected production options” and says it “is not an exhaustive catalog.” Mogami publishes a Docker image for self-hosting, with source under AGPL-3.0. The Fireblocks facilitator is open source under Apache-2.0, settles from a Fireblocks vault, requires a Fireblocks workspace API key and is testnet-only unless X402_ALLOW_MAINNET=true. x402-rs offers a self-hostable Docker image, and its hosted /supported endpoint listed only test networks when read on November 17, 2026.
Who pays gas and how the signature moves money
For EVM exact payments, the facilitator broadcasts the transaction and pays gas. With EIP-3009, the payer supplies a signed authorization rather than broadcasting a payment transaction.
The client signs EIP-712 data containing an EIP-3009 authorization with from, to, value, validAfter, validBefore and nonce. The authorization uses a random 32-byte nonce against replay and a validity window that constrains when it can execute.
Settlement calls transferWithAuthorization on the token contract. The signature fixes the authorized transfer, while the facilitator acts as the transaction broadcaster.
EVM exact also supports Permit2 as a fallback for ERC-20 tokens and ERC-7710 for smart-account delegation. Permit2 requires a one-time onchain approval and uses x402ExactPermit2Proxy as spender.
The EIP-2612 Gas Sponsoring and ERC-20 Approval Gas Sponsoring extensions can sponsor that approval step. CDP's published exception sponsors the Permit2 approval only for EIP-2612 tokens.
On Solana, the client partially signs a transfer transaction. The merchant or facilitator then signs as feePayer and pays the transaction fees.
An executed exact payment is irreversible. A seller refunds it by making a new transfer back to the payer.
Payment schemes define the amount and settlement lifecycle
exact fits a resource whose price is known before access. Settlement must transfer precisely that amount, with neither overpayment nor underpayment.
upto fits metered consumption, including LLM token usage. The client authorizes a maximum, and settlement sets the actual charge from consumption.
batch-settlement fits requests whose value moves later in batches. The client signs a commitment for each request and receives access immediately, while the EVM binding uses an escrow deposit and offchain vouchers.
auth-capture fits refundable payments or amounts unknown at authorization. Its lifecycle includes authorize, charge, capture, void, refund and reclaim.
The scheme specifications define these distinct payment mechanisms. A batch-settlement binding also exists for cloudflare:402, using credit-backed payments authenticated with HTTP Message Signatures.
A scheme's presence in the repository does not establish support at every facilitator. The facilitator's /supported response identifies its supported combinations.
| Scheme | What it charges | Fits |
|---|---|---|
exact | A fixed amount known before the request | Paid pages, API calls with a set price |
upto | Up to a signed maximum, settled on actual use | LLM tokens, metered compute |
batch-settlement | Signed commitments per request, settled later in batches | High-frequency calls, crawling |
auth-capture | Authorize a maximum, then capture, void or refund | Refundable purchases, unknown final amounts |
Networks and tokens extend beyond Base and USDC
x402 v2 identifies each network with a CAIP-2 identifier. Base uses eip155:8453, Base Sepolia uses eip155:84532, Polygon uses eip155:137, and Avalanche uses eip155:43114.
Solana mainnet uses solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp. Solana devnet uses solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1, and Avalanche Fuji uses eip155:43113.
USDC is the default asset for dollar-denominated price strings in the reference SDK configuration. On Base, its default token address is 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.
The protocol covers ERC-20 tokens on EVM and SPL or Token-2022 tokens on Solana. Its documented ecosystems also include TON, Algorand, Stellar, Aptos, Hedera, Keeta, NEAR, Concordium, XRPL, Cardano, Sui and Canton.
Production settlement through a facilitator requires support for the selected network and scheme. Facilitators support networks rather than specific tokens, according to the network and token documentation, and a server may instead settle itself.
The public testnet facilitator also supports Stellar testnet, Aptos testnet, Hedera testnet and XRPL testnet alongside Base Sepolia and Solana Devnet.
| Network | CAIP-2 id | Default USDC |
|---|---|---|
| Base | eip155:8453 | 0x8335…2913 |
| Base Sepolia | eip155:84532 | 0x036C…CF7e |
| Polygon | eip155:137 | 0x3c49…3359 |
| Avalanche | eip155:43114 | per facilitator |
| Solana | solana:5eykt4Us… | EPjFWdd5…Dt1v |
TypeScript, Python and Go SDKs and HTTP, MCP and A2A transports
TypeScript, Python and Go are the x402 reference implementations. Their server and client integrations cover accepting payment and retrying requests with payment.
TypeScript uses @x402/core, with chain packages including @x402/evm and @x402/svm. Server integrations include @x402/express, @x402/hono, @x402/next and @x402/fastify, while clients use @x402/fetch or @x402/axios.
Python installs with pip install x402 and integrates with FastAPI and Flask on the server, plus httpx and requests on the client. Go installs with go get github.com/x402-foundation/x402/go/v2 and supports Gin, net/http and Echo, with net/http clients.
The v1 migration guide maps older packages such as x402-express to their scoped v2 replacements. The repository's Java implementation still sets x402Version to 1.
x402 also defines MCP and A2A transports. Over MCP, a paid tool returns isError: true with payment requirements, the client retries using _meta['x402/payment'], and settlement information returns in _meta['x402/payment-response'].
Bazaar discovery provides GET /discovery/resources and GET /discovery/search. Its extension lets facilitators catalog paid endpoints and MCP tools.
Resource discovery accepts filters for type, payTo, scheme, network and extensions, with a result limit of 1 to 100.
The Sign-In-With-X extension uses CAIP-122 wallet authentication to identify returning payers and let servers skip payment. The facilitator has no role in that authentication.
Other official extensions include Payment Identifier for idempotency, Signed Offers & Receipts, and Builder Code using ERC-8021. TypeScript provides @x402/extensions, @x402/mcp and @x402/paywall.
The x402 Foundation governs the protocol
The x402 Foundation is the protocol's governing body under the Linux Foundation.
Cloudflare and Coinbase announced their intent to create the foundation on September 23, 2025. The Linux Foundation announced its launch on April 2, 2026, describing the governing body as initially developed by Coinbase, Cloudflare and Stripe.
On July 14, 2026, the Linux Foundation announced the operational launch and Coinbase's completed protocol contribution. On October 1, 2026, it appointed Michael Hursta as executive director.
The Technical Steering Committee lists Coinbase representative Erik Reppel, Cloudflare representative Rohin Lohe and Stripe representative Steve Kaliski. The technical charter places the project within LF Projects, LLC.
The canonical GitHub repository is now x402-foundation/x402. The former coinbase/x402 repository states that issues and pull requests moved and that it is now a development fork.
The charter uses Apache-2.0 for code and Creative Commons Attribution 4.0 for documentation. LF Projects holds title to the project's trademarks.
| Date | Event |
|---|---|
| May 6, 2025 | Coinbase publishes the x402 whitepaper |
| Sep 23, 2025 | Cloudflare and Coinbase announce the intent to form the x402 Foundation |
| Dec 11, 2025 | x402 v2 announced (spec v2.0 dated December 9) |
| Mar 31, 2026 | Technical charter adopted: x402, a Series of LF Projects, LLC |
| Apr 2, 2026 | The Linux Foundation announces the x402 Foundation |
| Jul 14, 2026 | Operational launch, 40 member organizations |
| Oct 1, 2026 | Executive director appointed, more than 50 members |
x402 gives HTTP 402 a payment protocol
HTTP 402 Payment Required first appeared in RFC 2068 in January 1997, reserved for future use. RFC 9110 still describes the status code as reserved.
x402 supplies payment objects, headers, verification and settlement rules around that status code.
How Xenarch uses x402
Xenarch uses x402 for paid access through WordPress, Joomla, a Cloudflare Worker and Python FastAPI integrations. Hosted payment links run at pay.xenarch.com, and the @xenarch/agent-mcp server exposes xenarch_pay_link to pay by link id using an envelope retrieved from the API.
Xenarch's shipped payment flow uses a v1 response body containing x402Version and accepts, and seller integrations accept X-PAYMENT. Shipped code does not send or read the v2 PAYMENT-REQUIRED or PAYMENT-SIGNATURE headers.
Xenarch supports USDC on Base, sets payTo to the seller's wallet, and forwards signed authorizations to a third-party facilitator that broadcasts and pays gas. Xenarch never holds funds or broadcasts transactions itself, and it rechecks the returned transaction hash onchain before booking payment. Xenarch charges a 0% fee.
Questions
No. x402 is an open payment protocol that uses existing tokens, including any ERC-20 through EIP-3009 or Permit2 on EVM and any SPL token on Solana. The reference SDKs default to USDC for '$' price strings, including on Base (eip155:8453).
Coinbase created x402. Its whitepaper is dated May 6, 2025, and the protocol is now governed by the x402 Foundation.
Yes, the protocol is free under Apache-2.0. For EVM exact, the facilitator or self-settling server broadcasts and pays gas, while on Solana the merchant or facilitator signs as feePayer and pays transaction fees. As of November 17, 2026, CDP includes 1,000 settlements per month free, then charges $0.001 per additional settlement.
No. x402 supports multiple networks and tokens, including ERC-20 tokens on EVM and SPL tokens on Solana. Your chosen facilitator must support the network and scheme.
An x402 facilitator verifies signed payment payloads and settles payments for resource servers. It does not take custody of funds, and servers can perform those operations themselves.
V2 introduced PAYMENT-* headers, CAIP-2 network identifiers, restructured payment objects, extensions and multi-facilitator support. Requirements moved into PAYMENT-REQUIRED, and amount replaced maxAmountRequired.
Yes, a seller can refund an exact payment through a new transfer back to the payer. The original transfer is irreversible. The separate auth-capture scheme defines a refund lifecycle.
Pay or charge over x402 with Xenarch
Give an AI agent a USDC wallet that pays x402 endpoints, or answer your own crawlers and API callers with 402.
npx @xenarch/agent-mcp
AgentsGating