x402 Agent API
Pay-per-request Polymarket skill data for AI agents — USDC on Base, no subscription, no API key.
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.
The free /v1/public/* API (see Quickstart) covers
leaderboards and commodity stats. The paid agent tier adds the deep grid:
full lifetime metrics, smart-money tags, per-market positioning, and the
24-hour signal stream.
Endpoints & prices
Base URL: https://api.polyrank.app (also served at
https://api-agent.polyrank.app).
| Endpoint | Price | Returns |
|---|---|---|
GET /v1/agent/trader/{proxy} | $0.005 | Full lifetime metrics row for one wallet |
GET /v1/agent/trader/{proxy}/tags | $0.005 | Smart-money tags + scores + rationale |
GET /v1/agent/market/{conditionId} | $0.01 | Skilled-cohort consensus vs market mid |
GET /v1/agent/market/{conditionId}/positioning | $0.02 | Top-200 positioned wallets: side, size, avg entry, unrealized P&L, tags |
GET /v1/agent/signals/smart-money | $0.01 | Last-24h smart-money signal events |
GET /x402/info | free | Machine-readable endpoint + payment discovery |
More endpoints (trader playbook, market flow, custom rankings) are coming —
they will appear in /x402/info when live.
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 (last 24h)",
"accepts": [
{
"scheme": "exact",
"network": "base",
"maxAmountRequired": "10000",
"resource": "https://api.polyrank.app/v1/agent/signals/smart-money",
"description": "Recent smart-money signal events (last 24h)",
"mimeType": "application/json",
"payTo": "0xEC89C6e7028b0e30E22eB3409d2F7c273EB20164",
"maxTimeoutSeconds": 60,
"asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"extra": { "name": "USD Coin", "version": "2" }
}
]
}maxAmountRequired is in atomic USDC units (6 decimals) — 10000 = $0.01.
asset is the canonical USDC contract on Base; extra is the EIP-712
domain your signer needs.
Pay it
You need a funded wallet — ~$1 of USDC on Base buys 100 signal pulls. The official x402 SDKs handle the whole handshake:
TypeScript quickstart
@x402/fetch + viem — a paid call in ~10 lines.
Python quickstart
x402[httpx] + eth-account — for quants and bot builders.
Cost math
| Budget | Buys you |
|---|---|
| $0.10 | 20 trader profiles |
| $1 | 100 signal pulls or 50 market positioning snapshots |
| $5 | A day of aggressive polling for a small strategy bot |
Always assert maxAmountRequired against your budget before signing —
see the guardrails section of each quickstart.