API Overview - PolyNode

The polynode API provides two main surfaces:

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

https://api.polynode.dev/v3

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:

# Query string
curl "https://api.polynode.dev/v3/stats?key=pn_live_..."

# Bearer header
curl -H "Authorization: Bearer pn_live_..." https://api.polynode.dev/v3/stats

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:

Metric	Count
Fills (trades)	1+ billion
Positions	200+ million
Unique wallets	2.5+ million
Redemptions	160+ million
Splits	30+ million
Merges	14+ million
Markets tracked	1.07 million
Token prices	2 million

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, "total_volume": 43013258.515682 }
{ "price": 0.42 }

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:

{ "amount": "120469388830" }

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:

{ "volume_all_time": "99993.937724000003072433173656463623046875" }

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.

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:

Shape	Endpoints	Top-level data key
Single-object	`GET /v3/wallets/{addr}`, `GET /v3/wallets/{addr}/pnl`, `GET /v3/markets/{token_id}/price`, `GET /v3/conditions/{cid}`, `GET /v3/builders/{code}`, `GET /v3/stats`	Fields at top level (no wrapper)
Named list	`/v3/trades`, `/v3/wallets/{addr}/trades`, `/v3/markets/{token_id}/trades`, `/v3/markets/slug/{slug}/trades`, `/v3/builders/{code}/trades`	`"trades": [...]`
Named list	`/v3/positions`, `/v3/wallets/{addr}/positions`	`"positions": [...]`
Named list	`/v3/leaderboard`	`"leaderboard": [...]`
Named list	`/v3/tags`, `/v3/builders`	`"tags": [...]`, `"builders": [...]`
Named list	`POST /v3/wallets/batch`	`"wallets": [...]`
Generic list	Everything else (fees, resolutions, splits, merges, NRC, activity, redemptions, tag-leaderboard, tag-markets, market-positions, condition-positions, market-by-condition, market-search, tokens/info)	`"data": [...]`

All list responses also include rows_returned, has_more, offset, limit, elapsed_ms.

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 and are rate limited per key.

Plan	Standard V3 REST	Heavy V3 trade endpoints
Starter	1,000 req/min	1,000 req/min
Growth	2,000 req/min	1,500 req/min
Enterprise	4,000 req/min default; custom by agreement	1,500 req/min default; custom by agreement

See Rate Limits for the full tier table and heavy-endpoint details.

Pagination

All list endpoints support:

?limit=N — results per page (default 100, max 300)
?offset=N — skip N results

Responses include the actual limit used, plus has_more: true/false to indicate if more pages exist. 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.

{
  "data": [...],
  "rows_returned": 100,
  "has_more": true,
  "offset": 0,
  "limit": 100,
  "elapsed_ms": 12
}

Endpoint categories

Category	Endpoints	What you can do
Wallet P&L	4	Wallet summary, dual P&L breakdown, batch queries, enriched positions
Wallet Activity	6	Trades, redemptions, splits, merges, NRC, combined activity
Combos	7	Combo markets, wallet combo positions, combo trades, lifecycle activity, and additive wallet summaries
Markets	8	Search, lookup by condition/token/slug, trades, positions, prices, candles
Leaderboard	3	Global P&L rankings, tag discovery, tag leaderboards
Builders	3	Builder rankings, stats, attributed trades
Global	5	Platform stats, trade feed, fees, resolutions, conditions
Tokens	1	Token price and market metadata

Explorer

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

​V3 Data API — Base URL

​Authentication

​Dataset Scale

​Key features

​Amounts and precision

​Identifiers and large numbers

​Nullable fields

​Response envelopes

​Timestamps

​Rate limits

​Pagination

​Response format

​Endpoint categories

​Explorer