Basis

The basis is the annualized percent difference between the price of a theoretical futures contract and the price of its underlying spot market. Coin Metrics calculates this for several exchange-assets such as binance-btc and ftx-eth. We calculate four basis metrics at defined days to expiration.

Definition

The annualized basis metrics measure the difference between the spot price and a futures price for a contract with given time to expiration. This difference is calculated as a percentage of the underlying spot price which we use our reference rates (using the calculation algorithm for frequencies 200ms, 1s, and 1m) to define, and annualized by the time to expiration.

Name	MetricID	Unit	Frequency
Annualized Futures Basis, 30 day expiration	basis_annualized_30d_exp	USD	1d, 1h
Annualized Futures Basis, 60 day expiration	basis_annualized_60d_exp	USD	1d, 1h
Annualized Futures Basis, 90 day expiration	basis_annualized_90d_exp	USD	1d, 1h
Annualized Futures Basis, 120 day expiration	basis_annualized_120d_exp	USD	1d, 1h

Methodology

We offer this calculation for various exchanges and assets in 30, 60, 90, and 120 day durations. The available contracts for an exchange and asset rarely ever align with the duration necessary and instead the target duration is calculated with a time adjusted weighting between the two contracts surrounding the target expiration. The target expiration is the time of the datapoint, t0, plus the indicated duration. For example if today was 2021-09-15 and we were creating a 30 day calculation then the target expiration would be 2021-10-15. In the case that the only futures contracts available for the asset and exchange combination were those with expirations on the last Friday of the month, we would use the contracts expiring on 2021-09-24 and 2021-10-29 as our two reference points. Please note that we currently utilized only quarterly contracts with expirations in March.

After defining the two contracts straddling the target expiration date, we find the basis between each contract and the spot price. Using the two contract’s basis we calculate the forward yield between the further dated contract and the nearer dated. This is the difference between the basis of each contract multiplied by their respective times to expiration, divided by the difference in their time to expiration.

Using this forward yield, we then calculate the target date’s basis by multiplying the front contract’s basis by the time to expiration and adding to it the forward yield multiplied by the difference between the front contract and the target expiration. We divide this by the total target duration to arrive at the basis for our target duration.

We currently calculate these metrics for the following exchange-asset combinations:

okex-btc, okex-eth, kraken-eth, huobi-eth, kraken-btc, huobi-btc, ftx-eth, deribit-eth, ftx-btc, deribit-btc, cme-btc, cme-eth, bitmex-btc, binance-btc, binance-eth

API Endpoints

Basis data can be accessed using the following endpoints:

• timeseries/exchange-asset-metrics

Exchange-asset metrics

get

Returns metrics for specified exchange-asset. Results are ordered by tuple (exchange_asset, time). To fetch the next page of results use next_page_url JSON response field.

Authorizations

Query parameters

exchange_assetsstring[]Required

Comma separated list of exchange-asset pairs or patterns like exchange-* or *-asset.

metricsstring[]Required

Comma separated metrics to request time series data for. Information on all available metrics can be found on page https://coverage.coinmetrics.io/exchange-asset-metrics-v2. Use the /catalog-all/exchange-assets endpoint for the full list of supported metrics per exchange-asset combination.

Example: ["open_interest_reported_future_usd","volume_reported_spot_usd_1d"]

frequencystringOptional

Frequency of the exchange-asset metrics. Supported values are 5m, 1h, 1d.

Default: 1d

start_timestringOptional

Start of the time interval. This field refers to the time field in the response. Multiple formats of ISO 8601 are supported: 2006-01-20T00:00:00Z, 2006-01-20T00:00:00.000Z, 2006-01-20T00:00:00.123456Z, 2006-01-20T00:00:00.123456789Z, 2006-01-20, 20060120. Inclusive by default. UTC timezone by default. Z suffix is optional and timezone parameter has a priority over it. If start_time is omitted, response will include time series from the earliest time available.

end_timestringOptional

