x402 Payment Protocol
ActiveHTTP-native payment protocol that revives the 402 Payment Required status code to enable programmatic stablecoin payments over standard HTTP. Clients attach signed USDC payment payloads to requests; servers verify via a facilitator and return the paid resource.
In one line
x402 is an open payment protocol built on HTTP 402 Payment Required, released by Coinbase in May 2025. A server returns 402 with a PAYMENT-REQUIRED header describing the cost. The client signs a USDC payment and retries with an X-PAYMENT header. The server verifies via a facilitator and returns the resource with an X-PAYMENT-RESPONSE receipt. No accounts or sessions required.
Quick Reference
| Field | Size | Description |
|---|---|---|
| HTTP 402 | Status code | Server returns 402 Payment Required with payment requirements in PAYMENT-REQUIRED header |
| PAYMENT-REQUIRED | Response header | Base64-encoded JSON: payment schemes, amount, currency, network, recipient address |
| X-PAYMENT | Request header | Base64-encoded signed payment payload. Client attaches this and retries the original request. |
| X-PAYMENT-RESPONSE | Response header | Base64-encoded receipt confirming payment settled onchain. Returned with the 200 response. |
| Facilitator | Service | Third-party verifier that checks payment validity before the resource server grants access. |
| Payment network | Base (L2) | USDC on Base blockchain. Gasless settlement via Coinbase facilitator API. |
Key Characteristics
3-step flow
Request resource. Receive 402 with requirements. Retry with signed payment. Receive resource with receipt.
Machine-native
No accounts, no browser, no human needed. AI agents and automated systems pay programmatically in the same HTTP exchange.
Facilitator model
A trusted facilitator verifies the payment payload before the server grants access. Prevents fake payment headers.
HTTP-native
Sits on top of standard HTTP. Works with any HTTP client. No new protocol stack needed.
Message Format
// Step 1: Client requests paid resource
GET /api/premium-data HTTP/1.1
Host: api.example.com
Accept: application/json
// Step 2: Server returns 402 with requirements
HTTP/1.1 402 Payment Required
Content-Type: application/json
PAYMENT-REQUIRED: eyJzY2hlbWVzIjpbeyJzY2hlbWUiOiJleGFjdCIsIm5ldHdvcmsiOiJiYXNlIiwiYW1vdW50IjoiMC4wMSIsImN1cnJlbmN5IjoiVVNEQyIsImFkZHJlc3MiOiIweDEyMzQuLi4ifV19
{"error":"payment_required","message":"This endpoint costs $0.01 USDC per request"}// Step 3: Client retries with payment header
GET /api/premium-data HTTP/1.1
Host: api.example.com
Accept: application/json
X-PAYMENT: eyJzY2hlbWUiOiJleGFjdCIsInBheWxvYWQiOnsidHhIYXNoIjoiMHhhYmNkLi4uIiwidG9rZW5BZGRyZXNzIjoiMHhVU0RDLi4uIiwiYW1vdW50IjoiMTAwMDAiLCJmcm9tIjoiMHh1c2VyLi4uIiwidG8iOiIweHNlcnZlci4uLiJ9fQ==
// Step 4: Server verifies via facilitator and returns resource
HTTP/1.1 200 OK
Content-Type: application/json
X-PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLCJ0eEhhc2giOiIweGFiY2QuLi4iLCJuZXR3b3JrIjoiYmFzZSIsInNldHRsZWRBdCI6IjIwMjYtMDEtMTVUMTA6MDA6MDBaIn0=
{"data":"Premium content..."}