hyperliquid-liquidation-toolkit

Liquidation-price and liquidation-cluster mathematics for Hyperliquid perpetual contracts.

This is a market-structure math toolkit, not a trading system. It contains no signals, no order logic, no strategy, and makes zero network calls. It answers two questions:

1. Where does a position get liquidated? — cross and isolated margin, maintenance-margin handling, leverage tiers.
2. Where is liquidation flow clustered? — given a set of estimated liquidation levels, find the price bands that concentrate notional at risk (the "V-Risk" of a level).

It makes no profit claims. It is a building block for risk dashboards, liquidation-map visualisations, and offline research.

Install

pip install hyperliquid-liquidation-toolkit

From source:

pip install -e ".[dev]"

Pure standard library at runtime (Python 3.9+). pytest is the only dev dependency.

Usage

1. Liquidation price of a position

from hyperliquid_liquidation_toolkit import (
    LONG,
    isolated_liquidation_price,
    maintenance_leverage_from_max_leverage,
)

# 1 BTC long opened at $60,000 with 10x isolated margin ($6,000 margin).
# BTC's max leverage is 40x, so its maintenance leverage is 80x.
maint_lev = maintenance_leverage_from_max_leverage(40)

liq = isolated_liquidation_price(
    entry_price=60_000.0,
    side=LONG,
    size=1.0,
    isolated_margin=6_000.0,
    maintenance_leverage=maint_lev,
)
print(f"Liquidation price: ${liq:,.2f}")  # -> $54,683.54

2. Liquidation clusters (V-Risk)

from hyperliquid_liquidation_toolkit import (
    detect_clusters,
    notional_at_risk_within,
)

# Estimated liquidation levels: (price, notional_at_risk_usd)
levels = [
    (61_000.0, 1_000_000.0),
    (58_800.0, 4_000_000.0),
    (58_750.0, 3_000_000.0),
    (58_700.0, 2_500_000.0),
    (55_000.0,   500_000.0),
]

# Point query: how much liquidation notional is within 0.5% of $58,750?
v_risk = notional_at_risk_within(58_750.0, levels, band_pct=0.005)
print(f"V-Risk near $58,750: ${v_risk:,.0f}")  # -> $9,500,000

# Sweep: group everything into ranked clusters.
for c in detect_clusters(levels, band_pct=0.005, min_notional=1_000_000.0):
    print(f"${c.total_notional:>12,.0f} clustered around ${c.vwap_price:,.0f}")

The math

The liquidation price follows Hyperliquid's published convention:

liq_price = entry_price - side * (margin_available / (size * (1 - l * side)))

with side = +1 (long) / -1 (short) and l = 1 / maintenance_leverage. On Hyperliquid the maintenance margin is half the initial margin at the asset's max leverage, so maintenance_leverage = 2 * max_leverage.

The difference between isolated and cross margin lives entirely in how margin_available is computed:

• Isolated: isolated_margin - size * entry_price * l
• Cross: account_value - maintenance_margin_required (account-wide)

Full assumptions (funding, fees, and the liquidation penalty are out of scope; results are estimates for tooling) are documented in the module docstrings.

Limitations

• Estimates, not guarantees. The exchange is the source of truth for live liquidations.
• Funding and unrealised PnL must already be reflected in the margin_available you pass in; this library does not fetch or model them.
• Cluster detection is greedy single-pass banding, not statistical clustering — deterministic and fast, by design.

Tests

pytest

All tests run fully offline.

License

MIT © Birant Egin