Get Liquidation Event

Time	Status	User Agent
Retrieving recent requests…

Retrieve the complete snapshot of one liquidation event: the event summary plus the account, asset, position and open-order snapshots captured at every node of the event.

Use this endpoint to reconstruct exactly what the risk engine did — which orders were cancelled, how many rounds of position reduction it took, what each round closed, and what it cost in realized PnL and liquidation fees. See Liquidation Event for what the event types and node types mean.

liquidationEventId is pushed in real time by the WebSocket Liquidation channels.

Rate Limit: 100 requests per 60 seconds.

Permission: RapidX API key with read-only permission is sufficient. No trading / write permission is required.

Request Parameters

Field	Type	Required	Description
`liquidationEventId`	String	Y	ID of the liquidation event to retrieve. Obtained from the WebSocket `LiquidationEvent` / `LiquidationPosition` channels.

Response Fields

Top-level:

Field	Type	Description
`code`	Integer	Business status code. `200000` indicates success.
`message`	String	Text message for the response.
`data`	Object	The liquidation event.

data:

Field	Type	Description
`liquidationEventId`	String	Liquidation event ID.
`portfolioId`	String	Portfolio that was liquidated.
`exchangeType`	String	Venue the event took place on: `BINANCE`, `OKX`, `EDX`.
`eventType`	String	`CANCELLATION` (orders cancelled only, no position closed) or `POSITION_LIQUIDATION` (positions force-closed).
`createAt`	Long	Time the liquidation event was opened, in milliseconds since Unix epoch.
`updateAt`	Long	Time the event was last updated, in milliseconds since Unix epoch. Equals the `updateAt` of the terminal node once the event is closed.
`triggerUniMmr`	Decimal	The `uniMMR` that tripped the liquidation trigger. Only present for `POSITION_LIQUIDATION`. May be negative, which means valid margin was already below zero.
`totalPositionsLiquidated`	Integer	Number of positions force-closed across the whole event. Only present for `POSITION_LIQUIDATION`.
`totalClosedPnl`	Decimal	Total realized PnL from the closed perpetual positions, in USDT. Negative for a loss. Only present for `POSITION_LIQUIDATION`.
`totalLiqFee`	Decimal	Total liquidation fees charged across the event, in USDT. Only present for `POSITION_LIQUIDATION`.
`nodes`	Array	The individual steps of the event, in execution order. See below.

data.nodes[]:

Each node is one step the risk engine executed, with the state of the account at that moment. Which snapshot fields are present depends on nodeType — see the node type table on Liquidation Event.

Field	Type	Description
`nodeId`	Long	Node execution ID, unique within the event.
`nodeType`	String	What this step did. See the node type table on Liquidation Event.
`roundSeq`	Integer	Position-reduction round, starting at `1`. Only present on `POSITION_REDUCE` nodes; the engine may need several rounds to bring the account back.
`createAt`	Long	Time this node started, in milliseconds since Unix epoch. Sort by this field to reconstruct the event timeline.
`updateAt`	Long	Time this node finished or was last updated, in milliseconds since Unix epoch.
`account`	Object	Account snapshot at this node. Omitted on the `POSITION_LIQUIDATED` container node. See below.
`assets`	Array	Asset snapshots at this node, one entry per coin. Omitted on the `POSITION_LIQUIDATED` container node. See below.
`positions`	Array	Position snapshots at this node. Present on nodes that touch positions; omitted on the container node and on the order-cancellation nodes. See below.
`orders`	Array	Snapshots of the open orders that were cancelled. Only present on `CANCEL_OPEN_ORDERS` and `CANCEL_ALL_ORDERS` nodes. See below.

data.nodes[].account:

Field	Type	Description
`equity`	Decimal	Total account equity on this venue, valued in USDT-equivalent (including cash balance and PnL).
`uniMmr`	Decimal	`validMargin` / `maintainMargin`. Unified maintenance margin ratio, expressed as a decimal where `1` = 100%. A forced liquidation is triggered when it falls below `1`. Returns the sentinel `999999` when the account has no maintenance margin requirement.
`validMargin`	Decimal	`marginValue` - `openLossMargin`.
`maintainMargin`	Decimal	Minimum margin required across all positions to avoid liquidation.
`availableMargin`	Decimal	Margin available for opening new positions or for withdrawal.
`upnl`	Decimal	Unrealized profit and loss of the account, in USDT.
`accountStatus`	String	Account status at this node: `NORMAL` (back within margin requirements), `LIQUIDATION` (liquidation in progress), `TAKEOVER` (position taken over by LTP).

data.nodes[].assets[]:

One entry per coin held on the venue at this node.

Field	Type	Description
`coin`	String	Coin symbol, e.g. `USDT`, `BTC`.
`exchangeType`	String	Venue this balance is held on: `BINANCE`, `OKX`, `EDX`.
`equity`	Decimal	Equity of this coin = balance + unrealized PnL from open positions.
`available`	Decimal	Quantity of this coin freely available for trading or transfer.
`frozen`	Decimal	Quantity locked (e.g. in open orders, pending withdrawals, or other holds).
`borrow`	Decimal	Quantity of this coin currently borrowed, where the venue / account type supports borrowing.
`debt`	Decimal	Outstanding borrowed amount of this coin not yet repaid. `0` if nothing is borrowed.
`price`	Decimal	Price of this coin in USDT at the time of the snapshot.

