Liquidation Logic

Exchange-specific margin-based liquidation simulation in backtest

Why Simulate Liquidation?

A leveraged backtest without liquidation simulation is fiction. A 10× leveraged position can be liquidated by a 10% adverse move — but without liquidation modeling, the backtest simply holds through the drawdown and recovers. This produces impossibly good results.

ClyptQ simulates liquidation per exchange with the correct maintenance margin rate (MMR), liquidation fee, and margin ratio formula for each venue.

How Liquidation Works

The Check

After every tick, for every futures account with open positions, ClyptQ checks whether the account should be liquidated:

For each futures account:
  1. Calculate unrealized PnL across all positions
  2. Calculate equity = cash + unrealized_pnl - liquidation_fee
  3. Calculate maintenance margin = total_notional × MMR
  4. Compute margin ratio (exchange-specific formula)
  5. If margin ratio breaches threshold → LIQUIDATE all positions

Two Margin Ratio Formulas

Exchanges use one of two formulas to compute margin ratio:

Inverted (Binance):

margin_ratio = (maintenance_margin / equity) × 100

Liquidation trigger: margin_ratio ≥ 100%

When equity falls below maintenance margin, the ratio exceeds 100% and liquidation triggers.

Normal (Bybit, Gateio, Kraken, Coinbase):

margin_ratio = equity / maintenance_margin

Liquidation trigger: margin_ratio < threshold (typically 1.0)

When equity falls below maintenance margin, the ratio drops below 1.0 and liquidation triggers.

Both formulas express the same economic condition — equity insufficient to cover margin requirements — but the numbers and threshold directions differ.

Exchange-Specific Parameters

Exchange	Default MMR	Liquidation Fee	Threshold	Formula	Notes
Binance	1.3%	0.75%	100%	Inverted	Tiered MMR by position size
Bybit	0.5%	0.6%	1.0	Normal	Lower MMR, more leverage allowed
Gateio	1.0%	0.5%	1.5	Normal	Higher threshold (more conservative)
Coinbase	6.67%	1.0%	1.0	Normal	CFTC regulated, MM = IM × ⅔
Kraken	2.0%	1.5%	1.0	Normal	Regulated, higher fees

The Default MMR values are Tier 1 (smallest position) rates. In reality, exchanges use tiered MMR where larger positions require higher maintenance margin. ClyptQ supports dynamic tier resolution for exchanges that expose tier data via CCXT: Binance (requires API key), Bybit, Gateio, and Kraken fetch real-time tier brackets. Coinbase does not expose tier data — it always uses the static default (6.67%).

Liquidation Calculation Step by Step

Example: Binance Futures (Inverted Formula)

Account state:
  Cash: $5,000
  Position: Long 2 BTC at entry $50,000
  Current price: $47,500 (5% decline)

Step 1: Unrealized PnL
  pnl = (current_price - entry_price) × quantity
  pnl = ($47,500 - $50,000) × 2 = -$5,000

Step 2: Liquidation fee estimate
  total_notional = |2 × $47,500| = $95,000
  liquidation_fee = $95,000 × 0.0075 = $712.50

Step 3: Equity
  equity = cash + unrealized_pnl - liquidation_fee
  equity = $5,000 + (-$5,000) - $712.50 = -$712.50

Step 4: Maintenance margin
  maintenance_margin = total_notional × MMR
  maintenance_margin = $95,000 × 0.013 = $1,235

Step 5: Margin ratio (Binance inverted)
  margin_ratio = (maintenance_margin / equity) × 100
  equity is negative → margin_ratio = ∞

Step 6: Check
  ∞ ≥ 100% → LIQUIDATED ✓

All positions are closed at market price, liquidation fee is deducted, and the account’s remaining equity (if any) is the post-liquidation balance.

Example: Bybit Futures (Normal Formula)

Account state:
  Cash: $10,000
  Position: Short 1 BTC at entry $50,000
  Current price: $54,500 (9% adverse move)

Step 1: Unrealized PnL
  pnl = (entry_price - current_price) × |quantity|  (short)
  pnl = ($50,000 - $54,500) × 1 = -$4,500

Step 2: Liquidation fee estimate
  total_notional = |1 × $54,500| = $54,500
  liquidation_fee = $54,500 × 0.006 = $327

