GET /v1/futures/liquidations
Updated
What does GET /v1/futures/liquidations do?
Every public liquidation event the futures venues publish, newest first. Max and up, and pay-per-call. Returns individual liquidation events: when, which venue and contract, which side, the price, the size in coins and the notional. side is the position that was liquidated: a long is closed by a forced sell.
Binance, OKX, Bybit and Gate publish liquidations; KuCoin, Bitget and MEXC publish none. Binance and OKX throttle their public feeds, so in a cascade their events are a lower bound; Bybit and Gate send every one.
The default window is the last hour. Narrow it with exchange, symbol, side, from and to; limit caps the events returned, up to 1,000.
Authentication
API key required. Set $BF to the API base and pass your key in $BLACKFORGE_API_KEY.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
exchange | string | No | binance, bybit, okx or gate (bitget, mexc and kucoin publish no liquidation feed). Omitted means all four. |
symbol | string | No | The venue's own contract symbol, as GET /v1/futures/symbols lists it: BTCUSDT (binance, bybit, bitget), BTC-USDT-SWAP (okx), BTC_USDT (gate, mexc), XBTUSDTM (kucoin). |
side | string (long | short) | No | The position that was liquidated. |
from | string | No | Range start, ISO 8601. Default: one hour before `to`. |
to | string | No | Range end, ISO 8601. Default: now. |
limit | number | No | How many events to return, newest first, 1 to 1000. Each counts as one row; `truncated` is true when the window held more. |
Parameter shapes from the live OpenAPI document.
Example request
curl -H "x-api-key: $BLACKFORGE_API_KEY" \
"$BF/v1/futures/liquidations?limit=5&from=2026-11-08T13:56:15Z&to=2026-11-09T13:56:15Z"Example response
{
"from": "2026-11-08T13:56:15.000Z",
"to": "2026-11-09T13:56:15.000Z",
"events": [
{
"ts": 1794232570086,
"exchange": "binance",
"symbol": "TSTUSDT",
"side": "long",
"price": 0.01462,
"quantity": 4010,
"notional": 58.6262
},
{
"ts": 1794232566522,
"exchange": "binance",
"symbol": "TSTUSDT",
"side": "long",
"price": 0.01468,
"quantity": 19813,
"notional": 290.85484
},
{
"ts": 1794232561146,
"exchange": "binance",
"symbol": "ONUSDT",
"side": "long",
"price": 0.252715,
"quantity": 2199,
"notional": 555.7202850000001
},
{
"ts": 1794232556156,
"exchange": "binance",
"symbol": "IDOLUSDT",
"side": "short",
"price": 0.0349232,
"quantity": 2999,
"notional": 104.7346768
},
{
"ts": 1794232556156,
"exchange": "binance",
"symbol": "JCTUSDT",
"side": "short",
"price": 0.010307,
"quantity": 4718,
"notional": 48.628426
}
],
"truncated": true
}Returns
A JSON object with the from and to of the window and an events array, newest first: each with ts (epoch milliseconds), exchange, symbol, side, price, quantity and notional. truncated is set when the window held more events than the limit.
Responses and errors
| Status | When |
|---|---|
400 | A parameter is malformed, side is not long or short, or limit is out of range. |
401 | The x-api-key header is missing or not a valid key. |
402 | No key and no x402 payment: the pay-per-call challenge is returned. |
403 | Your plan is below Max: liquidation events are Max and up, and pay-per-call. |
Columns it returns
Every futures column, its unit, the plan it opens on and the venues that publish it are on the futures data page, with the limits of each venue’s data.