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
/// @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)
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
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.
expectCredit, you're indicating the "expected price":
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.
Here we show how to calcuate the liquidation price of an account.
To avoid liquidation, we need:
- 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:
- if paperAmount > 0
- if paperAmount < 0
- Let's call 1±liquidationThreshold "multiplier", then:
- If liqPrice<0, it should be considered as the position can never be liquidated (absolutely safe).