Step 3: Equity
  equity = $10,000 + (-$4,500) - $327 = $5,173

Step 4: Maintenance margin
  maintenance_margin = $54,500 × 0.005 = $272.50

Step 5: Margin ratio (Bybit normal)
  margin_ratio = equity / maintenance_margin
  margin_ratio = $5,173 / $272.50 = 18.98

Step 6: Check
  18.98 > 1.0 → SAFE ✓

Example: Gateio (Higher Threshold)

Gateio uses a 1.5 threshold instead of 1.0 — meaning liquidation triggers earlier than on other exchanges:

Same setup, equity = $400, maintenance_margin = $272.50

margin_ratio = $400 / $272.50 = 1.47

On Bybit:   1.47 > 1.0 → SAFE
On Gateio:  1.47 < 1.5 → LIQUIDATED ✓

This is why exchange-specific simulation matters — the same position can be liquidated on one exchange and safe on another.

What Happens at Liquidation

When liquidation triggers:

1. All positions in the account are closed at current market price (with slippage applied)
2. Liquidation fee is deducted from equity
3. ExecutionResult is created with trigger_type: "liquidation" metadata
4. Console warning is printed: ⚠️ [LIQUIDATION] binance:futures: 2 positions liquidated
5. Remaining equity (if positive) stays as cash in the account

The ExecutionResult includes full audit data:

result.raw_response = {
    "trigger_type": "liquidation",
    "equity_before": 1235.50,
    "maintenance_margin": 1300.00,
    "margin_ratio": 105.2,         # Exceeded 100% (Binance)
    "mmr_used": 0.013,
    "liquidation_fee": 712.50,
    "pnl": -4287.50,
}

Cross vs Isolated Margin

Cross Margin (Default)

All positions in an account share the same margin pool. The entire account balance is used as collateral:

Account: $10,000 cash
Position A: Long 1 BTC ($50,000 notional)
Position B: Long 10 ETH ($15,000 notional)

Total notional: $65,000
Maintenance margin: $65,000 × 1.3% = $845
Equity: $10,000 + unrealized_pnl_A + unrealized_pnl_B

A loss on Position A is offset by the full account balance, including unrealized gains on Position B.

Isolated Margin

Each position has its own margin allocation. Losses on one position cannot consume margin from another:

Position A: $5,000 isolated margin
Position B: $5,000 isolated margin

Position A can only lose $5,000 — Position B's margin is protected.

ClyptQ’s current backtest uses cross margin by default (all positions share the account balance). Isolated margin simulation is planned for a future release.

Configuration

Default Behavior

No configuration needed. Liquidation is checked automatically for every futures account after each tick:

# This is enough — liquidation uses exchange defaults
AccountSpec(
    exchange="binance",
    market_type="futures",
    base_currency="USDT",
    initial_cash=10_000,
    max_leverage=10.0,
)

Custom MMR Override

For tiered positions or custom risk parameters:

# In the executor's check_liquidation call, you can override MMR
# This is useful for simulating large positions in higher tiers
# (e.g., Binance Tier 5 has 5% MMR for > $40M notional)

Impact on Strategy Design

Leverage Selection

Higher leverage means less equity buffer before liquidation:

Leverage	Equity as % of Position	Liquidation at % Loss
1×	100%	Never (spot equivalent)
3×	33%	~30% adverse move
5×	20%	~18% adverse move
10×	10%	~8% adverse move
20×	5%	~3.5% adverse move

Without liquidation simulation, a 10× backtest survives a 50% drawdown and “recovers.” With simulation, it gets liquidated at ~8% and the equity goes to near zero.

Stop Loss as Liquidation Prevention

Using stop-loss orders prevents liquidation and preserves capital:

FuturesTargetPositionIntention(
    ...
    leverage=5.0,
    stop_loss=entry_price * 0.95,  # 5% stop (well before 18% liq)
)

ClyptQ’s TP/SL simulation works together with liquidation — if the stop-loss doesn’t trigger (e.g., gap down), liquidation still fires as a backstop.

Related Pages

Exchange Specifics

Full exchange parameter tables including margin tiers

Cost Models

Fee structures that interact with liquidation costs