Skip to main content

​
x402 Payments

x402 lets an agent pay for a resource over HTTP, using the 402 Payment Required status code as a protocol rather than an error. No checkout page, no human, no session. Intents are signed off-chain, sequenced by the sequencer, batched, and settled on Set L2.

​
The flow

The intent is then sequenced, batched, committed, and settled — and the server can verify payment later using an inclusion proof.

​
Wire format

Base64 is used because raw JSON isn’t safe in an HTTP header value. The decoded document is exactly what POST /api/v1/x402/payments accepts — snake_case fields — so the header path and the API path take the identical shape.

​
Signing

The signature is Ed25519 over a X402_PAYMENT_V1 domain-separated SHA-256 signing hash.
The domain separator is part of the signed input. A signature computed over the bare intent — without the domain prefix — will not verify. This is the same pattern as the Merkle leaf hashing: every hash in the system is domain-separated.
The intent carries identity (intent_id, x402_version, tenant_id, store_id, source_agent_id, the signing key id), the payment terms, and a validity window.

​
Protocol limits

Keep max_validity_secs short. A signed intent is spendable until it expires, so a 24-hour window is a 24-hour liability if the intent leaks.

​
Replay protection

A verified intent burns its nonce through a primary-key reservation in the nonce-tracking table. Submitting the same intent twice fails on the second attempt rather than paying twice — which is what makes it safe for an agent to retry a request whose response it never saw. Header-submitted intents go through the same code path as the submission endpoint, so they get a sequence number, burn their nonce, and enter the normal batching pipeline identically.

​
Receipts

The X-Payment-Receipt header acknowledges sequencing and points at the full Merkle receipt:
That becomes available once the intent is batched. Until then the receipt header is your proof of sequencing, not of settlement.

​
Two implementations

These are not interchangeable. The sequencer path is the one that batches and settles on Set L2 with inclusion proofs. Check which side you’re integrating against before implementing signing — the schemes and headers differ.

​
Try it

The CLI ships x402 helpers under cli/src/x402/ — client, resource server, facilitator, budget, and agent integration. There’s also an x402 MCP server (stateset-x402, 5 tools) for paid API calls from an agent.