Reference

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

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 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	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	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

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	btcusd220624
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
funding_rate_frequency	perpetual-future only. Interval at which the funding rate is paid	8h
listing_timestamp	future & option only. The timestamp when a certain option instrument is listed on the exchange	2020-03-28 03:21:00 UTC
expiry	future & option only. Expiration date of the contract	2022-06-24 08:00:00 UTC
strike_price	option only. The strike price of the contract in USD.	60000
underlying_index	option only. Name of the underlying asset	SYN.BTC-10APR20

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

import http.client
import json

# Enter your Kaiko API Key
api_key = "KAIKO_API_KEY"
api_host = "us.market-api.kaiko.io"
api_base_endpoint = "/v2/data/derivatives.v2/reference"

# Start of mandatory parameter configuration
mandatory_params = {
    "exchange": "drbt",
    "instrument_class": "option",
}
# End of mandatory parameter configuration

# Start of optional parameter configuration
optional_params = {
    "base_assets": "eth",
    "quote_assets": "usd",
    "start_time": "2024-09-27T13:13:53.441Z"

}
# End of optional parameter configuration
conn = http.client.HTTPSConnection(api_host)
headers = {
    "X-Api-Key": api_key,
    "Accept": "application/json"
}

all_params = {**mandatory_params, **optional_params}

url_params = []
for param, value in all_params.items():
    url_params.append(f"{param}={value}")
url_params = '&'.join(url_params)

# Pagination for next pages
all_data = []
next_url = f"{api_base_endpoint}?{url_params}"
while next_url:
    conn.request("GET", next_url, headers=headers)
    response = conn.getresponse()
    data = json.loads(response.read().decode("utf-8"))
    all_data.extend(data.get("data", []))
    print(f"Fetched {len(data.get('data', []))} datapoints. Total: {len(all_data)}")
    next_url = data.get("next_url", "").replace("https://us.market-api.kaiko.io", "")
    if not next_url:
        break
conn.close()
print(f" datapoints fetched: {(all_data)}")

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

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