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 Exchanges
instrument_class	Yes	Instrument class. See Instruments
instrument	Yes	Instrument code. See Instruments

Query Parameters

Parameter	Required	Description
end_time	No	Ending time in ISO 8601 (exclusive). Automatically included in continuation tokens.
continuation_token	No	See Pagination
interval	No	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	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.
start_time	No	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

JavaScript

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'

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/order_book_snapshots.v1/exchanges/{exchange}/{instrument_class}/{instrument}/ob_aggregations/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-26T00:00:00Z",
    "end_time": "2024-09-26T10:00:00Z",
    "slippage_ref": "best",
    "slippage": "1000000",
    "interval": "1h",

}
# 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)}")

Ruby

message = "hello world"
puts message

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