x402 HTTP Flow

The x402 HTTP flow is the simplest way to interact with Key0. Plan discovery uses GET /discover, and the POST /x402/access endpoint handles challenge and settlement:

Discovery — GET /discover returns all available plans (HTTP 200). POST /x402/access without planId returns HTTP 400.
Challenge — planId present, no payment-signature header, creates a PENDING record.
Settlement (subscription) — planId + payment-signature, settles on-chain, returns an AccessGrant (JWT).
Settlement (per-request standalone) — planId + resource + payment-signature, settles on-chain, proxies to the backend, returns a ResourceResponse (API data, no token).

For a full sequence diagram of the Discovery → Challenge → Settlement flow, see How It Works.

Four Cases

Case 1: Discovery
Case 2: Challenge
Case 3: Settlement
Case 4: Route-Based Settlement

Use GET /discover to browse all available plans. No PENDING record is created — this is a pure pricing query.Note: POST /x402/access without planId returns HTTP 400 with a pointer to this endpoint.

Request

curl https://api.example.com/discover

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "agentName": "My Agent",
  "description": "Payment-gated API",
  "plans": [
    {
      "planId": "basic",
      "unitAmount": "$0.10",
      "description": "Basic plan - $0.10 USDC"
    }
  ],
  "routes": []
}

The discovery response contains one entry per plan configured in SellerConfig.plans, plus any route metadata when per-request routes are enabled.

Send a planId (and optionally requestId and resourceId) without a payment-signature header. The server creates a PENDING challenge record via engine.requestHttpAccess() and returns payment requirements for that specific plan.

If you omit requestId, the server auto-generates one in http-{uuid} format. You can provide your own UUID for idempotent retries — sending the same requestId again returns the existing challenge instead of creating a new one.

Request

curl -X POST https://api.example.com/x402/access \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "basic",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "resourceId": "photo-123"
  }'

Response

HTTP/1.1 402 Payment Required
payment-required: eyJ4NDAyVm... (base64-encoded JSON)
www-authenticate: Payment realm="https://api.example.com", accept="exact", challenge="http-a1b2c3d4-..."
Content-Type: application/json

{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:84532",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "amount": "100000",
      "payTo": "0xSellerWallet...",
      "maxTimeoutSeconds": 900,
      "extra": {
        "name": "USDC",
        "version": "2",
        "description": "Basic plan - $0.10 USDC"
      }
    }
  ],
  "extensions": {
    "key0": {
      "inputSchema": { "..." : "..." },
      "outputSchema": { "..." : "..." },
      "description": "..."
    }
  },
  "challengeId": "http-a1b2c3d4-...",
  "error": "Payment required"
}

The response now includes a challengeId that ties the payment to this specific challenge record. The www-authenticate header also carries the challenge ID.

Send the same planId and requestId along with a payment-signature header containing the signed EIP-3009 authorization. The server decodes the header, calls settlePayment() to execute the transfer on-chain, then calls engine.processHttpPayment() to transition the challenge through PENDING, PAID, and DELIVERED.

Request

curl -X POST https://api.example.com/x402/access \
  -H "Content-Type: application/json" \
  -H "payment-signature: eyJ4NDAyVm..." \
  -d '{
    "planId": "basic",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "resourceId": "photo-123"
  }'

The payment-signature header is a base64-encoded X402PaymentPayload (see EIP-3009 Authorization below for the decoded structure).

Response

HTTP/1.1 200 OK
payment-response: eyJzdWNjZXNz... (base64-encoded X402SettleResponse with txHash)
Content-Type: application/json

{
  "type": "AccessGrant",
  "challengeId": "http-a1b2c3d4-...",
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "tokenType": "Bearer",
  "resourceEndpoint": "https://api.example.com/photos/photo-123",
  "resourceId": "photo-123",
  "planId": "basic",
  "txHash": "0xSettledTx...",
  "explorerUrl": "https://sepolia.basescan.org/tx/0xSettledTx..."
}

The payment-response header contains the full X402SettleResponse from the on-chain settlement, base64-encoded. The JSON body is the AccessGrant with the JWT and resource endpoint URL.

For standalone paid routes (seller has proxyTo or fetchResource configured), include routeId and a resource field in the body. After payment, Key0 proxies the request to the backend and returns a ResourceResponse — no JWT issued.

Challenge request

curl -X POST https://api.example.com/x402/access \
  -H "Content-Type: application/json" \
  -d '{
    "routeId": "weather-query",
    "requestId": "550e8400-e29b-41d4-a716-446655440001",
    "resource": { "method": "GET", "path": "/api/weather/london" }
  }'

Response (HTTP 402 — same shape as subscription)

{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:84532",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "amount": "10000",
      "payTo": "0xSellerWallet...",
      "maxTimeoutSeconds": 900,
      "extra": { "name": "USDC", "version": "2", "routeId": "weather-query" }
    }
  ],
  "challengeId": "http-a1b2c3d4-...",
  "error": "Payment required"
}

