> ## Documentation Index
> Fetch the complete documentation index at: https://docs.derive.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Liquidations

Users who fall beneath their maintenance margin requirements are subject to liquidation. In this section we describe how liquidations take place. The ability to liquidate is open to all; users are encouraged to operate their own liquidation bots.

Liquidations are **local to a risk universe**. The auction and the Security Module that backstops it all belong to the universe the liquidated subaccount sits in.

# Liquidation Auctions

Liquidations are performed via an auction system where a percentage of all assets in the subaccount (cash, collateral, perpetuals and options) are available to bidders.

When a user falls beneath their maintenance margin requirements (i.e. maintenance margin becomes negative), any user can call the function `liquidate()`on said account. The auction process then begins; the user is prohibited from conducting any transactions using the flagged account.

**A note on portfolio margined accounts**: To avoid excess computation done on chain, when a portfolio margined subaccount is flagged for liquidation, the flagger also submits what they believe to be the worst case scenario (say, spot down 14%, IV up). This scenario, along with the static vol/spot and forward loss scenarios, is used to compute the margin requirements of the portfolio, as well as the buffer margin (explained below). As the auction proceeds (or if the flagger is incorrect), this scenario may no longer be the "worst" scenario. Consequently, liquidators (or any user) are able to submit what they believe to be the "correct" "worst" scenario. This new scenario is accepted if it decreases (makes more negative) the maintenance margin requirement of the subaccount in question.

## Buffer Margin

When liquidating an account, it is important that the resulting account has sufficiently more collateral than its maintenance margin requires. Otherwise, a small move in price against it will result in it being liquidated again. Consequently, we define the buffer margin as:

```Text Formula theme={null}
Buffer Margin = MtM Value + BUFFER_SCALE * (Maintenance Margin - MtM Value)
```

Where:

* `MtM Value` is the mark-to-market value of the account. This is the sum of all credits (cash and collateral for all accounts, long options for portfolio margin) and debits (short options for all accounts, borrowed collateral). Note that the unrealized profit and loss of perpetuals is accounted for in the cash asset due to continuous settlement.
* `Maintenance Margin` is defined for standard and portfolio margin accounts.
* `BUFFER_SCALE = 1.2`

Equivalently, `Buffer Margin = Maintenance Margin + 0.2 * (Maintenance Margin - MtM Value)` — it sits a fifth of the margin requirement below the maintenance margin.

The `Buffer Margin` represents how much of the cash asset needs to be added to the account in order to terminate the liquidation. For instance, a buffer margin of -1000 means at least \$1000 needs to be added in order to stop the liquidation.

> 📘 At the end of a liquidation, we want the liquidated account's buffer margin to be 0 to ensure that a small price move doesn't liquidate the account again.

## Charging the Liquidation Fee

When an account is flagged for liquidation, a small fee is charged. The fee is the liquidation fee percentage applied to the fraction of the account that would be liquidatable at **zero** discount:

```python Formula theme={null}
Liquidation Fee = LIQ_FEE_PERCENT * f_max(1.0) * MtM Value

f_max(1.0) = Buffer Margin / (Buffer Margin - MtM Value)
```

Where `LIQ_FEE_PERCENT = 2%`. The fraction is rounded up to the nearest 1% before the fee is computed, so the rounding flows into the fee.

## Solvent Auction

After the liquidation fee is charged, the account is put up for a solvent auction. Liquidators can take on a percentage of the entire subaccount at a discount to the mark-to-market value.

The auction quotes a **price factor** `d`, the fraction of mark-to-market value a bidder pays. It starts at `INITIAL_DISCOUNT_FACTOR = 0.98` — a 2% discount — and falls linearly to `THRESHOLD_DISCOUNT_FACTOR = 0.80` — a 20% discount — over the fast phase of `SHORT_DURATION = 100 seconds`:

```python Formula theme={null}
d(t) = 0.98 - (0.98 - 0.80) * t / SHORT_DURATION            for t <= SHORT_DURATION
```

