# Token-level liquidation volumes

## What is this endpoint for?

This endpoint returns the volumes of liquidations for derivatives contracts for a given asset. Data is aggregated across the interval requested, and expressed in USD value. Data is available for futures and perpetual futures.\
\
For exchange coverage, see [Cefi derivative markets](/coverage/cefi-derivative-markets.md)

### Endpoint

{% code overflow="wrap" %}

```http
https://<eu|us>.market-api.kaiko.io/v2/data/liquidation.v1/token/{asset}
```

{% endcode %}

### Path Parameters

| Parameter | Required? | Example                                                                                                           |
| --------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
| `region`  | Yes       | Choose between `eu` and `us`.                                                                                     |
| `asset`   | Yes       | <p>Base asset. See <br><br><a data-mention href="/pages/8ywkQXfxfv1FjtyspEaU">/pages/8ywkQXfxfv1FjtyspEaU</a></p> |

### Query Parameters

<table><thead><tr><th width="199">Parameter</th><th width="128">Required</th><th width="324">Description</th><th>Example</th></tr></thead><tbody><tr><td><code>interval</code></td><td>No</td><td>The interval parameter is suffixed with  <code>h</code> or <code>d</code> to specify hours or days, respectively. Any arbitrary value between one hour and one day can be used, as long as it sums up to a maximum of 1 day. <br><br>Default: <code>1h</code></td><td><code>1h</code></td></tr><tr><td><code>page_size</code></td><td>No</td><td><p>Number of snapshots to return data for. <br><br>See <a data-mention href="/pages/mP3amLsYqKTsrRBoblxX">/pages/mP3amLsYqKTsrRBoblxX</a><br><br>Default: <code>100</code></p><p>Maximum: <code>1000</code></p></td><td><code>10</code></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></td><td><code>asc</code></td></tr><tr><td><code>start_time</code></td><td>No</td><td>Starting time in ISO 8601 (inclusive).</td><td><code>2025-01-01T00:00:00.000Z</code></td></tr><tr><td><code>end_time</code></td><td>No</td><td>Ending time in ISO 8601 (exclusive).</td><td><code>2025-01-04T00:00:00.000Z</code></td></tr></tbody></table>

### Fields

<table><thead><tr><th width="208">Field</th><th width="283">Description</th><th>Example</th></tr></thead><tbody><tr><td><code>interval_time</code></td><td>Timestamp at which the interval begins in a readable format.</td><td><code>2025-03-17T00:00:00.000Z</code></td></tr><tr><td><code>interval_timestamp</code></td><td>Timestamp at which the interval begins. In milliseconds.</td><td><code>1742169600000000000</code></td></tr><tr><td><code>total_trades</code></td><td>The total number of long &#x26; short liquidation events.</td><td><code>703</code></td></tr><tr><td><code>total_amount</code></td><td>The total value of the long &#x26; short liquidations, expressed in USD.</td><td><code>4493384.579834212</code></td></tr><tr><td><code>long_trades</code></td><td>The total number of long liquidations.</td><td>275</td></tr><tr><td><code>long_amount</code></td><td>The total value of the long liquidations, expressed in USD</td><td><code>920343.8155558605</code></td></tr><tr><td><code>short_trades</code></td><td>The total number of short liquidations.</td><td><code>428</code></td></tr><tr><td><code>short_amount</code></td><td>The total value of the short liquidations, expressed in USD.</td><td><code>3573040.764278351</code></td></tr><tr><td><code>exchanges</code></td><td>A breakdown per exchange of the requested data</td><td>-</td></tr><tr><td><ul><li><mark style="color:blue;"><code>exchange</code></mark></li></ul></td><td>The specific exchange.</td><td><code>bbit</code></td></tr><tr><td><ul><li><mark style="color:blue;"><code>total_trades</code></mark></li></ul></td><td>The total number of long &#x26; short liquidation events for the specific exchange.</td><td>400</td></tr><tr><td><ul><li><mark style="color:blue;"><code>total_amount</code></mark></li></ul></td><td>The total value of the long &#x26; short liquidations for the specific exchange, expressed in USD.</td><td><code>2441098.7305411045</code></td></tr><tr><td><ul><li><mark style="color:blue;"><code>long_trades</code></mark></li></ul></td><td>The total number of long liquidations for the specific exchange.</td><td><code>131</code></td></tr><tr><td><ul><li><mark style="color:blue;"><code>long_amount</code></mark></li></ul></td><td>The total value of the long liquidations for the specific exchange, expressed in USD</td><td><code>303823.495563143</code></td></tr><tr><td><ul><li><mark style="color:blue;"><code>short_trades</code></mark></li></ul></td><td>The total number of short liquidations for the specific exchange.</td><td><code>269</code></td></tr><tr><td><ul><li><mark style="color:blue;"><code>short_amount</code></mark></li></ul></td><td>The total value of the short liquidations for the specific exchange, expressed in USD.</td><td><code>2137275.2349779615</code></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/liquidation.v1/token/eth?interval=1h&start_time=2025-01-31T09:00:01Z&end_time=2025-02-27T23:59:59Z&page_size=2'
```

{% 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 ---- #
asset = "eth"

# ---- Optional parameters ---- #
interval = "1h"
sort = "desc"
page_size = 2
start_time = "2025-04-11T00:00:00.000Z"
end_time = "2025-04-12T00:00:00.000Z"

# ---- 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_liquidation_data(api_key: str, asset: str, start_time: str, end_time: str, interval: 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/liquidation.v1/token/{asset}'
    params = {
        "start_time": start_time,
        "end_time": end_time,
        "sort": sort,
        "page_size": page_size,
        "interval": interval
    }
    
    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}")
        print(f"Response status code: {e.response.status_code if hasattr(e, 'response') else 'N/A'}")
        print(f"Response text: {e.response.text if hasattr(e, 'response') else 'N/A'}")
        return pd.DataFrame() 

# ---- Get the data ---- #
df = get_kaiko_liquidation_data(
    api_key=api_key, 
    asset=asset, 
    start_time=start_time, 
    end_time=end_time,
    interval=interval, 
    sort=sort, 
    page_size=page_size
)
```

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