Settlement request (with resource + payment-signature)

curl -X POST https://api.example.com/x402/access \
  -H "Content-Type: application/json" \
  -H "payment-signature: eyJ4NDAyVm..." \
  -d '{
    "routeId": "weather-query",
    "requestId": "550e8400-e29b-41d4-a716-446655440001",
    "resource": { "method": "GET", "path": "/api/weather/london" }
  }'

Response (HTTP 200 — ResourceResponse, not AccessGrant)

HTTP/1.1 200 OK
payment-response: eyJzdWNjZXNz... (base64-encoded X402SettleResponse)
Content-Type: application/json

{
  "type": "ResourceResponse",
  "challengeId": "http-a1b2c3d4-...",
  "requestId": "550e8400-e29b-41d4-a716-446655440001",
  "routeId": "weather-query",
  "txHash": "0xSettledTx...",
  "explorerUrl": "https://sepolia.basescan.org/tx/0xSettledTx...",
  "resource": {
    "status": 200,
    "body": { "city": "london", "tempF": 65, "condition": "Cloudy" }
  }
}

Use resource.body directly — no Bearer token, no follow-up request. Every call requires a fresh payment.If the backend returns a non-2xx status, the ResourceResponse still contains the backend’s error body and status. The challenge stays in PAID state so the refund cron can process it.

The resource field is required for standalone route purchases. For embedded per-request routes, the payment-signature header is sent directly on the route (e.g. GET /api/weather/london) — no /x402/access involved. See Paying for Access.

For the complete HTTP headers reference, see API Reference → Overview.

EIP-3009 Authorization

The payment-signature header carries a signed EIP-3009 transferWithAuthorization. This means the client signs an off-chain authorization that permits a specific USDC transfer, but never sends a transaction directly and never pays gas. The server (or a facilitator like Coinbase CDP) executes the transferWithAuthorization call on-chain, paying the gas fees. The USDC moves from the client’s wallet to the seller’s wallet in a single atomic transaction.

Decoded `payment-signature` Structure

{
  "x402Version": 2,
  "network": "eip155:84532",
  "scheme": "exact",
  "payload": {
    "signature": "0xSignedEIP3009...",
    "authorization": {
      "from": "0xBuyer...",
      "to": "0xSeller...",
      "value": "100000",
      "validAfter": "0",
      "validBefore": "1741180560",
      "nonce": "0xRandomNonce..."
    }
  },
  "accepted": {
    "scheme": "exact",
    "network": "eip155:84532",
    "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
    "amount": "100000",
    "payTo": "0xSeller...",
    "maxTimeoutSeconds": 900,
    "extra": { "name": "USDC", "version": "2" }
  }
}

Key fields:

payload.signature — the EIP-3009 signature authorizing the USDC transfer.
payload.authorization — the transfer parameters: sender, recipient, amount (in USDC base units, 6 decimals), validity window, and a random nonce.
accepted — echoes the PaymentRequirements from the 402 response, so the server can verify the client accepted the correct terms.

Next Steps

Paying for Access

Step-by-step client guide: discover plans, sign EIP-3009, and use the access token.

A2A Flow

The JSON-RPC based agent-to-agent payment flow for native A2A clients.

Settlement Strategies

Facilitator vs. gas wallet settlement and how EIP-3009 is executed on-chain.

State Machine

The full PENDING / PAID / DELIVERED / EXPIRED / REFUNDED lifecycle.

Getting Started

Protocols

Architecture

Integrations

Guides

Deployment

x402 HTTP Flow

Four Cases

Request

Response

Request

Response

Request

Response

Challenge request

Response (HTTP 402 — same shape as subscription)

Settlement request (with resource + payment-signature)

Response (HTTP 200 — ResourceResponse, not AccessGrant)

EIP-3009 Authorization

Decoded `payment-signature` Structure

Next Steps

Paying for Access

A2A Flow

Settlement Strategies

State Machine

Getting Started

Protocols

Architecture

Integrations

Guides

Deployment

​Four Cases

​Request

​Response

​Request

​Response

​Request

​Response

​Challenge request

​Response (HTTP 402 — same shape as subscription)

​Settlement request (with resource + payment-signature)

​Response (HTTP 200 — ResourceResponse, not AccessGrant)

​EIP-3009 Authorization

​Decoded payment-signature Structure

​Next Steps

Paying for Access

A2A Flow

Settlement Strategies

State Machine

Four Cases

Request

Response

Request

Response

Request

Response

Challenge request

Response (HTTP 402 — same shape as subscription)

Settlement request (with resource + payment-signature)

Response (HTTP 200 — ResourceResponse, not AccessGrant)

EIP-3009 Authorization

Decoded `payment-signature` Structure

Next Steps