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

# Orderbooks

> Access historical orderbook snapshots

The orderbooks endpoints provide access to historical bid/ask data collected from the Polymarket WebSocket feed since **January 1, 2026**. Each snapshot contains the full orderbook depth at a specific timestamp.

<Warning>
  Orderbook endpoints have stricter rate limits: **30 requests per minute**.
</Warning>

## Data Structure

Each orderbook snapshot contains bid and ask arrays as `[price, size]` tuples:

```json theme={null}
{
  "ts": 1768006613042,
  "asset_id": "113230976933674601135419276232321769865636781054804255103253100668166812267778",
  "market_id": "1034460",
  "outcome_index": 0,
  "bids": [[0.55, 1000], [0.54, 2500], [0.53, 5000]],
  "asks": [[0.56, 800], [0.57, 1500], [0.58, 3000]]
}
```

| Field           | Type    | Description                                                      |
| --------------- | ------- | ---------------------------------------------------------------- |
| `ts`            | integer | Unix timestamp in milliseconds                                   |
| `asset_id`      | string  | Token ID for the outcome                                         |
| `market_id`     | string  | Market ID                                                        |
| `outcome_index` | integer | Outcome position (0 = first outcome, typically "Yes")            |
| `bids`          | array   | Buy orders as `[price, size]` tuples, sorted by price descending |
| `asks`          | array   | Sell orders as `[price, size]` tuples, sorted by price ascending |

***

## Query Orderbooks

<ParamField path="GET" method="/orderbooks">
  Query orderbook snapshots with filters. Results are ordered by timestamp descending (most recent first).
</ParamField>

<Note>
  At least one of `market_id` or `asset_id` is required.
</Note>

### Query Parameters

<ParamField query="market_id" type="string">
  Filter by market ID.
</ParamField>

<ParamField query="asset_id" type="string">
  Filter by asset/token ID.
</ParamField>

<ParamField query="outcome" type="string">
  Filter by outcome. Accepts `yes`, `no`, `0`, or `1`.
</ParamField>

<ParamField query="from" type="integer">
  Start timestamp in milliseconds (inclusive).
</ParamField>

<ParamField query="to" type="integer">
  End timestamp in milliseconds (inclusive).
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Results per page (1–1000).
</ParamField>

<ParamField query="cursor_ts" type="integer">
  Timestamp cursor for pagination. Returns rows with `ts < cursor_ts`.
</ParamField>

### Examples

Get orderbook history for a market:

```bash theme={null}
curl "http://api.poly-data.xyz/orderbooks?market_id=1034460&limit=50"
```

Get orderbooks within a specific time range:

```bash theme={null}
curl "http://api.poly-data.xyz/orderbooks?market_id=1034460&from=1767290000000&to=1768010000000"
```

Filter by "Yes" outcome:

```bash theme={null}
curl "http://api.poly-data.xyz/orderbooks?market_id=1034460&outcome=yes&limit=100"
```

Response:

```json theme={null}
{
  "filters": {
    "market_id": "1034460",
    "asset_id": null,
    "outcome": null,
    "from": null,
    "to": null
  },
  "limit": 100,
  "count": 100,
  "next": {
    "cursor_ts": 1767950000000
  },
  "data": [
    {
      "ts": 1768006613042,
      "asset_id": "113230976933674...",
      "market_id": "1034460",
      "outcome_index": 0,
      "bids": [[0.55, 1000], [0.54, 2500]],
      "asks": [[0.56, 800], [0.57, 1500]]
    }
  ]
}
```

***

## Get Latest Orderbook

<ParamField path="GET" method="/orderbooks/latest">
  Get the most recent orderbook snapshot for a market or asset.
</ParamField>

<Note>
  At least one filter parameter (`market_id`, `asset_id`, or `outcome`) is required.
</Note>

### Query Parameters

<ParamField query="market_id" type="string">
  Filter by market ID.
</ParamField>

<ParamField query="asset_id" type="string">
  Filter by asset/token ID.
</ParamField>

<ParamField query="outcome" type="string">
  Filter by outcome. Accepts `yes`, `no`, `0`, or `1`.
</ParamField>

### Examples

Get latest orderbook for a market:

