Liquidations, Liquidator Vault, and ADL

When an account's equity falls below the maintenance margin requirement, positions are liquidated. The flow differs by margin mode:

• Cross positions liquidate together at the account level. Severely underwater accounts are handed to the Liquidator Vault, an active backstop primitive that absorbs positions at the user's entry price and unwinds them on the order book. If the vault refuses or its solvency cap is hit, auto-deleveraging (ADL) closes residual positions at the bankruptcy price against the most profitable opposing traders.
• Isolated positions liquidate independently. Each isolated bucket is checked on its own, and the close goes through the orderbook. Losses can't spill into the account's cross collateral or other isolated positions. Covered in Isolated liquidation below.

Liquidation

When it triggers

Liquidations are checked at the end of every block. The reference price used for the check depends on the market's asset class:

An account is liquidatable when:

account_value < maintenance_margin_required

Both sides are computed at the asset-class-appropriate reference price. See Mark price for why.

Account value

account_value = collateral + Σ unrealized_pnl

unrealized_pnl for each open position is computed at the liquidation reference price for that position's market.

Maintenance margin required

maintenance_margin_required = Σ position_mm
 
position_mm = position_size × liquidation_reference_price × MMR

MMR (maintenance margin ratio) is a per-market parameter. Current devnet values:

Authoritative source: GET /v1/markets, fields initialMarginRatioBps and maintenanceMarginRatioBps.

How it works

1. Cancel all open orders. Frees reserved margin. If that restores the account above maintenance margin, the liquidation stops here.

2. Backstop check. If the account is deeply underwater (account_value < (2/3) × maintenance_margin), positions route to the Liquidator Vault for the market they're in. The vault inherits each position at the user's entry price, transfers a pro-rata share of the user's collateral, and zeros the user's position. Anything the vault refuses or solvency-caps falls through to step 4.

