A liquidation event is the complete record of one forced risk-reduction cycle on a Portfolio. When a Portfolio's uniMMR falls below the liquidation threshold, the risk engine opens an event, works through a series of nodes — cancelling orders, reducing positions, netting hedges, settling debt — and closes the event once the account is back within margin requirements or has been taken over.
Every node carries a snapshot of the account, its assets and its positions as they were at that moment. Together the nodes give you a replayable, step-by-step audit trail of what the engine did and what it cost.
Event types
eventType | Meaning |
|---|---|
CANCELLATION | Order-cancellation only. The engine freed up margin by cancelling open orders and the account recovered — no position was closed. triggerUniMmr, totalPositionsLiquidated, totalClosedPnl and totalLiqFee are omitted. |
POSITION_LIQUIDATION | Positions were force-closed. The event totals (totalPositionsLiquidated, totalClosedPnl, totalLiqFee) and the uniMMR that tripped the trigger (triggerUniMmr) are all present. |
Node types
Nodes are the individual steps of the event. Not every node type appears in every event — the engine only executes the steps it needs, and stops as soon as the account is healthy again. Order nodes by createAt to reconstruct the timeline.
nodeType | What happened | account / assets / positions | orders | roundSeq |
|---|---|---|---|---|
POSITION_LIQUIDATED | Container node for the event. Carries no snapshot — skip it when rendering a timeline. | — | — | — |
CANCEL_OPEN_ORDERS | Cancelled the open orders on the symbols under pressure, releasing their frozen margin. | ✓ | ✓ | — |
CANCEL_ALL_ORDERS | Cancelled all open orders on the account, not just those on the affected symbols. | ✓ | ✓ | — |
POSITION_REDUCE | Force-reduced positions. The engine may need several passes; each pass is its own node, numbered by roundSeq starting at 1. | ✓ | — | ✓ |
NET | Netted off opposing (hedged) positions against each other instead of closing them on the market. | ✓ | — | — |
DEBT_SETTLED | Repaid debt in one currency using the balance of another (cross-currency debt repayment). | ✓ | — | — |
TAKEOVER | LTP took over the remaining position. Reached only when the account could not be brought back within margin on the market. | ✓ | — | — |
FINAL_JUDGMENT | Bankruptcy loss coverage — the shortfall left after takeover was absorbed. | ✓ | — | — |
COMPLETED / NORMAL_RECOVERY | Terminal node. Snapshot of the account once it is back within margin requirements and the event is closed. | ✓ | — | — |
✓ = the field is present on that node; — = the field is omitted.
Getting a liquidationEventId
liquidationEventIdThe REST endpoint below takes a liquidationEventId. You get one from the WebSocket Liquidation channels on the User Data stream, which push liquidationEventId on every liquidation update in real time — subscribe there first, then call this endpoint whenever you need the full snapshot for an event you have seen.
An endpoint for listing liquidation events over a time range is coming soon, so you will be able to look up historical events without having had the stream connected.
Related
- Liquidation — the three real-time WebSocket channels: node-level event updates, and order-level position updates for a Sub Portfolio or for all Sub Portfolios of a main account.
- User Data (orders, trades, assets, positions, accounts) — the
MarginCallchannel, which fires before liquidation starts and is your earliest warning. - Query ADL Rank — how close each of your positions is to being auto-deleveraged.