How to Get Started with Rebalancing API

09 Aug 2022

Alpaca's Rebalancing API offers investment advisors a way to easily create investment portfolios that are automatically updated to the specified cash, stock symbol percentage weights, rebalance conditions, and triggers selected. In this article, we dive into how you can start experimenting with Rebalancing API.

Note: At this moment, this offering is only available for Broker API

To get started, an investment advisor would first authenticate using your Broker API keys. Then you can start building your portfolio. Here’s an example of a balanced portfolio of stocks and bonds created through a REST call.

POST https://broker-api.alpaca.markets/v1/beta/rebalancing/portfolios

Payload body

{
    "name": "Balanced actual",
    "description": "A balanced portfolio of stocks and bonds",
    "weights":   [
        {
            "type": "asset",
            "symbol": "AAPL",
            "percent": "45"
        },
        {
            "type": "asset",
            "symbol": "TLT",
            "percent": "35"
        }
    ],
    "cooldown_days": 2,
}

Payload Body

NOTE: cooldown_days represents the number of calendar days after a rebalancing before the system can trigger another rebalance for this subscription.

You might be wondering, what if I want to still maintain a portion of cash🤔. You can! simply add “type”:” cash” to your “weights”. Please see the example below on how you can maintain a portion of the cash in the portfolio.

Example:

"weights":   [
        {
            "type": "cash",
            "percent": "10"
        },
        {
            "type": "asset",
            "symbol": "AAPL",
            "percent": "45"
        },
        {
            "type": "asset",
            "symbol": "TLT",
            "percent": "45"
        }

Okay, now what if you want to set conditions for when a rebalancing should be triggered then you can choose between a drift band and calendar type. What's the difference, you ask?

The 2 Types of Rebalancing

Drift Band: When a portfolio breaches a certain threshold, irrespective of the time period elapsed, the portfolio is adjusted. For instance, if we put a +/- 10% band on a portfolio, we would automatically adjust the entire portfolio when we reach the threshold for one of the holdings

Calendar: At the desired period, the state of the portfolio is analyzed and the portfolio is rebalanced to the default portfolio. For example, on April 1st our 50:50 AAPL TLT portfolio is not 55:45, so we would need to liquidate TLT and buy more AAPL to return to the desired state of exposure of 50:50.

Example with type = drift_band

"rebalance_conditions": [
       {
            "type": "drift_band",
            "sub_type": "absolute",
            "percent": "5"
        }
    ]

What are sub_types of Rebalancing?

Within types of drift_band and calendar, there are sub_types. In the case of type drift_band, there are two sub_types: absolute and relative. The absolute drift band type measures the value of the assets as a proportion to the whole portfolio, while the relative is as a proportion to itself. In both cases specifying a percent request field is required.

Here’s a comparison of a portfolio that started with 50% APPL and 50% MFTS

Scenario

Absolute Drift (percent = 5)

Relative Drift (percent = 5)

52.5% APPL, 47.5% MFTS

Rebalancing not triggered

Rebalancing triggered

55% APPL, 45% MFTS

Rebalancing triggered

Rebalancing would be triggered at

52.5% AAPL, 47.5% MFTS

Separately if you're using rebalancing type “calendar”, your options of sub_type are either (1) Weekly, (2) Monthly, (3) Quarterly and (4) Annually.

Example with subtype = calendar

"rebalance_conditions":    [
        {
            "type": "calendar",
            "sub_type": "annually",
            "day": "02-29"
        }
    ]

The day request field options for rebalancing type calendar for various subtypes are as follows.

sub_type	day field
annually	The value must be passed in “MM-DD” format. If “02-29” is specified and the current year is not a leap year, the rebalance will occur on the trading day preceding 2/29.
monthly/quarterly	The value must be an integer between 1 and 31 inclusive. This represents the day of the month. For quarterly, rebalancing will trigger on this day in January, March, June, and December.
weekly	The permitted values are “Monday”, “Tuesday”, “Wednesday”, ”Thursday”, “Friday”

Now that we have successfully set up our auto-rebalancing portfolio, here’s how we track it. Make a REST GET call request with your portfolio ID retrieved from the Response after Portfolio Creation. (Refer to portfolio creation above)

GET https://broker-api.alpaca.markets/v1/beta/rebalancing/portfolios/{portfolio_id}

Using the portfolio created above, here’s a sample response.

{
    "id": "32e24b33-c112-4bad-aab5-6f0ac8310b68",
    "name": "Balanced actual",
    "description": "A balanced portfolio of stocks and bonds",
    "status": "active",
    "cooldown_days": 2,
    "created_at": "2022-07-17T03:15:09.407116Z",
    "updated_at": "2022-07-17T03:15:09.408793Z",
    "weights": [
        {
            "type": "cash",
            "symbol": null,
            "percent": "10"
        },
        {
            "type": "asset",
            "symbol": "AAPL",
            "percent": "55"
        },
        {
            "type": "asset",
            "symbol": "TLT",
            "percent": "35"
        }
    ],
    "rebalance_conditions": []
}

You can update the weights, rebalancing condition, or the cooldown period using a REST PATCH call.

PATCH https://broker-api.alpaca.markets/v1/beta/rebalancing/portfolios/{portfolio_id}

Example of Payload Body for PATCH

We are adjusting the portfolio now to be 10% Cash and 90% TSLA

{
    “weights”:    [
        {
            “type”: “cash”,
            “percent”: “10”
        },
        {
            “type”: “asset”,
            “symbol”: “TSLA”,
            “percent”: “90”
        }
    ]
}

with a REST DELETE call to the following endpoint, sets the portfolio as inactive.

PATCH https://broker-api.alpaca.markets/v1/beta/rebalancing/portfolios/{portfolio_id}

Rebalancing Subscription

Here's the coolest part of the Rebalancing API - you can now create a subscription between an account and a portfolio. As cash inflows happen into the account (deposits, cash journals, etc.), the subscription automatically adjusts to the subscribed portfolio.

NOTE: The account must be active and must not have any existing active subscriptions.

Here's an example of creating an active subscription between an account and the previously created portfolio.

POST https://broker-api.alpaca.markets/v1/beta/rebalancing/subscriptions

Example of Payload Body to create a subscription

{
    "account_id": "7a987f40-efd8-4238-b6af-55f995e4661a",
    "portfolio_id": "32e24b33-c112-4bad-aab5-6f0ac8310b68"
}

Sample Response

{
    "id": "880140c9-8f6c-48b0-a6f7-3da7dce15750",
    "account_id”: "7a987f40-efd8-4238-b6af-55f995e4661a",
    "portfolio_id": "32e24b33-c112-4bad-aab5-6f0ac8310b68",
    "created_at": "2021-10-20T15:43:22.32Z",
    "updated_at": "2021-10-25T12:33:12.54Z",
    "last_rebalanced_at": null
}

Once you create a subscription, you make a REST GET call while passing the {subscription_id} to obtain information on your subscription - including last_rebalanced_at. The subscription_id from the response after creation is used as the path param.

NOTE: {subscription_id} is the id of the subscription created, it can be found in the return response of the REST POST call to create the subscription.

Below is an example of a REST GET call for a subscription.

GET https://broker-api.alpaca.markets//v1/beta/rebalancing/subscriptions/{subscription_id}

Sample Response

{
    "id": ”880140c9-8f6c-48b0-a6f7-3da7dce15750”,
    “account_id”: "7a987f40-efd8-4238-b6af-55f995e4661a",
    "portfolio_id": "32e24b33-c112-4bad-aab5-6f0ac8310b68",
    "created_at": "2022-07-3T15:43:22.32Z",
    "updated_at": "2022-07-3T15:43:22.32Z",
    "last_rebalanced_at": “2022-07-10T11:40:13.01Z"
}

Deleting a subscription is as simple as calling the subscription endpoint with REST DELETE call.

DELETE https://broker-api.alpaca.markets/ /v1/beta/rebalancing/subscriptions/{subscription_id}

Rebalancing Runs

And last but not least - we have Rebalancing Runs!

A Rebalancing Run is a set of orders that will be sent for execution to achieve a goal (liquidating a specified amount to set it aside for withdrawal or doing a full rebalance to the target allocation. Instead of creating a portfolio, which does rebalancing on a drift band or calendar day, you can use rebalancing runs to set up one-time asset allocation based on a specified weight.

NOTE The determination of a run’s orders and the execution of a run take place during normal market hours.

You can initiate a rebalancing run with a target allocation of by making a REST POST call like the example below:

POST https://broker-api.alpaca.markets//v1/rebalancing/runs

Request Body

{
    "account_id": "7a987f40-efd8-4238-b6af-55f995e4661a",
    "type": "full_rebalance",
    "weights": [
        {
            "type": "asset",
            "symbol": "TSLA",
            "percent": "50"
        },
        {
            "type": "asset",
            "symbol": "AMZN",
            "percent": "35"
        },
        {
            "type": "asset",
            "symbol": "AAPL",
            "percent": "15"
        }
    ]
}

Sample Response

{
    "id": "0b311b07-91b4-4e9e-b2be-4b78f6fbbc2e",
    "type": "full_rebalance",
    "amount": null,
    "initiated_from": "api",
    "status": "QUEUED",
    "reason": null,
    "account_id": "7a987f40-efd8-4238-b6af-55f995e4661a",
    "weights": [
        {
            "type": "asset",
            "symbol": "TSLA",
            "percent": "50"
        },
        {
            "type": "asset",
            "symbol": "AMZN",
            "percent": "35"
        },
        {
            "type": "asset",
            "symbol": "AAPL",
            "percent": "15"
        }
    ],
    "orders": [],
    "completed_at": null,
    "canceled_at": null,
    "created_at": "2022-07-20T13:11:15.054438-07:00",
    "updated_at": "2022-07-20T13:11:15.054438-07:00"
}

You can view the rebalancing runs created by making a REST GET call to the following endpoint.

GET https://broker-api.alpaca.markets/ /v1/beta/rebalancing/runs/{id}

Deleting a rebalancing run subscription is similar to a REST DELETE call to the same endpoint.

DELETE https://broker-api.alpaca.markets/ /v1/beta/rebalancing/runs/{id}

The rebalancing run {id} will be the path parameter for both the calls, much similar to all the REST GET/DELETE calls we have seen previously.

Conclusion

With the Rebalancing API, it is now possible for investment advisors to seamlessly create custom portfolios specifying the particular cash, stock symbol, and their corresponding percentage weights, conditions, and triggers to be selected.

View our documentation for additional information. If you have any questions regarding Rebalancing API, please reach out to us at [email protected].

Happy Coding!

Please note that this article is for general informational purposes only. All examples are for illustrative purposes only. Alpaca does not recommend any specific securities, cryptocurrencies or investment strategies.

All investments involve risk and the past performance of a security, or financial product does not guarantee future results or returns.There is no guarantee that any investment strategy will be successful in achieving its investment objectives. Diversification does not ensure a profit or protection against a loss. There is always the potential of losing money when you invest in securities, or other financial products. Investors should consider their investment objectives and risks carefully before investing.

Brokerage services are provided by Alpaca Securities LLC ("Alpaca Securities"), member FINRA/SIPC, a wholly-owned subsidiary of AlpacaDB, Inc. Technology and services are offered by AlpacaDB, Inc.

This is not an offer, solicitation of an offer, or advice to buy or sell securities, or open a brokerage account in any jurisdiction where Alpaca Securities is not registered (Alpaca is registered only in the United States).