Liquidations

Retrieves historical liquidations for derivatives markets.

All parameters are optional. Supported Exchanges:

• Binance

• OKX

• Bybit

• HTX

Historical Liquidations across major CEXes

GET https://api.coinact.gg/v1/liquidation-history

Query Parameters

Name	Type	Description
symbol	String	Get liquidations for a specific cryptocurrency eg: BTC
exchange	String	Get liquidations for a specific exchange (see endpoint /exchanges) default: ALL (every exchanges)
side	Integer	1 -> Short Liquidation 2 -> Long Liquidation
amountUsd	Float	Get liquidations superior to a certain USD amount. eg: 50000.5
start	UNIX Timestamp (s)	Get liquidations on a given period
end	UNIX Timestamp (s)	Get liquidations on a given period
page	Integer	id of the page you want to query (default=1)
limit	Integer	Number of liquidations to return (default:200 ; max: 200)

Headers

Name	Type	Description
x-api-key*	String	Your API Key

200: OK A list of liquidations

[
    {
        "symbol": "JTO",
        "side": 1,
        "pair": "JTO/USDT:USDT",
        "exchangeLabel": "OKX FUTURES",
        "exchangeId": 4096,
        "amountUsd": 593.23,
        "amount": 272.0,
        "priceUsd": 2.181,
        "threshold": -1,
        "ts": "2024-01-12T10:02:00"
    },
    {
        "symbol": "ETH",
        "side": 1,
        "pair": "ETH/USDT:USDT",
        "exchangeLabel": "OKX FUTURES",
        "exchangeId": 4096,
        "amountUsd": 54735.43,
        "amount": 20.9,
        "priceUsd": 2618.92,
        "threshold": -1,
        "ts": "2024-01-12T10:01:35"
    }
]

400: Bad Request An error indicating why the request is invalid

{
    "error": [
        {
            "loc": [
                "symbol"
            ],
            "msg": "Invalid symbol format",
            "type": "value_error"
        }
    ]
}

Usage Example:

Query BTC liquidations that happened on a given period no matter the exchange

import json
import requests
from urllib.parse import urljoin

COINACT_API_URL = "https://api.coinact.gg/v1/"
ENDPOINT = "liquidation-history"
HEADERS = {"x-api-key": "YOUR API KEY"}

def get_liquidations(session, start, end, page):
    params = {
        'symbol': 'BTC',
        'start': start,
        'end': end,
        'page': page
    }
    response = session.get(urljoin(COINACT_API_URL, ENDPOINT), headers=HEADERS, params=params)
    return json.loads(response.content)

def fetch_all_liquidations(start, end):
    liquidations = []
    page = 1
    with requests.Session() as session:
        while True:
            results = get_liquidations(session, start, end, page)
            if not results:
                break
            liquidations.extend(results)
            page += 1
    return liquidations

if __name__ == "__main__":
    start_timestamp = '1704123127'
    end_timestamp = '1705347127'
    all_liquidations = fetch_all_liquidations(start_timestamp, end_timestamp)
    print(all_liquidations)
    print(len(all_liquidations))