Exchange-provided metrics

Derivatives Risk endpoint

What is this endpoint for?

This endpoint returns exchange-provided metrics such as open interest, funding rates, and option greeks.

Endpoint

https://{eu/us}.market-api.kaiko.io/v2/data/derivatives.v2/risk

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	Yes	Instrument code. See Exchange trading pair codes (instruments) One instrument returned per query.	btcusdt250117
interval	No	Interval period (can be one of 1m, 1h, 4h, and 1d). Default 1m When you query data using aninterval greater than one minute, we'll return the data from the last minute of that time period. For example, if you query data for 09:00 with the interval set at 1h, we'll return data from 09:59 (since that's the last minute of the 09:00-10:00 hour period).	1h
page_size	No	Number of snapshots to return data for. (default: 100, min: 1, max: 1000). See Pagination	10
sort	No	Return the data in ascending (asc) or descending (desc) order. Default desc	asc
start_time	No	Starting time in ISO 8601 (inclusive).	2025-01-01T00:00:00.000Z
end_time	No	Ending time in ISO 8601 (exclusive).	2025-01-04T00:00:00.000Z

Fields: Perpetual-Future

Field	Description	Example
timestamp	Timestamp at which the interval begins. In milliseconds.	1650441900000
24h_volume	The volume of the trades executed in the last 24 hours (can be in base_asset, quote_asset or the number of contracts)	5270648
open_interest	The total outstanding number of contracts (units in which open interest metrics are quoted vary by exchange)	1127623
funding_rate	The current funding rate.	-0.0000756735759807
predicted_funding_rate	The predicted funding rate for the next period.	-0.0000845044644161

Fields: Future

Field	Description	Example
timestamp	Timestamp at which the interval begins. In milliseconds.	1650441900000
24h_volume	The volume of the trades executed in the last 24 hours (can be in base_asset, quote_asset or the number of contracts)	5270648
open_interest	The total outstanding number of contracts (units in which open interest metrics are quoted vary by exchange)	1127623
time_to_expiry	The number of minutes remaining before expiry.	41504
nearby	The soonest expiring contract with the same base & quote asset on the specified exchange	boolean value
quarterly_nearby	The soonest expiring quarterly contract with the same base & quote asset on the specified exchange	boolean value

Fields: Option

Field	Description	Example
timestamp	Timestamp at which the interval begins. In milliseconds.	1650441900000
24h_volume	The volume of the trades executed in the last 24 hours (can be in base_asset, quote_asset or the number of contracts)	5270648
open_interest	The total outstanding number of contracts (units in which open interest metrics are quoted vary by exchange)	1127623
time_to_expiry	The number of minutes remaining before expiry.	41504
nearby	The soonest expiring contract with the same base & quote asset on the specified exchange	boolean value
quarterly_nearby	The soonest expiring quarterly contract with the same base & quote asset on the specified exchange	boolean value
ask_iv	Implied volatility for the best ask.	57.5
bid_iv	Implied volatility for the best bid.	65.4
mark_iv	The implied volatility for the mark price.	69.42
delta	The delta value for the option.	0.8841
gamma	The gamma value for the option.	0.00003
rho	The rho value for the option.	21.26122
theta	The theta value for the option.	-26.18193
vega	The vega value for the option.	2.36321

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/risk?exchange=okex&instrument_class=perpetual-future&instrument=btc-usdt&page_size=2'

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 = "perpetual-future"
instrument = "btc-usdt"

# ---- Optional parameters ---- #
interval = "1h"
sort = "desc"
page_size = 100
start_time= None
end_time= None

# ---- 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, start_time: str, end_time: str, interval: str, sort: 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/risk'
    params = {
        "start_time": start_time,
        "end_time": end_time,
        "sort": sort,
        "page_size": page_size,
        "interval": interval,
        "exchange": exchange,
        "instrument_class": instrument_class,
        "instrument": instrument
    }

    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, interval=interval, start_time=start_time, end_time=end_time, sort=sort, page_size=page_size)
print (df)

BigQuery

Information from this endpoint can be accessed through Google BigQuery. To get started, read our guide.

Response example

{
    "query": {
        "page_size": "2",
        "exchange": "okex",
        "instrument_class": "perpetual-future",
        "instrument": "btc-usdt",
        "sort": "desc",
        "data_version": "v2",
        "commodity": "derivatives",
        "request_time": "2022-04-28T10:17:48.180Z"
    },
    "time": "2022-04-28T10:17:48.698Z",
    "timestamp": 1651141068698,
    "data": [
        {
            "timestamp": 1651141020000,
            "24h_volume": "10428503",
            "open_interest": "1084816",
            "funding_rate": "-0.0001225804461251",
            "predicted_funding_rate": "-0.0000652655998942"
        },
        {
            "timestamp": 1651140960000,
            "24h_volume": "10423219",
            "open_interest": "1086823",
            "funding_rate": "-0.0001225804461251",
            "predicted_funding_rate": "-0.0000654154039082"
        },

    ],

    /* ... */

    "access": {
        "access_range": {
            "start_timestamp": 1646006400,
            "end_timestamp": null
        },
        "data_range": {
            "start_timestamp": null,
            "end_timestamp": null
        }
    }
}