Triggering a rebalancing

In this guide, we expand on the knowledge we have outlined in the section 'Understanding portfolio orders' (if you have not already done so, we recommend that you read that chapter first).

How the one-off rebalancing triggers work

Generally, one-off rebalancing triggers are used to directly reallocate your users' investments outside the predefined rebalancing cycles defined by a rebalancing strategy.

The Investment API allows you to trigger a rebalancing for all your user’s portfolio investments at any time. This functionality supports common portfolio management cases such as exchanging instruments and changing target weights for portfolio allocations, ensuring that you can react quickly to new (market) information or user requests at any time.

One-off rebalancing can be triggered at the portfolio allocation level as well as at the individual account level. Triggering one-off rebalancing for individual accounts is particularly relevant to accommodate the specific investment needs of certain users.

Rebalancing process

Portfolio orders created as a result of a rebalancing trigger - whether via the Investment API or via automated strategies - go through a slightly extended lifecycle compared to simple portfolio buy and sell orders. This is because rebalancing usually does not involve capital inflows or outflows from a portfolio investment, but instead restructures the existing portfolio investment to achieve a desired target state. Capital is thus first freed up by selling overweight instruments in the portfolio and then used to buy underweight instruments.

Transferred to the concept of a portfolio order in the Investment API, this means that the list of individual orders in the portfolio order object is dynamic and grows over time as rebalancing progresses. To keep the overall process as transparent as possible, you will of course receive update webhook events when new orders are added.

Triggering a rebalancing

A one-off rebalancing trigger is defined by either an array of accounts, or an array of allocations.

To create a one-off rebalancing trigger for a portfolio allocation, send the following request:

POST /portfolios/rebalancings/executions

Example request

{
	"allocations": [
		"eafa39e3-7837-476f-8af1-49fa604e3f49"
	]
}

In this example, the one-off rebalancing is triggered at the 'global' portfolio allocation level, i.e., it applies to all accounts that have this allocation in their portfolio configuration.

You can also trigger the one-off portfolio rebalancing at a more granular level of individual accounts by selecting single or multiple accounts:

Example request

{
	"accounts": [
		"43801b85-bbcf-41c7-8389-b018082a5ec5",
		"20151679-c159-4f16-b8a2-267b3d968c6f"
	]
}

In both cases, the rebalancing_execution_id is returned. You can use this ID to list all portfolio orders created as a result of the trigger at all times.

The portfolio rebalancing execution request triggers a series of events in our system that lead to a rebalancing of the users' portfolios. This rebalancing of active portfolio investments to their target allocation is done through the execution of a set of individual orders. As we learned in the guide 'Understanding portfolio orders', a set of orders in the context of the Investment API is called a portfolio order.

In other words, for each account specified in the one-off rebalancing trigger, we create a portfolio order that, when executed (i.e., all individual orders have been executed) rebalances the portfolio investment with its target allocation.

Tracing a rebalancing

This section describes how you can track the progress of a rebalancing process.

As described above, you receive update webhook events for each account when new orders are added within a rebalancing process. The depicted flow focuses on the specifics of a portfolio order that triggers a rebalancing.

For more general details on the individual steps of a portfolio order, refer to the 'Understanding portfolio orders' guide.

1. Portfolio_order.NEW
2. Portfolio_order.PROCESSING
   • a) Individual_order.PROCESSING
   • b) Individual_order.FILLED
   • c) Step a & b repeat until all individual_orders of the batch are in the FILLED state.
3. Portfolio_order.UPDATED
   You receive this webhook when a new batch of single orders has been added to the portfolio order. This is not a new state, but only an update event while the portfolio order is still in the PROCESSING state. From now on, steps 3 & 4 repeat until the portfolio is rebalanced.
4. Portfolio_order.FILLED

Managing one-off rebalancings

Retrieving a rebalancing execution by ID

To retrieve a specific rebalancing trigger, send the following request:

GET /portfolios/rebalancings/executions/{execution_id}

Retrieving orders of a rebalancing execution

To retrieve more detailed information about the rebalancing execution, such as the affected accounts and corresponding orders for rebalancing the portfolio, send the following request:

GET /portfolios/rebalancings/executions/{execution_id}/orders

Example response

{
    "meta": {
        "count": 2,
        "limit": 10,
        "offset": 0,
        "order": "ASC",
        "sort": "status",
        "total_count": 2
    },
    "data": [
        {
            "account_id": "100bb408-149c-4e6f-8697-837c2a144a29",
            "portfolio_order_id": "b31723e0-8c8c-4bd0-a962-8bd26c5aee4d",
            "status": "FILLED",
            "created_at": "2022-09-28T09:14:02Z",
            "updated_at": "2022-09-28T09:14:02Z"
        },
        {
            "account_id": "98b21a45-5ea0-481f-bb1e-880aab0d154d",
            "portfolio_order_id": "411c625e-b2f4-4af4-ac21-e17846fb6bcc",
            "status": "PROCESSING",
            "created_at": "2022-09-28T09:14:02Z",
            "updated_at": "2022-09-28T09:14:02Z"
        }
    ]
}

In this example, the rebalancing trigger initiated a rebalancing for two portfolio investments - the first has already been completed, the second is still being executed.

You can use the portfolio_order_ids in the response to retrieve more detailed information:

GET /portfolios/orders/{portfolio_order_id}

Cancelling a rebalancing execution