How the protocol works
This page describes a typical x402-style flow on an EVM network with a stablecoin facilitator. Exact field names and encodings depend on your facilitator and the x402 specification version you target—always verify against your provider’s docs.
Sequence
Section titled “Sequence”- Client calls your API (e.g.
GET /api/premium/data). - Server decides the caller has not yet paid for this resource.
- Server responds with
402 Payment Requiredand a body (and often headers) describing payment requirements: network, asset, payee, amount, scheme (e.g. “exact” payment), timeouts, etc. - Client constructs a payment payload and signs or authorizes it with a wallet (human or automated).
- Client retries the same URL, attaching a
payment-signature(or your stack’s equivalent) header carrying the signed payload. - Server calls the facilitator
verify(and thensettle) with that payload. - On success, server returns
200and the protected response. On failure, server may return402or4xx/5xxwith an error body.
Headers you’ll see in the wild
Section titled “Headers you’ll see in the wild”Implementations vary; common patterns include:
| Concept | Purpose |
|---|---|
402 status | Signals “payment needed before this resource.” |
payment-required (or JSON body) | Machine-readable requirements (amount, payee, chain, asset). Often base64-encoded JSON in a header for compactness. |
payment-signature | Client’s signed payment authorization on retry. |
x-trace-id | Optional correlation ID for logs and observability (TallyPay uses this to stitch client + server events). |
Your middleware should not invent a parallel protocol—align header names and encodings with your facilitator and the x402 version you support.
Where verification runs
Section titled “Where verification runs”- Never trust the client alone: your server (or edge worker) must verify via the facilitator or your own verifier.
- Settlement may be asynchronous from the client’s perspective; your API should only release the resource when verify + settle succeed per your policy.
Idempotency and retries
Section titled “Idempotency and retries”Networks and RPCs fail. Clients may retry the paid request; your route should be idempotent where possible (same payment proof should not double-charge for the same logical entitlement). How you enforce that (nonce, session, resource key) is application logic on top of x402.