Order Book Data

GET

/download

Get Order Book Snapshots

Retrieve order book snapshots showing bid and ask levels with prices and quantities.

Python SDK Usage

python

1# Get order book snapshots
2df = client.get_orderbook(
3    symbol="BTCUSDT",
4    exchange=chd.exchanges.BINANCE_SPOT,
5    start_date="2025-08-01",
6    end_date="2025-08-01"
7)
8
9# Data includes bid/ask levels with prices and quantities
10print(df.head())
11

Data Format - CommonOrderbookEvent

Order book data is stored using the CommonOrderbookEvent structure, which captures both snapshots and incremental updates from exchanges:

Schema Overview

Each orderbook event contains timing information, exchange metadata, and individual price level updates for either bids or asks.

Field Definitions

Field	Type	Nullable	Description
received_time	INT64	No	Unix timestamp (nanoseconds) when our system received the event
event_time	INT64	No	Unix timestamp (exchange dependent on timescale) when the exchange generated the event
transaction_time	INT64	Yes	Exchange-specific transaction timestamp (when available)
symbol	STRING	No	Trading pair symbol (e.g., "BTCUSDT")
event_type	STRING	No	Type of orderbook event ("snapshot" or "update")
first_update_id	INT64	Yes	First update ID in the update sequence
final_update_id	INT64	Yes	Final update ID in the update sequence
prev_final_update_id	INT64	Yes	Previous final update ID (for gap detection)
last_update_id	INT64	Yes	Last update ID processed by the exchange
side	STRING	No	Order book side ("bid" or "ask")
price	STRING	No	Price level (stored as string for precision)
quantity	STRING	No	Quantity at price level (stored as string for precision)
order_count	INT64	Yes	Number of orders at this price level (when available from exchange)

Event Types

Snapshot Events

Complete orderbook state at a point in time

event_type = "snapshot"
Contains full bid/ask levels
Used for initialization
Overrides previous state with new data

Update Events

Incremental changes to orderbook

event_type = "update"
Single price level change
quantity = "0" means level removal

Working with the Data

python

1# Reconstruct orderbook from events
2import cryptohftdata as chd
3from datetime import datetime, timedelta
4import tqdm
5
6# Initialize the client
7client = chd.CryptoHFTDataClient(api_key="your-api-key-here")
8
9# Load orderbook events
10df = client.get_orderbook(
11    symbol="BTCUSDT",
12    exchange=chd.exchanges.BINANCE_FUTURES,
13    start_date="2025-08-01",
14    end_date="2025-08-01"
15)
16
17# Convert price and quantity to float
18df["price"] = df["price"].astype(float)
19df["quantity"] = df["quantity"].astype(float)
20
21# Reconstruct the final orderbook
22orderbook = {
23    'bid': {},
24    'ask': {}
25}
26
27was_prev_snapshot = False
28# Create numpy arrays for faster processing
29import numpy as np
30prices = np.array(df["price"])
31quantities = np.array(df["quantity"])
32event_types = np.array(df["event_type"])
33sides = np.array(df["side"])
34
35for i in tqdm.tqdm(range(len(df))):
36    price = prices[i]
37    quantity = quantities[i]
38    event_type = event_types[i]
39    side = sides[i]
40
41    if event_type == "snapshot":
42        if not was_prev_snapshot:
43            # Clear the orderbook as this is the start of a new snapshot
44            orderbook = {
45                'bid': {},
46                'ask': {}
47            }
48        was_prev_snapshot = True
49    else:
50        was_prev_snapshot = False
51
52    if quantity == 0:
53        # Remove the price level if quantity is zero
54        orderbook[side].pop(price, None)
55    else:
56        # Update the orderbook with the new price level
57        orderbook[side][price] = quantity
58
59# Example: Print top 5 bid levels
60print("Top 5 Bid Levels:")
61for price, quantity in sorted(orderbook['bid'].items(), key=lambda x: x[0], reverse=True)[:5]:
62    print(f"Price: {price}, Quantity: {quantity}")
63

Want to go deeper?

For a comprehensive tutorial on exploring orderbook data, including exchange comparisons and visualization, check out our blog post: How to Download Historical Crypto Orderbook Data with Python