x402 Payment Flow

The complete x402 flow is 3 HTTP steps. The client discovers payment requirements from a 402 response, submits a signed payment, and receives the resource with a settlement receipt. No accounts, sessions, or human interaction required.

1. Request

GET resource

2. Discover

402 + requirements

3. Pay

Retry + X-PAYMENT

4. Receive

200 + receipt

Client requests resource

Step 1 – GET request

http

GET /api/premium-data HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer optional-identity-token

Server returns 402

Step 2 – 402 Payment Required

http

HTTP/1.1 402 Payment Required
Content-Type: application/json
PAYMENT-REQUIRED: eyJzY2hlbWVzIjpbeyJzY2hlbWUiOiJleGFjdCIsIm5ldHdvcmsiOiJiYXNlIiwibWF4QW1vdW50UmVxdWlyZWQiOiIxMDAwMCIsInJlc291cmNlIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vYXBpL3ByZW1pdW0tZGF0YSIsInBheVRvIjoiMHgxMjM0NTY3ODkwYWJjZGVmMTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4In1dfQ==

{
  "error": "payment_required",
  "message": "This endpoint costs $0.01 USDC per request.",
  "x402Version": "1"
}

PAYMENT-REQUIRED decoded

http

// PAYMENT-REQUIRED header decoded from base64:
{
  "schemes": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "10000",
      "resource": "https://api.example.com/api/premium-data",
      "description": "Premium market data API call",
      "payTo": "0x1234567890abcdef1234567890abcdef12345678"
    }
  ]
}

Client retries with X-PAYMENT

Step 3 – Retry with payment

http

GET /api/premium-data HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer optional-identity-token
X-PAYMENT: eyJzY2hlbWUiOiJleGFjdCIsInBheWxvYWQiOnsidHhIYXNoIjoiMHhhYmNkZWYxMjM0NTY3ODkwYWJjZGVmMTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYiLCJ0b2tlbkFkZHJlc3MiOiIweGQzZTZhYzJkZjQyMGFlMzY5NjEwMTViZmJlNGY5MzVlN2I3OGI2ZmUiLCJhbW91bnQiOiIxMDAwMCIsImZyb20iOiIweHVzZXJXYWxsZXRBZGRyZXNzIiwidG8iOiIweDEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3ODkwYWJjZGVmMTIzNDU2NzgifX0=

X-PAYMENT decoded

http

// X-PAYMENT header decoded from base64:
{
  "scheme": "exact",
  "payload": {
    "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "tokenAddress": "0xd3e6ac2df420ae369610 15bfbe4f935e7b78b6fe",
    "amount": "10000",
    "from": "0xuserWalletAddress",
    "to": "0x1234567890abcdef1234567890abcdef12345678"
  }
}

Server returns 200 with receipt

Step 4 – 200 OK with receipt

http

HTTP/1.1 200 OK
Content-Type: application/json
X-PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLCJ0eEhhc2giOiIweGFiY2RlZjEyMzQ1Njc4OTAiLCJuZXR3b3JrIjoiYmFzZSIsInNldHRsZWRBdCI6IjIwMjYtMDEtMTVUMTA6MDA6MTBaIn0=

{
  "data": "Premium market data...",
  "timestamp": "2026-01-15T10:00:10Z"
}

X-PAYMENT-RESPONSE decoded

http

// X-PAYMENT-RESPONSE decoded from base64:
{
  "success": true,
  "txHash": "0xabcdef1234567890",
  "network": "base",
  "settledAt": "2026-01-15T10:00:10Z"
}

x402 Documentation – How It Works →