Three Lines That Saved a Position: Liquidation Risk Alerts on Hyperliquid

On August 27, HYPE hit a new all-time high of $86.71 with a market cap near $18.9 billion. In that same window, long-side liquidations on Hyperliquid totaled $21.88 million over 24 hours, because leveraged longs that had been riding the rally got shaken out on a sharp intraday reversal. Open interest sat at $3.47 billion against a $19.63 billion market cap, putting leverage exposure at close to 17.7% of market cap.

Those numbers tell you something important: at peak euphoria, a significant share of the market's open interest was sitting close to forced closure. Traders who had a liquidation risk alert wired up knew the pressure was building hours before the flush. Traders who didn't found out when their positions were gone.

This article walks through the practical side of building liquidation risk alerts on Hyperliquid using HyperTracker's API. You'll get working Python code, a tiered alert architecture that routes by cohort severity, and a multi-asset correlation detector that distinguishes an isolated spike from a broader deleveraging event.

What the Liquidation Risk Endpoint Returns

HyperTracker's liquidation risk endpoint lives at GET /api/external/{segmentId}/assets/liquidation-risk. Pass any of the 16 cohort segment IDs, and it returns every asset where that cohort has open positions, ranked by risk exposure. Each item includes three fields:

• totalValue: total open interest for the asset in that cohort
• riskValue: the dollar amount of positions within 75% of their liquidation threshold
• percentRisk: the ratio of at-risk value to total exposure

The 16 cohorts split into two axes. Eight classify wallets by perp equity (Shrimp through Leviathan), and eight classify by all-time PnL (Money Printer through Giga-Rekt). When a Leviathan's percentRisk spikes on ETH, the forced closure volume is large enough to move the market. When a Shrimp cohort spikes, it's noise. That asymmetry is why a flat average across all cohorts is useless for alerting, and why tiered routing matters.

Building Tiered Alerts by Cohort Impact

The simplest liquidation risk monitor treats every cohort equally. That's the wrong move, because the market impact of a Leviathan liquidation and a Fish liquidation are orders of magnitude apart. A better approach is to assign tiers based on the notional exposure each cohort represents, then route alerts differently for each tier.

Tier 1: critical cohorts

Leviathan (segment ID 7), Tidal Whale (ID 6), and Money Printer (ID 8). These represent the largest wallets and the most profitable traders on the platform. When their positions cluster near liquidation, the forced selling volume can trigger cascading price moves. Fire alerts immediately and consider automated position reduction.

Tier 2: warning cohorts

Whale (ID 5), Small Whale (ID 4), and Smart Money (ID 9). Meaningful capital, but less likely to single-handedly trigger a cascade. Alert for manual review and tighter stop management.

Tier 3: informational

Everything else: Apex Predator (ID 3), Dolphin (ID 2), Fish (ID 1), Shrimp (ID 16), and the remaining PnL cohorts (IDs 10-15). Log these to your time-series database for backtesting and research, but don't push them to your alert channel. An alert system that fires on everything becomes one that gets ignored.

Here's the Python implementation. It polls each tier's cohorts, computes a weighted score, and routes to the appropriate alert channel:

import requests, time

API_BASE = "https://ht-api.coinmarketman.com/api/external"
TOKEN = "YOUR_JWT_TOKEN"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

# Tier definitions: cohort_id -> (name, weight)
TIER_1 = {7: ("Leviathan", 2.0), 6: ("Tidal Whale", 1.5), 8: ("Money Printer", 1.3)}
TIER_2 = {5: ("Whale", 1.0), 4: ("Small Whale", 0.8), 9: ("Smart Money", 1.2)}
TIER_3_IDS = [3, 2, 1, 16, 10, 11, 12, 13, 14, 15]

def get_risk(segment_id):
    url = f"{API_BASE}/{segment_id}/assets/liquidation-risk"
    resp = requests.get(url, headers=HEADERS)
    resp.raise_for_status()
    return resp.json()["items"]

