# Price slippage (aggregation)

## What is this endpoint for?

This endpoint returns the **average** price slippage for the requested period. Read more about how the aggregation period works here: [Broken mention](broken://pages/olCeJDk3CCuULSNviPd9). 

### Endpoint

{% code overflow="wrap" %}

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

{% 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 width="246">Parameter</th><th width="119">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>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>interval</code></td><td>No</td><td>The interval parameter is suffixed with <code>s</code>, <code>m</code>, <code>h</code> or <code>d</code> to specify seconds, minutes, hours or days, respectively.<br><br>Any arbitrary value between one second and one day can be used, as long as it sums up to a maximum of 1 day. The suffixes are <code>s</code> (second), <code>m</code> (minute), <code>h</code> (hour) and <code>d</code> (day).<br><br> Default <code>1h</code>.</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. Default desc<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="274">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>poll_timestamp</code></td><td>The timestamp at which the interval begins.</td></tr><tr><td><code>ask_slippage</code></td><td>The average percentage of price slippage for a market buy order over a specified interval.</td></tr><tr><td><code>bid_slippage</code></td><td>The average percentage of price slippage for a market sell order over a specified interval.</td></tr></tbody></table>

### Request examples

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

```url
 'https://us.market-api.kaiko.io/v2/data/order_book_snapshots.v1/exchanges/krkn/spot/btc-usd/ob_aggregations/slippage?page_size=10&slippage=100000&interval=1h'
```

{% 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-01-03T00:00:00Z"
end_time= "2025-03-05T00:00:00Z"
slippage = 1000  
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, 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}/ob_aggregations/slippage'
    params = {
        "start_time": start_time,
        "end_time": end_time,
        "sort": sort,
        "page_size": page_size,
        "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), slippage=slippage, slippage_ref=slippage_ref)
```

{% endcode %}
{% endtab %}

{% tab title="Ruby" %}

```ruby
message = "hello world"
puts message
```

{% endtab %}
{% endtabs %}

### Response example

```json
{
    "query": {
        "page_size": 10,
        "exchange": "krkn",
        "instrument_class": "spot",
        "instrument": "btc-usd",
        "interval": "1h",
        "slippage": 100000,
        "slippage_ref": "mid_price",
        "sort": "desc",
        "aggregation": "slippage",
        "data_version": "v1",
        "commodity": "order_book_snapshots",
        "request_time": "2020-05-26T15:07:06.840Z"
    },
    "time": "2020-05-26T15:07:07.260Z",
    "timestamp": 1590505627260,
    "data": [
        {
            "poll_timestamp": 1590505200000,
            "ask_slippage": "0.00012513598764468878",
            "bid_slippage": "0.0003678539692963374"
        },
        {
            "poll_timestamp": 1590501600000,
            "ask_slippage": "0.00030969034268815156",
            "bid_slippage": "0.00024353107110561094"
        },
      /* ... */
    ],
    "result": "success",
    "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/price-slippage-aggregation.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.