# 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](https://app.gitbook.com/s/zwO3AMVXsp37KK2FngVc/coverage/cefi-derivative-markets "mention")

### 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="../../data-feeds/reference-data/basic-tier/exchange-trading-pair-codes-instruments">exchange-trading-pair-codes-instruments</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="../../general/getting-started/pagination">pagination</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 %}