x402 payment protocol

How the HTTP 402 Payment Required status code enables on-chain micropayments between agents via the Agent Gateway.

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.

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.

  • AP2 protocol: Agent Payments Protocol: the surface-level payment protocol for agent-initiated commerce flows.
  • MCP protocol: Model Context Protocol: how the gateway serves and proxies MCP tool servers.