Payment Flow

End-to-End Flow

Client                    Server                   Facilitator
  │                         │                          │
  │  GET /resource          │                          │
  │────────────────────────>│                          │
  │                         │                          │
  │  402 + X-Payment-Required                          │
  │<────────────────────────│                          │
  │                         │                          │
  │  (construct payment proof)                         │
  │                         │                          │
  │  GET /resource          │                          │
  │  + X-Payment header     │                          │
  │────────────────────────>│                          │
  │                         │  POST /verify            │
  │                         │─────────────────────────>│
  │                         │  { isValid: true }       │
  │                         │<─────────────────────────│
  │                         │                          │
  │                         │  POST /settle            │
  │                         │─────────────────────────>│
  │                         │  { success, txHash }     │
  │                         │<─────────────────────────│
  │                         │                          │
  │  200 + resource         │                          │
  │  + X-Payment-Response   │                          │
  │<────────────────────────│                          │

Step-by-Step Walkthrough

1. Initial Request

The client sends a standard HTTP request to a paid resource.

GET /api/data HTTP/1.1
Host: example.com

2. 402 Response

The server responds with HTTP 402 and includes payment requirements as a base64-encoded JSON in the X-Payment-Required header.

HTTP/1.1 402 Payment Required
X-Payment-Required: eyJ4NDAyVmVyc2lvbiI6MSwi...

Decoded, the header contains:

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "10000",
      "payTo": "0x...",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "maxTimeoutSeconds": 60,
      "resource": "/api/data",
      "description": "API access fee"
    }
  ]
}

The accepts array may include multiple payment options (different schemes or networks).

3. Parse Requirements

The client decodes the X-Payment-Required header and selects a payment option from accepts[]. The client should prefer scheme: "exact".

4. Construct Payment Proof

The client builds a scheme-specific payment proof:

Scheme	What the client signs
EVM	EIP-712 TransferWithAuthorization (USDC EIP-3009)
Credits	EIP-712 CreditsMandateSpend authorization
XRP	A signed XRPL Payment transaction

See the individual scheme pages for payload details:

• EVM Scheme
• Credits Scheme
• XRP Scheme

5. Retry with X-Payment

The client retries the original request with the payment proof as a base64-encoded JSON in the X-Payment header.

GET /api/data HTTP/1.1
Host: example.com
X-Payment: eyJ4NDAyVmVyc2lvbiI6MSwi...

6. Server Verifies Payment

The server decodes the X-Payment header and sends it to the appropriate facilitator for verification and settlement:

1. Verify — the facilitator checks the signature, amount, destination, and validity window
2. Settle — the facilitator executes the payment (on-chain transfer or off-chain debit)

7. Resource Delivery

On successful settlement, the server returns the requested resource along with a payment receipt:

HTTP/1.1 200 OK
X-Payment-Response: eyJzdWNjZXNzIjp0cnVlLC...
Content-Type: application/json

{ "data": "..." }

The X-Payment-Response header contains:

{
  "success": true,
  "transaction": "0x..."
}

Scheme-Specific Differences

Aspect	EVM	Credits	XRP
Signing	EIP-712 via Privy wallet (auto)	EIP-712 via Privy wallet (auto)	Native XRPL signing (manual)
Settlement	On-chain USDC transfer	Off-chain balance debit (immediate)	Submit to XRPL, async finality via chain parser
Status flow	signed → used	signed → used	signed → pending → used
Facilitator	External (facilitator.xechoai.xyz)	Internal (/api/facilitator/)	Internal (/api/facilitator/, same as Credits)
Mandate support	V1 and V3	V1 and V3	V1 only
Validity window	30–300 seconds	20 minutes (nonce window)	Transaction-level (tefMAX_LEDGER on expiry)