If nobody bids, the auction continues into the slow phase, where the price factor falls from `0.80` to `0` over `LONG_DURATION = 14,400 seconds` (4 hours):

```python Formula theme={null}
d(t) = 0.80 - 0.80 * (t - SHORT_DURATION) / LONG_DURATION   for t <= SHORT_DURATION + LONG_DURATION
```

Once `d` reaches zero the portfolio can be taken for free, and the insolvent auction begins.

When a liquidator wishes to liquidate the subaccount, they are able to take on any percentage of the subaccount up to a cap:

```python Formula theme={null}
Max Percentage = Buffer Margin / (Buffer Margin - d * MtM Value - (1 - d) * Reserved Funds)
```

Where:

* `d` is the current price factor.
* `MtM Value` is the mark-to-market value of the entire portfolio defined above.
* `Reserved Funds` is the amount of cash received by the portfolio from all previous liquidations during the auction. It is necessary to ensure liquidators liquidating at the same price pay the same price.
* `Buffer Margin` is the buffer margin of the current subaccount (including reserved funds).

`Max Percentage` is rounded **up** to the nearest 1%, and is capped at 100%. If a liquidator requests more than the cap, they are floored at `Max Percentage` and the liquidation terminates.

Otherwise, the liquidator receives their requested percentage of the current portfolio and pays

```python Formula theme={null}
Liquidator Cost = Percentage Received x (MtM Value - Reserved Funds) x d
```

of the cash asset to take on their chunk of the portfolio. The liquidation then continues.

*Note that all perpetual PNL and funding, along with all interest on the cash asset is settled before any liquidator bid.*

### Termination

Because the market moves while the auction runs, the auction is re-checked at every bid. A bid does not clear, and the auction terminates, if either of the following holds:

* `Buffer Margin >= 0` — the account is back above water, either because enough of the portfolio has been liquidated or because the market moved in the trader's favour. `Max Percentage` is clamped to 0 in this state.
* `Reserved Funds >= MtM Value` — the bid price `(MtM - Reserved Funds) * d` is no longer positive, i.e. the remaining portfolio is worth no more than the cash already paid into it.

If the price factor reaches zero, the solvent auction ends and the insolvent auction begins.

### Insolvent Auction

At the insolvent auction, offers start at the mark-to-market value of the portfolio and move over `INSOLVENT_DURATION = 100 seconds` towards the current `Maintenance Margin` of the liquidated portfolio.

Specifically, the current offer at a given time `t` is

```Text Formula theme={null}
currentOffer = min(0, mtm) + (t / INSOLVENT_DURATION) * (Maintenance Margin - mtm)
```

where

* `mtm` is the mark-to-market value of the portfolio

From the above, it is clear that all offers at the insolvent auction will be negative. This indicates that the liquidator will be paid by the Security Module (SM) of the universe (see below) to take on the portfolio.

The percentage that can be taken on by the liquidator during the insolvent auction is always up to 100%.

Offers which reach the maintenance margin stay there indefinitely (note the price liquidators receive will continuously vary with the dynamic maintenance margin of the portfolio).

The insolvent auction ends when either of the following conditions are met:

* All of the portfolio has been liquidated
* `Maintenance Margin >= 0`

# Security Module

Every risk universe has its **own** Security Module: a dedicated subaccount holding the universe's cash asset. It pays liquidators to take on insolvent accounts in that universe, and in return it receives a variety of fees, including a share of all interest paid on borrowed cash.

Because the SM is per universe, an insolvency in one universe cannot draw on another universe's backstop, and cannot reach another universe's users.

In the event of a large insolvency, a universe's SM could be depleted, triggering socialized losses **within that universe**.

## Socialized Losses

When the Security Module cannot cover an insolvent bid in full, the uncovered part is socialized.

> 📘 **\[New!]** V2 socialized losses through a temporary withdrawal fee charged to everyone withdrawing from the protocol. V3 instead debits each solvent account in the affected universe once, up front, in proportion to its value, and then phases the *maintenance margin* impact of that debit in over a short window so the debit itself cannot trigger further liquidations.