End of the time interval. This field refers to the time field in the response. Multiple formats of ISO 8601 are supported: 2006-01-20T00:00:00Z, 2006-01-20T00:00:00.000Z, 2006-01-20T00:00:00.123456Z, 2006-01-20T00:00:00.123456789Z, 2006-01-20, 20060120. Inclusive by default. UTC timezone by default. Z suffix is optional and timezone parameter has a priority over it. If end_time is omitted, response will include time series up to the latest time available.

start_inclusivebooleanOptional

Inclusive or exclusive corresponding start_* parameters.

Default: true

end_inclusivebooleanOptional

Inclusive or exclusive corresponding end_* parameters.

Default: true

timezonestringOptional

Timezone name for start_time and end_time timestamps. This parameter does not modify the output times, which are always UTC. Format is defined by TZ database.

Default: UTCExample: America/New_York

page_sizeinteger · int32 · min: 1 · max: 10000Optional

Number of items per single page of results. The value of this parameter is ignored if the endpoint supports the format parameter and its value is set to json_stream.

Default: 100

paging_fromstring · enumOptional

Where does the first page start, at the start of the interval or at the end. The value of this parameter is ignored if the endpoint supports the format parameter and its value is set to json_stream.

Default: endAvailable options:

sortstring · enumOptional

How results will be sorted. Metrics are sorted by (exchange_asset, time) by default. If you want to sort 1d metrics by (time, exchange_asset) you should choose time as value for the sort parameter. Sorting by time is useful if you request metrics for a set of exchange-assets.

Default: exchange_assetAvailable options:

limit_per_exchange_assetinteger · int32Optional

How many entries per exchange_asset result should contain. For example, this combination of parameters exchange_assets=binance-btc,coinbase-eth&metrics=volume_trusted_spot_usd_1h&limit_per_exchange_asset=1 returns the latest volume_trusted_spot_usd_1h values for binance-btc and coinbase-eth.

prettybooleanOptional

Human-readable formatting of JSON responses.

Default: false

formatstring · enumOptional

Format of the response.

Default: jsonAvailable options:

next_page_tokenstringOptional

Token for receiving the results from the next page of a query. Should not be used directly. To iterate through pages just use next_page_url response field.

Responses

application/json

objectOptional

Time series of exchange metrics.

application/json

application/json

application/json

get

HTTPcURLJavaScriptPython

GET /v4/timeseries/exchange-asset-metrics HTTP/1.1
Host: api.coinmetrics.io
Accept: */*

{
  "data": [
    {
      "exchange_asset": "binance-btc",
      "time": "2021-10-04T00:00:00.000000000Z",
      "open_interest_reported_future_usd": "3469621227.0258"
    },
    {
      "exchange_asset": "binance-btc",
      "time": "2021-10-05T00:00:00.000000000Z",
      "open_interest_reported_future_usd": "3562791590.02995"
    },
    {
      "exchange_asset": "binance-btc",
      "time": "2021-10-06T00:00:00.000000000Z",
      "open_interest_reported_future_usd": "3970248573.60142"
    },
    {
      "exchange_asset": "binance-btc",
      "time": "2021-10-07T00:00:00.000000000Z",
      "open_interest_reported_future_usd": "4110308192.96416"
    }
  ]
}

Shell

curl --compressed "https://api.coinmetrics.io/v4/timeseries/exchange-asset-metrics?metrics=basis_annualized_30d_exp&exchange_assets=binance-btc&pretty=true&api_key=<your_key>"

Python

import requests
response = requests.get('https://api.coinmetrics.io/v4/timeseries/exchange-asset-metrics?metrics=basis_annualized_30d_exp&exchange_assets=binance-btc&pretty=true&api_key=<your_key>').json()
print(response)

Python Client

from coinmetrics.api_client import CoinMetricsClient

api_key = "<API_KEY>"
client = CoinMetricsClient(api_key)

print(
    client.get_asset_metrics(
        metrics="basis_annualized_30d_exp", 
        exchange_assets="binance-btc",
    ).to_dataframe()
)