Liquidations

This guide describes how to liquidate all open positions in an account. This feature allows users to sell or liquidate all positions within their investment account so that they can quickly exit all of their investments.

NOTE

Once a liquidation is completed, the account is empty, i.e. there are no more open securities positions, but the account remains in active status and can be used for other purposes.

We will describe the API endpoint, request and response formats and highlight important contextual information for integrating this feature into your platform below.

How liquidations work

In our system, a liquidation order is an instruction to sell all existing positions in an account. Each position is liquidated by creating individual orders for each instrument in the account.

TIPP

The liquidation function is currently only available for accounts of type PORTFOLIO and will only be available for accounts of type TRADING at a later date.

In the meantime, if you would like to liquidate the position holdings for accounts of type TRADING, simply place unit sell orders.

Liquidating positions of 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 a liquidation

The liquidation 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`	A 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 liquidation has been cancelled by you or due to an error at the trading partner.

Example 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 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 a liquidation request

This section summarises the sequence of events that allow you to track a liquidation and the associated individual orders in their entirety.

Account_liquidation.NEW
You receive this webhook when the request for liquidation has been placed via the Investment API. It contains the generic metadata and an empty list of individual orders.
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.
Account_liquidation.FILLED
You receive this webhook when the 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 liquidation ID can be found in the client_reference field of the individual order object. For more information, see the relevant API specification.