About this project

This repository delivers a forward-looking liquidation-risk metric for BTC perpetuals on Hyperliquid, built as a proof-of-concept for a data leadership challenge. Instead of reporting liquidations that have already executed, it maps the latent liquidation pressure from positions that are still open, placed at the prices where they would trigger. The core outputs are a Cascade Fragility Index (CFI, 0–100), which measures proximity-weighted concentration of liquidable notional near the current mark price, and a Long/Short Asymmetry score (−1 to +1) indicating which side carries more fuel near price. The project is explicit about its data limitations: it samples the top ~2,000 wallets by recent activity rather than the full position book, reports coverage relative to open interest, filters null and dust liquidation prices, and notes that the metric is not backfillable because the API only exposes current account state. The pipeline is implemented as a Python package with modules for API access, wallet selection, metric calculation, storage, heatmap reconstruction, and site generation. It can be run locally as a one-shot pipeline, scheduled through an Airflow DAG, or updated automatically via a GitHub Actions workflow that rebuilds and deploys a single-page deliverable to GitHub Pages. Tests cover the CFI and asymmetry mathematics, cleaning filters, and append-only history behavior. The project explicitly states it is not a price forecast or timing trigger, but a conditional risk geography over a wallet sample.