Market depth (snapshot)

"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 uses our Bids and asks (snapshot) as source data and enhances its raw data with the Market Depth metric.

Market Depth provides insight into the "depth" of an exchange's order book by aggregating the volume of bids and asks within 0-10% of the best bid or ask, respectively. A higher volume of bids and asks at each level implies more liquidity.

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}/snapshots/depth

Path Parameters

Parameter	Required?	Description
region	Yes	Choose between eu and us.
exchange	Yes	Exchange code. See Exchanges
instrument_class	Yes	Instrument class. See Instruments
instrument	Yes	Instrument code. See Instruments

Query Parameters

Parameter	Required	Description
continuation_token	No	See Pagination
start_time	No	Starting time in ISO 8601 (inclusive). Automatically included in continuation tokens.
end_time	No	Ending time in ISO 8601 (exclusive). Automatically included in continuation tokens.
page_size	No	Number of snapshots to return data for. (default: 10, max: 100). See Pagination Automatically included in continuation tokens.
sort	No	Return the data in ascending asc or descending desc order. Default: desc. Automatically included in continuation tokens.

Fields

Field	Description
poll_timestamp	The timestamp at which the raw data snapshot was taken.
poll_date	The date at which the raw data snapshot was taken.
timestamp	The timestamp provided by the exchange. null when not provided.
bid_volume_x	The volume of bids placed within 0 and x% of the best bid. This is what we call "Market Depth".
ask_volume_x	The volume of asks placed within 0 and x% of the best ask. This is what we call "Market Depth"

Request examples

cURL

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/snapshots/depth?page_size=10'

Python

import http.client
import json

# Enter your Kaiko API Key
api_key = "KAIK0_API_KEY"
api_host = "us.market-api.kaiko.io"
api_base_endpoint = "/v2/data/order_book_snapshots.v1/exchanges/{exchange}/{instrument_class}/{instrument}/snapshots/depth"

# Start of mandatory parameter configuration
exchange = "krkn"
instrument_class = "spot"
instrument = "btc-usd"
# End of mandatory parameter configuration

# Start of optional parameter configuration
optional_params = {
    "start_time": "2024-09-25T11:16:35.947Z",
    "end_time": "2024-09-25T11:25:35.947Z",

}
# End of optional parameter configuration

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

api_endpoint = api_base_endpoint.format(exchange=exchange, instrument_class=instrument_class, instrument=instrument)

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

# Initial request
endpoint_with_params = f"{api_endpoint}?{url_params}"

# Pagination for next pages
all_trades = []
next_url = endpoint_with_params
while next_url:
    conn.request("GET", next_url, headers=headers)
    response = conn.getresponse()
    data = json.loads(response.read().decode("utf-8"))
    all_trades.extend(data.get("data", []))
    print(f"Fetched {len(data.get('data', []))} datapoints. Total: {len(all_trades)}")
    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_trades)}")

Response example

{
    "query": {
        "page_size": 10,
        "exchange": "krkn",
        "instrument_class": "spot",
        "instrument": "btc-usd",
        "slippage": 0,
        "limit_orders": 0,
        "slippage_ref": "mid_price",
        "sort": "desc",
        "metric": "depth",
        "data_version": "v1",
        "commodity": "order_book_snapshots",
        "request_time": "2020-05-26T14:29:44.757Z"
    },
    "time": "2020-05-26T14:29:44.816Z",
    "timestamp": 1590503384816,
    "data": [
        {
            "poll_timestamp": 1590503344916,
            "poll_date": "2020-05-26T14:29:04.916Z",
            "timestamp": null,
            "bid_volume0_1": "37.606",
            "bid_volume0_2": "102.304",
            "bid_volume0_3": "141.907",
            "bid_volume0_4": "177.446",
            "bid_volume0_5": "203.634",
            "bid_volume0_6": "218.450",
            "bid_volume0_7": "283.128",
            "bid_volume0_8": "293.533",
            "bid_volume0_9": "321.986",
            "bid_volume1": "348.213",
            "bid_volume1_5": "405.080",
            "bid_volume2": "444.782",
            "bid_volume4": "837.949",
            "bid_volume6": "1110.065",
            "bid_volume8": "1110.065",
            "bid_volume10": "1110.065",
            "ask_volume0_1": "7.401",
            "ask_volume0_2": "13.744",
            "ask_volume0_3": "58.917",
            "ask_volume0_4": "131.104",
            "ask_volume0_5": "165.971",
            "ask_volume0_6": "193.786",
            "ask_volume0_7": "257.001",
            "ask_volume0_8": "286.384",
            "ask_volume0_9": "312.040",
            "ask_volume1": "319.040",
            "ask_volume1_5": "382.927",
            "ask_volume2": "475.467",
            "ask_volume4": "909.144",
            "ask_volume6": "1229.664",
            "ask_volume8": "1323.505",
            "ask_volume10": "1323.505"
        },
      /* ... */
],
    "result": "success",
    "continuation_token": "Z8FjYwcAjf7MZEG382e5MpmZx7wkuziQTyy2k5fVgSrcF8jAYqUpRgPH5cbQ9MhJiFaxGRbwiERMp3cWhXJshy",
    "next_url": "https://us.market-api.kaiko.io/v2/data/order_book_snapshots.v1/exchanges/cbse/spot/btc-usd/snapshots/depth?continuation_token=Z8FjYwcAjf7MZEG382e5MpmZx7wkuziQTyy2k5fVgSrcF8jAYqUpRgPH5cbQ9MhJiFaxGRbwiERMp3cWhXJshy",
    "access": {
        "access_range": {
            "start_timestamp": null,
            "end_timestamp": null
        },
        "data_range": {
            "start_timestamp": null,
            "end_timestamp": null
        }
    }
}