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.

Example:

# 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

Return type

float

Note:

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