DocumentationAPI endpoints, Python SDK, and historical data format
Ask on ChatGPTMark Price Data
GET
/download
Get Mark Price History
Retrieve mark price data for futures contracts. Mark price is used for liquidation calculations.
Python SDK Usage
python
1# Get mark price data (futures exchanges only)
2df = client.get_mark_price(
3 symbol="BTCUSDT",
4 exchange=chd.exchanges.BINANCE_FUTURES, # Note: futures exchange
5 start_date="2025-08-01",
6 end_date="2025-08-01"
7)
8
9# Data includes: timestamp, mark_price
10print(df.head())
11Important Note
Mark price data is typically only available for futures exchanges like binance-futures, bybit-futures, etc.
Data Format - CommonMarkPrice
Mark price data is stored using the CommonMarkPrice structure, which captures mark price information along with related funding data and settlement estimates:
Schema Overview
Each mark price event contains timing information, symbol data, and comprehensive pricing information including mark price, index price, estimated settlement price, and funding rate details.
Field Definitions
| Field | Type | Nullable | Description |
|---|---|---|---|
| received_time | INT64 | No | Unix timestamp (nanoseconds) when our system received the mark price 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') |
| mark_price | STRING | Yes | Mark price used for liquidation calculations (stored as string for precision) |
| index_price | STRING | Yes | Index price from underlying spot exchanges (stored as string for precision) |
| estimated_settle_price | STRING | Yes | Estimated settlement price for contract expiration (stored as string for precision) |
| funding_rate | STRING | Yes | Current funding rate for perpetual contracts (stored as string for precision) |
| next_funding_time | INT64 | Yes | Unix timestamp when the next funding payment will occur |
Price Types
Mark Price
Fair value price used for liquidations
- Based on index price and funding premium
- Prevents manipulation
- Updates continuously
- Used for PnL calculations
Index Price
Weighted average from spot exchanges
- Composite price from multiple spot markets
- Reference for mark price calculation
- Updated in real-time
Settlement Price
Estimated final settlement price
- For contract expiration
- Based on underlying spot price
- Used for final settlement
Working with the Data
python
1# Analyze mark price vs index price
2import cryptohftdata as chd
3import pandas as pd
4import matplotlib.pyplot as plt
5
6# Initialize the client
7client = chd.CryptoHFTDataClient(api_key="your-api-key-here")
8
9# Get mark price data
10df = client.get_mark_price(
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 string prices to float for analysis
18df['mark_price_float'] = df['mark_price'].astype(float)
19df['index_price_float'] = df['index_price'].astype(float)
20
21# Calculate mark price premium
22df['mark_premium'] = df['mark_price_float'] - df['index_price_float']
23df['mark_premium_pct'] = (df['mark_premium'] / df['index_price_float']) * 100
24
25# Analyze funding rate impact
26df['funding_rate_pct'] = df['funding_rate'].astype(float) * 100
27
28print("Mark Price Analysis:")
29print(f"Average mark premium: {df['mark_premium_pct'].mean():.4f}%")
30print(f"Current funding rate: {df['funding_rate_pct'].iloc[-1]:.4f}%")
31
32# Plot mark price vs index price
33plt.figure(figsize=(12, 8))
34plt.subplot(2, 1, 1)
35plt.plot(df.index, df['mark_price_float'], label='Mark Price', linewidth=2)
36plt.plot(df.index, df['index_price_float'], label='Index Price', linewidth=2)
37plt.title('Mark Price vs Index Price')
38plt.legend()
39plt.ylabel('Price (USDT)')
40
41plt.subplot(2, 1, 2)
42plt.plot(df.index, df['mark_premium_pct'], label='Mark Premium %', color='red')
43plt.title('Mark Price Premium')
44plt.ylabel('Premium (%)')
45plt.xlabel('Time')
46plt.legend()
47plt.tight_layout()
48plt.show()
49