Market depth (aggregation)

"Snapshots" show a point-in-time view generated every 30 seconds, whereas "aggregations" show an aggregation of all 30-second snapshots from the period requested.

What is this endpoint for?

This endpoint returns the average market depth for the requested period.

We are unable to collect the full 10% snapshot from all exchanges we cover. Thus, for some exchanges, 'Market Depth' does not accurately portray the exchange's order book volume.

Endpoint

https://us.market-api.kaiko.io/v2/data/order_book_snapshots.v1/exchanges/{exchange}/{instrument_class}/{instrument}/ob_aggregations/depth

Path Parameters

Parameter

Required?

Description

region

Yes

Choose between eu and us.

exchange

Yes

Exchange code.

See Exchange codes

instrument_class

Yes

Instrument class. See Exchange trading pair codes (instruments)

instrument

Yes

Instrument code. See Exchange trading pair codes (instruments)

Query Parameters

Parameter

Required

Description

end_time

Ending time in ISO 8601 (exclusive). Automatically included in continuation tokens.

continuation_token

See Pagination

interval

The interval parameter is suffixed with s, m, h or d to specify seconds, minutes, hours or days, respectively. Any arbitrary value between one second and one day can be used, as long as it sums up to a maximum of 1 day. The suffixes are s (second), m (minute), h (hour) and d (day). Default 1h.

page_size

Number of snapshots to return data for. (default: 10, max: 100). See Pagination Automatically included in continuation tokens.

sort

Return the data in ascending asc or descending desc order. Default desc Automatically included in continuation tokens.

start_time

Starting time in ISO 8601 (inclusive). Automatically included in continuation tokens.

Fields

poll_timestamp

The timestamp at which the interval begins

bid_volume_x

The average volume of bids placed within 0 and x% of the best bid over a specified interval.

ask_volume_x

The average volume of asks placed within 0 and x% of the best ask over a specified interval.

Request examples

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
  'https://us.market-api.kaiko.io/v2/data/order_book_snapshots.v1/exchanges/krkn/spot/btc-usd/ob_aggregations/depth?page_size=10&interval=1h'

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

##### 2. Choose the value of the query's parameters #####
# ---- Required parameters ---- #
exchange = "krkn" 
instrument_class = "spot"
pair = "btc-usd" #called "instrument" in the documentation

# ---- Optional parameters ---- #
sort = "desc"
page_size = 100
start_time= "2025-03-03T00:00:00Z"
end_time= "2025-03-05T00:00:00Z"

