API reference

x402 resource

ANY /api/public/x402/r/:endpointId — no API key. Headers: PAYMENT-SIGNATURE (base64 JSON PaymentPayload, x402 v2; X-PAYMENT accepted as alias). Response headers: PAYMENT-REQUIRED on 402, PAYMENT-RESPONSE on success.

PaymentPayload (decoded PAYMENT-SIGNATURE)

{
  "x402Version": 2,
  "accepted": { "scheme":"exact","network":"eip155:5042","amount":"50000","asset":"0x3600…0000","payTo":"0x…","maxTimeoutSeconds":60,"extra":{"name":"USDC","version":"2"} },
  "payload": {
    "signature": "0x…",                      // EIP-3009 TransferWithAuthorization, USDC domain {name:"USDC",version:"2",chainId:5042}
    "authorization": { "from":"0x…","to":"0x…(=payTo)","value":"50000","validAfter":"0","validBefore":"<unix>","nonce":"0x<32 bytes>" }
  }
}

KLIK agent checkout

GET /api/public/klik/agent/:id — checkout metadata (merchant, product, price, network, payTo, termsHash, expiresAt, refundPolicy, requiredCustomerInfo, settlementStatus). POST the same URL with x402 headers and {"customer":{"email":"…"}} when required. Returns order, fulfillment and settlement.

Swap Agent API

Auth: Authorization: Bearer kx_… (scope swap:quote). 120 requests/min per key by default.

GET /api/public/swap-agent/chains
GET /api/public/swap-agent/quote?agentId=<uuid>&tokenIn=0x…&tokenOut=0x…&amountIn=1000000&slippageBps=50

200 {
  "requestId": "…", "chainId": 5042,
  "decision": "allow" | "deny",   "reason": null | "Slippage above the agent limit.",
  "quoteExpiresAt": "…(30s)", "best": { "amountOut":"…","minAmountOut":"…","priceImpactPercent":0.12,"kairoFeeBps":25,"hops":[…] },
  "alternatives": [ … ],
  "execution": { "status": "not_enabled" }
}

Status

GET /api/public/x402/status — public health: facilitator reachability and latency, configured networks and contracts.

Errors

HTTP	error	Meaning
402	(no header)	Payment required. Read PAYMENT-REQUIRED.
402	wrong_network · wrong_asset · wrong_recipient · amount_mismatch · insufficient_amount · expired · not_yet_valid · invalid_payload · unsupported_version	Payment did not match the issued requirement. Nothing was charged.
409	payment_already_used	This authorization nonce was already presented. Never charged twice.
202	settlement_pending · settlement_unconfirmed	Circle or Arc has not confirmed yet. Retry with the same PAYMENT-SIGNATURE.
503	facilitator_unavailable · settlement_unavailable · merchant_not_ready · endpoint_paused	Temporarily unavailable. Retry with the same header.
501	metered_pricing_unavailable	Usage-based (upto) pricing is not enabled.
502	upstream_unavailable	Paid, but the merchant's API failed. paymentId is returned for a refund.
401/403/429	missing_or_invalid_api_key · insufficient_scope · rate_limited	API-key endpoints only.