Protocol detail

Polyrank implements the official x402 specification (V1) with the exact scheme over EIP-3009 USDC transfers. If you use @x402/fetch, x402-axios, or the Python x402 client, all of this is handled for you.

1 — The 402 response

A priced route called without payment returns HTTP 402:

{
  "x402Version": 1,
  "error": "payment required: Top-200 positioned wallets for a market",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "20000",
      "resource": "https://api.polyrank.app/v1/agent/market/0x…/positioning",
      "description": "Top-200 positioned wallets for a market",
      "mimeType": "application/json",
      "payTo": "0xEC89C6e7028b0e30E22eB3409d2F7c273EB20164",
      "maxTimeoutSeconds": 60,
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "extra": { "name": "USD Coin", "version": "2" }
    }
  ]
}

• network uses official wire names (base, base-sepolia). CAIP-2 aliases (eip155:8453) are accepted inbound.
• extra is the EIP-712 domain of the USDC contract — your signer needs it to construct the transferWithAuthorization signature.
• maxAmountRequired is atomic USDC (6 decimals).

2 — The X-PAYMENT header

Retry the same request with X-PAYMENT: base64(JSON):

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "base",
  "payload": {
    "signature": "0x…65-byte ECDSA…",
    "authorization": {
      "from": "0xYourAgentWallet…",
      "to": "0xEC89C6e7028b0e30E22eB3409d2F7c273EB20164",
      "value": "20000",
      "validAfter": "1765391000",
      "validBefore": "1765391060",
      "nonce": "0x…32 random bytes…"
    }
  }
}

3 — Server-side checks (in order)

1. Amount — authorization.value must cover maxAmountRequired.
2. OFAC blocklist — sanctioned payer addresses get 451 with error: "payer_blocked" before any payment processing.
3. Replay guard — each (payer, nonce) pair is single-use: 402 "authorization nonce already used".
4. Facilitator verify — off-chain signature/balance validation.

Only then does the data handler run.

4 — Settlement & the receipt

If the handler succeeds, Polyrank settles the transfer before responding and returns the receipt in the X-PAYMENT-RESPONSE header (base64 JSON):

{
  "success": true,
  "transaction": "0x…on-chain tx hash…",
  "network": "base",
  "payer": "0xYourAgentWallet…"
}

Settle-after-verify semantics protect you:

• Handler error (4xx/5xx) → no settlement. You are not charged for failures.
• Settlement failure → the transfer never executed; you get 402 with error: "settlement failed … you were not charged; retry with a fresh nonce".

Error quick-reference

Discovery

GET /x402/info (free, no payment) returns machine-readable metadata: endpoints, prices, networks, and this documentation URL. Point your agent framework's discovery at it.