Coinglass Liquidation Heatmap Scraper

Collect crypto futures liquidations from Coinglass: one row per forced liquidation (exchange, coin, pair, long or short, USD size, price, time) plus long/short totals per exchange and market-wide for the same window. Built for traders, quant hobbyists and bot builders who schedule runs and feed the JSON into dashboards, alerts or models. No account or API key is needed.

Data only, not financial advice.

Use cases

• Liquidation dashboards: chart long vs short liquidations per exchange, refreshed every hour on a schedule.
• Market-shock alerts: get a Telegram message when a single liquidation above your USD threshold hits (for example $1M+ BTC longs).
• Squeeze research: compare long and short totals across Binance, OKX, Bybit, Hyperliquid and others around big price moves.
• Model features: store hourly snapshots and use liquidation volume and side balance as inputs to your own backtests.

Quick start

1. Open the Actor and click Start. The form is prefilled with a 1-hour window, every exchange, every coin and no size floor.
2. Read the rows in the Output tab, or export them as JSON, CSV or Excel.

To keep only the larger events, start from this input:

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

An empty input ({}) runs the same defaults as the prefilled form: a 1-hour window across all exchanges and coins, up to 2,000 events.

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, up to 20. Empty = all.
symbols	array	[]	Optional coin watchlist, up to 100 ("BTC", "btc" and "BTCUSDT" all select BTC). Empty = every coin.
minUsd	number	0	Keep only liquidations of at least this USD size. Totals are computed from the kept events.
maxEvents	integer	2000	Maximum events collected per run (100–5,000).
alertUsd	number	0	When above 0, each liquidation at or above this USD size (long or short) sends one Telegram message, largest first, up to 25 per run. 0 turns alerts off.
telegramBotToken	string	empty	Secret bot token for alerts; if empty, the TELEGRAM_BOT_TOKEN secret environment variable is used.
telegramChatId	string	empty	Chat that receives the alerts.
requestDelaySecs	number	0.3	Pause between pages of results (0–10 seconds).

A misspelt input field stops the run with an error that names it, so a typo never silently returns an unfiltered board.

Output

The dataset has two record kinds:

• liquidation_event: recordKey, source, kind, exchange, symbol, pair, side (long/short), window, valueUsd, quantity, price, eventTime, sourceUrl, collectedAt.
• liquidation_bucket: one row per exchange and side, plus an All row per side for the whole market, with valueUsd, quantity, eventCount and coveredSeconds (the time span the events actually cover).

Fields that don't apply to a kind are null. The run summary (key-value store OUTPUT) reports counts, coverage, the alert report and any warnings. records counts only rows saved to the dataset; if your maximum charge per run stops the run early, stoppedBy is chargeLimit and the status message says how many rows 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"}

Pricing

• $0.0015 per result row, the same for a liquidation event row and a total row.
• $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 pay only for rows actually saved to the dataset; if fetching or validation fails, no rows are saved and none are charged. Platform usage is included.

Worked cost: a run that saves 180 events and 20 total rows (200 rows) costs $0.005 + 200 × $0.0015 = $0.305. 1,000 rows cost $1.50 plus the start. Raise minUsd or narrow exchanges/symbols to keep runs small; set a maximum charge per run to cap spend.

Scheduling and monitoring

• Schedule the Actor every hour with timeWindow: "1h" for a continuous feed. recordKey is stable for the same liquidation, so de-duplicate on it when consecutive windows overlap.
• For alert-only use, set alertUsd high (for example 1000000) together with telegramChatId and the bot token. A failed or skipped send is a warning in OUTPUT, never a failed run.

FAQ

How fresh is the data? Each run reads the live liquidation feed at run time; nothing is cached between runs.

Why does a 24h window cover less than 24 hours? The source keeps roughly the last 2–3 hours of individual events. A wider window returns what is available and reports the span it covered in coveredSeconds and a warning.

Which exchanges are covered? Major futures exchanges including Binance, OKX, Bybit, Bitget, Gate, HTX, Hyperliquid, BitMEX and others. Filter with exchanges for a subset; a filter entry with no events in the window is listed in the warnings.

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

What happens on partial data? Unavailable values are explicit null, never guessed, and problems are listed in the run warnings.

Export formats? JSON, CSV, Excel, XML or RSS from the dataset, or read it through the Apify API in your own pipeline.

Limits

• A snapshot of the recent liquidation feed, not a full historical archive.
• Up to 5,000 events per run (maxEvents).
• Totals are computed from the events collected in this run after your filters, not from a separate all-time source.

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