Getting Started With Futures Data
Last updated
Last updated
This notebook demonstrates basic functionality offered by the Coin Metrics Python API Client and Market Data Feed.
Coin Metrics offers a vast assortment of data for hundreds of cryptoassets. The Python API Client allows for easy access to this data using Python without needing to create your own wrappers using requests
and other such libraries.
To understand the data that Coin Metrics offers, feel free to peruse the resources below.
The Coin Metrics API v4 website contains the full set of endpoints and data offered by Coin Metrics.
The Coin Metrics Product Documentation gives detailed, conceptual explanations of the data that Coin Metrics offers.
The API Spec contains a full list of functions.
Download the entire notebook as either a jupyter notebook to run yourself or as a pdf from the two links below
Futures contracts are standardized contracts that allow counterparties to enter into an agreement to buy or sell a standardized asset under contract specifications that are defined by the exchange. Each specific futures contract offered by a specific exchange will have identical contract specifications regardless of who is the counterparty.
The contract specifications include information such as the underlying base and quote asset, the margin asset, the contract size, the listing time, expiration time, and other terms.
Coin Metrics offers contract specifications for both futures and options. Here we define futures to include both non-perpetual futures that expire and perpetual futures (sometimes called perpetual swaps).
Open interest represents the number of contracts that are currently outstanding and not settled for a specific derivatives market.
Assets level (i.e btc)
Asset Pair level (i.e. btc-usd)
Exchange level (i.e. binance)
Exchange-Asset level (i.e. binance-btc)
Market level (i.e. binance-BTCUSDT-future)
0
binance-BTCUSDT-future
2024-09-15 21:42:00+00:00
87506.236
5214374094.5096
2024-09-15 21:42:31.800754+00:00
2024-09-15 21:42:00+00:00
1
binance-BTCUSDT-future
2024-09-15 21:43:00+00:00
87493.551
5213766952.1553
2024-09-15 21:43:55.721238+00:00
2024-09-15 21:43:00+00:00
2
binance-BTCUSDT-future
2024-09-15 21:44:00+00:00
87505.378
5215066763.2038
2024-09-15 21:44:48.749434+00:00
2024-09-15 21:44:00+00:00
3
binance-BTCUSDT-future
2024-09-15 21:45:00+00:00
87499.076
5215364925.1648
2024-09-15 21:45:41.693858+00:00
2024-09-15 21:45:00+00:00
4
binance-BTCUSDT-future
2024-09-15 21:46:00+00:00
87503.139
5214338303.9517
2024-09-15 21:46:35.001759+00:00
2024-09-15 21:46:00+00:00
...
...
...
...
...
...
...
1435
binance-BTCUSDT-future
2024-09-16 21:37:00+00:00
84817.5
4903884915.75
2024-09-16 21:37:39.951283+00:00
2024-09-16 21:37:00+00:00
1436
binance-BTCUSDT-future
2024-09-16 21:38:00+00:00
84825.836
4902466778.702
2024-09-16 21:38:33.480165+00:00
2024-09-16 21:38:00+00:00
1437
binance-BTCUSDT-future
2024-09-16 21:39:00+00:00
84832.474
4902417772.9756
2024-09-16 21:39:26.976255+00:00
2024-09-16 21:39:00+00:00
1438
binance-BTCUSDT-future
2024-09-16 21:40:00+00:00
84842.805
4902471801.315
2024-09-16 21:40:46.680850+00:00
2024-09-16 21:40:00+00:00
1439
binance-BTCUSDT-future
2024-09-16 21:41:00+00:00
84851.162
4904380193.3676
2024-09-16 21:41:40.406353+00:00
2024-09-16 21:41:00+00:00
1440 rows × 6 columns
Use the get_exchange_asset_metrics client function to pull the all BTC exchange-asset pairs at daily frequency:
0
binance-btc
2023-09-18
3.074676e+09
1
binance-btc
2023-09-19
3.220249e+09
2
binance-btc
2023-09-20
3.359060e+09
3
binance-btc
2023-09-21
3.272911e+09
4
binance-btc
2023-09-22
3.280109e+09
...
...
...
...
3280
okex-btc
2024-09-12
2.346645e+09
3281
okex-btc
2024-09-13
2.431933e+09
3282
okex-btc
2024-09-14
2.693548e+09
3283
okex-btc
2024-09-15
2.608818e+09
3284
okex-btc
2024-09-16
2.569876e+09
3285 rows × 3 columns
Next, we'll take a look at liquidations data. As a reminder, exchanges which offer futures markets utilize a risk management system that will attempt to close a user’s position before the point at which the user begins to owe more than what is in the user's account. The trade or order that closes the user's position is referred to as a liquidation.
This time, we'll use the get_market_liquidations client function to pull all BTCUSDT liquidations over the last 24 hours on Binance:
0
binance-BTCUSDT-future
2024-09-15 21:54:34.145000+00:00
1726437274145000000
0.011
59648.0
trade
2024-09-15 21:54:34.297968+00:00
buy
1
binance-BTCUSDT-future
2024-09-15 21:57:52.361000+00:00
1726437472361000000
0.006
59663.1
trade
2024-09-15 21:57:53.574117+00:00
buy
2
binance-BTCUSDT-future
2024-09-15 22:02:17.426000+00:00
1726437737426000000
0.242
59511.0
trade
2024-09-15 22:02:18.244282+00:00
sell
3
binance-BTCUSDT-future
2024-09-15 22:02:19.433000+00:00
1726437739433000000
0.041
59503.1
trade
2024-09-15 22:02:20.362299+00:00
sell
4
binance-BTCUSDT-future
2024-09-15 22:02:33.095000+00:00
1726437753095000000
0.009
59479.2
trade
2024-09-15 22:02:34.376645+00:00
sell
Notice that this timeseries also includes the liquidation type. Some exchanges report “liquidations orders” in which they will report the creation of a liquidation order when a trader’s position initially enters liquidation. When a trader’s position enters liquidation, an exchange will typically enter a limit order at the price at which the trader will be bankruptcy price. The liquidation orders will show the amount of the position that is being liquidated and the liquidation price, but will not represent the matched trades that are executed as a result of the liquidation. Other exchanges will report “liquidation trades” which represent the actual matched trade as a result of a liquidation order but will not report liquidation orders. Some exchanges will report both liquidation orders and liquidation trades.
In addition to examining individual liquidations, we can also leverage aggregated liquidations metrics. This allows us to quickly view the total amount of USD-denominated liquidations that have occurred over large timeframes, without needing to aggregate the amounts at the trade level.
61
binance-btc
[{'metric': 'liquidations_reported_future_buy_...
335
bitfinex-btc
[{'metric': 'liquidations_reported_future_buy_...
401
bitmex-btc
[{'metric': 'liquidations_reported_future_buy_...
577
bybit-btc
[{'metric': 'liquidations_reported_future_buy_...
925
deribit-btc
[{'metric': 'liquidations_reported_future_buy_...
978
ftx-btc
[{'metric': 'liquidations_reported_future_buy_...
1213
huobi-btc
[{'metric': 'liquidations_reported_future_buy_...
1475
kraken-btc
[{'metric': 'liquidations_reported_future_buy_...
1688
okex-btc
[{'metric': 'liquidations_reported_future_buy_...
0
binance-btc
2024-09-15 10:00:00+00:00
41189.76644
-123119.61981
1
binance-btc
2024-09-15 11:00:00+00:00
2219.32844
-26757.74386
2
binance-btc
2024-09-15 12:00:00+00:00
20766.66452
-540.03552
3
binance-btc
2024-09-15 13:00:00+00:00
166694.89730
-28269.05000
4
binance-btc
2024-09-15 14:00:00+00:00
208587.82170
-319846.10928
...
...
...
...
...
167
okex-btc
2024-09-16 16:00:00+00:00
2309.60000
-231.20680
168
okex-btc
2024-09-16 17:00:00+00:00
753306.85950
-676171.41858
169
okex-btc
2024-09-16 18:00:00+00:00
0.00000
-245113.87800
170
okex-btc
2024-09-16 19:00:00+00:00
0.00000
-18840.23928
171
okex-btc
2024-09-16 20:00:00+00:00
52104.18704
-131510.72160
172 rows × 4 columns
0
btc
2024-09-14 22:00:00+00:00
27085472082.8134
1
btc
2024-09-14 23:00:00+00:00
27086895034.416401
2
btc
2024-09-15 00:00:00+00:00
27089846618.242401
3
btc
2024-09-15 01:00:00+00:00
27103605277.447899
4
btc
2024-09-15 02:00:00+00:00
27206441557.918598
Funding rates are a mechanism that exchanges use to ensure that perpetual futures trade at a price that is close to the price of the underlying spot markets. The funding rate is used to calculate the funding fee which long position holders pay short position holders, or vice versa, as a way to incentivize market participants to take positions that keep perpetual futures prices close to the underlying.
Coin Metrics funding rate data from the timeseries/market-funding-rates endpoint includes the following fields:
market: The id of the market. Market ids use the following naming convention: exchangeName-baseAsset-quoteAsset-spot for spot markets, exchangeName-futuresSymbol-future for futures markets, and exchangeName-optionsSymbol-option for options markets.
time: The exchange-reported time in ISO 8601 date-time format. Always with nanoseconds precision.
rate: The funding rate expressed as a percentage over the period. For example, if the funding rate is 0.10%, expressed as an 8 hour rate and calculated over the past 8 hours, the rate is 0.0010.
period: The periodicity of the funding rate. If the rate is 0.0010then this rate would be applied every period defined by this field.
interval: The interval of time over which the funding rate is calculated.
database_time: The timestamp when the data was saved in the database in ISO 8601 date-time format with nanoseconds precision.
0
binance-1000BONKUSDC-future
2024-05-01 00:00:00+00:00
2024-09-16 20:00:00+00:00
1
binance-1000BONKUSDT-future
2023-11-22 16:00:00+00:00
2024-09-16 20:00:00+00:00
2
binance-1000BTTCUSDT-future
2022-01-26 08:00:00.001000+00:00
2022-04-11 08:00:00+00:00
3
binance-1000FLOKIUSDT-future
2023-05-06 16:00:00+00:00
2024-09-16 16:00:00+00:00
4
binance-1000LUNCBUSD-future
2022-05-30 16:00:00.005000+00:00
2023-06-08 08:00:00+00:00
...
...
...
...
442
binance-ZILUSDT-future
2020-06-17 08:00:00.007000+00:00
2024-09-16 16:00:00+00:00
443
binance-ZILUSD_PERP-future
2022-04-06 08:00:00.013000+00:00
2022-12-26 08:00:00.014000+00:00
444
binance-ZKUSDT-future
2024-06-17 12:00:00+00:00
2024-09-16 20:00:00+00:00
445
binance-ZROUSDT-future
2024-06-20 16:00:00+00:00
2024-09-16 20:00:00+00:00
446
binance-ZRXUSDT-future
2020-06-24 08:00:00+00:00
2024-09-16 16:00:00+00:00
447 rows × 3 columns
0
bitmex-XBTUSD-future
2024-09-10 04:00:00+00:00
2024-09-10 04:00:55.910555+00:00
-0.000116
08:00:00
08:00:00
1
bitmex-XBTUSD-future
2024-09-10 12:00:00+00:00
2024-09-10 12:00:40.929397+00:00
0.000037
08:00:00
08:00:00
2
bitmex-XBTUSD-future
2024-09-10 20:00:00+00:00
2024-09-10 20:00:01.451626+00:00
0.000048
08:00:00
08:00:00
3
bitmex-XBTUSD-future
2024-09-11 04:00:00+00:00
2024-09-11 04:00:15.978545+00:00
0.0001
08:00:00
08:00:00
4
bitmex-XBTUSD-future
2024-09-11 12:00:00+00:00
2024-09-11 12:00:04.727025+00:00
0.0001
08:00:00
08:00:00
...
...
...
...
...
...
...
58
okex-BTC-USD-SWAP-future
2024-09-15 08:00:00+00:00
2024-09-15 08:00:05.108766+00:00
0.000062
08:00:00
08:00:00
59
okex-BTC-USD-SWAP-future
2024-09-15 16:00:00+00:00
2024-09-15 16:00:12.545520+00:00
0.000061
08:00:00
08:00:00
60
okex-BTC-USD-SWAP-future
2024-09-16 00:00:00+00:00
2024-09-16 00:00:04.734967+00:00
0.000046
08:00:00
08:00:00
61
okex-BTC-USD-SWAP-future
2024-09-16 08:00:00+00:00
2024-09-16 08:00:07.052638+00:00
0.000013
08:00:00
08:00:00
62
okex-BTC-USD-SWAP-future
2024-09-16 16:00:00+00:00
2024-09-16 16:00:06.345528+00:00
0.000011
08:00:00
08:00:00
63 rows × 6 columns
Coin Metrics also calculates several aggregated funding rate metrics.
Aggregate Funding Rate is the average funding rate weighted by open interest, published once per hour and representing the average funding rate converted to 8 hour, 1 day, 30 day, and 1 year time periods.
futures_aggregate_funding_rate_usd_margin_*: metrics represent the average funding rate weighted by open interest from perpetual futures markets where the margin asset is U.S. dollars or stablecoins converted to a specified time period.
futures_aggregate_funding_rate_coin_margin_*: represent the average funding rate weighted by open interest from perpetual futures markets where the margin asset is equivalent to the underlying base asset converted to a specified period.
futures_aggregate_funding_rate_all_margin_*: represent the average funding rate weighted by open interest from all perpetual futures markets, regardless of the margin asset, converted to a specified time period.
0
btc
2023-10-01 00:00:00+00:00
0.000101
0.036712
0.003017
1
btc
2023-10-02 00:00:00+00:00
0.000087
0.031662
0.002602
2
btc
2023-10-03 00:00:00+00:00
0.000086
0.031306
0.002573
3
btc
2023-10-04 00:00:00+00:00
0.000109
0.039942
0.003283
4
btc
2023-10-05 00:00:00+00:00
0.000071
0.025923
0.002131
4711
binance-btc
futures_aggregate_funding_rate_all_margin_1y_p...
1d
2020-07-27 18:00:00+00:00
2024-09-16 21:00:00+00:00
24034
bitfinex-btc
futures_aggregate_funding_rate_all_margin_1y_p...
1d
2020-12-02 09:00:00+00:00
2024-09-16 21:00:00+00:00
29530
bitmex-btc
futures_aggregate_funding_rate_all_margin_1y_p...
1d
2020-07-27 18:00:00+00:00
2024-09-16 21:00:00+00:00
41723
bybit-btc
futures_aggregate_funding_rate_all_margin_1y_p...
1d
2021-05-01 20:00:00+00:00
2024-09-16 21:00:00+00:00
66927
deribit-btc
futures_aggregate_funding_rate_all_margin_1y_p...
1d
2020-07-27 18:00:00+00:00
2024-09-16 21:00:00+00:00
69721
ftx-btc
futures_aggregate_funding_rate_all_margin_1y_p...
1d
2020-07-27 18:00:00+00:00
2022-11-12 04:00:00+00:00
88682
huobi-btc
futures_aggregate_funding_rate_all_margin_1y_p...
1d
2020-07-27 18:00:00+00:00
2024-09-16 21:00:00+00:00
105482
kraken-btc
futures_aggregate_funding_rate_all_margin_1y_p...
1d
2020-10-09 09:00:00+00:00
2024-09-16 21:00:00+00:00
126904
okex-btc
futures_aggregate_funding_rate_all_margin_1y_p...
1d
2020-10-30 09:00:00+00:00
2024-09-16 21:00:00+00:00
0
binance-btc
2023-01-01 00:00:00+00:00
0.1095
1
binance-btc
2023-01-02 00:00:00+00:00
0.012148
2
binance-btc
2023-01-03 00:00:00+00:00
0.046845
3
binance-btc
2023-01-04 00:00:00+00:00
0.041311
4
binance-btc
2023-01-05 00:00:00+00:00
0.061746
...
...
...
...
2915
okex-btc
2023-12-27 00:00:00+00:00
0.376005
2916
okex-btc
2023-12-28 00:00:00+00:00
0.254648
2917
okex-btc
2023-12-29 00:00:00+00:00
0.536332
2918
okex-btc
2023-12-30 00:00:00+00:00
0.455873
2919
okex-btc
2023-12-31 00:00:00+00:00
0.548358
2920 rows × 3 columns
exchange_asset
binance-btc
0.109500
0.012148
0.046845
0.041311
0.061746
0.077517
0.096432
0.089722
0.057266
0.017031
...
0.281263
0.206533
0.154560
0.195473
0.425674
0.383043
0.379663
0.549031
0.457254
0.387193
bitfinex-btc
0.240054
0.382189
0.211039
0.229558
0.074891
0.131655
0.131765
0.160125
0.113086
0.129979
...
0.270820
0.156269
0.125486
0.308607
0.465474
0.147093
0.655639
0.688972
0.453521
0.265981
bitmex-btc
0.109500
-0.147477
-0.027653
-0.075540
0.109140
0.058906
-0.078846
0.109500
0.109500
0.109500
...
0.124057
0.120385
0.105715
0.111534
0.109102
0.118988
0.178754
0.469497
0.127023
0.127770
bybit-btc
0.332716
0.328811
0.106620
0.109500
0.108059
0.056104
0.076392
-0.001772
0.090156
-0.066673
...
0.109500
0.109500
0.109500
0.109500
0.109500
0.109500
0.109500
0.109500
0.109500
0.109500
deribit-btc
0.004014
-0.004356
0.000194
-0.000777
-0.000004
-0.003702
-0.000003
0.000411
0.000128
0.009021
...
0.162735
0.222283
0.009642
0.074016
0.344480
0.472755
0.558913
0.589233
0.398686
0.509796
huobi-btc
0.109500
0.099561
0.109500
0.109500
-0.031955
0.109500
0.109500
0.815508
-0.012098
0.062326
...
0.261585
1.119745
0.330376
0.585262
0.487209
1.132452
0.657258
0.739781
0.549361
0.700592
kraken-btc
0.030208
0.040457
-0.095853
-0.027047
0.061041
-0.130703
-0.061580
0.036233
-0.006607
0.217927
...
0.316554
0.166807
0.167266
0.130185
0.474480
0.381600
0.226822
0.361264
0.169106
0.289377
okex-btc
0.209290
0.191624
-0.019627
0.007415
0.206787
0.104460
-0.038630
0.124934
0.025828
0.020786
...
0.396916
0.417243
-0.002470
0.271116
0.250061
0.376005
0.254648
0.536332
0.455873
0.548358
8 rows × 365 columns
Cumulative Funding Rate is the cumulative average funding rate that would be accumulated by contract holders over a specified time period. Published once per hour, representing the cumulative realized funding rate over the previous 1 day, 7 day, and 30 day time periods.
futures_cumulative_funding_rate_usd_margin_*: metrics represent the cumulative average funding rate weighted by open interest from futures markets where the margin asset is U.S. dollars or stablecoins over the previous specified time period.
futures_cumulative_funding_rate_coin_margin_*: metrics represent the cumulative average funding rate weighted by open interest from futures markets where the margin asset is equivalent to the underlying base asset over the previous specified time period.
futures_cumulative_funding_rate_all_margin_*: metrics represent the cumulative average funding rate weighted by open interest from all futures markets, regardless of the margin asset, over the previous specified time period.
0
btc
2023-01-01 00:00:00+00:00
0.00041
0.002146
0.0015
1
btc
2023-01-02 00:00:00+00:00
0.000358
0.002479
0.001736
2
btc
2023-01-03 00:00:00+00:00
0.000128
0.002587
0.001735
3
btc
2023-01-04 00:00:00+00:00
0.000176
0.002641
0.001754
4
btc
2023-01-05 00:00:00+00:00
0.000194
0.002957
0.001745