# Market depth (snapshot)

{% hint style="info" %}
"Snapshots" show a point-in-time view generated every 30 seconds, whereas "aggregations" show an aggregation of all 30-second snapshots from the period requested.
{% endhint %}

## What is this endpoint for?

This endpoint uses our [Raw order book snapshot](/rest-api/data-feeds/level-1-and-level-2-data/level-2-aggregations/raw-order-book-snapshot.md) as source data and enhances its raw data with the Market Depth metric. 

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.

{% hint style="info" %}
We are unable to collect the full 10% snapshot from all exchanges we cover. Thus, for some exchanges, 'Market Depth' does not accurately portray the exchange's order book volume.
{% endhint %}

### Endpoint

{% code overflow="wrap" %}

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

{% 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="/pages/QiW5iUvcyBF9RISFmZFV">/pages/QiW5iUvcyBF9RISFmZFV</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="/pages/8ywkQXfxfv1FjtyspEaU">/pages/8ywkQXfxfv1FjtyspEaU</a></td></tr><tr><td><code>instrument</code></td><td>Yes</td><td>Instrument <code>code</code>.<br><br>See <a data-mention href="/pages/8ywkQXfxfv1FjtyspEaU">/pages/8ywkQXfxfv1FjtyspEaU</a></td></tr></tbody></table>

### Query Parameters

<table><thead><tr><th>Parameter</th><th width="112">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>continuation_token</code></td><td>No</td><td>See <a data-mention href="/pages/mP3amLsYqKTsrRBoblxX">/pages/mP3amLsYqKTsrRBoblxX</a></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>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>page_size</code></td><td>No</td><td>Number of snapshots to return data for. (default: 10, max: 100). <br><br>See <a data-mention href="/pages/mP3amLsYqKTsrRBoblxX">/pages/mP3amLsYqKTsrRBoblxX</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></tbody></table>

### Fields

<table><thead><tr><th width="233">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></tbody></table>

### Request examples

{% 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/depth?page_size=10'
```

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

# ---- 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/depth'
    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))
```

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

### Response example

```json
{
    "query": {
        "page_size": 10,
        "exchange": "krkn",
        "instrument_class": "spot",
        "instrument": "btc-usd",
        "slippage": 0,
        "limit_orders": 0,
        "slippage_ref": "mid_price",
        "sort": "desc",
        "metric": "depth",
        "data_version": "v1",
        "commodity": "order_book_snapshots",
        "request_time": "2020-05-26T14:29:44.757Z"
    },
    "time": "2020-05-26T14:29:44.816Z",
    "timestamp": 1590503384816,
    "data": [
        {
            "poll_timestamp": 1590503344916,
            "poll_date": "2020-05-26T14:29:04.916Z",
            "timestamp": null,
            "bid_volume0_1": "37.606",
            "bid_volume0_2": "102.304",
            "bid_volume0_3": "141.907",
            "bid_volume0_4": "177.446",
            "bid_volume0_5": "203.634",
            "bid_volume0_6": "218.450",
            "bid_volume0_7": "283.128",
            "bid_volume0_8": "293.533",
            "bid_volume0_9": "321.986",
            "bid_volume1": "348.213",
            "bid_volume1_5": "405.080",
            "bid_volume2": "444.782",
            "bid_volume4": "837.949",
            "bid_volume6": "1110.065",
            "bid_volume8": "1110.065",
            "bid_volume10": "1110.065",
            "ask_volume0_1": "7.401",
            "ask_volume0_2": "13.744",
            "ask_volume0_3": "58.917",
            "ask_volume0_4": "131.104",
            "ask_volume0_5": "165.971",
            "ask_volume0_6": "193.786",
            "ask_volume0_7": "257.001",
            "ask_volume0_8": "286.384",
            "ask_volume0_9": "312.040",
            "ask_volume1": "319.040",
            "ask_volume1_5": "382.927",
            "ask_volume2": "475.467",
            "ask_volume4": "909.144",
            "ask_volume6": "1229.664",
            "ask_volume8": "1323.505",
            "ask_volume10": "1323.505"
        },
      /* ... */
],
    "result": "success",
    "continuation_token": "Z8FjYwcAjf7MZEG382e5MpmZx7wkuziQTyy2k5fVgSrcF8jAYqUpRgPH5cbQ9MhJiFaxGRbwiERMp3cWhXJshy",
    "next_url": "https://us.market-api.kaiko.io/v2/data/order_book_snapshots.v1/exchanges/cbse/spot/btc-usd/snapshots/depth?continuation_token=Z8FjYwcAjf7MZEG382e5MpmZx7wkuziQTyy2k5fVgSrcF8jAYqUpRgPH5cbQ9MhJiFaxGRbwiERMp3cWhXJshy",
    "access": {
        "access_range": {
            "start_timestamp": null,
            "end_timestamp": null
        },
        "data_range": {
            "start_timestamp": null,
            "end_timestamp": null
        }
    }
}        
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kaiko.com/rest-api/data-feeds/level-1-and-level-2-data/level-2-aggregations/market-depth-snapshot.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.