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

hashtagWhat is this endpoint for?

hashtagEndpoint

hashtagPath Parameters

hashtagQuery Parameters

hashtagFields

hashtagRequest examples

hashtagResponse example

What is this endpoint for?

Endpoint

Path Parameters

Query Parameters

Fields

Request examples

Response example