Raw order book snapshot

This data is included in the following Kaiko packages:

• Level 1 & Level 2 Data [Level 2 Aggregations]
• Level 1 & Level 2 Data [Level 2 Tick-Level]

CeFi Spot ticker packs.

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}/spot/{instrument}/snapshots/raw

Path Parameters

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

Query Parameters

Parameter	Required	Description
continuation_token	No	See
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 data for. Default: 10 Max: 100 See 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.
end_time	No	Ending time in ISO 8601 (exclusive). 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.
asks	The sell orders in the snapshot. If the limit_orders 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_orders 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 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/raw?page_size=10&limit_orders=2'

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

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

Response example

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

This data is included in the following Kaiko packages:

• Level 1 & Level 2 Data [Level 2 Aggregations]
• Level 1 & Level 2 Data [Level 2 Tick-Level]

CeFi Spot ticker packs.

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}/spot/{instrument}/snapshots/raw

Path Parameters

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

Query Parameters

Parameter	Required	Description
continuation_token	No	See
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 data for. Default: 10 Max: 100 See 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.
end_time	No	Ending time in ISO 8601 (exclusive). 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.
asks	The sell orders in the snapshot. If the limit_orders 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_orders 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 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/raw?page_size=10&limit_orders=2'

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

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

Response example

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