def weighted_score(coin, tier):
    total_w, w_sum = 0, 0
    for seg_id, (name, weight) in tier.items():
        assets = get_risk(seg_id)
        match = next((a for a in assets if a["coin"] == coin), None)
        if match:
            w_sum += match["percentRisk"] * weight
            total_w += weight
    return w_sum / total_w if total_w else 0

def scan():
    all_assets = get_risk(7)  # use Leviathan as asset index
    for asset in all_assets:
        coin = asset["coin"]
        t1 = weighted_score(coin, TIER_1)
        t2 = weighted_score(coin, TIER_2)
        if t1 >= YOUR_CRITICAL_THRESHOLD:
            send_critical_alert(coin, t1)
        elif t2 >= YOUR_WARNING_THRESHOLD:
            send_warning_alert(coin, t2)

while True:
    scan()
    time.sleep(300)  # 5-min poll matches API refresh

A note on thresholds and weights. The tier assignments and weights above are illustrative starting points. HyperTracker classifies wallets into cohorts. It does not prescribe specific alert thresholds, position sizing rules, or risk management parameters. Calibrate both thresholds and weights to your own risk tolerance and backtesting results.

Detecting Multi-Asset Correlation Spikes

An isolated spike on a single asset is one thing. When liquidation risk climbs simultaneously across BTC, ETH, and SOL in the same cohort, that's a broader deleveraging signal. The difference matters because a correlated spike means the forced selling will hit multiple positions in a portfolio at once, compounding the damage.

The detection logic is straightforward. After computing weighted risk scores for each asset, count how many are above your threshold simultaneously. If the count crosses a second threshold (for example, three or more assets elevated at the same time), escalate the alert severity:

def detect_correlation(tier, threshold):
    """Count assets above threshold in a given tier."""
    all_assets = get_risk(list(tier.keys())[0])
    elevated = []
    for asset in all_assets:
        score = weighted_score(asset["coin"], tier)
        if score >= threshold:
            elevated.append((asset["coin"], score))
    return elevated

elevated = detect_correlation(TIER_1, YOUR_CRITICAL_THRESHOLD)
if len(elevated) >= 3:  # example threshold - calibrate to your model
    send_correlated_alert(elevated)  # highest severity

Why does this matter? Consider the late August 2026 rally. HYPE hit its all-time high while long-side liquidations dominated every timeframe. If your alert system only watched individual assets, it might fire separately for BTC, ETH, and HYPE, each classified as a routine spike. A correlation detector would have recognized the pattern across all three and escalated to a single high-severity alert: "broad long liquidation pressure building across the entire portfolio."

Pairing Risk Scores with Cohort Bias

Liquidation risk tells you that pressure is building. It doesn't tell you which direction. That's where the bias endpoint comes in. HyperTracker's GET /api/external/{segmentId}/bias returns whether a cohort is net long or net short on a given asset. Pairing the two endpoints gives your alert system directional context:

• High liquidation risk + cohort leaning long = the forced selling, if it happens, will push price down
• High liquidation risk + cohort leaning short = forced buying (short squeezes) will push price up

This distinction changes how you respond. If you're holding a long position and the Leviathan cohort is also heavily long with elevated liquidation risk, you're on the same side as a potential cascade. That's a signal to reduce. But if the Leviathans are heavily short with elevated risk, a short squeeze might actually benefit your long position.

def get_bias(segment_id, coin):
    url = f"{API_BASE}/{segment_id}/bias"
    resp = requests.get(url, headers=HEADERS)
    data = resp.json()
    match = next((a for a in data["items"] if a["coin"] == coin), None)
    return match["bias"] if match else "neutral"

# In your alert handler:
coin, score = "ETH", weighted_score("ETH", TIER_1)
if score >= YOUR_CRITICAL_THRESHOLD:
    bias = get_bias(7, coin)  # Leviathan bias
    msg = f"ALERT: {coin} risk={score:.1f}%, Leviathan bias={bias}"
    send_critical_alert(msg)

