Provides historical event updates for futures order books, including bid and ask price levels, volumes, and sequence information for each update across exchanges.
⚠️ Historical Data Availability Notice (click to expand)
To ensure optimal performance and system reliability, historical data for Order Book Snapshots and Order Book Events via REST API is available for the past 18 months only. If you require access to deeper historical data—for use cases such as machine learning model training, backtesting strategies, or conducting long-term research—we strongly recommend using our bulk file delivery options. These solutions are designed to efficiently handle large-scale data access and offer full historical coverage across all supported exchanges and instruments.
Why this limitation?
- REST APIs are optimized for recent, low-latency access to granular data. Using them for deep historical queries can lead to performance degradation, rate limiting, and an inconsistent experience. Bulk delivery options are purpose-built for large data pulls and are the best fit for these needs.
🚨 Important Notice for BitMEX Data (click to expand)
BitMEX’s volume field represents the number of contracts traded, not the volume in the base asset. To obtain the correct volume, users must adjust for contract size using underlyingToPositionMultiplier from our Reference endpoint.
For details on this calculation and how to retrieve the correct values, see our Changelog Update.
Time Range Limit
The maximum time range (difference between startDate and endDate) is 18 months.
Not specifying startDate and endDate
If the startDate and endDate query parameters are not provided, the API will return the data from the previous 24 hours.
RESPONSE DATA (click to expand)
BitMEX’s volume field represents the number of contracts traded, not the volume in the base asset. To obtain the correct volume, users must adjust for contract size using underlyingToPositionMultiplier from our Reference endpoint.
For details on this calculation and how to retrieve the correct values, see our Changelog Update.
RESPONSE DATA
| JSON Field/Path | Value Type | Description |
|---|---|---|
| payload.metadata.requestedStartDate | integer | The start date and time requested for the order book event data. |
| payload.metadata.requestedEndDate | integer | The end date and time requested for the order book event data. |
| payload.metadata.returnedStartDate | integer | The actual start date and time returned for the order book event data. |
| payload.metadata.returnedEndDate | integer | The actual end date and time returned for the order book event data. |
| payload.metadata.next | string | The URL for the next page of data (nullable if there is no next page). |
| payload.metadata.api-version | string | The version of the API used for this request. |
| payload.data[].instrument | string | The instrument or trading pair for which the order book event data is recorded (e.g., BTCUSD_PERP). |
| payload.data[].exchange | string | The name of the exchange where the order book event data applies (e.g., binance). |
| payload.data[].exchangeTimestamp | integer | The timestamp from the exchange when the order book event occurred. |
| payload.data[].exchangeTimestampNanoseconds | integer | The nanoseconds part of the timestamp, representing sub-second precision. |
| payload.data[].sequence | string | The sequence number of the order book event. |
| payload.data[].ask | array | An array containing the ask-side order book levels for this event. |
| payload.data[].ask[].price | float | The price level of the ask order. |
| payload.data[].ask[].volume | float | The volume at the given ask price level. |
| payload.data[].ask[].numOrders | integer | The number of orders at the given ask price level (nullable if not applicable). |
| payload.data[].bid | array | An array containing the bid-side order book levels for this event. |
| payload.data[].bid[].price | float | The price level of the bid order. |
| payload.data[].bid[].volume | float | The volume at the given bid price level. |
| payload.data[].bid[].numOrders | integer | The number of orders at the given bid price level (nullable if not applicable). |