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.

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). The 3-day example window above fits comfortably inside that; Build and above keep the full retained archive.

Links

• GitHub Repository