Liquidation

Liquidation protects the system from accounts that can no longer meet their margin obligations. When an account's equity falls below its maintenance margin requirement, the liquidation process transfers positions to solvent counterparties.

Trigger Conditions

Liquidation triggers when an account becomes underwater:

Portfolio Margin:

$$\text{Equity} < \text{Maintenance Margin Required}$$

Standard Margin:

$$\text{Maintenance Margin} < 0$$

Where maintenance margin = equity - MM required.

The system continuously polls all accounts with positions to check health.

State Machine

Accounts progress through four liquidation states:

State	Description	Order Restrictions
Healthy	Equity > MM required	None
PreLiquidation	Equity < MM, grace period active	Risk-increasing orders blocked
InLiquidation	Auction in progress	All orders blocked
Liquidated	Auction completed	Account cleared

State Transitions

1. Healthy → PreLiquidation: Account falls below MM threshold
2. PreLiquidation → Healthy: Account recovers above MM (user added funds or closed positions)
3. PreLiquidation → InLiquidation: Grace period expires without recovery
4. InLiquidation → Liquidated: Auction completes successfully

Pre-Liquidation Grace Period

When an account enters pre-liquidation:

1. Risk-increasing orders are blocked immediately
2. Risk-reducing orders (closing positions) remain allowed
3. A 60-second grace period begins
4. If the account recovers (equity > MM) before grace expires, it returns to Healthy
5. If still underwater after grace, liquidation auction begins

The grace period gives users time to:

• Deposit additional collateral
• Close positions to reduce margin requirement
• React to sudden market moves

Liquidation Auction

When the grace period expires, a Dutch auction begins:

Solvent Auction (Equity > 0)

Starting price = equity × (1 - penalty), decreasing over time.

Liquidators bid to take over the account's positions in exchange for:

• Account equity (minus penalty)
• Responsibility for all positions

The penalty creates incentive for liquidators to participate.

Insolvent Auction (Equity < 0)

If the account is insolvent (equity negative), the insurance fund provides a bonus to incentivize liquidators to absorb the underwater positions.

Position Transfer

When a liquidation completes:

1. All positions transfer from the liquidated account to the liquidator
2. The liquidator receives (solvent) or pays (receives bonus for insolvent) the settlement value
3. Margin root is updated on-chain
4. Account state transitions to Liquidated

Partial vs Full Liquidation

Type	Condition	Behavior
Partial	≤ 5 positions	Liquidate specific positions until MM restored
Full	> 5 positions	Liquidate entire account

Partial liquidation is deterministic:

• Positions are ordered by a consistent algorithm (not random)
• Liquidator receives positions in defined order
• Process stops when account returns to healthy state

Insolvency Waterfall

When liquidation cannot recover full value, losses are absorbed in order:

1. Account Equity: Liquidated user absorbs loss up to their equity
2. Insurance Fund: Covers shortfall if equity insufficient
3. ADL (Auto-Deleveraging): If insurance fund depleted, profitable counterparties are deleveraged proportionally
4. Socialized Loss: Final backstop (not currently implemented)

Insurance Fund

The insurance fund:

• Accumulates from liquidation penalties
• Covers insolvent liquidations
• Is replenished through trading fees and penalties
• Has a minimum reserve target

ADL (Auto-Deleveraging)

If the insurance fund cannot cover losses:

• Counterparties with profitable positions are selected
• Positions are forcibly closed at mark price
• Selection prioritizes highest profit and leverage
• Affected users receive notification

API Endpoints

Get Liquidation Status

GET /liquidation/status?wallet=0x...

Response:

{
  "success": true,
  "data": {
    "wallet": "0x...",
    "state": "pre_liquidation",
    "margin_mode": "portfolio",
    "equity": "4500.00",
    "mm_required": "5000.00",
    "maintenance_margin": "-500.00",
    "entered_pre_liq_at": 1737312000000,
    "mm_shortfall": "500.00",
    "auction_id": null
  }
}

Get Liquidation History

GET /liquidation/history?wallet=0x...&limit=20

Returns state transition history for an account.

Get Auction Details

GET /liquidation/auction/{auction_id}

Returns auction status, positions, and settlement details.

WebSocket Notifications

Liquidation state changes are broadcast on the liquidation channel:

{
  "type": "LiquidationStateChange",
  "wallet": "0x...",
  "previous_state": "healthy",
  "new_state": "pre_liquidation",
  "equity": "4500.00",
  "mm_required": "5000.00",
  "shortfall": "500.00",
  "auction_id": null,
  "timestamp": 1737312000000
}

Subscribe to receive real-time updates for your wallet.

Parameters

Parameter	Value	Description
poll_interval	5 seconds	Health check frequency
grace_period	60 seconds	Time before auction starts
min_shortfall_threshold	0	Minimum shortfall to trigger pre-liquidation
partial_liquidation_threshold	5 positions	Below this, partial liquidation is used

Best Practices

For Traders

1. Monitor margin ratio: Keep equity well above MM (recommend 2x buffer)
2. Set alerts: Use WebSocket to detect pre-liquidation early
3. Prepare dry powder: Keep spare collateral ready to deposit
4. Use stop-losses: Automate position reduction before liquidation

Querying Health

Check your margin status regularly:

# Portfolio margin
curl "https://api.hypercall.xyz/portfolio?wallet=0x..."

# Look for:
# - equity vs maintenance_margin_required
# - margin_ratio (equity / IM)

Recovery During Grace Period

If you enter pre-liquidation:

1. Deposit collateral via the funding flow
2. Close positions to reduce margin requirement
3. Cancel open orders that increase risk

Risk-reducing actions are always allowed, even in pre-liquidation.

On-Chain vs Off-Chain

Component	Location	Notes
Health monitoring	Off-chain	5-second polling
State transitions	Off-chain	Logged and persisted
Grace period timer	Off-chain	Configurable
Auction execution	On-chain	Position transfer on Controller contract
Settlement	On-chain	Value transfer and margin root update

The off-chain engine handles detection and orchestration; on-chain execution ensures settlement finality.

---

See also:

• Portfolio Margin: MM calculation for portfolio accounts
• Standard Margin: MM calculation for standard accounts
• Margin Floor: Safety floors that affect liquidation threshold