Historical trades

Use GET /historical/trades to read source-independent executions in global collector-time order. The response contains flat trade rows, rather than the type and data event envelope shown on the Trades schema page.

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

Exact venue-native instrument, when you need to narrow the market further.

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/trades?source=hyperliquid&market=BTC&limit=2"

Example response shape:

{
  "items": [
    {
      "event_id": "trade-123",
      "source": "hyperliquid",
      "market": "BTC",
      "instrument": null,
      "collector_timestamp": 1727200000000,
      "exchange_timestamp": 1727199999998,
      "source_capture_id": "capture-123",
      "schema_version": 2,
      "price": 63450.5,
      "quantity": 0.2,
      "side": "buy",
      "order_id": "order-123",
      "maker": null,
      "taker": null,
      "liquidation": false
    }
  ],
  "has_more": false,
  "next_cursor": null
}

items contains flat rows ordered by collector_timestamp across matching sources. event_id, source, market, collector_timestamp, source_capture_id, schema_version, price, and quantity are required in each row. price and quantity are numbers. instrument, exchange_timestamp, side, order_id, maker, taker, and liquidation 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 or absent. 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.

Trades schema for SDK and snapshot 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