Derivative liquidation events

Each and every derivative liquidation event

What is this endpoint for?

This endpoint returns all derivative liquidation events for a given instrument on an exchange. It includes all details available for the event like price and position. Data is available for futures and perpetual futures. For exchange coverage, see Cefi derivative markets.

Endpoint

https://{region}.market-api.kaiko.io/v2/data/liquidation.v1/trades/{exchange}/{instrument_class}/{instrument}

Path Parameters

Parameter	Required?	Example
region	Yes	Choose between: eu us
exchange	Yes	Exchange code. See Exchange codes
instrument_class	Yes	Choose between : future perpetual-future
instrument	Yes	Instrument code. See Exchange trading pair codes (instruments)

Query Parameters

Parameter	Required	Description	Example
start_time	No	Starting time in ISO 8601 (inclusive). Automatically included in continuation tokens.	2025-01-23T00:01:00.000Z
end_time	No	Ending time in ISO 8601 (exclusive). Automatically included in continuation tokens.	2025-02-25T23:59:00.000Z
sort	No	Return the data in ascending (asc) or descending (desc) order. Default: desc	asc
page_size	No	See Pagination Default: 100 Maximum: 1000	500

Fields

Field	Description	Example
amount	The quantity, displayed in base currency.	0.113
amount_quote	The quantity, displayed in the quote asset.	9362.592400000001
amount_usd	The quantity, displayed in USD.	9359.689996356
price	The price at which the liquidation was executed, displayed in USD.	82854.8
rate	Rate used to convert quote currency to USD. For example: 1 USDT = 0.997 USD	0.99969
position_side	The position liquidated	long
timestamp	The timestamp provided by the exchange or the collection timestamp in Unix Timestamp (in milliseconds)	1741785829372000000
trade_id	Unique trade ID (unique to the exchange). In case the exchange does not provide an ID, we generate it ourselves.	d472cae0135..dfdh6_g

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/trades/bbit/perpetual-future/eth-usdt?start_time=2025-04-12T00:00:00Z&end_time=2025-04-12T08:00:00Z&page_size=10'

Python

##### 1. Import dependencies #####
import requests
import pandas as pd
from urllib.parse import urlencode

##### 2. Choose the value of the query's parameters #####
# ---- Required parameters ---- #
exchange = "bbit"
instrument_class = "perpetual-future"
instrument = "eth-usdt"

# ---- Optional parameters ---- #
page_size = 10
sort = "desc"
start_time = "2025-04-12T00:00:00Z"
end_time = "2025-04-12T08: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_liquidation_trades(api_key: str, exchange: str, instrument_class: str, instrument: str, 
                                 start_time: str, end_time: str, sort: str, page_size: int):
    headers = {'Accept': 'application/json', 'X-Api-Key': api_key}
    
    base_url = f'https://us.market-api.kaiko.io/v2/data/liquidation.v1/trades/{exchange}/{instrument_class}/{instrument}'
    params = {
        "start_time": start_time,
        "end_time": end_time,
        "sort": sort,
        "page_size": page_size
    }
    
    # Debug: Show the URL being generated
    query_string = urlencode(params)
    full_url = f"{base_url}?{query_string}"
    print(f"DEBUG - Making request to URL: {full_url}")
    print(f"DEBUG - Headers: {headers}")
    
    try:
        res = requests.get(base_url, headers=headers, params=params)
        
        # Debug: Show the actual URL that requests used
        print(f"DEBUG - Actual request URL: {res.url}")
        print(f"DEBUG - Response status code: {res.status_code}")
        
        res.raise_for_status() 
        data = res.json()
        
        if 'data' not in data:
            print("No data returned.")
            return pd.DataFrame() 
            
        df = pd.DataFrame(data['data'])
        print(f"DEBUG - Initial data fetch successful, got {len(df)} records")
        
        # Handle pagination with continuation token
        page_count = 1
        while 'next_url' in data:
            next_url = data['next_url']
            if next_url is None:
                break
                
            print(f"DEBUG - Fetching page {page_count + 1} with URL: {next_url}")
            res = requests.get(next_url, headers=headers)
            res.raise_for_status()
            data = res.json()
            
            if 'data' in data:
                new_records = len(data['data'])
                df = pd.concat([df, pd.DataFrame(data['data'])], ignore_index=True)
                print(f"DEBUG - Fetched additional {new_records} records, total now: {len(df)}")
                page_count += 1
            else:
                print("DEBUG - No more data in pagination response")
                break
        
        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 ---- #
print("Starting API request...")
df = get_kaiko_liquidation_trades(
    api_key=api_key, 
    exchange=exchange,
    instrument_class=instrument_class,
    instrument=instrument,
    start_time=start_time, 
    end_time=end_time,
    sort=sort, 
    page_size=page_size
)

Response example

```json
{
   "query": {
      "exchange": "bbit",
      "instrument": "eth-usdt",
      "instrument_class": "perpetual-future",
      "commodity": "liquidationEvents",
      "request_time": "2025-04-04T11:58:32.545Z",
      "start_time": "2025-02-12T00:00:01.000Z",
      "start_timestamp": 1739318401000,
      "end_time": "2025-02-24T23:59:37.000Z",
      "end_timestamp": 1740441577000,
      "page_size": 10,
      "sort": "desc",
      "data_version": "v1"
   },
   "answer_time": "2025-04-04T11:58:32.554Z",
   "answer_timestamp": 1743767912554,
   "access": {
      "access_range": {
         "start_timestamp": 1688428800000,
         "end_timestamp": 2177539199000
      },
      "data_range": {
         "start_timestamp": null,
         "end_timestamp": null
      }
   },
   "data": [
      {
         "amount": 0.1,
         "amount_quote": 249.77100000000002,
         "amount_usd": 249.76370743089532,
         "price": 2497.71,
         "rate": 0.9999708029791101,
         "position_side": "long",
         "timestamp": 1740441553739,
         "trade_id": "376def42502a7a307b85d7ffdebec8c8c08990b19f6fb165e0f97c8fd058a1b2"
      },
      {
         "amount": 0.04,
         "amount_quote": 99.7556,
         "amount_usd": 99.75268743366291,
         "price": 2493.89,
         "rate": 0.9999708029791101,
         "position_side": "long",
         "timestamp": 1740441446020,
         "trade_id": "f1062a8c42743ffbddc3d129d65f1ae6848227b871361d6fd66f3bbbbb4b10da"
      },
        /*---*/
    ],
    */....
    
"continuation_token": "3RuQ1KYk3AEZTJXXqsaUMrdUKSYH4CVdGUFQCZC5pts7AYMafCjbnYSuedeLMFu72PsXKepcvdtpvZmNzXmotWV1ARAF8hJxLfaDXn75MmkN3zMq6ma9Ym",
   "next_url": "https://us.market-api.kaiko.io/v2/data/liquidation.v1/trades/bbit/perpetual-future/eth-usdt?continuation_token=3RuQ1KYk3AEZTJXXqsaUMrdUKSYH4CVdGUFQCZC5pts7AYMafCjbnYSuedeLMFu72PsXKepcvdtpvZmNzXmotWV1ARAF8hJxLfaDXn75MmkN3zMq6ma9Ym"
}