Liquidation Pressure Map & Cascade Fragility Index

Faro already shows Liquidation Volume — the liquidations that have already fired. The other half is missing: not what just got liquidated, but where the leverage that is still open would get liquidated next. That gap is the metric below.

The metric is a Liquidation Pressure Map for BTC perpetuals on Hyperliquid: a density of the price levels where currently-open leveraged positions would be force-liquidated, separated by side. Longs liquidate below the price; shorts liquidate above. On top of the map I compute two numbers a trader can actually watch:

• Cascade Fragility Index (CFI, 0–100) — how much liquidable size sits close to the current price. It answers “is risk building beneath the surface?”. Closer and bigger means a small move can force liquidations that push price into the next cluster — a cascade.
• Long/Short Asymmetry (−1…+1) — which side is the fuel. It answers “are we set up to squeeze up or flush down?”.

Why this adds something Faro doesn't already have: it is the forward side of the Liquidation Volume Faro shows today. Volume is what already happened; this is risk that hasn't fired yet, with a price attached to it. They answer different questions, and a trader reads them together — one says the fuel is sitting there, the other says it caught.

It matters most for BTC perps, intraday to swing. In practice it changes where you put a stop (don't leave it inside a cluster you could get run into), whether you fade or join a move heading toward a cluster, and how big you go into crowded positioning. Source data is all public and needs no key: metaAndAssetCtxs for the mark price (the price Hyperliquid liquidates against), oracle, funding and open interest; clearinghouseState per wallet for the signed size, the exchange's own liquidationPx, and the position notional. The catch: no public endpoint returns the whole book, so the map is built from a sample of wallets (Appendix C).

The DAG (liquidation_pressure_dag.py) is thin on purpose: it sequences reusable modules and does nothing clever itself. All the real logic — the API client, the metric, the storage layer — lives in plain importable functions, so the same code runs whether Airflow drives it or the small runner behind the live page does. That logic is unit-tested: pytest -q covers the CFI and asymmetry maths (including that near-mark dust can't spike the index), the cleaning filters, and the loss-resistant history — run it before any deploy. Flow: refresh_universe → extract_market_context → extract_positions → validate → transform → load.

Scheduling cadence. Every ~10 minutes. Open positions and the mark price move continuously, so a stale map misleads; but positions don't turn over second to second and I won't hammer a free API, so 10 minutes is the balance between freshness and load. The wallet universe is refreshed on a far slower beat — once a day — because re-ranking the leaderboard is a ~30 MB download and the set of most active wallets barely changes within a day. The loop sleeps adaptively to hold the cadence even as a run takes longer.

Source extraction. Two sources, two cadences. The wallet universe comes from Hyperliquid's public leaderboard feed (daily). Per run, clearinghouseState is queried for every wallet. The /info endpoint is weight-limited to 1,200 weight per minute per IP and that call costs 2, so the hard ceiling is 600 calls/min. I run a thread pool behind a shared token bucket pinned at ~7.5 req/s (≈75% of the ceiling) — enough headroom that retries and the occasional metaAndAssetCtxs (weight 20) never trip the limit. That fetches ~2,000 wallets in about 4.5 minutes with zero rate-limit errors.

Data validation. Two tiers. Hard checks fail the run and quarantine the data: a non-positive mark, or mark/oracle drift beyond 5% (a sign something is wrong upstream). Soft checks pass the data through but flag it. The per-position cleaning drops three things, each for a reason I hit in the real data: liquidationPx = null (cross-margin positions, where the trigger depends on the whole account and isn't placeable per position); dust below $10k notional (which returns nonsense triggers — I watched a $1 position report a liquidation price of $1.8 trillion); and anything more than 60% away from the mark (numerically unreliable and irrelevant to a near-term cascade). Every count is stored, never hidden.

Transformation logic. A pure function, so it's testable and the DAG calls it directly: bucket each kept position by its liquidationPx, weight by notional, and take the CFI as the notional-weighted average proximity using a smooth kernel K(d)=exp(−d/τ), τ = 8%. I chose the exponential kernel over a raw 1/d precisely so a dust position sitting on the mark can't send the index to infinity. Full formula in Appendix B.

Storage and output-table design. Three artifacts, each matched to its job:

The part worth calling out is how the series is stored: an append-only ledger with union semantics and atomic writes, never a read-modify-write. Each run appends one immutable line first, then rebuilds the CSV view as the union of (ledger ∪ existing CSV ∪ new row). A stale or empty read can therefore add a point but never drop one — which is exactly the failure you worry about in something that keeps accumulating for months. In production these become warehouse tables; the shapes are the same.

Failure handling and observability. Tasks retry with exponential backoff. Per-wallet errors are tolerated and counted rather than failing the whole map — a map missing three wallets out of two thousand beats no map — and the run only hard-fails if the wallet error rate clears 50%. Alerts fire on staleness beyond two cadences, a drop in coverage, or a spike in the error rate. Every published reading also carries its own provenance, freshness, coverage and a confidence label, so whatever reads it — a trader or an AI agent — can downgrade or skip it instead of quoting a number it can't stand behind.

Backfill. One limit, up front: the map can't be backfilled from the public API, because clearinghouseState only returns each account's current state — there is no “state as of last Tuesday”. So the CFI series builds forward from first deploy, and only the wallet selection looks at history. The full backfill path — event-sourcing the open-position book from the fills feed — is in Appendix C.

Strip out the engineering and here is the trade. Liquidation cascades feed on themselves: a forced sell pushes price lower, which trips the next forced sell. What makes a market dangerous isn't how much leverage is on — it's how close the triggers sit to the current price. The CFI measures that, so it rises before a fragile move, not after it.

How to read it:

• Squeeze setup (bullish fuel) — asymmetry well positive with a fat short cluster just above price. The shorts are the fuel; a poke higher can light them and run price up into the cluster.
• Flush risk (bearish fuel) — asymmetry negative with longs stacked just below. A poke lower can cascade into a long flush.
• Risk warning — CFI in the red band: large size is parked within a few percent of price on at least one side. This is when you tighten risk, not when you add.
• Calm — CFI low: the fuel is far away, so a move has to travel before it finds any, and moves tend to stay orderly.

What it is not. Not a forecast and not a timing trigger. Clusters can sit unlit for days, and the levels behave more like magnets than walls — price often drifts toward a big cluster before anything happens. Read it as a map of where the market is structurally fragile, not as a buy or sell signal. And it is a sample of the book, not the whole thing.

Pair it with, before you act: funding and OI (is the exposed side actually crowded, and paying to stay on?), spot aggressor flow / CVD (is anyone really pushing toward the cluster?), and the obvious one inside Faro — the realized Liquidation Volume, to confirm whether the fuel you're watching actually caught.

How I'd put it in front of a trader (the live charts above are the working mock):

• Primary — the density ladder. Liquidable notional by price level: longs below the mark in teal, shorts above in red, with the mark line and a ±5% band. A smoothed density by default (clean; area is proportional to notional) with a one-click switch to exact bars when a trader wants the precise number at a level. Hover gives a crosshair and the dollar amount.
• The same field over time — a heatmap. Price on the vertical, time on the horizontal, brightness = liquidable notional, with the mark-price path drawn over it. A resolution toggle (10-minute / hourly / daily) lets you go from “what changed this hour” to “how has the structure built over the week”. This is where you see fragility accumulate.
• The index itself — gauge plus dual-axis history. A 0–100 gauge for the at-a-glance regime, beside the CFI plotted against BTC price on a second axis with green/amber/red regime bands. CFI rising while price chops sideways is the textbook “risk building beneath the surface”.

Time horizon: the map is a live snapshot; the history and heatmap read best over hours to days. Thresholds and annotations worth adding: the regime bands, the asymmetry sign, and a callout on the single nearest large cluster (“$X of short fuel at +2.1%”). Overlays: mark/oracle, funding sign, and the one I'd push hardest for — Faro's own realized Liquidation Volume on the same price axis, so a trader sees fuel and ignition in one view. Where it lives: the BTC perp / derivatives page, in a positioning-and-risk tab, and exposed to Faro's agents as a structured, confidence-tagged signal (regime, asymmetry, nearest cluster, coverage) so the AI can cite it — and hedge or refuse when coverage is thin.

Data quality is the part that has to be right, so here is the current run in full:

Reconciliation. No endpoint returns the full book, so I reconcile what I can: sampled $1.07B against OI $3.07B — the coverage ratio above — and mark versus oracle drift, which flags a data-quality event when it widens. What this is: a high-coverage sample of the most active wallets, not the full book. History integrity: every CFI reading lands in the append-only ledger and is snapshotted to git each run, and each snapshot keeps its full histogram for the heatmap — so nothing is silently dropped, and the whole series can be rebuilt from git history via rebuild_history.py.

For each qualifying position with liquidable notional N and fractional distance to its trigger d = |liqPx − mark| / mark, the proximity weight is K(d) = exp(−d/τ) with τ = 8%. Then CFI = 100 · Σ N·K(d) / Σ N — the notional-weighted average proximity, bounded 0–100; the smooth kernel is what stops a single dust position on the mark from blowing it up. Asymmetry = (short_pressure − long_pressure) / (short_pressure + long_pressure), where side pressure is Σ N·K(d) on that side. The Fig.01 density curve is gaussian-smoothed for legibility (area stays proportional to notional); hover reports the real notional within ±1.25% of a level.

Two distances, two jobs. The keep filter drops any position whose trigger sits more than 60% from the mark — at that range the price is usually garbage, not real risk. The map is built over that same ±60%, but it opens zoomed to the mark ±30% (the band that matters for a near-term cascade); pan or zoom out on the chart to see the rest. Either way the kernel makes anything past roughly 20% count for almost nothing in the CFI.

On the regime bands. The cut-offs (calm < 25, elevated < 50, else fragile) are provisional. I set them by hand from the range the CFI takes in the readings so far — low in calm books, climbing as big clusters pull in toward the mark — not from a long history, because there isn't one yet: the series only accumulates forward and the map can't be backfilled from the public API. They should be recalibrated once enough history builds up, or off a proper backtest once the production backfill in Appendix C exists, rather than treated as fixed.

How the sample is built today

(1) Pull the public leaderboard feed (~38k addresses). (2) Rank by activity_score = week volume + month volume and keep the top 2,000 — turnover is a good proxy for wallets that are actually carrying perp risk (ranking by account value pulls in spot holders and idle vaults with no perp exposure, which I checked early on). (3) Query their live state concurrently, within the rate budget above. (4) Keep whichever currently hold a qualifying open BTC position (notional ≥ $10k, liquidationPx present, within 60% of mark) — a few hundred at any instant — and aggregate them. The 2,000 is a daily, activity-ranked pick; the on-map subset is not a second selection, just whichever of those 2,000 hold a live position this snapshot.

Why this sample is enough for a proof of concept

Liquidable open interest is concentrated in the most active wallets, so a high-activity sample captures what matters for a cascade — the large clusters near price — while the long tail is many tiny positions that barely move anything. This run reaches 35% of reported BTC open interest. (Exchange OI is one-sided, so total open-position notional is roughly twice the reported figure; even so, capturing ~half of the reported OI is a large, representative slice of what matters.) The universe is rebuilt daily and re-ranked by recent activity, so quiet wallets drop out and newly active ones come in on their own — the list won't drift into dead addresses.

What the real, production version looks like (described, not built)

• Full population, not a sample. Subscribe to the Hyperliquid fills WebSocket and keep a rolling registry of every address trading BTC, ranked by trailing volume — discovery becomes continuous rather than a daily snapshot.
• Event-sourced position engine. Derive each wallet's open position by applying its fills, funding and liquidations in real time instead of polling clearinghouseState per wallet. This scales to the whole market and removes the rate-limit ceiling on coverage, approaching ~100% of OI.
• Historical backfill. Replay the historical fill/funding/liquidation tape (per-wallet userFillsByTime plus an archival node or data export for the full feed) from each wallet's first trade forward, reconstructing the open-position book — and therefore the liquidation map and CFI — at any past timestamp. Caveat: per-wallet fill history is capped, so a true genesis-to-now reconstruction needs the archival feed and a snapshot anchor for positions opened before the available window.
• Continuous reconciliation. Check the engine's derived aggregate OI against the exchange's reported OI every cycle as a live data-quality gate; a divergence flags a missed fill or a bug before it reaches a trader.