Token-level liquidation volumes

Liquidation insight for derivatives exchanges

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 Derivatives markets - centralized

Endpoint

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

Path Parameters

Parameter	Required?	Example
region	Yes	Choose between eu and us.
asset	Yes	Base asset. See Exchange trading pair codes (instruments)

Query Parameters

Parameter	Required	Description	Example
interval	No	The interval parameter is suffixed with h or d 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. Default: 1h	1h
page_size	No	Number of snapshots to return data for. See Pagination Default: 100 Maximum: 1000	10
sort	No	Return the data in ascending (asc) or descending (desc) order. Default: desc	asc
start_time	No	Starting time in ISO 8601 (inclusive).	2025-01-01T00:00:00.000Z
end_time	No	Ending time in ISO 8601 (exclusive).	2025-01-04T00:00:00.000Z

Fields

Field	Description	Example
interval_time	Timestamp at which the interval begins in a readable format.	2025-03-17T00:00:00.000Z
interval_timestamp	Timestamp at which the interval begins. In milliseconds.	1742169600000000000
total_trades	The total number of long & short liquidation events.	703
total_amount	The total value of the long & short liquidations, expressed in USD.	4493384.579834212
long_trades	The total number of long liquidations.	275
long_amount	The total value of the long liquidations, expressed in USD	920343.8155558605
short_trades	The total number of short liquidations.	428
short_amount	The total value of the short liquidations, expressed in USD.	3573040.764278351
exchanges	A breakdown per exchange of the requested data	-
exchange	The specific exchange.	bbit
total_trades	The total number of long & short liquidation events for the specific exchange.	400
total_amount	The total value of the long & short liquidations for the specific exchange, expressed in USD.	2441098.7305411045
long_trades	The total number of long liquidations for the specific exchange.	131
long_amount	The total value of the long liquidations for the specific exchange, expressed in USD	303823.495563143
short_trades	The total number of short liquidations for the specific exchange.	269
short_amount	The total value of the short liquidations for the specific exchange, expressed in USD.	2137275.2349779615

Request examples

cURL

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'

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
)

Response example

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