Skip to main content
The polynode API provides two main surfaces:
  1. V3 Historical Data — query the complete Polymarket V1 + V2 historical dataset. 1.2 billion fills, 228 million positions, 2.7 million wallets. Dual P&L (realized + unrealized), position tracking with settlement status, builder analytics, market search, and leaderboards.
  2. Real-time Streaming — live WebSocket feeds for settlements, trades, price updates, position changes, and more. See the WebSocket tab.
The V3 endpoints are live and provide the most comprehensive Polymarket dataset available.

​
V3 Data API — Base URL

​
Authentication

Every /v3/* endpoint requires an API key. Pass it either as a key query parameter or as a bearer token in the Authorization header:
Get a key from the dashboard. All examples in this section assume ?key=YOUR_KEY is appended (omitted only for brevity in the code blocks).

​
Dataset Scale

Query GET /v3/stats for live counts. Current scale:

​
Key features

  • Dual P&L — realized and unrealized profit/loss for every wallet, computed from the full event history using weighted-average cost basis math
  • Position status — every position is tagged as open, closed, redeemable, or redeemed based on live settlement data
  • Redeemable payouts — see exactly how much USDC a wallet can claim from resolved markets
  • Builder attribution — 77 million fills attributed to 1,502 unique builders
  • Batch queries — query up to 100 wallets in a single call
  • Time-range filters — filter trades, redemptions, and activity by Unix timestamp
  • Market search — full-text search across 1 million+ market questions

​
Amounts and precision

Monetary fields come in two conventions depending on the endpoint: Decimal USD (JSON number). Used by aggregated P&L responses (wallet summary, batch, pnl, positions) and by token-price responses (/v3/markets/{token_id}/price, /v3/tokens/{token_id}):
net_realized_pnl: 22053845.825455 means $22,053,845.83 USD**. `price: 0.42` means **$0.42 per share (Polymarket outcome prices are always in the range 0–1). Raw 6-decimal USDC (JSON string). Used by event-level rows — fees, splits, merges, redemptions, NRC, activity, tag-leaderboard rollups, market-positions rows:
Divide by 1_000_000 to get USD. "120469388830" is 120,469.38883 USDC. Full-precision decimal (JSON string). Used by raw subgraph fields like volume_all_time, liquidity, price:
These are stored at full Postgres numeric precision (up to ~50 digits). Round on the client; do not parse as a JS Number. Each endpoint’s response-fields table explicitly notes which convention applies.

​
Identifiers and large numbers

Polymarket token_id and position_id values are 78-digit decimal integers (uint256). They are returned as JSON strings so they survive standard JSON parsers — IEEE 754 doubles cannot represent them. Treat them as opaque strings; do not parse them as numbers.

​
Polymarket Protocol V2 markets

Markets on Polymarket Protocol V2, Polymarket’s new market system, appear in the same endpoints with the same fields and units. Their rows add protocol_version: "v2", module, structural_condition_id, on multi-outcome markets neg_risk_event_id, and on resolved markets the exact result as payouts_ppm. Endpoints that take a condition id accept the 66-character form and Polymarket’s 31-byte form. Elsewhere on this page, “V1” and “V2” refer to Polymarket’s exchange before and after the April 2026 exchange upgrade. See Polymarket Protocol V2 markets.

​
Nullable fields

Many fields can be null in real responses even when the example shows a populated value — typically when a row was created before the metadata pipeline backfilled it, or when a market hasn’t resolved yet. Each endpoint’s response-fields table has a Nullable column. Defensive clients should accept null for any field marked nullable, plus for any field whose row predates indexing.

​
Response envelopes

Endpoints fall into three envelope shapes: Standard ungrouped list responses also include rows_returned, has_more, offset, limit, and elapsed_ms. Grouped trade responses are the exception: with group_by=order_hash, the response includes trades, rows_returned, grouped_by, and elapsed_ms, but omits has_more, offset, and limit.

​
Owner addresses

Pass an owner EOA to a wallet endpoint below and the response combines the EOA’s Polymarket wallets (Safe, proxy, deposit wallets) that have data for that endpoint. Passing a Safe, proxy or deposit wallet returns just that wallet, as before.
The response keeps its usual fields, sums them across the combined wallets, and lists those wallets in wallets. Here the Safe has -292.08 over 479 positions and the deposit wallet -65.65 over 9 (excerpt, values from 2026-10-21):
Endpoints that accept an owner EOA: Combined responses:
  • address (wallet on credits routes) is still the address you passed.
  • wallets lists the EOA first when it has its own history, then its Safe, proxy and deposit wallets. Only wallets with data for that endpoint are listed, so wallets can differ between endpoints.
  • Totals and counts are summed across the combined wallets, and time-series buckets are summed per bucket. A field that cannot be summed, such as a status, is null when the combined wallets disagree.
  • Lists keep the endpoint’s sort order, and limit, offset, has_more, and next_offset page through the combined list. Combining covers the first 10,000 rows (offset + limit up to 10,000). A deeper page returns only the address you passed, with no wallets.
  • Rows are never merged across wallets: two wallets holding the same token return two rows, and a fill between two of the owner’s wallets appears once for each wallet. Include wallet when you key rows by token_id or id.
  • In POST /v3/wallets/batch, each owner EOA is combined on its own. The response keeps one element per requested address, in request order.
  • If any combined wallet returns an error, the request returns that error instead of a partial result. If combining does not finish in time, the request returns 503.
Nothing changes when:
  • You pass a Safe, proxy, or deposit wallet, or an EOA that owns no wallets with data. The response is the same as before, with no wallets field.
  • You call rebates, rewards, Copy PnL, webhooks, or WebSocket wallet filters. These still match only the exact address you pass. V1 and V2 wallet endpoints are also unchanged.

​
Timestamps

All Unix timestamps in responses are in seconds (e.g., "1778674056"). The resolved_at field in resolutions uses milliseconds (e.g., "1778674836000"). Datetime strings like updated_at are in UTC.

​
Rate limits

V3 REST data endpoints require a paid API key. Limits are shared across all API keys owned by the same account, so keys can be used at the same time without multiplying the account’s throughput. See Rate Limits for the full tier table and heavy-endpoint details.

​
Pagination

Most list endpoints support:
  • ?limit=N — results per page (usually default 100 and max 300)
  • ?offset=N — skip N results
The Builder trader leaderboard is an explicit exception: it returns at most 100 rows per request and supports the first 500 ranks. Ungrouped responses include the actual limit used, plus has_more: true/false to indicate if more pages exist. Grouped trade requests still accept limit and offset, but their responses omit those fields and has_more; track the requested values and stop after an empty trades array. For deep trade-history walks, prefer after and before time windows instead of very large offsets.

​
Response format

Every response includes elapsed_ms showing server-side query time in milliseconds.

​
Endpoint categories

​
Explorer

Browse the data interactively with pre-built SQL recipes at explorer.polynode.dev.