**Trigger.** During an insolvent auction, the SM's cash is drained to zero to pay the bidder. Any remaining payout is minted to the bidder and recorded as a socialization event on the universe. The socialized amount `H` is exactly `bidder payout − available SM cash`; the SM bears everything up to its balance.

**Snapshot and freeze.** The event freezes the shortfall `H`, the oracle feeds, the timestamp, and the set of subaccounts in scope. While the event is pending, **every balance operation in that universe is rejected**. The only permitted operations are the realization steps, which sweep all subaccounts in ascending order in bounded chunks. When the sweep completes, the universe unfreezes. Chunking is invisible: any number of chunks produces the same final state.

**Per-account share.** Each account with a positive mark-to-market value at the frozen feeds is debited

```python Formula theme={null}
share_i = H * mtm_i / total_spot_value
```

Where:

* `mtm_i` is the account's mark-to-market value at the frozen feeds, including collateral.
* `total_spot_value` is the universe's total spot value: the sum over its spot assets of `(total supply - total borrow) x spot price`, less crystallized-but-unsettled cash.

Accounts with a non-positive mark-to-market value pay nothing. The Security Module is excluded. The liquidator who took the insolvent portfolio is **not** excluded and it pays its share like anyone else.

**Margin impact.** The cash is debited immediately and in full, so mark-to-market and initial margin feel it at once. Maintenance margin does not:

| Quantity | Impact |
| - | - |
| Mark-to-market | Full, immediate |
| Initial margin | Full, immediate |
| Maintenance margin | Credited by `abs(debit) x (1 - write_down)` |

where

```python Formula theme={null}
write_down = clamp((now - issued_at) / DT_WRITE_DOWN_SECONDS, 0, 1)
```

The credit decays continuously and automatically to zero over `DT_WRITE_DOWN_SECONDS`. This gives a solvent account a window to top up or de-risk before the debit can make it liquidatable, without ever letting it escape the debit.

An account **already under auction receives no such credit**: its liquidation margin sees the full debit immediately.

**Cash conservation.** The amount minted to the bidder and the amount burned across the sweep net to zero, so the total cash in the universe is unchanged by a socialization.

# Liquidator Requirements

To liquidate an account, the liquidator must have an account consisting **only** of the cash asset.

The liquidator is required to possess a minimum amount of cash. During the solvent auction, the liquidator is required to have sufficient cash so that their buffer margin (after taking on the portfolio) is 0. Specifically:

```Text Formula theme={null}
cashRequired = f * d * (MtM Value - ResFunds) + f * abs(Buffer Margin - ResFunds)
```

where:

* `f` is the percentage of the current portfolio the liquidator has taken on
* `d` is the current price factor
* `MtM Value` is the mark-to-market value of the portfolio
* `ResFunds` is the total reserved funds for the portfolio undergoing solvent liquidation
* `Buffer Margin` is the buffer margin of the account.

The first term represents the cash the liquidator pays to take on the account (they have to have enough cash to buy it!) while the second term represents the amount of extra cash that must remain in the liquidator’s account to ensure the resulting portfolio has at least zero buffer margin.

For the insolvent auction, we instead require that the liquidator's final account has zero maintenance margin. Similar logic yields

```Text Formula theme={null}
cashRequired = f * abs(Maintenance Margin) - cashReceived
```

where `cashReceived` is the cash received by the liquidator for taking on the portfolio.

**Note**: *A liquidator is required to have a subaccount using the same manager as the liquidated account and therefore in the same risk universe. I.e. if Bob is liquidating Alice who is using the Prime standard manager, then the subaccount Bob is liquidating Alice with must also subscribe to said manager.*

# Example (Solvent Auction)

Consider Alice’s portfolio in the Prime universe, consisting of:

* \$400,000 of USDC
* 10 short ETH perpetuals
* 30 short ETH calls

Suppose Alice’s portfolio is subject to liquidation.

**Liquidation Fee**: Let’s say the initial market value of her portfolio is 100,000 and her maintenance margin is -33,333, so her buffer margin is

```python Formula theme={null}
Buffer Margin = 100,000 + 1.2 * (-33,333 - 100,000) = -$60,000
```

