24h Volume—Open Interest—24h Liquidations$1.36B24h Long/Short—BTC Dominance—ETH Dominance—
App
Language ▾
$ USD ▾
/api/sd/liquidations
GETAvailable

Liquidation summary for one coin

Self-data layer: liquidation summary for one coin

GET/api/sd/liquidations

Request

Query parameters

NameTypeRequiredDefaultAllowed valuesDescription
coinstringRequired——Coin symbol; 400 when missing. Alias: `base`. Example: BTC

Example request

curl -s "https://www.coinboss.com/api/sd/liquidations?coin=BTC"

Response fields

The field table is generated from real responses, so it lists exactly what the endpoint returns. Paths use a[] for array items and {*} for objects keyed by a dynamic name such as a coin or an exchange.

FieldTypeUnitDescription
successboolean—true when the request succeeded. On failure the body is `{ success: false, code, error, request_id }`.
coinstring—Coin symbol, upper case (for example BTC).
nownumbermsServer time when the response was built.
windowsobject—Totals for each window (keys such as `1h`, `4h`, `12h`, `24h`). dynamic keys: 1h,4h,12h,24h
windows.{*}object—Per-window values.
windows.{*}.long_usdnumberUSDLiquidated long positions; null when no source covered the window.
windows.{*}.short_usdnumberUSDLiquidated short positions; null when no source covered the window.
windows.{*}.total_usdnumberUSDLong + short.
windows.{*}.countnumber—Number of liquidation orders.
windows.{*}.long_pctnumber%Share of longs in the total.
windows.{*}.max_orderobject—Largest single liquidation in the window.
windows.{*}.max_order.exchangestring—Exchange id, lower case (for example `binance`).
windows.{*}.max_order.symbolstring—Instrument symbol as normalised by CoinBoss (for example BTCUSDT).
windows.{*}.max_order.sidestring—Side of the liquidated position (`long` = a long was liquidated).
windows.{*}.max_order.pricenumber—Last price in the quote currency (USD or USDT unless stated).
windows.{*}.max_order.qtynumber—Order size in contracts or coins as published by the exchange.
windows.{*}.max_order.contract_multipliernumber—Coins per contract used to convert `qty` to notional.
windows.{*}.max_order.value_usdnumberUSDNotional of the liquidation: price × qty × contract multiplier.
windows.{*}.max_order.timestampnumbermsTimestamp.
by_exchangeobject—Per-exchange split for each window. dynamic keys: 1h,4h,12h,24h
by_exchange.{*}array—Per-exchange breakdown.
by_exchange.{*}[]object—Per-exchange breakdown.
by_exchange.{*}[].exchangestring—Exchange id, lower case (for example `binance`).
by_exchange.{*}[].long_usdnumberUSDLong side.
by_exchange.{*}[].short_usdnumberUSDShort side.
by_exchange.{*}[].total_usdnumberUSDTotal.
by_exchange.{*}[].countnumber—Number of liquidation orders.
by_exchange.{*}[].share_pctnumber%Share of the total.
last_event_atnumbermsTime of the most recent liquidation for this coin.
last_event_age_snumbersSeconds since that event.
sourcesarray—State of every liquidation feed: how it is collected and when it last delivered.
sources[]object—Data sources.
sources[].exchangestring—Exchange id, lower case (for example `binance`).
sources[].viastring—Collection method (`ws`, `rest`, …).
sources[].statusstring—Feed state judged from its own event times and heartbeats.
sources[].feed_last_event_age_snumber|nullsSeconds since the event.
sources[].ws_heartbeat_age_snumber|nullsSeconds since the event.
sources[].judged_bystring—Which timestamp the status was judged from.
sources[].coin_last_event_age_snumber|nullsSeconds since the event.
sources[].min_event_usdnumberUSDSmallest order size the feed publishes; smaller liquidations are not visible on this venue.
sources[].notestring|null—Note.
sources[].node_heartbeat_age_snumbersSeconds since the event. may be absent
sources[].pipeline_last_event_age_snumbersSeconds since the event. may be absent
coverageobject—What is and is not included in the numbers above. Compare this before comparing totals with another source.
coverage.collected_exchangesarray—Exchanges with a public liquidation feed that CoinBoss collects.
coverage.collected_exchanges[]string—Exchanges collected.
coverage.unavailablearray—Exchange / contract pairs that could not be included, each with a reason. They are never counted as 0.
coverage.unavailable[]object—Items for which no data is available, with reasons. Never reported as 0.
coverage.unavailable[].exchangestring—Exchange id, lower case (for example `binance`).
coverage.unavailable[].reasonstring—Reason code.
methodobject—Plain-text statement of the formulas used for this response.
method.eventstring—Plain-text note on what one liquidation event is: one liquidation order pushed by the exchange stream or returned by its public REST API.
method.sidestring—Side of the liquidated position (`long` = a long was liquidated).
method.value_usdstringUSDNotional of the liquidation: price × qty × contract multiplier.
method.dedupestring—Plain-text note on de-duplication: events are unique by exchange, symbol, side, price, value and timestamp, plus the exchange order id where provided.
method.null_rulestring—Plain-text note that a window without any collected event returns null rather than 0, and where exchanges without a public feed are listed.
method.binance_notestring—Plain-text caveat that Binance pushes at most one liquidation per symbol per second, so Binance totals are a lower bound.
method.min_event_usdstringUSDSmallest order the feed publishes.

Generated 2026-11-11 23:00 UTC from 4 real responses.

Example response

