Coinglass Liquidation Heatmap

Quick Start

Collect crypto liquidation events and aggregated long/short heatmap totals across major exchanges. Use it for trading dashboards, market-shock monitoring, and scheduled snapshots of forced-liquidation activity. Start with this minimal input:

{"timeWindow": "1h", "minUsd": 10000}

Data is public market data; no account or API key is needed.

Input

Name	Type	Default	What it does
timeWindow	string	1h	Lookback window: 1h, 4h, 12h, or 24h.
exchanges	array	[]	Optional exchange allow-list (e.g. ["Binance", "OKX"]), case-insensitive. Empty = all.
symbols	array	[]	Optional coin watchlist ("BTC", "btc", and "BTCUSDT" all select BTC). Empty = every symbol.
minUsd	number	0	Keep only liquidation events of at least this USD size.
maxEvents	integer	2000	Maximum events collected per run (100–5000).
alertUsd	number	0	When > 0, every event at or above this USD size sends one Telegram alert. 0 disables alerts.
telegramBotToken	string	empty	Secret bot token for alerts; falls back to the TELEGRAM_BOT_TOKEN environment variable.
telegramChatId	string	empty	Chat that receives the alerts.
requestDelaySecs	number	0.3	Pause between paged requests.

Output

The dataset has two record kinds. liquidation_event rows carry recordKey, source, kind, exchange, symbol, pair, side (long/short), window, valueUsd, quantity, price, eventTime, sourceUrl, and collectedAt. liquidation_bucket rows aggregate per exchange and side: valueUsd, quantity, eventCount, and coveredSeconds.

The run summary (KeyValue store OUTPUT) reports counts, coverage, the alert report, and any warnings. records counts only the rows stored in the dataset; if your maximum charge per run stops the run early, stoppedBy is chargeLimit and the summary line says how many records were stored.

Output example

Real records from a run with the Quick Start input: one liquidation event and the all-exchange long total for the same window.

{"recordKey":"liq:Binance:DOGE:1792562507111:long:30055.6","source":"coinglass-capi","kind":"liquidation_event","exchange":"Binance","symbol":"DOGE","pair":"DOGEUSDT","side":"long","window":"1h","valueUsd":30055.6362,"quantity":369870,"price":0.08126,"eventCount":null,"eventTime":"2026-10-21T06:01:47.111000+00:00","coveredSeconds":null,"sourceUrl":"https://www.coinglass.com/LiquidationData","collectedAt":"2026-10-21T06:06:58.889263+00:00"}
{"recordKey":"liq-bucket:All:long:1h","source":"coinglass-capi","kind":"liquidation_bucket","exchange":"All","symbol":null,"pair":null,"side":"long","window":"1h","valueUsd":987002.19,"quantity":5128779.99567,"price":null,"eventCount":27,"eventTime":null,"coveredSeconds":2725,"sourceUrl":"https://www.coinglass.com/LiquidationData","collectedAt":"2026-10-21T06:06:58.889263+00:00"}

FAQ

How fresh is the data? Each run reads the live feed. The feed retains roughly the last 2–3 hours of events; a wider window reports the span actually covered via coveredSeconds.

Which exchanges are covered? Major futures exchanges including Binance, OKX, Bybit, Bitget, Gate, HTX, Hyperliquid, and others. Filter with exchanges if you need a subset.

Is there a minimum event size? The feed itself carries events from roughly $1,000 upward; raise the floor with minUsd.

What happens on partial data? Unavailable values are returned as explicit null, never guessed, and problems are listed in the run warnings. A failed alert send is a warning, not a failed run.

Price

$0.0015 per result row, the same for a liquidation event row and an exchange total row, plus $0.005 per run start. The run-start event is charged per GB of memory; the default 512 MB run is one start event. The start is charged even if the run saves no rows. You are charged only for result rows that are actually saved to the dataset; if fetching or validation fails, no rows are saved and none are charged. Platform usage is included in these prices.

For support, contact Apify support and include the Actor run ID.