Skip to content
Tollgate Docs

402 Payment Required envelope

When a request to a gated endpoint arrives without an x-tollgate-iou header, Tollgate responds:

  • HTTP status: 402
  • Content-Type: application/json; charset=utf-8
  • WWW-Authenticate: Tollgate realm="iou-v1", price="$0.05"
  • X-Tollgate-Privacy: https://tollgatepay.com/privacy
  • X-Tollgate-Chain: 8453
  • X-Tollgate-Capabilities: iou-v1
  • traceparent: 00-<traceId>-<spanId>-01

Body

Shape (PaymentRequiredResponse in @tollgatepay/core/types):

{
  "price": { "amountMicros": 50000, "currency": "USDC", "displayAmount": "$0.05" },
  "endpoint": "/api/premium",
  "developerAddress": "0x...",
  "developerSalt": "0x...",
  "chainId": 8453,
  "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "protocolVersion": "1",
  "eip712Domain": { "name": "Tollgate", "version": "1", "chainId": 8453, "verifyingContract": "0x...", "salt": "0x..." },
  "minApprovalSuggested": 10000000,
  "capabilities": ["iou-v1"],
  "privacyPolicyUrl": "https://tollgatepay.com/privacy"
}

Fields

  • price.amountMicros — integer micro-USDC (6 decimals). 50_000 = $0.05.
  • endpoint — canonicalized path. This is the path the agent MUST sign. Do not re-canonicalize client-side.
  • developerAddress — the payout address and the address the agent authorises with USDC.approve.
  • developerSalt — used to derive apiKeyHash = HMAC-SHA256(apiKey, developerSalt). Salt rotation invalidates previously-served 402s — agents MUST re-fetch.
  • chainId — the chain this IOU settles on. Base (8453) at launch.
  • tokenAddress — USDC contract on chainId.
  • eip712Domain — the EIP-712 domain to sign against. Echo it exactly in the typed-data domain field.
  • minApprovalSuggested — UI hint (micros). Pre-approve this much so subsequent requests don't stall.
  • capabilities — protocol capabilities the server offers. ["iou-v1"] at launch.
  • privacyPolicyUrl — GDPR Art. 14 notice URL. Agents SHOULD persist this for compliance records.

Retry

After signing, send the exact same request with x-tollgate-iou: <base64-JSON envelope>. See IOU + EIP-712 domain for the envelope shape.