Historical L2 order books

Use GET /historical/orderbook-l2 to read stateless L2 source events in global collector-time order. Each flat REST row has fixed price and size fields for up to 25 levels per side. The L2 schema page describes SDK and snapshot event envelopes and how to reconstruct a complete book; this endpoint returns the source observations without doing that reconstruction. source_event_is_snapshot: true identifies a complete source snapshot. false identifies a sparse update with absolute level quantities. Do not treat every returned row as a complete order book.

Access and time range

Omit both start and end to query the latest ten minutes without authentication. Supply either bound to query a chosen interval with a Polaris API key in Authorization: Bearer YOUR_API_KEY. start and end are inclusive collector timestamps in Unix milliseconds. With only start, the query runs through now; with only end, it covers the preceding ten minutes.

Query parameters

string

Exact source ID. Omit to query across sources.

string

Exact normalized routing market. Omit to query across markets.

string

Venue-native instrument filter.

integer

Inclusive collector time in Unix milliseconds. Requires a Polaris API key.

integer

Inclusive collector time in Unix milliseconds. Requires a Polaris API key.

integer

default:200

Page size from 1 to 1000.

string

Opaque next_cursor from the previous page of the same query.

Use Catalog to find exact source and market IDs.

Request and response

curl "https://api.polaris.supply/historical/orderbook-l2?source=hyperliquid&market=BTC&limit=2"

Example response excerpt, showing level 00 and 24 only:

{
  "items": [
    {
      "event_id": "book-123",
      "source": "hyperliquid",
      "market": "BTC",
      "instrument": null,
      "collector_timestamp": 1727200000000,
      "exchange_timestamp": null,
      "source_capture_id": "capture-123",
      "schema_version": 2,
      "source_event_is_snapshot": true,
      "bid_px_00": 63450.0,
      "bid_sz_00": 1.2,
      "ask_px_00": 63451.0,
      "ask_sz_00": 0.8,
      "bid_px_24": null,
      "bid_sz_24": null,
      "ask_px_24": null,
      "ask_sz_24": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Every full item also has all intermediate bid_px_01 through bid_px_23, bid_sz_01 through bid_sz_23, ask_px_01 through ask_px_23, and ask_sz_01 through ask_sz_23 fields. Each level price or size is a nullable number. event_id, source, market, collector_timestamp, source_capture_id, schema_version, and source_event_is_snapshot are required. instrument and exchange_timestamp are present but can be null.

Pagination and errors

When has_more is true, send next_cursor as cursor while keeping the other query parameters unchanged. Stop when has_more is false; next_cursor is then null. The API documents 400 for an invalid request, 401 when authentication is needed, 422 when query work exceeds its limit, 429 when the request quota is exceeded, and 503 when the service is unavailable. Narrow the requested time range after a 422; respect Retry-After after a 429. Errors have an error object with code, message, and resolution.

L2 order-book schema for reconstruction and SDK event fields
Python SDK, TypeScript SDK, and Rust SDK for client methods
Snapshots for bulk historical files

​Access and time range

​Query parameters

​Request and response

​Pagination and errors

​Related documentation

Access and time range

Query parameters

Request and response

Pagination and errors

Related documentation