Skip to main content

Liquidation

Liquidation Mechanism​

Traders whose netValue falls below the maintenance margin may have their positions being force-closed, which is called "liquidation".

During the liquidation, the system tries to sell the position at a discount based on the mark price. Anyone interested in this deal can join liquidation and are known as "liquidator".

Liquidators are permitted to take over the position, entirely or partially, of the liquidated account, whithout consuming the liquidity from orderbook. The whole liquidation process will last until no position left or the netValue is greater than the maintenance margin.

As the liquidation is open to the public, there is no guarantee that your request will be executed. It will not be executed or partially executed if:

  • Someone else submitted a liquidation request before you, or
  • The trader deposited enough margin in time, or
  • The mark price moved beyond your price protection.

Trigger a Liquidation​

You can trigger a liquidation by calling IPerpetual#liquidate():

/// @param  liquidatedTrader is the trader you want to liquidate.
/// @param  requestPaper is the size of the position you want to take.
/// requestPaper is positive when you want to liquidate a long position, and negative when short.
/// @param expectCredit is the amount of credit you want to pay (when liquidating a short position)
/// or receive (when liquidating a long position)
/// @return liqtorPaperChange is the final executed change of the liquidator's paper amount
/// @return liqtorCreditChange is the final executed change of the liquidator's credit amount

function liquidate(address liquidatedTrader, int256 requestPaper, int256 expectCredit)
external
returns (int256 liqtorPaperChange, int256 liqtorCreditChange);

Liquidation is just like a normal trade. Liquidators can customize amount and set price protection to avoid losses caused by changes in markPrice.

The parameter expectCredit is the amount of credit you want to pay (when liquidating a short position) or receive (when liquidating a long position). You can set the expectCredit by yourself.

By setting requestPaper and expectCredit, you're indicating the "expected price":

expectedPrice=−1∗expectCreditrequestPaperexpectedPrice = -1 * \frac{expectCredit}{requestPaper}

The smart contract will not execute with price higher(lower) than the expected price if you're liquidating a long(short) position.

Auto Scaled Amount​

Your liquidation will be limited to the position size. For example, if the position remains 10ETH and you're requesting a 15ETH liquidation. Only 10ETH will be executed. And the other 5ETH request will be canceled. This scenario is common to gas war for liquidation.

Liquidation Price​

Here we show how to calcuate the liquidation price of an account.

To avoid liquidation, we need:

netValue≥maintenanceMarginnetValue \geq maintenanceMargin
  • We first calculate the maintenanceMargin for all other markets' positions. Let's call it maintenanceMargin'. Then we have netValue of the account. Let's call it netValue'. So we have:
netValue′+paperAmount∗price+creditAmount≥maintenanceMargin′+∣paperAmount∣∗price∗liquidationThresholdnetValue' + paperAmount * price + creditAmount \geq maintenanceMargin' + \lvert paperAmount \rvert * price * liquidationThreshold
  • if paperAmount > 0
paperAmount∗price∗(1−liquidationThreshold)≥maintenanceMargin′−netValue′−creditAmountpaperAmount * price * (1-liquidationThreshold) \geq maintenanceMargin' - netValue' - creditAmount
price≥(maintenanceMargin′−netValue′−creditAmount)paperAmount∗(1−liquidationThreshold)price \geq \frac{(maintenanceMargin' - netValue' - creditAmount)}{paperAmount * (1-liquidationThreshold)}
liqPrice=(maintenanceMargin′−netValue′−creditAmount)paperAmount∗(1−liquidationThreshold)liqPrice = \frac{(maintenanceMargin' - netValue' - creditAmount)}{paperAmount * (1-liquidationThreshold)}
  • if paperAmount < 0
paperAmount∗price∗(1+liquidationThreshold)≥maintenanceMargin′−netValue′−creditAmountpaperAmount * price * (1+liquidationThreshold) \geq maintenanceMargin' - netValue' - creditAmount
price≤(maintenanceMargin′−netValue′−creditAmount)paperAmount∗(1+liquidationThreshold)price \leq \frac{(maintenanceMargin' - netValue' - creditAmount)}{paperAmount * (1+liquidationThreshold)}
liqPrice=(maintenanceMargin′−netValue′−creditAmount)paperAmount∗(1+liquidationThreshold)liqPrice = \frac{(maintenanceMargin' - netValue' - creditAmount)}{paperAmount * (1+liquidationThreshold)}
  • Let's call 1±liquidationThreshold "multiplier", then:
liqPrice=(maintenanceMargin′−netValue′−creditAmount)paperAmount∗multiplierliqPrice = \frac{(maintenanceMargin' - netValue' - creditAmount)}{paperAmount * multiplier}
  • If liqPrice<0, it should be considered as the position can never be liquidated (absolutely safe).