The liquidation flow

liquidation

1. Alice sends a limit order, and the application matches it to Bob’s under-collateralized position.

Alice wants to sell 1 synthetic BTC for 30000 USDC and pay a maximum amount of 5 USDC as a fee for the trade.

Bob has a position with -1 BTC and +31000 USDC. Notice that Bob’s position can be matched against Alice’s order. If Bob’s position is below the maintenance margin according to the system parameters, the application can match Alice’s limit order and Bob’s position without his signature or consent.

Consequently, after Alice sends a limit order, the application sends the StarkEx gateway a liquidation request that includes Alice’s limit order and the following:

liquidated_position_id

The ID of Bob’s position.
actual_collateral

The actual amount of collateral transferred.
actual_synthetic

The actual amount of synthetic sold in the liquidation.
actual_liquidator_fee

The actual fee that Alice paid. Bob is not required to pay a fee, because his position is liquidated.

2. StarkEx checks the validity of the request.

StarkEx checks the following constraints:

  • The amounts and fees transferred are compatible with Alice’s order. For more information see The trade workflow.

  • Bob’s position is indeed liquidatable, that is, the Total Account Value / Total Maintenance Margin Requirement ratio is below 1.

  • The Total Account Value / Total Maintenance Margin Requirement ratio of Bob’s position is improved due to the liquidation.

  • Bob’s amount of synthetic holdings is reduced due to the trade.

3. Liquidate is included in a batch.

If the Liquidation request is valid, it is included in a batch to be submitted on-chain along with validity proof. See here for a detailed description of the on-chain state update.

Implementing a transfer in your application

To implement transfer functionality in your application, use the add_transaction API with the Liquidate transaction type.

The StarkEx REST API reference includes all necessary information.

Additional resources