Open Interest

GET

/download

Get Open Interest Data

Retrieve open interest data for futures contracts showing total outstanding positions.

Python SDK Usage

python

1# Get open interest data (futures exchanges only)
2df = client.get_open_interest(
3    symbol="BTCUSDT",
4    exchange=chd.exchanges.BINANCE_FUTURES,
5    start_date="2025-08-01",
6    end_date="2025-08-01"
7)
8
9# Data includes: timestamp, open_interest, open_interest_value
10print(df.head())
11
12# Calculate open interest changes
13df['oi_change'] = df['open_interest'].diff()
14df['oi_change_pct'] = df['oi_change'] / df['open_interest'].shift(1) * 100
15

Data Format - CommonOpenInterest

Open interest data is stored using the CommonOpenInterest structure, which captures the total outstanding positions in futures contracts at specific points in time:

Schema Overview

Each open interest event contains timing information, symbol data, and comprehensive position metrics including total open interest by quantity and notional value.

Field Definitions

Field	Type	Nullable	Description
received_time	INT64	No	Unix timestamp (nanoseconds) when our system received the open interest data
symbol	STRING	No	Trading pair symbol (e.g., 'BTCUSDT')
sum_open_interest	STRING	Yes	Total open interest by contract quantity (stored as string for precision)
sum_open_interest_value	STRING	Yes	Total open interest notional value in quote currency (stored as string for precision)
timestamp	INT64	No	Unix timestamp when the open interest snapshot was taken by the exchange

Open Interest Metrics

Contract Quantity

Total number of outstanding contracts

sum_open_interest field
Measured in base currency units
Shows market participation level
Higher values indicate more activity

Notional Value

Total dollar value of outstanding positions

sum_open_interest_value field
Denominated in quote currency
Accounts for current price levels
Better for cross-symbol comparisons

Market Analysis Applications

Key Use Cases

Market Sentiment: Rising OI with rising price suggests bullish sentiment
Trend Strength: Increasing OI confirms trend continuation
Reversal Signals: Divergence between price and OI may indicate reversals
Liquidity Assessment: Higher OI generally means better liquidity
Risk Management: Monitor OI changes for position sizing decisions

Working with the Data

python

1# Detailed open interest analysis
2import cryptohftdata as chd
3import pandas as pd
4import matplotlib.pyplot as plt
5import numpy as np
6
7# Initialize the client
8client = chd.CryptoHFTDataClient(api_key="your-api-key-here")
9
10# Get open interest data
11oi_df = client.get_open_interest(
12    symbol="BTCUSDT",
13    exchange=chd.exchanges.BINANCE_FUTURES,
14    start_date="2025-08-01",
15    end_date="2025-08-01"
16)
17
18# Get price data for comparison
19price_df = client.get_ticker(
20    symbol="BTCUSDT",
21    exchange=chd.exchanges.BINANCE_FUTURES,
22    start_date="2025-08-01",
23    end_date="2025-08-01"
24)
25
26# Convert to numeric for analysis
27oi_df['oi_quantity'] = oi_df['sum_open_interest'].astype(float)
28oi_df['oi_value'] = oi_df['sum_open_interest_value'].astype(float)
29price_df['price'] = price_df['last_price'].astype(float)
30
31# Calculate OI changes
32oi_df['oi_change'] = oi_df['oi_quantity'].diff()
33oi_df['oi_change_pct'] = (oi_df['oi_change'] / oi_df['oi_quantity'].shift(1)) * 100
34
35# Merge with price data for correlation analysis
36merged_df = pd.merge_asof(
37    oi_df.sort_values('timestamp'), 
38    price_df.sort_values('event_time')[['event_time', 'price']], 
39    left_on='timestamp', right_on='event_time',
40)
41
42# Calculate price changes
43merged_df['price_change'] = merged_df['price'].diff()
44merged_df['price_change_pct'] = (merged_df['price_change'] / merged_df['price'].shift(1)) * 100
45
46# Analyze OI-Price relationship
47correlation = merged_df['oi_change_pct'].corr(merged_df['price_change_pct'])
48print(f"OI vs Price Change Correlation: {correlation:.4f}")
49
50# Identify key patterns
51merged_df['oi_price_divergence'] = np.where(
52    (merged_df['oi_change_pct'] > 0) & (merged_df['price_change_pct'] < 0), 'Bearish Divergence',
53    np.where(
54        (merged_df['oi_change_pct'] < 0) & (merged_df['price_change_pct'] > 0), 'Bullish Divergence',
55        'Aligned'
56    )
57)
58
59# Plot analysis
60fig, ((ax1, ax2), (ax3, ax4)) = plt.subplots(2, 2, figsize=(15, 10))
61
62# OI quantity over time
63ax1.plot(merged_df.index, merged_df['oi_quantity'], label='Open Interest', color='blue')
64ax1.set_title('Open Interest Quantity')
65ax1.set_ylabel('Contracts')
66ax1.legend()
67
68# OI value over time
69ax2.plot(merged_df.index, merged_df['oi_value'], label='OI Value', color='green')
70ax2.set_title('Open Interest Value')
71ax2.set_ylabel('USDT')
72ax2.legend()
73
74# Price vs OI changes
75ax3.scatter(merged_df['price_change_pct'], merged_df['oi_change_pct'], alpha=0.6)
76ax3.set_xlabel('Price Change %')
77ax3.set_ylabel('OI Change %')
78ax3.set_title(f'OI vs Price Changes (Corr: {correlation:.3f})')
79ax3.grid(True, alpha=0.3)
80
81# OI change distribution
82ax4.hist(merged_df['oi_change_pct'].dropna(), bins=30, alpha=0.7, color='orange')
83ax4.set_xlabel('OI Change %')
84ax4.set_ylabel('Frequency')
85ax4.set_title('OI Change Distribution')
86
87plt.tight_layout()
88plt.show()
89
90# Summary statistics
91print("Open Interest Analysis Summary:")
92print("Average OI Quantity:", merged_df['oi_quantity'].mean(), "contracts")
93print("Average OI Value: $", merged_df['oi_value'].mean())
94print("OI Volatility:", merged_df['oi_change_pct'].std(), "%")
95print("Max OI:", merged_df['oi_quantity'].max(), "contracts")
96print("Min OI:", merged_df['oi_quantity'].min(), "contracts")