--- title: "What is x402? HTTP 402 payments explained | Settlens" description: "x402 turns HTTP 402 into a machine-readable payment handshake. Learn the roles, the V2 flow step by step, schemes, CAIP-2 networks and common failure modes." url: https://settlens.com/learn/what-is-x402 last_updated: 2026-10-13 published: 2026-10-13 --- # What is x402? > **In short:** x402 is an open payment standard that gives HTTP 402 a meaning: the server answers with machine-readable terms in a PAYMENT-REQUIRED header, the client retries with a signed PAYMENT-SIGNATURE, and a facilitator verifies and settles the payment on a network such as Base or Solana. x402 is an open payment standard that lets any HTTP client, including an AI agent, pay for a resource within ordinary HTTP requests. This guide walks through the roles, the V2 handshake, schemes and networks, and where implementations break. HTTP defines a `402 Payment Required` status code, but [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110#section-15.5.3) 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](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md) defines the data types and the facilitator API; the [V2 HTTP transport](https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/http.md) 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](https://settlens.com/learn/glossary#agentic-payment), 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. _x402 roles_ | Role | What it does | What it exchanges | | --- | --- | --- | | [Client](https://settlens.com/learn/glossary#client) | Any application or agent that requests a protected resource and pays for it. | Reads `PAYMENT-REQUIRED`, sends `PAYMENT-SIGNATURE`. | | [Resource server](https://settlens.com/learn/glossary#resource-server) | The service that requires payment for an API, content or data. | Answers 402, calls the facilitator, returns `PAYMENT-RESPONSE`. | | [Facilitator](https://settlens.com/learn/glossary#facilitator) | Verifies payment authorizations and settles them on a network. Resource servers can delegate this or host the endpoints themselves. | `POST /verify`, `POST /settle`, `GET /supported`. | ## 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. _Diagram: Sequence diagram of the x402 V2 authorization flow: the client requests the resource and receives 402 with PAYMENT-REQUIRED, signs and retries with PAYMENT-SIGNATURE; the resource server calls the facilitator's /verify, runs the resource, calls /settle, the facilitator broadcasts the transaction, and the server returns 200 with PAYMENT-RESPONSE._ _The x402 V2 authorization flow over HTTP. Other flows reorder verify, settle and execution (see the next section)._ 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`](https://settlens.com/learn/glossary#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](https://settlens.com/learn/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](https://settlens.com/learn/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](https://settlens.com/learn/x402-v2-headers) page. ## Payment flows: when the money moves V2 separates _how_ value moves (the [asset transfer method](https://settlens.com/learn/glossary#asset-transfer-method)) from _when_ it moves relative to the handler (the [payment flow](https://settlens.com/learn/glossary#payment-flow)). A payment option declares its flow in `extra.paymentFlow`; omitting it means the mechanism's default. _Payment flows defined by the x402 V2 core specification_ | Flow | Order | Effect for the client | | --- | --- | --- | | `authorization` (default) | verify, resource, settle, respond | Funds move only after the handler succeeds. Clients should prefer it when a resource offers several flows. | | `upfront` | settle, resource, respond | Payment is committed before the handler runs. If the handler fails, the client has paid; the core specification defines no refund for this case. | | `escrow` | settle, resource, settle, respond | A first settle commits a deposit or ceiling, a second records the final charge. | 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](https://settlens.com/learn/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`](https://github.com/x402-foundation/x402/blob/main/specs/schemes/exact/scheme_exact.md) 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](https://github.com/x402-foundation/x402/tree/main/specs/schemes), each with per-network bindings. - **Network** is a [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) 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](https://settlens.com/learn/glossary#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](https://github.com/x402-foundation/x402/blob/main/specs/transports-v1/http.md) and [V2](https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/http.md) HTTP transport specifications. _Wire-level differences between x402 V1 and V2 (HTTP transport)_ | Aspect | V1 | V2 | | --- | --- | --- | | Payment terms | JSON body of the 402 response | `PAYMENT-REQUIRED` header, Base64 JSON | | Client payment header | `X-PAYMENT` | `PAYMENT-SIGNATURE` | | Settlement header | `X-PAYMENT-RESPONSE` | `PAYMENT-RESPONSE` | | Network identifiers | Names such as `base-sepolia` | CAIP-2, such as `eip155:84532` | | Amount field | `maxAmountRequired` | `amount` | | Resource description | `resource` URL inside each requirement | One top-level `resource` object | | Chosen option in the payload | Scheme and network only | The full requirement, in `accepted` | | Extensions | No | `extensions` object | The [V1 to V2 migration guide](https://settlens.com/learn/x402-v1-to-v2-migration) 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](https://settlens.com/learn/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](https://settlens.com/learn/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](https://settlens.com/learn/agent-spending-policy). For a longer treatment with examples, read [x402 security failure modes](https://settlens.com/blog/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: **Passive scan (demo target)** ```text $ 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](https://settlens.com/learn/glossary#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: **Authorized active probe (demo target)** ```text $ 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 ``` > **Active probes need authorization** > > Run `--active --authorized --authorization-ref` only against endpoints you own or are approved to test. The probe sends one invalid signature, never calls `/settle`, never moves funds and needs no wallet or private key. Captured payment authorizations can also be checked offline with `verify-payment`, explained on the [EIP-3009 page](https://settlens.com/learn/eip-3009). Agents can run the same pre-payment checks through the [Settlens MCP server](https://settlens.com/mcp) before they sign anything. The [quickstart](https://settlens.com/docs/quickstart) covers installation for pilot participants, and [Assess](https://settlens.com/product/assess) describes the scan in detail. ## Frequently asked questions **Is x402 a blockchain or a token?** No. x402 is a payment protocol; over HTTP its messages travel in headers. Payments settle on existing networks, such as EVM chains or Solana, in existing assets such as USDC. The protocol defines no token of its own. **Does every resource server need a third-party facilitator?** No. The specification lets resource servers delegate verification and settlement to a facilitator or host the /verify and /settle endpoints themselves. **What is the difference between /verify and /settle?** /verify is read-only: it checks that a payment authorization is valid for the requirements and must not commit payment state. /settle durably commits the payment, typically by broadcasting a transaction, and returns the transaction hash. **What changed between x402 V1 and V2?** V2 carries the payment terms in the PAYMENT-REQUIRED header instead of the response body, renames X-PAYMENT to PAYMENT-SIGNATURE and X-PAYMENT-RESPONSE to PAYMENT-RESPONSE, uses CAIP-2 network identifiers, replaces maxAmountRequired with amount, moves the resource description to a top-level object and adds extensions. **Can I test an x402 endpoint without paying?** Yes. A Settlens passive scan never sends a payment signature. The optional active probe sends one intentionally invalid signature with the owner's authorization. Neither calls /settle or moves funds. ## Sources 1. [x402 protocol specification, version 2](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md) — x402 Foundation 2. [x402 HTTP transport, version 2](https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/http.md) — x402 Foundation 3. [x402 HTTP transport, version 1](https://github.com/x402-foundation/x402/blob/main/specs/transports-v1/http.md) — x402 Foundation 4. [x402 scheme: exact](https://github.com/x402-foundation/x402/blob/main/specs/schemes/exact/scheme_exact.md) — x402 Foundation 5. [CAIP-2: Blockchain ID Specification](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) — Chain Agnostic Standards Alliance 6. [RFC 9110: HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110) — IETF