Raw order book snapshot + market depth, bid/ask spread & price slippage

What is this endpoint for?

This endpoint returns raw order book used to calculate our aggregations, alongside the aggregations:

• 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.

• Price Slippage - calculates the potential slippage for a market buy order if it were placed at the time the Order Book Snapshot was taken.

• Bid-ask Spread - The bid-ask spread is the difference between the highest price that a buyer is willing to pay for an asset (the bid) and the lowest price that a seller is willing to accept (the ask). A smaller spread implies more liquidity.

Endpoint

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

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
continuation_token	No	See Pagination
end_time	No	Ending time in ISO 8601 (exclusive). Automatically included in continuation tokens.
limit_orders	No	Number of orders to return on bid and ask side per snapshot. To retrieve the best bid/ask, set this parameter to 1 Default: 10
page_size	No	Number of snapshots to return (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.
slippage	No	Order size (in quote asset) for which to calculate the percentage of slippage. Default: 0. When null is returned, not enough volume is present on the order book to execute the order.
slippage_ref	No	Price point for which to calculate slippage from. Either from the mid-price (mid_price) or from the best bid/ask (best). Default: mid_price.

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"
spread	The difference between the best bid and the best ask at the time the snapshot was taken. This is what we call "Bid Ask Spread"
mid_price	The mid price between the best bid and the best ask.
ask_slippage	The percentage price slippage for a market buy order placed at the time that the order book snapshot was taken.
bid_slippage	The percentage price slippage for a market sell order placed at the time that the order book snapshot was taken.
asks	The sell orders in the snapshot. If the limit_oders parameter is used, this will be reflected here. amount is the quantity of asset to sell, displayed in the base currency. price is displayed in the quote currency.
bids	The buy orders in the snapshot. If the limit_oders parameter is used, this will be reflected here. amount is the quantity of asset to buy, displayed in the base currency. price is displayed in the quote currency.

Request example

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/full?slippage=100000&page_size=10&limit_orders=2&slippage_ref=best'

Python

##### 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"
limit_orders= 10
slippage= 0
slippage_ref= "mid_price"

# ---- 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, limit_orders: int, slippage: int, slippage_ref: str):
    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}/snapshots/full'
    params = {
        "start_time": start_time,
        "end_time": end_time,
        "sort": sort,
        "page_size": page_size,
        "limit_orders": limit_orders,
        "slippage": slippage,
        "slippage_ref": slippage_ref
    }

    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), limit_orders=limit_orders, slippage=slippage, slippage_ref=slippage_ref)

Response example

JSON

{
    "query": {
        "page_size": 10,
        "exchange": "krkn",
        "instrument_class": "spot",
        "instrument": "btc-usd",
        "slippage": 100000,
        "limit_orders": 2,
        "slippage_ref": "best",
        "sort": "desc",
        "metric": "full",
        "data_version": "v1",
        "commodity": "order_book_snapshots",
        "request_time": "2020-05-26T14:10:06.320Z"
    },
    "time": "2020-05-26T14:10:06.418Z",
    "timestamp": 1590502206418,
    "data": [
        {
            "poll_timestamp": 1590502155757,
            "poll_date": "2020-05-26T14:09:15.757Z",
            "timestamp": null,
            "bid_volume0_1": "46.595",
            "bid_volume0_2": "110.570",
            "bid_volume0_3": "167.920",
            "bid_volume0_4": "198.416",
            "bid_volume0_5": "243.554",
            "bid_volume0_6": "346.467",
            "bid_volume0_7": "354.090",
            "bid_volume0_8": "359.058",
            "bid_volume0_9": "381.422",
            "bid_volume1": "384.066",
            "bid_volume1_5": "467.014",
            "bid_volume2": "522.441",
            "bid_volume4": "918.911",
            "bid_volume6": "1187.306",
            "bid_volume8": "1187.306",
            "bid_volume10": "1187.306",
            "ask_volume0_1": "13.158",
            "ask_volume0_2": "40.072",
            "ask_volume0_3": "71.129",
            "ask_volume0_4": "179.463",
            "ask_volume0_5": "259.140",
            "ask_volume0_6": "266.315",
            "ask_volume0_7": "324.288",
            "ask_volume0_8": "353.024",
            "ask_volume0_9": "376.738",
            "ask_volume1": "405.965",
            "ask_volume1_5": "467.665",
            "ask_volume2": "506.326",
            "ask_volume4": "862.843",
            "ask_volume6": "1322.553",
            "ask_volume8": "1428.856",
            "ask_volume10": "1428.856",
            "spread": "0.1",
            "mid_price": "8819.95",
            "ask_slippage": "0.0002782477139043083900226757369614512",
            "bid_slippage": "0.0",
            "asks": [
                {
                    "amount": "5.914",
                    "price": "8820"
                },
                {
                    "amount": "0.08",
                    "price": "8821"
                }
            ],
            "bids": [
                {
                    "amount": "11.814",
                    "price": "8819.9"
                },
                {
                    "amount": "4.197",
                    "price": "8819.8"
                }
            ]
        },
      /* ... */
],
    "result": "success",
    "continuation_token": "Ehad6pjoEpvpZSkvbtsyx8WxTj9vgc4s5VSow1USG8pXP1UGFSxSF7fTacxA54rYoqebnMTdCpE3ZxB3nSTM5CYNModkKRASDWMHymPFHNXnGL73RdkHSVUv6UYa4YwrRinH7JbwRqbB5HwmZdxWaonnaVkeZZc1wZiuK2oR4ePQdotGEnvKY8spPjYwnX8s3D6w1bCqZqL6ENaNH5Pa6b53MdbmyQBjE8F",
    "next_url": "https://us.market-api.kaiko.io/v2/data/order_book_snapshots.v1/exchanges/krkn/spot/btc-usd/snapshots/full?continuation_token=Ehad6pjoEpvpZSkvbtsyx8WxTjvgc4s5VSow1USG8pXP1UGFSxSF7fTacxA54rYoqebnMTdCpE3ZxB3nSTM5CYNModkKRASDWMHymPFHNXnGL73RdkHSVUv6UYa4YwrRinH7JbwRqbB5HwmZdxWaonnaVkeZZc1wZiuK2oR4ePQdotGEnvKY8spPjYwnX8s3D6w1bCqZqL6ENaNH5Pa6b53MdbmyQBjE8F",
    "access": {
        "access_range": {
            "start_timestamp": null,
            "end_timestamp": null
        },
        "data_range": {
            "start_timestamp": null,
            "end_timestamp": null
        }
    }
}