The Polling-to-Webhook Upgrade Path

The code samples above all use REST polling on a 5-minute loop, which matches HyperTracker's data refresh cadence. For a Pulse tier account ($179/mo), that's the right architecture: pull data, score it, alert if needed, sleep, repeat.

But polling has a structural weakness. Your alert latency equals your poll interval plus compute time. If a risk spike happens right after your last poll, you won't see it for up to 5 minutes. For most risk management use cases, that's acceptable. For automated position sizing or high-frequency strategies, it's not.

The upgrade path is webhook delivery, available on the Flow tier ($799/mo) and above. With webhooks, HyperTracker pushes risk data to your endpoint as soon as it refreshes, which eliminates the polling loop entirely. Your code becomes simpler (no scheduler, no sleep cycle), and your latency drops to network transit time.

For the Stream tier ($1,999/mo), WebSocket connections provide continuous updates. The pattern shifts from request-response to event-driven: subscribe to risk changes, process them as they arrive, and fire alerts in near real-time.

Start with polling, upgrade when you outgrow it. The Pulse tier at $179/mo gives you everything you need to build a working alert pipeline. Polling every 5 minutes is sufficient for most risk monitoring. Move to webhooks or WebSocket only when you need lower latency, which usually means you're running automated position management that adjusts faster than a human would.

Threshold Calibration: Backtesting Against Historical Data

The hardest part of any alerting system isn't the code. It's the threshold. Set it too low and you drown in false positives. Set it too high and you miss the cascade that matters.

HyperTracker provides roughly four weeks of historical cohort metric data, which gives you enough to backtest your threshold against recent market conditions. The approach is to pull historical risk scores, overlay them with price data, and identify the percentRisk values that preceded significant price moves.

A practical calibration workflow:

1. Pull four weeks of daily risk snapshots for your Tier 1 cohorts across BTC, ETH, and your most-traded assets
2. Mark the dates where significant drawdowns occurred (10%+ moves in 24 hours or less)
3. Measure what the weighted percentRisk was in the polling intervals leading up to each drawdown
4. Set your alert threshold at a level that would have fired before most of those drawdowns without triggering daily on routine fluctuations

This isn't a one-time exercise. Market structure changes. Leverage appetite shifts with sentiment. The threshold that worked during the cautious post-correction period in early August (when HYPE was down nearly 20% over 30 days) won't necessarily work during the euphoric rally that pushed HYPE to all-time highs later that same month. Revisit your calibration at least monthly.

Putting It Into Production

A working alert pipeline needs a few things beyond the core scoring logic:

• Persistent state: Store every risk score you compute, even when it's below threshold. Historical scores are your calibration dataset. A simple time-series database (InfluxDB, TimescaleDB, or even SQLite for prototyping) works.
• Deduplication: If a coin stays above threshold for three consecutive polls, send one alert with a "still elevated" flag rather than three identical messages. Alert fatigue kills the usefulness of any monitoring system.
• Cooldown logic: After an alert fires and the trader takes action, suppress re-alerts on the same asset for a configurable cooldown period. Otherwise the system nags about a risk you've already addressed.
• Dashboard overlay: Pipe risk scores into Grafana or Retool alongside price data. Visual pattern recognition is faster than reading log output, and it makes threshold calibration intuitive.

Build Your Liquidation Risk Alert Pipeline

HyperTracker's API gives you pre-computed liquidation risk scores across 16 behavioral cohorts. One REST call per cohort, refreshed every 5 minutes. Start on the free tier to explore, then scale to Pulse ($179/mo) for production alerting.

Get Your API Key

Liquidation cascades don't send calendar invites. They happen during holiday weekends, oracle mismatches, and the exact moment leverage gets overcrowded. The traders who survive them consistently share one trait: they knew the pressure was building before the price moved. A few lines of code polling the right endpoint, weighted by the right cohorts, routed to the right channel. That's the difference between an alert on your phone and a liquidation receipt in your inbox.