Skip to main content

x402 Endpoints

Request → 402 Challenge​

A protected endpoint responds with 402 Payment Required and a JSON payload:

{
  "x402Version": 1,
  "resourceId": "0xf296...",
  "accepts": [
    {
      "scheme": "exact:evm:permit2",
      "network": "bnb",
      "asset": "0x55d398326f99059fF775485246999027B3197955",
      "amount": "1000000",
      "router": {
        "address": "0xRouter",
        "intent": {
          "paymentId": "0x...",
          "resourceId": "0x...",
          "referenceHash": "0x...",
          "nonce": "0x...",
          "deadline": 1731763200
        },
        "referenceData": "api:credits:134"
      }
    }
  ],
  "metadata": {
    "merchant": "Pepay Labs",
    "memo": "x402 gating"
  }
}

Client response​

Clients choose an accept option, execute the router call, then retry with an authorization header:

X-PAYMENT-AUTHORIZATION: <base64 payload>

@pepaylabs/x402flex can parse and verify this header automatically.

Verification​

Use decodePaymentSettledEvent or the middleware settleWithRouter helper to confirm settlement. Always correlate by paymentId + resourceId.

paymentId is bound to token/amount/deadline/resourceId/referenceHash/nonce; persist the invoice nonce if you need to recompute it.

Common patterns​

  • API credits: encode your internal ID in referenceData.
  • Agents: keep referenceData short so MCP tools can round-trip it.
  • Sessions: include session tags in referenceData to enforce budgets.