Liquidate Subaccount

Submits a transaction to liquidate a subaccount's balance for a specified liquidation amount.

Rate limits

• 30 liquidations/min or 5 liquidations every 10 seconds per wallet. (weight=20)

See more details in API Rate limits.

Request

Websocket

Connect

WEBSOCKET [GATEWAY_WEBSOCKET_ENDPOINT]

Message

{
  "liquidate_subaccount": {
    "tx": {
      "sender": "0x7a5ec2748e9065794491a8d29dcf3f9edb8d7c43746573743000000000000000",
      "liquidatee": "0x7a5ec2748e9065794491a8d29dcf3f9edb8d7c43746573743000000000000000",
      "productId": 1,
      "isEncodedSpread": false,
      "amount": "1000000000000000000",
      "nonce": "1"
    },
    "signature": "0x"
  }
}

REST

POST [GATEWAY_REST_ENDPOINT]/execute

Body

{
  "liquidate_subaccount": {
    "tx": {
      "sender": "0x7a5ec2748e9065794491a8d29dcf3f9edb8d7c43746573743000000000000000",
      "liquidatee": "0x7a5ec2748e9065794491a8d29dcf3f9edb8d7c43746573743000000000000000",
      "mode": 0,
      "healthGroup": 1,
      "amount": "1000000000000000000",
      "nonce": "1"
    },
    "signature": "0x"
  }
}

Request Parameters

Parameter	Type	Required	Description
tx	object	Yes	Liquidate subaccount transaction object. See Signing section for details on the transaction fields.
tx.sender	string	Yes	Hex string representing the subaccount's 32 bytes (address + subaccount name) of the tx sender.
tx.liquidatee	string	Yes	Hex string representing the subaccount's 32 bytes (address + subaccount name) of the subaccount being liquidated.
tx.productId	number	Yes	Perp Liquidation: A valid perp product Id. Spot Liquidation: A valid spot product Id. Spread Liquidation: An encoded perp / spot product Ids, where the lower 16 bits represent the spot product and the higher 16 bits represent the perp product. isEncodedSpread must be set to true for spread liquidation. See Signing section for more details.
tx.isEncodedSpread	bool	Yes	When set to true, the productId is expected to encode a perp and spot product Ids as follows: (perp_id << 16) | spot_id
tx.amount	string	Yes	The amount to liquidate multiplied by 1e18, sent as a string.
tx.nonce	string	Yes	This is an incrementing nonce, can be obtained using the Nonces query.
signature	string	Yes	Signed transaction. See Signing section for more details.

Signing

See more details and examples in our signing page.

The solidity typed data struct that needs to be signed is:

struct LiquidateSubaccount {
    bytes32 sender;
    bytes32 liquidatee;
    uint32 productId;
    bool isEncodedSpread;
    int128 amount;
    uint64 nonce;
}

sender: a bytes32 sent as a hex string; includes the address and the subaccount identifier.

liquidatee: a bytes32 sent as a hex string; includes the address and the subaccount identifier.

productId: The product to liquidate as well as the liquidation mode.

• Perp liquidation ⇒ A valid perp product id is provided and isEncodedSpread is set to false.

• Spot liquidation ⇒ A valid spot product id is provided and isEncodedSpread is set to false

• Spread Liquidation => If there are perp and spot positions in different directions, liquidate both at the same time. Must be set to a 32 bits integer where the lower 16 bits represent the spot product and the higher 16 bits represent the perp product. isEncodedSpread must be set to true.

Computing productId for Spread Liquidation

btc_spot = 1
btc_perp = 2

spread_product_id = (btc_perp << 16) | btc_spot

isEncodedSpread: indicates whether productId encodes both a spot and a perp product Id for spread liquidation.

amount: the amount to liquidate multiplied by 1e18, sent as a string. Can be positive or negative, depending on if the user’s balance is positive or negative.

nonce: the tx_nonce. This is an incrementing nonce, can be obtained using the Nonces query.

Note: for signing you should always use the data type specified in the solidity struct which might be different from the type sent in the request e.g: nonce should be an uint64 for Signing but should be sent as a string in the final payload.

Response

Success

{
  "status": "success",
  "signature": {signature},
  "request_type": "execute_liquidate_subaccount"
}

Failure

{
  "status": "failure",
  "signature": {signature},
  "error": "{error_msg}",
  "error_code": {error_code},
  "request_type": "execute_liquidate_subaccount"
}