calculate_estimated_liquidation_price

Documentation for eth_defi.gmx.utils.calculate_estimated_liquidation_price function.

calculate_estimated_liquidation_price(entry_price, collateral_usd, size_usd, is_long, maintenance_margin=0.01, pending_funding_fees_usd=0.0, pending_borrowing_fees_usd=0.0, include_closing_fee=True, collateral_is_index_token=False, collateral_amount=None)

Calculate liquidation price matching GMX V2 SDK implementation.

This function implements the exact liquidation price calculation from the official GMX TypeScript SDK, accounting for fees, leverage, maintenance margin, and whether collateral token matches the index token.

How GMX Liquidation Works:

GMX liquidates positions when remaining collateral after fees falls below the minimum collateral requirement. The calculation must account for: - Pending funding fees (can be positive or negative) - Pending borrowing fees (always reduces collateral) - Position closing fees (~0.1% of position size) - Maintenance margin requirement (~0.5% of position size, min $5)

Accurate vs Approximate Mode:

  • If collateral_is_index_token and collateral_amount are provided: Uses EXACT formula matching GMX SDK (recommended)

  • If not provided: Uses APPROXIMATE formula (simpler but ±0.5% error)

Exact Calculation Formulas:

Same token (e.g., ETH collateral for ETH/USD position):

Long: liq_price = (size + liq_collateral + fees) / (size_tokens + collateral_tokens) Short: liq_price = (size - liq_collateral - fees) / (size_tokens - collateral_tokens)

Different tokens (e.g., USDC collateral for ETH/USD position):

Long: liq_price = (liq_collateral - remaining_collateral + size) / size_tokens Short: liq_price = (size - liq_collateral + remaining_collateral) / size_tokens

Approximate Formula (fallback):

liq_price = entry_price * (1 ± max_loss_ratio)

This provides quick estimates when token details are unavailable.

# Approximate mode (quick estimate)
liq_price = calculate_estimated_liquidation_price(
    entry_price=2000.0,
    collateral_usd=1000.0,
    size_usd=5000.0,  # 5x leverage
    is_long=True,
    pending_funding_fees_usd=5.0,
    pending_borrowing_fees_usd=10.0,
)
# Result: ~$1608 (approximate, ±0.5% error)

# Exact mode (matches GMX SDK)
liq_price = calculate_estimated_liquidation_price(
    entry_price=2000.0,
    collateral_usd=1000.0,
    collateral_amount=0.5,  # 0.5 ETH collateral
    size_usd=5000.0,
    is_long=True,
    collateral_is_index_token=True,  # ETH collateral for ETH position
    pending_funding_fees_usd=5.0,
    pending_borrowing_fees_usd=10.0,
)
# Result: $1681.67 (exact, matches GMX TypeScript SDK)
Parameters

  • entry_price (float) – Price at which the position was opened

  • collateral_usd (float) – Total collateral value in USD

  • size_usd (float) – Total position size in USD (collateral × leverage)

  • is_long (bool) – True for long position, False for short position

  • maintenance_margin (float) – Minimum margin requirement as decimal (default 0.01 = 1%) GMX typically uses 1% for most markets

  • pending_funding_fees_usd (float) – Accumulated funding fees in USD (can be negative for rebates)

  • pending_borrowing_fees_usd (float) – Accumulated borrowing fees in USD (always positive)

  • include_closing_fee (bool) – If True, includes 0.1% closing fee in calculation (default: True)

  • collateral_is_index_token (bool) – Whether collateral token matches index token (e.g., ETH collateral for ETH/USD). Required for exact calculation. If False, assumes different token like USDC.

  • collateral_amount (float | None) – Amount of collateral in tokens (e.g., 0.5 for 0.5 ETH). Required for exact calculation. If None, uses approximate formula.

Returns

Liquidation price in USD, or None when the approximation cannot produce a meaningful value (e.g. small positions where the GMX_MIN_LIQUIDATION_COLLATERAL_USD floor dominates the formula, or degenerate inputs like size_in_tokens == 0). Callers must treat None as “unknown” — never substitute 0 or any other fallback that downstream code could interpret as a valid liquidation price.

Return type

float | None

Note:

For maximum accuracy, provide collateral_is_index_token and collateral_amount. Without these, the function uses an approximate formula with ±0.5% error.

Historical caveat: previously this function returned 0.0 for unresolvable cases. That was a footgun — Freqtrade’s downstream stoploss_or_liquidation() and get_liquidation_price() paths do not treat 0.0 as falsy, so the sentinel landed in the DB, was then offset by a 5% buffer, and the resulting non-zero liquidation price triggered false ExitType.LIQUIDATION exits. None is the correct unknown sentinel and is now used uniformly.