# 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

{% code overflow="wrap" %}

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

{% endcode %}

### Path Parameters

<table><thead><tr><th width="203">Parameter</th><th>Required?</th><th>Description</th></tr></thead><tbody><tr><td><code>region</code></td><td>Yes</td><td>Choose between <code>eu</code> and <code>us</code>.</td></tr><tr><td><code>exchange</code></td><td>Yes</td><td><p>Exchange <code>code.</code> </p><p><br>See <a data-mention href="../../../reference-data/basic-tier/exchange-codes">exchange-codes</a></p></td></tr><tr><td><code>instrument_class</code></td><td>Yes</td><td>Instrument <code>class</code>. <br><br>See <a data-mention href="../../../reference-data/basic-tier/exchange-trading-pair-codes-instruments">exchange-trading-pair-codes-instruments</a></td></tr><tr><td><code>instrument</code></td><td>Yes</td><td>Instrument <code>code</code>.<br><br>See <a data-mention href="../../../reference-data/basic-tier/exchange-trading-pair-codes-instruments">exchange-trading-pair-codes-instruments</a></td></tr></tbody></table>

### Query Parameters

<table><thead><tr><th width="239">Parameter</th><th width="95">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>continuation_token</code></td><td>No</td><td>See <a data-mention href="../../../../general/getting-started/pagination">pagination</a></td></tr><tr><td><code>end_time</code></td><td>No</td><td>Ending time in ISO 8601 (exclusive).<br><br><em>Automatically included in continuation tokens.</em></td></tr><tr><td><code>limit_orders</code></td><td>No</td><td>Number of orders to return on bid and ask side per snapshot.<br><br>To retrieve the best bid/ask, set this parameter to <code>1</code> <br><br>Default: <code>10</code></td></tr><tr><td><code>page_size</code></td><td>No</td><td>Number of snapshots to return (default: 10, max: 100).<br><br>See <a data-mention href="../../../../general/getting-started/pagination">pagination</a><br><br><em>Automatically included in continuation tokens.</em></td></tr><tr><td><code>sort</code></td><td>No</td><td>Return the data in ascending <code>asc</code> or descending <code>desc</code> order. <br><br>Default: <code>desc.</code><br><br><em>Automatically included in continuation tokens.</em></td></tr><tr><td><code>start_time</code></td><td>No</td><td>Starting time in ISO 8601 (inclusive).<br><br><em>Automatically included in continuation tokens.</em></td></tr><tr><td><code>slippage</code></td><td>No</td><td>Order size (in quote asset) for which to calculate the percentage of slippage. <br><br>Default: <code>0</code>. <br><br>When <code>null</code> is returned, not enough volume is present on the order book to execute the order.</td></tr><tr><td><code>slippage_ref</code></td><td>No</td><td>Price point for which to calculate slippage from. Either from the mid-price (<code>mid_price</code>) or from the best bid/ask (<code>best</code>). <br><br>Default: <code>mid_price</code>.</td></tr></tbody></table>

### Fields

<table><thead><tr><th width="241">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>poll_timestamp</code></td><td>The timestamp at which the raw data snapshot was taken.</td></tr><tr><td><code>poll_date</code></td><td>The date at which the raw data snapshot was taken.</td></tr><tr><td><code>timestamp</code></td><td>The timestamp provided by the exchange. <code>null</code> when not provided.</td></tr><tr><td><code>bid_volume_x</code></td><td>The volume of bids placed within 0 and x% of the best bid.<br><br>This is what we call "Market Depth"</td></tr><tr><td><code>ask_volume_x</code></td><td>The volume of asks placed within 0 and x% of the best ask.<br><br>This is what we call "Market Depth"</td></tr><tr><td><code>spread</code></td><td>The difference between the best bid and the best ask at the time the snapshot was taken.<br><br>This is what we call "Bid Ask Spread"</td></tr><tr><td><code>mid_price</code></td><td>The mid price between the best bid and the best ask.</td></tr><tr><td><code>ask_slippage</code></td><td>The percentage price slippage for a market buy order placed at the time that the order book snapshot was taken.</td></tr><tr><td><code>bid_slippage</code></td><td>The percentage price slippage for a market sell order placed at the time that the order book snapshot was taken.</td></tr><tr><td><code>asks</code></td><td>The sell orders in the snapshot. If the <code>limit_oders</code> parameter is used, this will be reflected here. <code>amount</code> is the quantity of asset to sell, displayed in the base currency. <code>price</code> is displayed in the quote currency.</td></tr><tr><td><code>bids</code></td><td>The buy orders in the snapshot. If the <code>limit_oders</code> parameter is used, this will be reflected here. <code>amount</code> is the quantity of asset to buy, displayed in the base currency. <code>price</code> is displayed in the quote currency.</td></tr></tbody></table>

### Request example

{% tabs %}
{% tab title="cURL" %}
{% code overflow="wrap" %}

```url
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'
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code overflow="wrap" %}

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

{% endcode %}
{% endtab %}
{% endtabs %}

### Response example

{% tabs %}
{% tab title="JSON" %}

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

{% endtab %}
{% endtabs %}