Account liquidation

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

POST /accounts/{account_id}/liquidations

Example request

{
  "user_id": "7c9dc9d0-8953-42f9-9b5e-f602a6201577"
}

An 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:

Status Description
NEW An account liquidation request has been placed, relevant checks are being conducted.
PROCESSING All individual sell orders have been created. Order checks have passed and the individual orders are executed.
FILLED All individual orders have been executed successfully. The securities and cash positions have been updated accordingly.
CANCELLED The account liquidation has been cancelled by you or due to an error at the trading partner.

Account liquidation object

Example

{
  "id": "10bfd760-dbf0-4302-b415-7ac7ffec7a52",
  "created at": "2021-07-21T14:10:00.000Z",
  "updated_at": "2021-07-21T14:10:00.000Z",
  "account_id": "d7a57c3e-2be9-4c4e-b3ff-48e1e7815659",
  "user_id": "2ef01903-3b0f-487c-89d8-303684d2f23c",
  "cash_amount": "",
  "currency": "EUR",
  "status": "PROCESSING",
  "orders" : [
    {
      "id": "6a8c5a23-abff-4faf-83bb-6c4871110409",
      "side": "SELL",
      "state":"NEW"
    },
    {
      "id": "5e6dc328-7add-4ad6-9626-8f691b0369cc",
      "side": "SELL",
      "state": "PROCESSING"
    },
    {
      "id": "d35f1d8c-675f-45d9-9689-48db5ed174aa",
      "side": "SELL",
      "state": "FILLED",
    }
  ]
}

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.

The field 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

GET /orders/{order_id}

For more information, see the 'Orders' guide.

Webhooks

A webhook is sent for each state transition that the account liquidation undergoes in its lifecycle.

Example webhook

{
  "id": "f1ea50ca-3f20-417d-b0bd-729bb5e59035",
  "created_at": "2023-01-30T10:40:02.114491885Z",
  "type": "ACCOUNT_LIQUIDATION.PROCESSING",
  "object": {
    "id": "7e8b0710-9ae9-40db-b0de-0e9d670a4b41",
    "user_id": "3acaced2-efda-4609-bc60-97ad6e6fd2d8",
    "account_id": "56ee6a37-5347-40b3-9c35-5fcb2b2fdfae",
    "created_at": "2023-01-30T10:39:55Z",
    "cash_amount": "",
    "currency": "EUR",
    "status": "PROCESSING",
    "updated_at": "2023-01-30T10:40:00Z",
    "orders": [
      {
        "id": "778caa17-f0b3-4c52-93da-4d06e3b8f048",
        "side": "SELL",
        "status": "NEW"
      },
      {
        "id": "cf164087-2906-4537-ab38-8731cce711ff",
        "side": "SELL",
        "status": "PROCESSING"
      },
      {
        "id": "7f66ecb6-5ada-4d51-bf6c-d2a3323b573f",
        "side": "SELL",
        "status": "NEW"
      }
    ]
  },
  "webhook_id": "1e20ef73-db1f-4291-a04b-b6ac00217729"
}

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.

  1. Account_liquidation.NEW
    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.
  2. Account_liquidation.PROCESSING
    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 NEW to PROCESSING.
    • a) Individual_order.NEW You receive this webhook for each individual order that is created.
    • b) Individual_order.PROCESSING You receive this webhook for each individual order that changes status to PROCESSING.
    • c) Individual_order.FILLED You 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 FILLED.
  3. Account_liquidation.FILLED
    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?

On This Page