The fraction used to compute her liquidation fee is

```python Formula theme={null}
f_max(1.0) = -60,000 / (-60,000 - 100,000) = 37.5%  ->  rounded up to 38%
```

The liquidation fee she is charged is

```python Formula theme={null}
Liquidation Fee = 2% x 38% x $100,000 = $760
```

**Auction**:

Suppose there are two liquidators in the system: Bob and Charlie.

The auction starts at a price factor of 0.98. Forty seconds pass and the factor falls to 0.908 (a 9.2% discount). At this point Bob decides he wants to liquidate. Alice’s mark-to-market value and buffer margin are recomputed. Say these are 98,000 and -62,000 respectively.

The maximum amount that Bob can liquidate is given by

```python Formula theme={null}
Max Percentage = -62,000 / (-62,000 - 0.908 x 98,000) = 41.1%  ->  42%
```

Bob only wants to liquidate 20% of Alice’s portfolio. He pays

```python Formula theme={null}
Bob Cost = 20% x 98,000 x 0.908 = $17,796.80
```

to take on 20% of Alice’s portfolio. I.e. he receives 20% of:

* 400,000 of USDC (320,000 remaining)
* 10 short ETH perpetuals (8 remaining)
* 30 short ETH calls (24 remaining)

Bob is required to have the following cash in his liquidating account

```python Formula theme={null}
Required Cash (Bob) = 20% x 0.908 x 98,000 + 20% x abs(-62,000) = $30,196.80
```

The liquidation continues. At 100 seconds the fast phase ends and the price factor is 0.80; a 30% discount would take hours from here, so Charlie steps in.

When Charlie decides to step in, Alice’s ***remaining*** portfolio has a mark-to-market value of 82,000 and buffer margin of -46,000. There are also \$17,796.80 of reserved funds. The maximum amount that Charlie can liquidate is

```python Formula theme={null}
Max Percentage = -46,000 / (-46,000 - 0.8 x 82,000 - 0.2 x 17,796.80) = 39.9%  ->  40%
```

Charlie takes the full 40%. He pays

```python Formula theme={null}
Charlie Cost = 40% x (82,000 - 17,796.80) x 0.8 = $20,545.02
```

and receives 40% of

* 320,000 of USDC (note: the 17,796.80 of reserved funds are not included!)
* 8 short ETH perpetuals
* 24 short ETH calls

Charlie is required to have the following amount of cash in his account

```python Formula theme={null}
Required Cash (Charlie) = 40% x 0.8 x (82,000 - 17,796.80) + 40% x abs(-46,000 - 17,796.80) = $46,063.74
```

The liquidation terminates once Alice's buffer margin reaches zero.

# Example (Insolvent Auction)

Alice’s portfolio becomes insolvent and the insolvent auction begins.

Suppose that 10 seconds into the insolvent auction, Bob wants to liquidate. At this point in time, her portfolio has

* `Mark to Market = -$4,000`
* `Maintenance Margin = -$15,000`

Using the formula from above, we have

```Text Formula theme={null}
currentOffer = min(0, -4,000) + (10 / 100) * (-15,000 - (-4,000)) = -$5,100
```

In other words, Bob can take on 100% of the portfolio and receive an additional payout of \$5,100 from the Security Module. If Bob wants only 40%, then he receives 40% of the entire portfolio and is paid out

```Text Formula theme={null}
SM Payout = 0.4 * 5,100 = $2,040
```

from the SM. He is required to have

```Text Formula theme={null}
cashRequired = 0.4 * abs(-15,000) - 2,040 = $3,960
```

of the cash asset in his account in order to liquidate the account.

If the Prime Security Module did not hold the \$2,040, the uncovered part would be socialized across the solvent accounts in the Prime universe.


## Related topics

- [Liquidations ](/liquidations-2.md)
- [public/get_liquidation_history](/api-reference/liquidations/publicget_liquidation_history.md)
- [Trading Fees on Derive: Maker, Taker, RFQ, and Liquidation](/integrators/trading/trading-fees.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.