Derivatives contract details

What is this endpoint for?

This endpoint provides details of the contracts, including base asset, quote asset, contract size, contract size unit, listing_timestamp, expiry, strike price, and underlying index.

Endpoint

https://<eu|us>.market-api.kaiko.io/v2/data/derivatives.v2/reference

Path Parameters

Parameter	Required?	Example
region	Yes	Choose between eu and us.

Query Parameters

Parameter	Required	Description	Example
exchange	Yes	Should be one of the exchanges currently supported	okex
instrument_class	Yes	future, perpetual-future, or option	future
instrument	No	Instrument code. See Exchange trading pair codes (instruments)	ethusd220624, btc*220624, *usdt, btc*may22*
base_assets	No	For finding the instruments with the certain base asset	btc, eth
quote_assets	No	For finding the instruments with the certain quote asset	usd, usdt
option_type	No	option only. For finding either only the call options or put options	C, P
min_strike	No	option only. Used to retrieve options whose strike price is above this minimum value (exclusive/inclusive)	10000
max_strike	No	option only. Used to retrieve options whose strike price is below this maximum value (exclusive/inclusive)	90000
start_time Deribit exchange only	No	future & option only. Used to retrieve futures and options that expire after this date and time (inclusive)	2022-06-23T00:01:00.000Z
end_time Deribit exchange only	No	future & option only. Used to retrieve futures and options that are listed before this date and time (exclusive)	2022-06-25T23:59:00.000Z
page_size	No	Number of snapshots to return data for. (default: 1000, min: 1, max: 1000). See Pagination	500

Fields: Perpetual-Future

Field	Description	Example
exchange	The exchange where the specified instrument is being traded	binc
instrument_class	Shows wether the specified instrument is future, perpetual-future or option	perpetual-future
instrument	The specified instrument	btc-usdc
base	The base asset of the instrument	btc
quote	The unit in which the instrument is quoted	usdc
contract_size	Size of the contract	1
contract_size_unit	Unit in which contract is denominated	btc
listing_timestamp	Date listed by exchange	2024-01-03 12:30:00 UTC
funding_rate_frequency	Interval at which the funding rate is paid	8h

Fields: Future

Field	Description	Example
exchange	The exchange where the specified instrument is being traded	okex
instrument_class	Shows wether the specified instrument is future, perpetual-future or option	future
instrument	The specified instrument	btcusdt250117
base	The base asset of the instrument	btc
quote	The unit in which the instrument is quoted	usdt
contract_size	Size of the contract	0.01
contract_size_unit	Unit in which contract is denominated	btc
listing_timestamp	The timestamp when a certain option instrument is listed on the exchange	2025-01-03 08:10:00 UTC
expiry	Expiration date of the contract	2025-01-17 08:00:00 UTC

Fields: Option

Field	Description	Example
exchange	The exchange where the specified instrument is being traded	drbt
instrument_class	Shows wether the specified instrument is future, perpetual-future or option	option
instrument	The specified instrument	btc10dec21100000c
base	The base asset of the instrument	btc
quote	The unit in which the instrument is quoted	usd
contract_size	Size of the contract	1
contract_size_unit	Unit in which contract is denominated	btc
listing_timestamp	The timestamp when a certain option instrument is listed on the exchange	2021-11-18 08:16:00 UTC
expiry	Expiration date of the contract	2021-12-10 08:00:00 UTC
strike_price	The strike price of the contract in USD.	30000
underlying_index	Name of the underlying asset	BTC-10DEC21

Request examples

