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

Starting time in ISO 8601 (inclusive). Automatically included in continuation tokens.

2025-01-23T00:01:00.000Z

end_time

Ending time in ISO 8601 (exclusive). Automatically included in continuation tokens.

2025-02-25T23:59:00.000Z

sort

Return the data in ascending (asc) or descending (desc) order. Default: desc

asc

page_size

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 --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'

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

PreviousAll trades NextBorrows, repayments, liquidations, and withdrawals

Last updated 9 months ago

Was this helpful?

##### 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 )

Good morning

hashtagWhat is this endpoint for?

hashtagEndpoint

hashtagPath Parameters

hashtagQuery Parameters

hashtagFields

hashtagRequest examples

hashtagResponse example

What is this endpoint for?

Endpoint

Path Parameters

Query Parameters

Fields

Request examples

Response example