Trade Data

GET

/download

Get Trade History

Retrieve individual trade executions with timestamps, prices, quantities, and trade direction.

Python SDK Usage

python

1# Get trade data
2df = client.get_trades(
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: timestamp, price, quantity, side (buy/sell), trade_id
10print(df.head())
11
12# Analyze trade volume by side
13volume_by_side = df.groupby('side')['quantity'].sum()
14print(volume_by_side)
15

Data Format - CommonTrade

Trade data is stored using the CommonTrade structure, which captures individual trade executions with precise timing and market information:

Schema Overview

Each trade event contains execution timing, symbol information, price/quantity data, and market direction indicators.

Field Definitions

Field	Type	Nullable	Description
received_time	INT64	No	Unix timestamp (nanoseconds) when our system received the trade event
event_time	INT64	No	Unix timestamp (exchange dependent on timescale) when the exchange generated the event
symbol	STRING	No	Trading pair symbol (e.g., 'BTCUSDT')
trade_id	INT64	No	Exchange-specific unique trade identifier
price	STRING	No	Trade execution price (stored as string for precision)
quantity	STRING	No	Trade quantity/volume (stored as string for precision)
trade_time	INT64	No	Unix timestamp (exchange dependent on timescale) when the trade occurred
is_buyer_maker	BOOLEAN	No	True if buyer was the maker (passive side), false if taker
order_type	STRING	No	Type of order that generated this trade (e.g., "LIMIT", "MARKET")

Trade Direction Analysis

Sell Trades (Taker Sell)

Market sell orders hitting bid levels

is_buyer_maker = true
Buyer placed passive order (maker)
Seller took liquidity (taker)
Generally bearish pressure

Buy Trades (Taker Buy)

Market buy orders hitting ask levels

is_buyer_maker = false
Seller placed passive order (maker)
Buyer took liquidity (taker)
Generally bullish pressure

Working with Trade Data

python

1# Analyze trade flow from CryptoHFTData using Python
2import cryptohftdata as chd
3import pandas as pd
4import numpy as np
5
6# Initialize the client
7client = chd.CryptoHFTDataClient(api_key="your-api-key-here")
8
9# Load trade data
10df = client.get_trades(
11    symbol="BTCUSDT",
12    exchange=chd.exchanges.BINANCE_SPOT,
13    start_date="2025-08-01",
14    end_date="2025-08-01"
15)
16
17# Convert timestamps to datetime
18df['trade_datetime'] = pd.to_datetime(df['trade_time'], unit='us')
19df['received_datetime'] = pd.to_datetime(df['received_time'], unit='ns')
20
21# Convert price and quantity to float for analysis
22df['price_float'] = df['price'].astype(float)
23df['quantity_float'] = df['quantity'].astype(float)
24
25# Calculate trade volume in quote currency
26df['volume_usd'] = df['price_float'] * df['quantity_float']
27
28# Determine trade direction based on is_buyer_maker
29df['trade_side'] = df['is_buyer_maker'].map({True: 'sell', False: 'buy'})
30
31# Calculate buy/sell pressure
32buy_volume = df[df['trade_side'] == 'buy']['volume_usd'].sum()
33sell_volume = df[df['trade_side'] == 'sell']['volume_usd'].sum()
34total_volume = buy_volume + sell_volume
35
36buy_pct = buy_volume/total_volume*100
37sell_pct = sell_volume/total_volume*100
38net_flow = buy_volume - sell_volume
39
40print("Buy Volume: $" + "{:,.2f}".format(buy_volume) + " (" + "{:.1f}".format(buy_pct) + "%)")
41print("Sell Volume: $" + "{:,.2f}".format(sell_volume) + " (" + "{:.1f}".format(sell_pct) + "%)")
42print("Net Flow: $" + "{:,.2f}".format(net_flow))
43
44# Calculate VWAP (Volume Weighted Average Price)
45vwap = (df['price_float'] * df['quantity_float']).sum() / df['quantity_float'].sum()
46print("VWAP: $" + "{:.2f}".format(vwap))
47
48# Analyze latency between exchange and our system
49df['latency_ms'] = (df['received_time'] / 1000 / 1000) - df['event_time']
50avg_latency = df['latency_ms'].mean()
51print("Average Latency: " + "{:.0f}".format(avg_latency) + " milliseconds")

Want to go deeper?

For a comprehensive tutorial on trade flow analysis, including VWAP calculation and whale trade detection, check out our blog post: Trade Flow Analysis: How to Calculate VWAP and Detect Whale Trades in Python