### Response example

{% code overflow="wrap" %}

```json

{
   "query": {
      "request_time": "2025-04-04T12:09:55.546Z",
      "query_start_time": "2025-01-31T09:00:01Z",
      "query_end_time": "2025-02-27T23:59:59Z",
      "data_start_time": "2025-01-31T09:00:00Z",
      "data_end_time": "2025-02-28T00:00:00Z",
      "start_time": "2025-02-27T22:00:00Z",
      "start_timestamp": 1740693600000,
      "end_time": "2025-02-28T00:00:00Z",
      "end_timestamp": 1740700800000,
      "page_size": 2,
      "sort": "desc",
      "token": "eth",
      "interval": "1h",
      "commodity": "liquidationEvents",
      "data_version": "v1"
   },
   "answer_time": "2025-04-04T12:09:55.574Z",
   "answer_timestamp": 1743768595574,
   "access": {
      "access_range": {
         "start_timestamp": 1688428800000,
         "end_timestamp": 2177539199000
      },
      "data_range": {
         "start_timestamp": null,
         "end_timestamp": null
      }
   },
   "data": [
      {
         "interval_time": "2025-02-27T23:00:00Z",
         "interval_timestamp": 1740697200000000000,
         "total_trades": 40,
         "total_amount": 474520.3599480028,
         "long_trades": 2,
         "long_amount": 11062.85615080547,
         "short_trades": 38,
         "short_amount": 463457.50379719737,
         "exchanges": [
            {
               "exchange": "bbit",
               "total_trades": 17,
               "total_amount": 281481.78156436956,
               "long_trades": 0,
               "long_amount": 0,
               "short_trades": 17,
               "short_amount": 281481.78156436956
            },
            {
               "exchange": "okex",
               "total_trades": 23,
               "total_amount": 193038.57838363323,
               "long_trades": 2,
               "long_amount": 11062.85615080547,
               "short_trades": 21,
               "short_amount": 181975.72223282777
            }
         ]
      },
    /*---*/
"continuation_token": "4AQYBmrXFXrfMgzPkwxZmPNbc7WvZ1vVyZfqFXgjH9iCzvLnGZMMQTLoXwGdCLrB3DXwBVD9eSh2BjdpvsKGeWx9cBQfVc88qsDr64eCyNCNguwka8DLYbtT9F57FxpMFzrFyCTqiHMGBqdJsRj4K51oD2RmMK9oXwEB4o6VpQDWFvG3W5ndFJT13Uxvyycw41hgU2xDs6KTqSpzPrqmCwdeMzX2L71FUrhziwv7VXp9Txwz8Jac6wjGEJZpxYG7C3tF48YMN7hoSUvrXco9VxoDDpdSfduib8wtHjhjGV1re4z4CKBj6FcLakVvvVV1HoJLzpNbf7yMJZdyrTKXRYec6b",
   "next_url": "https://us.market-api.kaiko.io/v2/data/liquidation.v1/token/eth?continuation_token=4AQYBmrXFXrfMgzPkwxZmPNbc7WvZ1vVyZfqFXgjH9iCzvLnGZMMQTLoXwGdCLrB3DXwBVD9eSh2BjdpvsKGeWx9cBQfVc88qsDr64eCyNCNguwka8DLYbtT9F57FxpMFzrFyCTqiHMGBqdJsRj4K51oD2RmMK9oXwEB4o6VpQDWFvG3W5ndFJT13Uxvyycw41hgU2xDs6KTqSpzPrqmCwdeMzX2L71FUrhziwv7VXp9Txwz8Jac6wjGEJZpxYG7C3tF48YMN7hoSUvrXco9VxoDDpdSfduib8wtHjhjGV1re4z4CKBj6FcLakVvvVV1HoJLzpNbf7yMJZdyrTKXRYec6b"
}
```

{% endcode %}


---

# 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/analytics-solutions/kaiko-derivatives-risk-indicators/token-level-liquidation-volumes.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.