Polydata API v3
A fast analytics API for Polymarket — traders, leaderboards, markets, events, weather, whales, oracle accuracy and more. Everything is served straight from our database; no third-party API ever sits on the request path.
Introduction
The API is organized into 13 verticals. Every endpoint returns JSON and carries the same tariff-metadata envelope, so you always know your plan, whether the result was trimmed, and what to upgrade for more.
All you need to make your first call: a base URL, an API key, and the
X-API-Key header. Jump straight to the
quickstart if you like.
Base URL
https://dev-api.polydata.pro/api/v3
All paths below are relative to this base. HTTPS only.
Authentication
Every request (except the public health/status probes) must send your API
key in the X-API-Key header.
X-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
- Your key is delivered directly and once. We store only its SHA-256 hash — we cannot recover or re-send the raw key. Treat it like a password.
- Missing / invalid / revoked key → HTTP 401.
- Public probes that need no key:
GET /health,GET /status,GET /status/public.
Plans & rate limits
Beta cohort default tier: explorer — 300 requests / 60 s (≈5 req/s).
| Tier | Requests / 60 s | History cap | Compare wallets | Export |
|---|---|---|---|---|
| free | 30 | 30 d | 1 | no |
| explorer (you) | 300 | 180 d | 2 | no |
| trader | 1 000 | 365 d | 3 | yes |
| alpha | very high | all | 10 | yes |
Retry-After header (seconds until the next window). Back off and
retry after that delay. Need more during the beta? Ask us to bump your key to
trader — no new key required.
Response envelope
Every response carries tariff metadata alongside the data. When you hit a
plan cap the API does not hard-fail — it returns
HTTP 200 with the result trimmed and
truncated: true.
| Field | Meaning |
|---|---|
plan | Your effective tier for this call. |
truncated | true if the result was trimmed by a plan cap. |
lock_reason | e.g. "plan_limit" when a feature is locked, else null. |
upgrade_hint | Tier that would unlock more, or null. |
available_sections / locked_sections | What this tier can / cannot see. |
max_history_days | History window cap (null = no cap / all history). |
max_rows | Row cap for the current call. |
Quickstart
# Health (no key needed) curl https://dev-api.polydata.pro/api/v3/health # Trader stats (with your key) curl -H "X-API-Key: pk_live_xxxxxxxx" \ "https://dev-api.polydata.pro/api/v3/trader/0x015458216dd5521addbe6f9e87a8a0e841ab5b34/stats" # Top traders, 30-day window curl -H "X-API-Key: pk_live_xxxxxxxx" \ "https://dev-api.polydata.pro/api/v3/leaderboard/traders?period=30d"
A 200 with a JSON body means you're in.
A 401 means the key header is missing or wrong;
a 429 means you hit the rate limit (honor Retry-After).
Health & status
public · no key| GET | /health | Liveness + database reachability. |
| GET | /status | Same payload (legacy alias). |
| GET | /status/public | Per-subsystem freshness grades for the public status page. |
Trader
{address} = lowercase 0x…| GET | /trader/{address}/stats | Lifetime summary: trades, volume, active days, unique markets, username. |
| GET | /trader/{address}/activity/daily?limit=90 | Per-day time series (max 365). |
| GET | /trader/{address}/markets?limit=50 | Top markets by volume (max 200). |
| GET | /trader/{address}/trades?limit=50 | Recent fills, keyset pagination (max 200). |
| GET | /trader/compare?address=0x..&address=0x.. | Side-by-side compare (explorer: 2 wallets). |
| POST | /trader/{address}/export-jobs | Queue a snapshot export (trader/alpha only). |
| GET | /trader/export-jobs/{job_id} | Export job status. |
| GET | /trader/export-jobs/{job_id}/download | Download finished export. |
Leaderboard
period = 1d · 7d · 30d| GET | /leaderboard/traders?period=30d | Top traders ranked by realized PnL (real_pnl). See disclaimer. |
| GET | /leaderboard/markets?period=30d | Top markets by volume. |
Market
{condition_id} = String PK| GET | /market/{condition_id}/overview | Metadata + all-time aggregates + resolution + recent fills. |
| GET | /markets/search?q=... | Search markets by title (explorer: up to 50 rows). |
Event
| GET | /event/{event_id} | Event metadata + aggregate rollup. |
| GET | /event/{event_id}/markets?limit=&offset= | Markets belonging to the event. |
| GET | /event/{event_id}/traders?limit=&offset= | Top traders on the event. |
Platform stats
cache-first| GET | /stats | Platform overview: volume, active markets, traders. |
| GET | /stats/hourly | Last-24h hourly activity. |
| GET | /stats/daily?days= | Per-day platform rollup. |
| GET | /stats/growth | Growth / trend metrics. |
PMX Index
open on all tiers| GET | /pmx-index | Current snapshot: composite + 5 sub-indices. |
| GET | /pmx-index/{name}/history?interval=1h|6h|1d | History of one sub-index. name ∈ {PMX-Volume, PMX-Whale, PMX-Politics, PMX-Crypto, PMX-Sentiment}. |
Oracle (PolyOracle)
Brier score · calibration| GET | /oracle/leaderboard | Top traders by forecasting accuracy. |
| GET | /oracle/trader/{address} | Accuracy breakdown for one wallet. |
Whales
| GET | /whales | Top wallets by size / activity. |
| GET | /whales/moves | Recent large trades. |
| GET | /whales/flow?market_id= | Net whale flow (optionally per market). |
Screener
| GET | /screener | Advanced market filtering. |
| GET | /screener/summary | Aggregate screener summary. |
Research & export
export → trader/alpha| GET | /research/datasets | Catalog of exportable datasets. |
| POST | /research/export-jobs | Queue a CSV/Parquet dataset export. |
| GET | /research/export-jobs/{job_id} | Export job status. |
| GET | /research/export-jobs/{job_id}/download | Download finished export. |
Weather
9 endpoints| GET | /weather/cities | City grid + live weather markets per city. |
| GET | /weather/city/{city} | City overview: events, brackets, forecast, counts. |
| GET | /weather/city/{city}/forecast | Multi-source TMAX/TMIN forecast time series. |
| GET | /weather/city/{city}/actuals | Observed daily highs/lows. |
| GET | /weather/city/{city}/anomalies | Deviation vs climate normals. |
| GET | /weather/city/{city}/markets | Weather markets for the city + trade stats. |
| GET | /weather/traders | Top weather-market traders. |
| GET | /weather/forecast-evolution/{city}/{date} | How a forecast for a date evolved over time. |
| GET | /weather/bot-bundle | Compact multi-city snapshot for bots. |
What real_pnl means
The real_pnl value on /trader/* and the rank on
/leaderboard/traders is realized PnL only,
computed over markets that have resolved, using the canonical
cash-flow formula:
What we deliberately do NOT include:
- Unrealized PnL (open positions). Mark-to-market on unresolved markets is excluded. The Polymarket UI "Profit" figure does include it, so for wallets with many open positions our number is intentionally lower than the UI.
- Resolutions we don't yet have a winner record for. A class
of short-term markets (minute-scale crypto Up/Down, dated
sports) is archived upstream faster than our sync can capture the resolution.
For short-term-heavy traders this makes our
real_pnllower than the UI.
Example from our parity audit: trader swisstony shows
UI Profit ≈ $9.36M vs v3 real_pnl ≈ $5.05M. The gap is entirely
missing short-term resolutions plus unrealized value — the formula itself is
bit-exact against our raw data. Bottom line: our numbers are a
conservative, realized-only measure.
Status page
Live system health (no login):
https://dev-api.polydata.pro/api/v3/status/public # raw JSON https://polydata.pro/status # human-readable page
If you see elevated errors, check the status page before contacting support — it shows per-subsystem freshness (serving tables, trades, markets).
Support & beta terms
Pre-GA. Endpoints, response shapes, and limits may change with notice. Export jobs are best-effort. No uptime SLA during the beta.
You're in the beta because your feedback shapes GA. Please report any number that looks wrong (send the wallet/market + what you expected), latency spikes, 5xx errors, or endpoints/fields you wish existed.
Contact: support@polydata.pro (or your direct beta channel).