Derivatives 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

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

Instrument code. See

ethusd220624, btc*220624, *usdt, btc*may22*

base_assets

For finding the instruments with the certain base asset

btc, eth

quote_assets

For finding the instruments with the certain quote asset

usd, usdt

option_type

option only. For finding either only the call options or put options

C, P

min_strike

option only. Used to retrieve options whose strike price is above this minimum value (exclusive/inclusive)

10000

max_strike

option only. Used to retrieve options whose strike price is below this maximum value (exclusive/inclusive)

90000

start_time

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

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

Number of snapshots to return data for. (default: 1000, min: 1, max: 1000). See

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

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

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

all the instruments will be shown regardless of dates

PreviousReference Data NextDerivatives price

Last updated 1 month ago