x402 Agent API

The Agent API sells Polyrank's deep data per request, priced in USDC on Base, using the open x402 protocol. There is no signup, no API key, and no subscription: your agent calls an endpoint, receives an HTTP 402 with payment requirements, signs a USDC authorization, and retries. Total integration is a few lines with the official SDKs.

Endpoints & prices

Base URL: https://api.polyrank.app (also served at https://api-agent.polyrank.app).

POST /v1/agent/rankings/custom takes the Ranking Builder's config shape (see Ranking Builder): a weights map of metric id → {weight, window} plus optional cohort filters — activity floors (min_trades, min_resolved, min_volume_usdc, min_active_days), value gates (min_realized_pnl, min_profit_factor, min_win_rate_pct, max_roi_pct, since_date), recency (active_within_days, first_trade_within_days, max_volume_usdc, best_category), relative percentile gates (skill_gates: top-X% on any metric, max 8), and absolute raw-value ranges (metric_filters: {metric, min?, max?} on any displayable metric's lifetime value, max 12 — unmeasured wallets are excluded by definition). Three web-only filters are NOT applied on the agent tier (exclude_bonders, smart_money_tags_any_of, follower_count_max) — they need auxiliary tables the lean executor skips; configs carrying them are accepted with those keys ignored. The top-level na_policy field ("exclude" default, or "neutral_50") controls wallets missing a weighted metric — exclude them (only fully-measured wallets qualify) or score the gap as a neutral 50th percentile — and is honored identically to the web Builder, including on /v1/agent/rankings/published/{slug}. Invalid configs are rejected with 400 before settlement — you are never charged for a rejected request.

The flow in one diagram

Agent                        Polyrank                      Facilitator
  │ GET /v1/agent/…             │                               │
  │────────────────────────────▶│                               │
  │   402 {x402Version, accepts}│                               │
  │◀────────────────────────────│                               │
  │ sign EIP-3009 (USDC)        │                               │
  │ GET … + X-PAYMENT           │                               │
  │────────────────────────────▶│  verify                       │
  │                             │──────────────────────────────▶│
  │                             │◀──── isValid ─────────────────│
  │                             │  run handler, then settle     │
  │                             │──────────────────────────────▶│
  │  200 + data                 │◀──── tx hash ─────────────────│
  │  + X-PAYMENT-RESPONSE       │                               │
  │◀────────────────────────────│                               │

You are charged only when the request succeeds — failed handlers never settle, and a failed settlement returns 402 without moving your USDC. The settlement receipt (with the on-chain transaction hash) comes back in the X-PAYMENT-RESPONSE header. Full wire detail: Protocol.

Try the 402 right now

curl -s https://api.polyrank.app/v1/agent/signals/smart-money | jq

{
  "x402Version": 1,
  "error": "payment required: Recent smart-money signal events. Supports ?since= cursor (incremental → $0.02 effective)",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "50000",
      "resource": "https://api.polyrank.app/v1/agent/signals/smart-money",
      "description": "Recent smart-money signal events. Supports ?since= cursor (incremental → $0.02 effective)",
      "mimeType": "application/json",
      "payTo": "0xEC89C6e7028b0e30E22eB3409d2F7c273EB20164",
      "maxTimeoutSeconds": 60,
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "extra": { "name": "USD Coin", "version": "2" }
    }
  ]
}

maxAmountRequired is in atomic USDC units (6 decimals) — 50000 = $0.05. asset is the canonical USDC contract on Base; extra is the EIP-712 domain your signer needs.

Pay it

You need a funded wallet with USDC on Base — see the cost math below for what a given budget buys. The official x402 SDKs handle the whole handshake:

Cost math

Always assert maxAmountRequired against your budget before signing — see the guardrails section of each quickstart.