```bash theme={null}
curl "http://api.poly-data.xyz/orderbooks/latest?market_id=1034460"
```

Get latest orderbook for a specific token:

```bash theme={null}
curl "http://api.poly-data.xyz/orderbooks/latest?asset_id=113230976933674601135419276232321769865636781054804255103253100668166812267778"
```

Response:

```json theme={null}
{
  "ts": 1768006613042,
  "asset_id": "113230976933674601135419276232321769865636781054804255103253100668166812267778",
  "market_id": "1034460",
  "outcome_index": 0,
  "bids": [[0.55, 1000], [0.54, 2500], [0.53, 5000]],
  "asks": [[0.56, 800], [0.57, 1500], [0.58, 3000]]
}
```

<Info>
  This endpoint has a 500ms cache TTL for near real-time data access.
</Info>

***

## Get Orderbooks by Market ID

<ParamField path="GET" method="/orderbooks/:market_id">
  Convenience endpoint to get orderbook snapshots for a specific market. Results are ordered by timestamp descending.
</ParamField>

### Path Parameters

<ParamField path="market_id" type="string" required>
  Market ID.
</ParamField>

### Query Parameters

<ParamField query="outcome" type="string">
  Filter by outcome. Accepts `yes`, `no`, `0`, or `1`.
</ParamField>

<ParamField query="from" type="integer">
  Start timestamp in milliseconds (inclusive).
</ParamField>

<ParamField query="to" type="integer">
  End timestamp in milliseconds (inclusive).
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Results per page (1–1000).
</ParamField>

<ParamField query="cursor_ts" type="integer">
  Timestamp cursor for pagination. Returns rows with `ts < cursor_ts`.
</ParamField>

### Example

```bash theme={null}
curl "http://api.poly-data.xyz/orderbooks/1034460?limit=100"
```

Response:

```json theme={null}
{
  "market_id": "1034460",
  "filters": {
    "outcome": null,
    "from": null,
    "to": null
  },
  "limit": 100,
  "count": 100,
  "next": {
    "cursor_ts": 1767950000000
  },
  "data": [
    {
      "ts": 1768006613042,
      "asset_id": "113230976933674...",
      "market_id": "1034460",
      "outcome_index": 0,
      "bids": [[0.55, 1000], [0.54, 2500]],
      "asks": [[0.56, 800], [0.57, 1500]]
    }
  ]
}
```

***

## Pagination Example

For large historical queries, use cursor-based pagination. Start with a very high `cursor_ts` value and follow the `next` cursor:

```python theme={null}
import requests
import time

market_id = "1034460"
all_orderbooks = []
cursor_ts = "9999999999999"

while True:
    params = {"limit": 100, "cursor_ts": cursor_ts}

    response = requests.get(
        f"http://api.poly-data.xyz/orderbooks/{market_id}",
        params=params
    )

    if response.status_code == 429:
        print("Rate limited, waiting 60s...")
        time.sleep(60)
        continue

    data = response.json()

    if "data" not in data:
        print(f"Unexpected response: {data}")
        break

    all_orderbooks.extend(data["data"])
    print(f"Fetched {len(data['data'])} rows (total: {len(all_orderbooks)})")

    if data.get("next") and data["next"].get("cursor_ts"):
        cursor_ts = data["next"]["cursor_ts"]
    else:
        break

    time.sleep(0.1)  # Be kind to the API

print(f"Retrieved {len(all_orderbooks)} orderbook snapshots")
```

<Tip>
  Add a small delay between requests (e.g., `time.sleep(0.1)`) to avoid hitting the 30 requests/minute rate limit.
</Tip>

***

## Common Use Cases

<Columns cols={2}>
  <Card title="Backtesting" icon="clock-rotate-left">
    Fetch historical orderbooks within a time range to simulate trading strategies.
  </Card>

  <Card title="Spread Analysis" icon="chart-line">
    Calculate bid-ask spreads over time to analyze market liquidity.
  </Card>

  <Card title="Event Studies" icon="calendar-check">
    Study how orderbooks change around major news events.
  </Card>

  <Card title="Market Making" icon="scale-balanced">
    Analyze historical depth to calibrate market making parameters.
  </Card>
</Columns>