# ---- 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, pair: str, instrument_class: str, start_time: str, end_time: 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/order_book_snapshots.v1/exchanges/{exchange}/{instrument_class}/{pair}/ob_aggregations/depth'
    params = {
        "start_time": start_time,
        "end_time": end_time,
        "sort": sort,
        "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, pair=pair, instrument_class=instrument_class, start_time=start_time, end_time=end_time ,sort=sort, page_size=int(page_size))

Response example

{
    "query": {
        "page_size": 10,
        "exchange": "krkn",
        "instrument_class": "spot",
        "instrument": "btc-usd",
        "interval": "1h",
        "slippage": 0,
        "slippage_ref": "mid_price",
        "sort": "desc",
        "aggregation": "depth",
        "data_version": "v1",
        "commodity": "order_book_snapshots",
        "request_time": "2020-05-26T14:58:55.582Z"
    },
    "time": "2020-05-26T14:58:56.395Z",
    "timestamp": 1590505136395,
    "data": [
        {
            "poll_timestamp": 1590501600000,
            "bid_volume0_1": "31.31635593220339",
            "bid_volume0_2": "90.78996610169492",
            "bid_volume0_3": "144.16212711864407",
            "bid_volume0_4": "182.9676525423729",
            "bid_volume0_5": "219.1858220338983",
            "bid_volume0_6": "263.02182203389833",
            "bid_volume0_7": "296.666686440678",
            "bid_volume0_8": "322.5334237288136",
            "bid_volume0_9": "340.6282881355932",
            "bid_volume1": "356.4558474576271",
            "bid_volume1_5": "427.1106949152542",
            "bid_volume2": "475.76238135593223",
            "bid_volume4": "863.1048559322035",
            "bid_volume6": "1137.2281271186441",
            "bid_volume8": "1137.5447796610172",
            "bid_volume10": "1137.5447796610172",
            "ask_volume0_1": "22.772533898305085",
            "ask_volume0_2": "36.96916101694915",
            "ask_volume0_3": "78.57454237288135",
            "ask_volume0_4": "144.87783898305085",
            "ask_volume0_5": "195.61884745762714",
            "ask_volume0_6": "237.96824576271186",
            "ask_volume0_7": "282.3425338983051",
            "ask_volume0_8": "314.0606779661017",
            "ask_volume0_9": "330.76757627118644",
            "ask_volume1": "344.3153644067797",
            "ask_volume1_5": "413.4595423728814",
            "ask_volume2": "475.48172033898305",
            "ask_volume4": "886.8459152542373",
            "ask_volume6": "1272.5998644067795",
            "ask_volume8": "1371.7920847457626",
            "ask_volume10": "1371.7920847457626"
        },
      /* ... */
    ],
    "result": "success",
    "access": {
        "access_range": {
            "start_timestamp": null,
            "end_timestamp": null
        },
        "data_range": {
            "start_timestamp": null,
            "end_timestamp": null
        }
    }
}

PreviousMarket depth (snapshot)NextPrice slippage (snapshot)

Last updated 9 months ago

Was this helpful?

##### 1. Import dependencies ##### import requests import pandas as pd ##### 2. Choose the value of the query's parameters ##### # ---- Required parameters ---- # exchange = "krkn" instrument_class = "spot" pair = "btc-usd" #called "instrument" in the documentation # ---- Optional parameters ---- # sort = "desc" page_size = 100 start_time= "2025-03-03T00:00:00Z" end_time= "2025-03-05T00:00:00Z" # ---- 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, pair: str, instrument_class: str, start_time: str, end_time: 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/order_book_snapshots.v1/exchanges/{exchange}/{instrument_class}/{pair}/ob_aggregations/depth' params = { "start_time": start_time, "end_time": end_time, "sort": sort, "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, pair=pair, instrument_class=instrument_class, start_time=start_time, end_time=end_time ,sort=sort, page_size=int(page_size))

{ "query": { "page_size": 10, "exchange": "krkn", "instrument_class": "spot", "instrument": "btc-usd", "interval": "1h", "slippage": 0, "slippage_ref": "mid_price", "sort": "desc", "aggregation": "depth", "data_version": "v1", "commodity": "order_book_snapshots", "request_time": "2020-05-26T14:58:55.582Z" }, "time": "2020-05-26T14:58:56.395Z", "timestamp": 1590505136395, "data": [ { "poll_timestamp": 1590501600000, "bid_volume0_1": "31.31635593220339", "bid_volume0_2": "90.78996610169492", "bid_volume0_3": "144.16212711864407", "bid_volume0_4": "182.9676525423729", "bid_volume0_5": "219.1858220338983", "bid_volume0_6": "263.02182203389833", "bid_volume0_7": "296.666686440678", "bid_volume0_8": "322.5334237288136", "bid_volume0_9": "340.6282881355932", "bid_volume1": "356.4558474576271", "bid_volume1_5": "427.1106949152542", "bid_volume2": "475.76238135593223", "bid_volume4": "863.1048559322035", "bid_volume6": "1137.2281271186441", "bid_volume8": "1137.5447796610172", "bid_volume10": "1137.5447796610172", "ask_volume0_1": "22.772533898305085", "ask_volume0_2": "36.96916101694915", "ask_volume0_3": "78.57454237288135", "ask_volume0_4": "144.87783898305085", "ask_volume0_5": "195.61884745762714", "ask_volume0_6": "237.96824576271186", "ask_volume0_7": "282.3425338983051", "ask_volume0_8": "314.0606779661017", "ask_volume0_9": "330.76757627118644", "ask_volume1": "344.3153644067797", "ask_volume1_5": "413.4595423728814", "ask_volume2": "475.48172033898305", "ask_volume4": "886.8459152542373", "ask_volume6": "1272.5998644067795", "ask_volume8": "1371.7920847457626", "ask_volume10": "1371.7920847457626" }, /* ... */ ], "result": "success", "access": { "access_range": { "start_timestamp": null, "end_timestamp": null }, "data_range": { "start_timestamp": null, "end_timestamp": null } } }

Good night

What is this endpoint for?

Endpoint

Path Parameters

Query Parameters

Fields

Request examples

Response example