What is x402?

x402 is an open payment protocol built on top of HTTP. It gives any HTTP endpoint the ability to require a micropayment before responding, using the standard 402 Payment Required status code as a machine-readable payment challenge.

The protocol is network-agnostic — the same flow works over ICP, EVM, and Solana. Consensus implements x402 on both sides: the server issues challenges and the client handles them transparently.

---

The Payment Flow

Every x402 interaction follows four steps:

Client                     Resource Server               Facilitator
  │                               │                            │
  ├─── GET /api/data ────────────►│                            │
  │                               │                            │
  │◄── 402 Payment Required ──────┤                            │
  │    X-Payment-Required: {...}  │                            │
  │                               │                            │
  │    (client signs payment)     │                            │
  │                               │                            │
  ├─── GET /api/data ────────────►│                            │
  │    X-Payment: {...}           │                            │
  │                               ├─── verify payment ────────►│
  │                               │◄── verified ───────────────┤
  │◄── 200 OK ────────────────────┤                            │

Step 1 — Initial request The client sends a normal HTTP request. No special headers are required.

Step 2 — Payment challenge The server responds 402 Payment Required with a X-Payment-Required header containing a JSON object that describes what payment is needed:

{
  "scheme": "exact",
  "network": "icp:1:xafvr-biaaa-aaaai-aql5q-cai",
  "maxAmountRequired": "100000",
  "payTo": "<principal>",
  "description": "Premium data endpoint",
  "mimeType": "application/json"
}

Step 3 — Client pays The client reads the challenge, signs and submits a payment on the specified network, then retries the original request with the signed proof in the X-Payment header.

Step 4 — Verification and response The server forwards the payment proof to the facilitator. The facilitator verifies on-chain settlement and returns confirmation. The server then processes the request and returns the response.

From the client’s perspective, steps 2–4 are invisible. wrapFetchWithPayment intercepts the 402, handles the payment, and returns the final 200 response.

---

The X-Payment-Required Header

When the server issues a 402, the X-Payment-Required header contains a JSON object with the following fields:

Field	Type	Description
scheme	string	Payment scheme — always "exact" for Consensus
network	string	Network identifier — see Supported Networks
maxAmountRequired	string	Maximum amount the server will accept as payment
payTo	string	Address or principal that receives the payment
description	string	Human-readable description of what is being paid for
mimeType	string	MIME type of the response once payment is accepted

A single route can advertise multiple accepted networks simultaneously. The client picks one.

---

The X-Payment Header

After paying, the client attaches proof in the X-Payment header. The exact structure is scheme- and network-specific, but always includes:

Field	Type	Description
scheme	string	Must match the scheme from the challenge
network	string	Must match the network from the challenge
payload	string	Signed payment proof — format is network-specific

The server does not validate this itself — it forwards it to the facilitator, which does the chain-level verification.

---

The exact Scheme

Consensus uses the exact scheme exclusively. Under this scheme:

• The client pays exactly the amount specified in maxAmountRequired
• No range, no estimation, no partial payment
• Payment goes directly to payTo on-chain
• The facilitator confirms that the exact transfer occurred before the server responds

This makes pricing deterministic and auditable — both the client and server know the cost before any payment is made.

---

Implementation

For complete setup guides on both sides of the payment flow:

• Facilitator — Resource Server — protect Express routes with paymentMiddleware, connect to the facilitator, accept multiple networks
• Facilitator — Client — build a client with wrapFetchWithPayment across ICP, EVM, and Solana
• Supported Networks — every network and token the facilitator accepts