1 of 2

Raw order book snapshot

What is this endpoint for?

The raw data on which our Level 2 Aggregations such as market depth , bid/ask spread, and price slippage are built. Details a point-in-time view of the bids and asks on an exchange's order book to 10% depth. Used to build your own custom level 2 aggregations.

Endpoint

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

Path Parameters

Parameter

Required?

Description

region

Yes

Choose between eu and us.

Parameter

Required

Description

Field

Description

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.

Parameter

Required?

Description

Parameter

Required

Description

Field

Description

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.

Parameter

Required?

Description

Parameter

Required

Description

Field

Description

sort

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

slippage

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

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.

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.

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

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

Raw order book snapshot

What is this endpoint for?

Endpoint

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

Path Parameters

Parameter

Required?

Description

region

Yes

Choose between eu and us.

Parameter

Required

Description

Field

Description

bids

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

# ---- 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):
    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/raw'
    params = {
        "start_time": start_time,
        "end_time": end_time,
        "sort": sort,
        "page_size": page_size,
        "limit_orders": limit_orders
    }

    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)

{
    "query": {
        "page_size": 10,
        "exchange": "krkn",
        "instrument_class": "spot",
        "instrument": "btc-usd",
        "slippage": 0,
        "limit_orders": 2,
        "slippage_ref": "mid_price",
        "sort": "desc",
        "metric": "raw",
        "data_version": "v1",
        "commodity": "order_book_snapshots",
        "request_time": "2020-05-26T14:13:08.823Z"
    },
    "time": "2020-05-26T14:13:08.899Z",
    "timestamp": 1590502388899,
    "data": [
        {
            "poll_timestamp": 1590502335760,
            "poll_date": "2020-05-26T14:12:15.760Z",
            "timestamp": null,
            "asks": [
                {
                    "amount": "12",
                    "price": "8830"
                },
                {
                    "amount": "3.67",
                    "price": "8832.9"
                }
            ],
            "bids": [
                {
                    "amount": "13.316",
                    "price": "8829.9"
                },
                {
                    "amount": "0.097",
                    "price": "8829.4"
                }
            ]
        }
      /* ... */         
    ],
    "result": "success",
    "continuation_token": "Z8FjTagUoHd3UCqMvqmRJXlwzbTxSnSXpxxZpHWNCmrsrcnhSpMG2gdcmFKRPd88",
    "next_url": "https://us.market-api.kaiko.io/v2/data/order_book_snapshots.v1/exchanges/cbse/spot/btc-usd/snapshots/raw?continuation_token=Z8FjTagUoHd3UCqMvqmRJXlwzbTxSnSXpxxZpHWNCmrsrcnhSpMG2gdcmFKRPd88",
    "access": {
        "access_range": {
            "start_timestamp": null,
            "end_timestamp": null
        },
        "data_range": {
            "start_timestamp": null,
            "end_timestamp": null
        }
    }
}

Raw order book snapshot

What is this endpoint for?

Endpoint

Path Parameters

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

What is this endpoint for?

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

What is this endpoint for?

Endpoint

Path Parameters

Query Parameters

Fields

Request example

Response example

Raw order book snapshot

What is this endpoint for?

Endpoint

Path Parameters

Query Parameters

Fields

Request examples

Response example