x402 payment protocol

x402 defines a machine-readable payment handshake over standard HTTP. An agent and a server can negotiate, settle, and verify an on-chain payment without any out-of-band coordination.

How x402 works

x402 extends HTTP with two message components:

HTTP 402 Payment Required response: When a resource requires payment, the server returns a 402 response with a machine-readable payment payload. The payload specifies the amount, accepted token or currency, the payment network, and the destination address.

PAYMENT-REQUIRED response header: When a resource requires payment, the gateway returns a HTTP 402 response with the payment requirement in the PAYMENT-REQUIRED header. The client makes the required on-chain payment and attaches the signed payment proof in the payment proof header on a retry of the original request.

sequenceDiagram
    participant A as Agent
    participant G as Gateway
    participant B as Blockchain

    A->>G: GET /tool
    G-->>A: 402  PAYMENT-REQUIRED: {amount, network, address}
    A->>B: Pay on-chain
    B-->>A: Confirmed
    A->>G: GET /tool + payment proof header
    G-->>A: 200 + response

The protocol is transport-agnostic and works over any standard HTTP endpoint. Verifying payment on-chain directly, with no dedicated payment intermediary, is one supported verification mode; the gateway can also delegate verification to a facilitator, either another connected gateway or an external HTTP facilitator service, as an alternative.

How a payment is matched to the surface’s requirements

The 402 response lists the payment requirements configured on the surface’s Payment element, and the client chooses one. When the client retries with its payment, the gateway accepts the payment only if it names one of those requirements exactly: the same scheme, network, token, recipient, and amount, and the same token transfer details. Signature, on-chain, and facilitator checks all take their expected values from the matched requirement rather than from the client, and settlement uses that requirement too.

This binding has two practical consequences:

• A surface with x402 payment turned on and an empty list of payment requirements, or with a requirement whose amount is non-numeric, rejects every payment.
• For the Up To scheme, the client’s authorisation must name exactly the configured amount as its limit.

For the requirement fields, see Payment element.

Networks

x402 payments settle on-chain. The Agent Gateway ships with out-of-the-box support for these networks, with more configurable per deployment:

• Base: the default network for x402 payments in the gateway.
• Ethereum
• Optimism
• Arbitrum
• Polygon
• Avalanche
• Solana

Network support and accepted tokens are configured per gateway deployment in x402.json.

Related

• Payment element: field reference for x402 verification, settlement, and payment requirements.
• MCP protocol: Model Context Protocol: how the gateway serves and proxies MCP tool servers.