> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polynode.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> polynode API reference. Real-time streaming, historical data, P&L analytics, market data, and more.

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](/websocket/overview).

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:

```bash theme={null}
# 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](https://polynode.dev/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}`):

```json theme={null}
{ "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:

```json theme={null}
{ "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`:

```json theme={null}
{ "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](/guides/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.

```json theme={null}
{
  "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](/data/wallets/summary)    | 4         | Wallet summary, dual P\&L breakdown, batch queries, enriched positions                                 |
| [Wallet Activity](/data/wallets/trades) | 6         | Trades, redemptions, splits, merges, NRC, combined activity                                            |
| [Combos](/data/combos/overview)         | 7         | Combo markets, wallet combo positions, combo trades, lifecycle activity, and additive wallet summaries |
| [Markets](/data/markets/search)         | 8         | Search, lookup by condition/token/slug, trades, positions, prices, candles                             |
| [Leaderboard](/data/leaderboard/global) | 3         | Global P\&L rankings, tag discovery, tag leaderboards                                                  |
| [Builders](/data/builders/list)         | 3         | Builder rankings, stats, attributed trades                                                             |
| [Global](/data/global/stats)            | 5         | Platform stats, trade feed, fees, resolutions, conditions                                              |
| [Tokens](/data/tokens/info)             | 1         | Token price and market metadata                                                                        |

## Explorer

Browse the data interactively with pre-built SQL recipes at [explorer.polynode.dev](https://explorer.polynode.dev).