This guide provides instructions on how to liquidate all open positions in an account. This functionality allows users to sell or liquidate all their positions within their investment account, enabling them to quickly exit all their investments. We describe below the API endpoint, request/response formats and highlight important contextual information for integrating this functionality into your platform.
How account liquidations work
In our system, an account liquidation request is an instruction to completely sell out all existing positions in an account. Each position is liquidated by creating unit orders for each instrument in the account. After a liquidation is completed, the account is empty, i.e. there are no longer any open securities positions, but the account remains in active status and can be used for other purposes.
Liquidating an account
You can initiate a liquidation of an account by
account_liquidation_id will be returned as a response. You can use this ID to track the progress of the liquidation and assign the resulting individual orders as described below.
Lifecycle of an account liquidation
The liquidation of an account follows our standard order approach; its entire lifecycle is represented as a series of states. The status of an account liquidation at a given point in time provides a clear view of the processing status and possible actions:
||An account liquidation request has been placed, relevant checks are being conducted.|
||All individual sell orders have been created. Order checks have passed and the individual orders are executed.|
||All individual orders have been executed successfully. The securities and cash positions have been updated accordingly.|
||The account liquidation has been cancelled by you or due to an error at the trading partner.|
Account liquidation object
The above example shows an ongoing liquidation for an account that had three open positions. The liquidation is still in the
PROCESSING status because not all individual orders have been fully executed.
cash_amount is populated once all individual orders have been executed. It is important to note that each individual order in a liquidation goes through its own distinct lifecycle.
To get detailed information about the individual orders, execute
For more information, see the 'Orders' guide.
A webhook is sent for each state transition that the account liquidation undergoes in its lifecycle.
Tracing an account liquidation request
This section summarises the sequence of events that allow you to track an account liquidation and the associated individual orders in their entirety.
You receive this webhook when the request to liquidate an account has been placed via the Investment API. It contains the generic metadata and an empty list of individual orders.
You receive this webhook when the first individual order in the list is executed, i.e. when the status of the individual order changes from
Individual_order.NEWYou receive this webhook for each individual order that is created.
Individual_order.PROCESSINGYou receive this webhook for each individual order that changes status to
Individual_order.FILLEDYou receive this webhook when an individual order has been completely executed.
- d) Steps a to c are repeated until all individual orders have the status
You receive this webhook when the account liquidation is completed and the user's investment account is empty, i.e. there are no more open securities positions.
To make tracing and mapping of individual orders as easy and seamless as possible, each individual order executed in step 3 carries the corresponding
account_liquidation_id. The account liquidation ID can be found in the
client_reference field of the individual order object. For more information, see the relevant API specification.
Was this page helpful?