What is x402?

HTTP defines a 402 Payment Required status code, but RFC 9110 still lists it as reserved for future use, with no standard semantics. x402 supplies them: the server answers 402 with machine-readable payment terms, the client pays by signing an authorization and retries, and the server returns the resource once the payment is verified and settled. The x402 V2 core specification defines the data types and the facilitator API; the V2 HTTP transport defines how they travel in headers.

Because the terms are structured data rather than a checkout page, software can read and act on them. That is what makes x402 a fit for agentic payments, where an AI agent pays per request for an API, a dataset or a tool, with no human filling in a form.

The three roles

The specification names three components. A single company can play more than one role, for example a resource server that hosts its own facilitator endpoints.

The handshake, step by step

The default payment flow in V2 is called authorization: the payment is verified before the resource runs and settled after it succeeds. The numbers in the diagram match the list below.

1. Request. The client calls the resource without any payment header.
2. Payment required. The server answers 402 and puts a Base64-encoded PaymentRequired object in the PAYMENT-REQUIRED header. It holds x402Version, a resource object describing what is sold, and an accepts array of payment options.
3. Choose and sign. The client picks one entry of accepts (a scheme, network, asset, amount and recipient) and builds the scheme-specific payload. For the exact scheme on EVM chains this is usually an EIP-3009 authorization signed with EIP-712.
4. Retry with payment. The client repeats the request with a Base64-encoded PaymentPayload in the PAYMENT-SIGNATURE header. The payload echoes the chosen option in its accepted field.
5. Verify. The resource server sends the payload and the payment requirements to the facilitator's POST /verify. Verification is read-only: it must not commit payment state.
6. Verification result. The facilitator answers with a VerifyResponse: isValid, and an invalidReason when it is false (one of the x402 error codes).
7. Execute. Only after a successful verification does the server run the protected handler.
8. Settle. The server calls POST /settle with a request of the same structure as the /verify call.
9. Broadcast. The facilitator commits the payment, typically by submitting a transaction to the network.
10. Settlement result. The facilitator returns a SettleResponse with success, the transaction hash and the network.
11. Deliver. The server returns the resource with a Base64-encoded settlement response in the PAYMENT-RESPONSE header.

The exact header encodings, every field and decoded examples are on the x402 V2 headers page.

Payment flows: when the money moves

V2 separates how value moves (the asset transfer method) from when it moves relative to the handler (the payment flow). A payment option declares its flow in extra.paymentFlow; omitting it means the mechanism's default.

Whatever the flow, the core specification sets one invariant: at least one check, a verify or a settle, must run before the resource executes. Clients must not build a payment for a flow they do not recognize. What the facilitator does at each step, and how it fails, is covered in x402 facilitator security.

Schemes, networks and assets

Each entry in accepts combines a scheme, a network and an asset:

• Scheme is the payment logic. exact transfers a specific amount known in advance, for example to read an article or call a tool once. The specification repository also defines upto, batch-settlement and auth-capture under specs/schemes, each with per-network bindings.
• Network is a CAIP-2 chain identifier, namespace:reference. In V2, eip155:8453 is Base mainnet, eip155:84532 is Base Sepolia and solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp is Solana mainnet.
• Asset is the token contract address (or an ISO 4217 code for fiat rails), and amount is an integer string in the asset's atomic units. For a token with 6 decimals, such as USDC, "10000" means 0.01.

Each option also names the recipient (payTo), the maximum time allowed for payment completion (maxTimeoutSeconds) and scheme-specific data in extra. For EIP-3009 tokens, extra.name and extra.version carry the token's EIP-712 domain name and version, which the client needs to sign.

x402 V2 compared with V1

V2 carries every protocol message in headers, including the payment terms that V1 sent in the response body. It also adopted CAIP-2 network identifiers and separated the resource description from the payment options. The official @x402/core schemas still parse both versions, keyed on x402Version, but the wire formats differ. The table summarizes them from the V1 and V2 HTTP transport specifications.

The V1 to V2 migration guide lists the other differences, such as the facilitator's /supported response and the error codes, with the steps for servers, clients and facilitators.

Where x402 implementations go wrong

Most defects fall into a few families. Each one maps to concrete items in the x402 security checklist.

• The challenge is not machine-readable. No 402, terms only in the body (the V1 habit), a header that is not valid Base64 JSON, or an object the official SDK rejects. Agents then cannot pay, or each client interprets the terms differently.
• The terms are not bound to the request. A resource.url that differs from the requested URL, a redirect, or terms served over plaintext HTTP where a network attacker can rewrite payTo or amount before the client signs.
• The options are malformed or ambiguous. Decimal amounts, network names instead of CAIP-2, a payTo that is not an address on the advertised chain, duplicate entries, very long maxTimeoutSeconds.
• The terms drift. Price or recipient changes between identical requests, which can be intentional dynamic pricing or a sign of tampering.
• The resource fails open. The handler runs, or content is returned, for a payment that was never verified. An invalid signature then unlocks the resource for free.
• The facilitator accepts what it should reject. A /verify that reports a forged signature as valid, or a facilitator that does not support the scheme and network the server advertises. See x402 facilitator security.
• The agent pays without limits. No allowlist of recipients, tokens and networks, and no amount cap, so the agent signs whatever the server asks. See the agent spending policy guide.

For a longer treatment with examples, read x402 security failure modes.

How to test an x402 endpoint

Settlens checks these behaviors without paying. A passive scan requests the resource without any payment header, decodes PAYMENT-REQUIRED, validates it with the official @x402/core SDK and Settlens' own rules, checks the binding to the requested URL and repeats the request to detect drift. Against the bundled demo target:

$ settlens scan http://127.0.0.1:4402/secure --no-write
Settlens x402 assessment e78d70a9
Targets 1 · Active 0 · Settlement calls 0
 
127.0.0.1  GET http://127.0.0.1:4402/secure
13 pass · 0 fail · 0 warn · 0 skip
 
Total: 13 pass · 0 fail · 0 warn · 0 skip

An active probe goes one step further, but only with the owner's written approval: it retries once with an intentionally invalid PAYMENT-SIGNATURE and expects the resource to refuse it. The demo's /bypass route is built to unlock anyway, and the probe reports it:

$ settlens scan http://127.0.0.1:4402/bypass \
    --active --authorized --authorization-ref DEMO-APPROVAL-002 --no-write
Settlens x402 assessment 54ae4bc7
Targets 1 · Active 1 · Settlement calls 0
 
127.0.0.1  GET http://127.0.0.1:4402/bypass
13 pass · 1 fail · 1 warn · 0 skip
  FAIL critical Invalid payment authorization is denied
       The endpoint returned HTTP 200 after an invalid payment authorization.
  WARN medium   Invalid payment uses a standard failure status
       Expected HTTP 400 or 402 for invalid payment, received HTTP 200.
 
Total: 13 pass · 1 fail · 1 warn · 0 skip

Captured payment authorizations can also be checked offline with verify-payment, explained on the EIP-3009 page. Agents can run the same pre-payment checks through the Settlens MCP server before they sign anything. The quickstart covers installation for pilot participants, and Assess describes the scan in detail.

Frequently asked questions