cURL

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
'https://us.market-api.kaiko.io/v2/data/derivatives.v2/reference?exchange=drbt&instrument_class=option&base_assets=btc&page_size=50'```python

Python

##### 1. Import dependencies #####
import requests
import pandas as pd

##### 2. Choose the value of the query's parameters #####
# ---- Required parameters ---- #
exchange = "okex"
instrument_class = "future"

# ---- Optional parameters ---- #
instrument = None
base_assets = None
quote_assets = "btc"
option_type = None
min_strike = None
max_strike = None
start_time = None
end_time = None
page_size = 500

# ---- API key configuration ---- #
api_key = "YOUR_API_KEY"

##### 3. Get the data #####
# ---- Function to run an API call ---- # 
# Get the data in a dataframe --------- # 

def get_kaiko_data(api_key: str, exchange: str, instrument_class: str, instrument: str, base_assets: str, quote_assets: str, option_type: str, min_strike: int, max_strike: int, start_time: str, end_time: str, page_size: int):
    headers = {'Accept': 'application/json', 'X-Api-Key': api_key}
    
    url = f'https://us.market-api.kaiko.io/v2/data/derivatives.v2/reference'
    params = {
        "exchange": exchange,
        "instrument_class": instrument_class,
        "instrument": instrument,
        "base_assets": base_assets,
        "quote_assets": quote_assets,
        "option_type": option_type,
        "min_strike": min_strike,
        "max_strike": max_strike,
        "start_time": start_time,
        "end_time": end_time,
        "page_size": page_size
    }

    try:
        res = requests.get(url, headers=headers, params=params)
        res.raise_for_status() 
        data = res.json()
        if 'data' not in data:
            print("No data returned.")
            return pd.DataFrame() 
        df = pd.DataFrame(data['data'])

        # Handle pagination with continuation token
        while 'next_url' in data:
            next_url = data['next_url']
            if next_url is None:
                break
            res = requests.get(next_url, headers=headers)
            res.raise_for_status()
            data = res.json()
            if 'data' in data:
                df = pd.concat([df, pd.DataFrame(data['data'])], ignore_index=True)
        return df

    except requests.exceptions.RequestException as e:
        print(f"API request error: {e}")
        return pd.DataFrame() 

# ---- Get the data ---- #
df = get_kaiko_data(api_key=api_key, exchange=exchange, instrument_class=instrument_class, instrument=instrument, base_assets=base_assets, quote_assets=quote_assets, option_type=option_type, min_strike=min_strike, max_strike=max_strike, start_time=start_time, end_time=end_time, page_size=page_size)
print (df)

Response example

{
    "query": {
        "exchange": "drbt",
        "instrument_class": "option",
        "base_assets": [
            "btc"
        ],
        "page_size": "50",
        "data_version": "v2",
        "commodity": "derivatives",
        "request_time": "2022-11-30T15:26:49.66Z"
    },
    "time": "2022-11-30T15:26:55.623Z",
    "timestamp": 1669822015623,
    "data": [
        {
            "exchange": "drbt",
            "instrument_class": "option",
            "instrument": "btc10apr204750c",
            "base": "btc",
            "quote": "usd",
            "contract_size": "1",
            "contract_size_unit": "btc",
            "listing_timestamp": "2020-03-28 03:21:00 UTC",
            "expiry": "2020-04-10 08:00:00 UTC",
            "strike_price": "4750",
            "underlying_index": "SYN.BTC-10APR20"
        },
        /*---*/
    ],
    "result": "success",
    "continuation_token": "VHoT1C16LjCmtrfParGdwd4mVJnV1Qaqx5AMgXWsYawuiw68Qfymdf215NBcg9LzPJNxA9cZsBjB5S8JBHd8Giw2qoFDFvJ1tP3M5",
    "next_url": "https://us.market-api.kaiko.io/v2/data/derivatives.v2/reference?continuation_token=VHoT1C16LjCmtrfParGdwd4mVJnV1Qaqx5AMgXWsYawuiw68Qfymdf215NBcg9LzPJNxA9cZsBjB5S8JBHd8Giw2qoFDFvJ1tP3M5",
    "access": {
        "access_range": {
            "start_timestamp": 1646006400000,
            "end_timestamp": null
        },
        "data_range": {
            "start_timestamp": null,
            "end_timestamp": null
        }
    }
}

Searching for contracts (Deribit exchange only)

You can get a list of all the futures or options that can be traded between two specific times by using the start_time and end_time settings. For instance, if you're interested in all the futures or options that can be traded between October 1, 2022, and October 2, 2022, you would set start_time as 2022-10-01T00:00:00.000Z and end_time as 2022-10-03T00:00:00.000Z. If you want to find futures or options that were traded at a specific time, simply use the same time for both start_time and end_time. If you only provide one of the start_time or end_time, the other one will be automatically determined as shown in the table below.

start_time (ISO 8601)	end_time (ISO 8601)	Description
Given	Given	start_time (ISO 8601) and end_time (ISO 8601) are the specified datetime respectively
Given	Not given	end_time (ISO 8601) = start_time (ISO 8601) + 1 day
Not given	Given	start_time (ISO 8601) = end_time (ISO 8601) - 1 day
Not given	Not given	all the instruments will be shown regardless of dates