Example: BTC Liquidation Heatmap

Visualizing Liquidation Events

We built an open-source Jupyter notebook that visualizes BTC liquidation events on Hyperliquid using historical data from 0xArchive.

This heatmap shows completed forced executions, not projected liquidation price levels or pending triggers. The completed liquidation-events guide explains the event data.

What It Does

• Fetches liquidation data via the oxarchive Python SDK
• Deduplicates trade records and maps long vs short positions
• Generates 6 visualizations:

Price vs time liquidation heatmap: density map of liquidation activity

Scatter plot with BTC price overlay: longs in red, shorts in green

Hourly liquidation volume distribution: liquidation volume grouped by hour

Size distribution with percentile stats: distribution of liquidation sizes by percentile

Cascade detection: P99 liquidation bursts in 5-minute windows

Long vs short imbalance over time: price subplot

Example Output (3-day window)

13,399 unique liquidations: shorts accounted for 64.9% and longs for 35.1%, with $143M total notional.

Get Started

pip install -r requirements.txt
cp .env.example .env
jupyter notebook liquidation_heatmap.ipynb

Works with a free API key from 0xarchive.io/dashboard (all covered markets, most recent 30 days on Free). A new three-day window inside Free’s most recent 30 days fits the Free plan. Reproducing the fixed example’s original dates requires a plan that still includes those dates; Build and above keep the full retained archive.

Links

• GitHub Repository