/api/sd/liquidations?coin=BTC · Real response captured 2026-11-13 03:57:52 UTC. Long arrays and maps are shortened for display: sources had 11 items; windows had 4 items; by_exchange had 4 items; by_exchange.{*} had 10 items; coverage.unavailable had 10 items; coverage.collected_exchanges had 11 items.

  • {
    • "success": true,
    • "coin": "BTC",
    • "now": 1794542272606,
    • "windows": {
      • "1h": { … 6 },
      • "4h": { … 6 }
      },
    • "by_exchange": {
      • "1h": [ … 2 ],
      • "4h": [ … 2 ]
      },
    • "last_event_at": 1794542269523,
    • "last_event_age_s": 3,
    • "sources": [
      • { … 9 },
      • { … 9 }
      ],
    • "coverage": {
      • "collected_exchanges": [ … 8 ],
      • "unavailable": [ … 2 ]
      },
    • "method": {
      • "event": "one row per liquidation order pushed by the exchange (WS) or returned by its public REST; REST used to fill WS gaps (OKX/Gate/HTX)",
      • "side": "LONG = a long position was liquidated (forced sell); SHORT = a short position was liquidated (forced buy)",
      • "value_usd": "linear: filled qty × price; inverse: contracts × contract face value (USD)",
      • "dedupe": "unique (exchange, symbol, side, price, value_usd, timestamp) + exchange order id hash where provided",
      • "null_rule": "a window with no collected event returns null (shown as —), never 0; exchanges without a public feed are listed in coverage.unavailable",
      • "binance_note": "Binance WS pushes at most one liquidation per symbol per second (latest only) → Binance totals are a lower bound",
      • "min_event_usd": "collectors keep events above a per-exchange floor (sources[].min_event_usd: OKX/Bitget/HTX/Bitfinex/Deribit ≥ $100; Gate/Hyperliquid/Lighter ≥ $1; Binance/Bybit…"
      }
    }

Verified samples

Besides the example above, the probe calls this endpoint with these parameters and checks the schema each time.

ParametersHTTPLatencyResult
coin=ETH20059 msPass
coin=SOL20030 msPass
coin=ARKM20017 msPass
—4002 msPass returns the expected error

Checked 2026-11-13 03:57:52 UTC

Details

Authentication
None. Public endpoint.
Rate limit
1200 requests per minute per IP
Server cache
15s
Edge micro-cache
10s
Update frequency
real-time (exchange WebSocket push); REST polling: okx every 15 s, gate every 25 s, htx every 5 min; hyperliquid node fill batches ingested every 5 s
Window
rolling windows 1 h, 4 h, 12 h, 24 h
Data sources
Liquidation orders collected in-house from the public liquidation feeds of 11 venues (e.g. binance, okx, bybit, gate, bitget, htx); Hyperliquid liquidations come from the fills of a self-operated Hyperliquid node.
Exchange coverage
11 venues with active collectors (binance USDT-M + COIN-M, okx, bybit linear + inverse, gate USDT + BTC settled, bitget, htx, hyperliquid, aster, lighter, bitfinex, deribit); crypto assets only (tokenized stock / index / commodity / FX contracts are routed to the separate TradFi dataset); binance pushes at most one liquidation per symbol per second, so its totals are a lower bound; minimum stored event size: 100 USD on okx / bitget / htx / bitfinex / deribit / binance COIN-M, 1 USD on gate / hyperliquid / lighter, none on binance USDT-M / bybit / aster
Units
USD notional (price x quantity) per liquidation order; timestamps in Unix ms; side LONG = long position liquidated, SHORT = short position liquidated; max_order price normalized for multiplier contracts
Method
per window: long_usd, short_usd, total_usd = SUM(value_usd), count; by_exchange breakdown; largest single order
Timestamps
Unix epoch milliseconds (UTC) unless the field description says otherwise
Response format
json
Stability
Stable
Available since
2026-11-11

Live status

AvailableChecked 2026-11-13 03:57:52 UTCHTTP 200853 msSchema matchesNewest data point 3s old

Availability, last 30 days

100% of 410 checks passed

Errors

Failed calls share one shape on every endpoint. The full list is on the errors page. Errors and rate limits →

CodeHTTPMeaningWhat to do
INVALID_PARAM400A required parameter is missing or a value is not accepted. `param` names the parameter when it is known.Do not retry unchanged; fix the request.
UNAUTHORIZED401The `CB-API-KEY` header was sent but the key is unknown or revoked. Public data needs no key — drop the header or use a valid key.Do not retry unchanged.
FORBIDDEN403The route is not part of the public API (internal or account-only).Do not retry.
NOT_FOUND404Unknown route, or the requested coin / exchange / fund does not exist.Do not retry; check the path and identifiers against the catalog.
RATE_LIMITED429More requests than the per-minute limit. `Retry-After` gives the seconds to wait.Wait for `Retry-After`, then retry with backoff.
INTERNAL500Unexpected server error. The message is generic by design; quote `request_id` when reporting it.Retry once after a few seconds; report it with the request id if it persists.
UPSTREAM_FAILED503The data source behind this endpoint did not answer in time. No stale or substitute numbers are returned in its place.Retry with backoff; check the status page.
UNAVAILABLE501 / 503The dataset is temporarily not ready (cache warming) or the endpoint has no lawful public source yet.Retry later; the catalog marks endpoints that are unavailable by design.
REQUEST_FAILED200Some older endpoints answer HTTP 200 with `success: false`. Always check `success`, not only the HTTP status.Depends on the message; treat as a failed request.

Try it

GET/api/sd/liquidationsAvailable
Parameters

string — Coin symbol; 400 when missing. Alias: `base`.

Request URLhttps://www.coinboss.com/api/sd/liquidations?coin=BTC
Choose an endpoint and press “Send request”. The response, headers and timing will appear here.