3. Close positions on the book. Remaining positions (those the vault didn't absorb) are closed against the live orderbook starting with the largest notional, IOC. If no liquidity exists, the position can't be closed here.

4. Remaining collateral. Positive leftover goes to the vault. Negative collateral after backstop + book closes triggers ADL.

There is no liquidation fee in the post-vault model. Vault PnL on absorbed inventory replaces the fee revenue stream.

Partial vs full liquidation

Liquidations are partial by default for accounts in the maintenance-margin band. The engine only closes enough to restore the initial margin ratio. Accounts that drop below (2/3) × maintenance_margin are handed wholesale to the vault — no partial-restore step.

What you see

When your account is liquidated, you receive a WebSocket event on the liquidations channel:

{
  "type": "liquidation",
  "account_id": 12,
  "positions_closed": 1,
  "positions_remaining": 0
}

If your positions were absorbed by the vault, a BackstopExecuted event will also fire on the events channel.

Isolated liquidation

Isolated positions liquidate one at a time, scoped to a single position and its bucket. This runs as a separate sweep right after the cross liquidation sweep at each block end.

When it triggers

For each open isolated position:

bucket + unrealized_pnl_at_reference_price < notional × MMR

The reference price is the same as for cross liquidations (oracle for real estate, median mark for everything else). When the inequality holds, that one position liquidates. Other positions on the account, cross or isolated, are unaffected.

How it closes

The position closes through the orderbook, not the backstop. The engine cancels any open orders the account holds on that market, then walks the book at IOC on the close side until the position is flat. Realized PnL accrues into the bucket; the liquidation fee comes out of the bucket. When the position fully closes, whatever remains in the bucket (the surplus, if any) returns to the account's cross collateral.

If the book is empty on the close side, the position can't close this block. An empty-book cooldown is set on the account so the sweep doesn't loop fruitlessly every block; the sweep retries when liquidity returns.

Bad debt is confined

If the bucket can't absorb the loss (negative bucket after the close), the deficit is socialized through the same path cross liquidations use — the system, not the trader's other collateral, eats it. The trader's cross collateral and any other isolated positions on the account stay exactly intact.

This is the headline isolated-margin guarantee: a blown-up isolated position can lose only what was in its bucket.

Why a voluntary close can be rejected

A user-initiated close (your PlaceOrder reduce, not the sweep) is rejected if the worst-case fill at the order's price floor would push the bucket negative. The system would otherwise have to either drain the trader's cross collateral or take on bad debt for what looks like a normal order, neither of which respects the isolated promise.

In practice you'll see IsolatedReduceWouldCreateBadDebt if you try a pure market close on an isolated position (no slippage cap) or a limit price below the bucket-survival point. Tighten the limit, set a slippage cap, or let the next liquidation sweep handle it.

Liquidator Vault

The Liquidator Vault is an active backstop: it inherits inventory rather than just absorbing cash. Inherited positions are unwound through the orderbook.

Sub-vaults

The vault is composed of sub-vaults, each with its own collateral, positions, and asset-class scope. v1 ships with a single Mixed sub-vault that accepts every market. Post-v1 the vault tiers into per-asset-class sub-vaults (Real Estate / Commodities / Crypto) so that risk on one asset class can't drain capital allocated to another.

Capacity

There is no fixed per-position cap. A sub-vault accepts as much inventory as its own solvency allows — when its account value falls below the same margin thresholds that gate user accounts, it's the sub-vault that gets liquidated and falls through to ADL. Vault collateral can go negative as a system liability when ADL exhausts.

What you see

/v1/vault returns parent collateral, total collateral, and per-sub-vault state including kind, tier, allowed markets, current collateral, and open position count.

Auto-deleveraging (ADL)

ADL fires when the vault refuses a backstop (e.g. unrouted market) OR when residual positions remain after the vault's solvency cap is reached. It forcibly closes profitable opposing positions at the bankruptcy price to cover the deficit.

When it triggers

ADL fires when either:

1. The Liquidator Vault refuses the backstop (no routing, market not allowed by sub-vault, or sub-vault missing).
2. The vault accepted what it could absorb under its solvency cap, leaving residual positions on the bankrupt account.

How it works

For each market where the bankrupt account had a residual position:

1. Compute bankruptcy price. entry - collateral/size for longs, entry + collateral/size for shorts. This is the price at which the position's PnL exactly equals the user's collateral — the loss the system has to socialize.

2. Find opposing profitable traders. Liquidated long → ADL targets profitable shorts (and vice versa).

3. Rank by profit ratio. Candidates sorted by unrealized_pnl / position_notional, highest first.

4. Symmetric close at bankruptcy price. Both the bankrupt position and the matched target position close at the bankruptcy price. The target loses the unrealized PnL on the closed portion. Open interest decrements symmetrically (no OI imbalance from the close — fixes a bug in the prior oracle-priced ADL).

5. Residual to vault. If ADL exhausts profitable counterparties before clearing the deficit, the residual loss is absorbed onto the receiving sub-vault's collateral, which goes negative by the deficit amount. The system invariant Σ(account.collateral) = bridge_USDC is preserved (the Treasury and sub-vault accounts are in the account sum).

What you lose in an ADL event

If you are ADL'd, a portion of your profitable position is forcibly closed at the bankruptcy price. You realize PnL = (bankruptcy_price - entry) × close_size for longs (or the inverse for shorts) — typically less than your unrealized PnL would suggest, since the bankruptcy price is past your mark.

Minimizing ADL risk

• ADL only fires when the vault can't absorb. A well-funded vault with adequate per-asset-class capital allocation makes ADL a tail event.
• Lower-leverage positions with modest PnL are further back in the queue.
• ADL cannot affect accounts with no open positions.

ADL events

Each ADL execution emits an AdlExecuted event:

• market_id: which market
• liquidated_account_id: the bankrupt account (or sub-vault id, if a sub-vault was the source)
• liquidated_side: side of the bankrupt position
• target_account_id: counterparty whose position was reduced
• target_side: side of the reduced position
• close_size: how much was closed
• close_price: the bankruptcy price
• realized_pnl_forfeited: PnL the target gave up vs. their unrealized position
• remaining_deficit: deficit remaining after this step