Triggering a rebalancing

Before reading this guide, we recommend you read the “Understanding portfolio orders” guide, as we will expand on the concepts discussed there.

How one-off rebalancing triggers work

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

A one-off rebalancing can be triggered both on a portfolio allocation level as well as on an individual account level. Triggering a one-off rebalancing on individual accounts is particularly relevant to allow for dedicated investment needs of specific users.

More generally, one-off rebalancing triggers are used to directly reallocate your users investments outside of predefined rebalancing cycles as defined by a rebalancing strategy.

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 particular example, the one-off rebalancing is invoked on a “global” portfolio allocation level, meaning that it applies to all accounts that have this allocation in their portfolio configuration.

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

Example request

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

In either case, the POST request returns a rebalancing_execution_id.

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

In other words, for each account that was specified in the one-off rebalancing trigger, we create one portfolio order that when executed - meaning all individual orders have been executed - realigns the portfolio investment with its target allocation.

The rebalancing_execution_id can be used to list all portfolio orders that were created as a result of the trigger at all times.

Rebalancing process

This section explains the rebalancing process, and details how you can track its progress until the portfolio investments have been rebalanced.

Portfolio orders that are created as a result of a rebalancing trigger - whether through the public API or through automated strategies - undergo a slightly prolonged life cycle compared to simple portfolio buy and sell orders. That is because a rebalancing typically does not deal with capital in- or outflows of a portfolio investment, but rather restructures the existing portfolio investment to reflect a desired target state. As such, capital is first freed up by selling overweight instruments in the portfolio, and then used to buy underweighted instruments.

Translating this back 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 as the rebalancing progresses over time. Of course, to keep the overall process as transparent as possible, you will receive update webhook events when new orders are added.

Tracing a rebalancing

You receive the following webhooks for each account for which a rebalancing has been triggered. The depicted flow focuses on the particularities that are unique to a portfolio order that executes a rebalancing. Please refer to the Understanding portfolio orders guide for more general details of each step of a portfolio order.

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 state FILLED.
3. Portfolio_order.UPDATED
   You receive this webhook when a new batch of individual orders has been added to the portfolio order. This is not a new state, just an update event while the portfolio order is still in PROCESSING. From now, steps 3 & 4 repeat until the portfolio is rebalanced.
4. Portfolio_order.FILLED

Managing one-off rebalancings

Retrieving a single rebalancing execution

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 affected accounts and corresponding rebalancing portfolio orders, send a request to the following endpoint:

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

Calling this endpoint will retrieve the following information:

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 and the the second is still undergoing execution.

The individual portfolio_order_ids in the response can be used to retrieve more detailed information about each of them by calling GET /portfolios/orders/{portfolio_order_id}.

Cancelling a rebalancing execution

The current version only allows for cancelling the individual portfolio orders that were created as a result of this trigger individually, future versions may include more advanced cancellation and management functionality of rebalancing executions.

What's next?

Now you know how to trigger a rebalancing for your users portfolio investments, and know how to track the progress of a rebalancing execution. You can continue with learning how to implement more complex, automated rebalancing strategies (COMING SOON).