Bid-ask spread (aggregation)

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/full?page_size=10&slippage=100000&interval=1h&start_time=2019-12-04T00:00:00Z&end_time=2019-12-06T00:00:00Z'

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

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

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

{
    "query": {
        "page_size": 10,
        "exchange": "krkn",
        "instrument_class": "spot",
        "instrument": "btc-usd",
        "interval": "1h",
        "slippage": 100000,
        "slippage_ref": "mid_price",
        "sort": "desc",
        "aggregation": "full",
        "data_version": "v1",
        "commodity": "order_book_snapshots",
        "request_time": "2020-05-26T14:46:00.561Z"
    },
    "time": "2020-05-26T14:46:03.776Z",
    "timestamp": 1590504363776,
    "data": [
        {
            "poll_timestamp": 1590501600000,
            "ask_slippage": "0.00032766083806437735",
            "bid_slippage": "0.0002206511273162024",
            "bid_volume0_1": "31.751239130434783",
            "bid_volume0_2": "87.33763043478261",
            "bid_volume0_3": "139.32403260869566",
            "bid_volume0_4": "177.62314130434783",
            "bid_volume0_5": "206.71984782608695",
            "bid_volume0_6": "251.4888043478261",
            "bid_volume0_7": "287.1503043478261",
            "bid_volume0_8": "317.3515869565217",
            "bid_volume0_9": "335.79671739130436",
            "bid_volume1": "352.03117391304346",
            "bid_volume1_5": "419.0988260869565",
            "bid_volume2": "470.6285",
            "bid_volume4": "859.7884347826086",
            "bid_volume6": "1134.0595760869564",
            "bid_volume8": "1134.4657173913045",
            "bid_volume10": "1134.4657173913045",
            "ask_volume0_1": "21.558043478260867",
            "ask_volume0_2": "37.20532608695652",
            "ask_volume0_3": "78.02648913043478",
            "ask_volume0_4": "143.83753260869565",
            "ask_volume0_5": "192.98572826086954",
            "ask_volume0_6": "235.31961956521738",
            "ask_volume0_7": "280.5659565217391",
            "ask_volume0_8": "309.4857717391304",
            "ask_volume0_9": "327.8923152173913",
            "ask_volume1": "341.79707608695657",
            "ask_volume1_5": "411.3568043478261",
            "ask_volume2": "475.6048586956521",
            "ask_volume4": "885.1007826086956",
            "ask_volume6": "1263.1216413043478",
            "ask_volume8": "1364.2838369565218",
            "ask_volume10": "1364.2838369565218",
            "mid_price": "8830.427717391303",
            "spread": "1.175"
        }
      /* ... */
    ],
    "result": "success",
    "access": {
        "access_range": {
            "start_timestamp": null,
            "end_timestamp": null
        },
        "data_range": {
            "start_timestamp": null,
            "end_timestamp": null
        }
    }
}