data.nodes[].positions[]:

Field	Type	Description
`positionId`	String	Internal position ID for this symbol and side within the Portfolio.
`exchangeType`	String	Venue the position is held on: `BINANCE`, `OKX`, `EDX`.
`sym`	String	Unified symbol identifier, e.g. `BINANCE_PERP_BTC_USDT`.
`positionSide`	String	Position side: `NONE` in one-way mode, `LONG` or `SHORT` in hedge mode.
`positionQty`	Decimal	Position quantity. Positive = long, negative = short. Unit varies by venue: contracts on `OKX`, base currency on `BINANCE`.
`positionValue`	Decimal	Market value of the position (mark price × quantity).
`markPrice`	Decimal	Mark price used for the PnL and liquidation check at this node.
`unrealizedPnl`	Decimal	Unrealized profit or loss on this position at this node, in USDT.
`positionMode`	String	Position mode on this venue: `NET` (one-way) or `BOTH` (dual-side).
`leverage`	Integer	Leverage applied to this position at the time.
`closedQty`	Decimal	Quantity closed by this node. Unit varies by venue: contracts on `OKX`, base currency on `BINANCE`.
`closedPnl`	Decimal	Realized PnL from the quantity closed by this node, in USDT.
`liqFee`	Decimal	Liquidation fee charged for this position at this node, in USDT.

data.nodes[].orders[]:

Snapshots of the open orders cancelled by this node, as they were immediately before cancellation.

Field	Type	Description
`orderId`	String	Order ID.
`exchangeType`	String	Venue the order was placed on: `BINANCE`, `OKX`, `EDX`.
`sym`	String	Unified symbol identifier, e.g. `BINANCE_PERP_BTC_USDT`.
`side`	String	Order side: `BUY` or `SELL`.
`orderType`	String	Order type: `LIMIT` or `MARKET`.
`price`	Decimal	Order price. `0` for market orders.
`orderQty`	Decimal	Order quantity. Unit varies by venue: contracts on `OKX`, base currency on `BINANCE`.
`orderState`	String	State the order was in when the snapshot was taken, e.g. `NEW`, `PARTIALLY_FILLED`.
`reduceOnly`	Boolean	`true` if the order could only reduce an existing position.

Example Response

{
  "code": 200000,
  "message": "Success",
  "data": {
    "liquidationEventId": "7391234567890001",
    "portfolioId": "1702884522340000",
    "exchangeType": "BINANCE",
    "eventType": "POSITION_LIQUIDATION",
    "createAt": 1700000000000,
    "updateAt": 1700000060000,
    "triggerUniMmr": "0.55",
    "totalPositionsLiquidated": 2,
    "totalClosedPnl": "-120.50",
    "totalLiqFee": "6.00",
    "nodes": [
      {
        "nodeId": 7391000000001,
        "nodeType": "POSITION_LIQUIDATED",
        "createAt": 1700000000000,
        "updateAt": 1700000060000
      },
      {
        "nodeId": 7391000000002,
        "nodeType": "CANCEL_ALL_ORDERS",
        "createAt": 1700000001000,
        "updateAt": 1700000010000,
        "account": {
          "equity": "10000.00",
          "uniMmr": "0.55",
          "validMargin": "8000.00",
          "maintainMargin": "2000.00",
          "availableMargin": "6000.00",
          "upnl": "-200.00",
          "accountStatus": "LIQUIDATION"
        },
        "assets": [
          {
            "coin": "USDT",
            "exchangeType": "BINANCE",
            "equity": "10000.00",
            "available": "8000.00",
            "frozen": "2000.00",
            "borrow": "0",
            "debt": "0",
            "price": "1.00"
          }
        ],
        "orders": [
          {
            "orderId": "1703213979730000",
            "exchangeType": "BINANCE",
            "sym": "BINANCE_PERP_BTC_USDT",
            "side": "SELL",
            "orderType": "LIMIT",
            "price": "49000.00",
            "orderQty": "0.1",
            "orderState": "NEW",
            "reduceOnly": false
          }
        ]
      },
      {
        "nodeId": 7391000000003,
        "nodeType": "POSITION_REDUCE",
        "roundSeq": 1,
        "createAt": 1700000020000,
        "updateAt": 1700000050000,
        "account": {
          "equity": "9800.00",
          "uniMmr": "0.48",
          "validMargin": "7800.00",
          "maintainMargin": "2000.00",
          "availableMargin": "5800.00",
          "upnl": "-400.00",
          "accountStatus": "LIQUIDATION"
        },
        "assets": [
          {
            "coin": "USDT",
            "exchangeType": "BINANCE",
            "equity": "9800.00",
            "available": "9800.00",
            "frozen": "0",
            "borrow": "0",
            "debt": "0",
            "price": "1.00"
          }
        ],
        "positions": [
          {
            "positionId": "1704179813908000",
            "exchangeType": "BINANCE",
            "sym": "BINANCE_PERP_BTC_USDT",
            "positionSide": "LONG",
            "positionQty": "0.1",
            "positionValue": "5000.00",
            "markPrice": "50000.00",
            "unrealizedPnl": "-10.00",
            "positionMode": "NET",
            "leverage": 10,
            "closedQty": "0.05",
            "closedPnl": "-5.00",
            "liqFee": "0.50"
          }
        ]
      }
    ]
  }
}

Request Parameters

Response Fields

Example Response

200200