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).

The smart-money in /v1/agent/reports/smart-money and /v1/agent/signals/smart-money is a historical id, kept so existing integrations and paid agents keep working: the first two serve the weekly Skill Report, the third the tagged-trader signal feed (large trades by wallets carrying a behaviour tag — tags describe size and style, not a proven record).

POST /v1/agent/rankings/custom takes exactly the request the main API's POST /v1/rankings/custom takes — the same schema object, strict at every level (see Ranking Builder): a weights map of metric id → {weight, window} over the 84 catalog metrics at any window they exist at, plus the copy-engine score sk_score_14d and the entry-timing ids at lifetime; and the full filters set — activity floors, value gates, recency (active_within_days, active_within_hours), categories / best_category, exclude_bonders, skill_gates and metric_filters (each with a window), copy_engine, timing, cluster_policy, copy_placeable, smart_money_tags_any_of and follower_count_max — all applied as the web Builder applies them. Two filters are refused on every rail, here and on the main API: market_kinds and exchange_versions (no per-wallet data exists for them). The options explain, extra_metrics, extra_engine_metrics, include_raw, include_verdict, include_cluster / dedupe_clusters, sort_by / sort_dir and na_policy behave as on the main API.

as_of (YYYY-MM-DD) is honoured or refused, never ignored. The board is ranked from that day's metric snapshot (lifetime window, wallet grain, the snapshotted metrics and the filters the snapshot can answer), and the response echoes as_of. Any input the snapshot cannot answer — a windowed weight, a copy_engine gate, explain, a non-composite sort, a day with no snapshot — is a 400 with the reason. GET /v1/agent/metrics/windows (free) lists which metric exists at which window and exactly what as_of honours.

An unknown field anywhere in the body is a 400 (until 2026-10-17 an unknown top-level field — including as_of — was silently dropped and the live board billed). Every invalid config is rejected with 400 before settlement — you are never charged for a rejected request. To reproduce one of the Builder's goals, POST its request from GET /v1/agent/rankings/goals (free).

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 tagged-trader signal events (large trades by tagged wallets). 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 tagged-trader signal events (large trades by tagged wallets). 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.