A really simple command line interface for automatically rebalancing your Interactive Brokers equity portfolio.

Trader Bee

A couple of years ago I demonstrated how to create an automated Alpaca stock portfolio rebalancer in R. That code eventually became my rblncr R package, which is available for anyone to use. It works pretty well, has good test coverage, and is super configurable - a weekly rebalancing demo is available to view here.

My plan was to extend rblncr to work with Interactive Brokers as well, since that’s where I actually keep all my holdings, but there were some limitations which made this hard to implement (see grumble below). In the end I created a python based command line interface to automatically rebalance an equity portfolio according to user defined portfolio weights. I removed all the configuration options and tried to make something that is focused on getting the job done as simply as possible.

This isn’t a tool for day traders. It is intended to be used by people who rebalance their portfolios infrequently - say, yearly or quarterly. And it aims to achieve that with as little effort from a human as possible.

If you want to just see the code, head over to the github repo for installation instructions. I’ll do a walkthough lower down in this article.

Grumbling about the IB API

In general, developing against the Interactive Brokers API is a really unpleasant experience. Their native API clients are pretty hard to use (at least, they are for me, a child of the RESTful era). The documentation is difficult to navigate and requires a server/app implementation which I barely understand. Thankfully, community libs like ib_async exist to repackage the native API into easy to use functions that a not-so-smart person (ahem) can use.

But! Interactive Brokers don’t actually provide a globally accessible endpoint for you to interact with. No, that would be waaay to easy. Their API is actually exposed via an Interactive Brokers application running on your machine. So it’s actually a way to programmatically interact with their native app, which you have to spin up and configure before you start trading.

But but! That application cannot run in headless mode. The only way to log in is to actually point and click and type in the login window. So you need a display to run it on. You can work around this by creating a virtual display and then running something like Openbox, but then you run into the next problem - how do you programmatically launch it, and get past the login screen? Well, the folks over at IBController make that somewhat easy by automating the point-and-click on the fake display to log in for you.

But but but! Paper login can be automated noninteractively if you navigate the swamp of despair above, but live accounts require 2fa via their app, so you can’t have your headless machine spin up on a cron job to trade periodically unless you are prepared to be near your phone to click ‘allow’ on their push notification whenever your bot wants to trade.

But but but but! If you get through all of the above, the API for paper runs on 4002 by default, but the port for live is port 4001, so you need conditional logic in your code to detect what kind of account you are interacting with and then sets the port accordingly!

It actually boggles my mind that this situation exists, but basically if you want to noninteractively interact with Interactive Brokers you need to set up a docker container that runs an X11 display, which you can launch their native app on via a bash script provided by an IBController bash script, using credentials that you pass in via a mounted config file or environment args. Thankfully, I have already done this, and I maintain a headless Interactive Brokers container image at ib-headless.

Bonus: It periodically checks for new API releases from the Interactive Brokers website, and, if there is a new one, it builds a new image and tags it as a new release!

So, to get an interactive brokers API running on your machine, simply run the following command. If it’s a live account, you’ll need to click allow in your 2FA IB app on your phone. It always exposes the API on port 4003.

docker run -it --rm --name broker  -p 4003:4003 -e USERNAME=ibuser -e PASSWORD=ibpasswd -e TRADINGMODE={paper|live} ghcr.io/riazarbi/ib-headless:10.30.1t

Get to the walkthrough already

iblncr is a command line interface that can be installed via pipx. I have tested it on MacOS, and I’m pretty sure it will work fine on Linux. I wouldn’t be surprised if it also works on Windows - I’m not using any platform specific code.

It’s just a python module under the hood, so you can also pip install it and integrate the underlying functions into your existing code.

If you want to use iblncr to launch a headless IB gateway (you don’t need to, you could also just your existing Trader Workstation if you have it installed), you’ll also need a container runtime like podman or docker.

pipx install git+https://github.com/riazarbi/iblncr.git

There are two main commands.

iblncr-py3.13riaz@Riazs-MBP % iblncr --help
Usage: iblncr [OPTIONS] COMMAND [ARGS]...

  Interactive Brokers Portfolio Rebalancer

Options:
  -h, --help  Show this message and exit.

Commands:
  launch     Launch the IB Gateway Docker container
  rebalance  Run the portfolio rebalancer

`iblncr launch`

This will launch a headless Interactive Brokers Gateway container (called broker) which exposes the API at port 4003. When the container spins up it will ask you for your account type, IB username, and IB password. It will then handle the login behind the scenes. If it’s a live account you can expect a 2FA prompt that you’ll need to approve.

The container will be run in interactive mode, so you’ll get a lot of logging to your terminal - this is the IBController logging, and can be helpful if the login fails.

Leave this terminal window open while you are rebalancing. To shut down just CTRL-C to shut down the container gracefully. The nice thing about this being in a container is that if any of the many moving parts lock up and the gateway launch fails, you can just stop and remove the container and launch again. It also means that you won’t clutter up your filesystem with Java jars and config.ini files all over the place.

`iblncr rebalance`

The rebalancer is designed to be noninteractive if you give it all the information it needs, and interactive if you don’t.

Obviously you need to have an API running before running the rebalancer. In my typical workflow, I will launch in one terminal window and then rebalance in a new window.

The rebalancer needs some information to rebalance your portfolio. In particular, it needs to know what port the API is on, what IB account you are rebalancing, and what you want the portfolio holdings to be. If you provide none of that information, it will default to port 4003, and try and guide you in the right direction to provide the rest of the information.

Here is a typical workflow if you provide no information. I’ll use my paper account as an example.

1. No API gateway running

riaz@Riazs-MacBook-Pro % iblncr rebalance
API connection failed: ConnectionRefusedError(61, "Connect call failed ('127.0.0.1', 4003)")
Make sure API port on TWS/IBG is open
Error getting accounts: [Errno 61] Connect call failed ('127.0.0.1', 4003)
API connection failed: ConnectionRefusedError(61, "Connect call failed ('127.0.0.1', 4003)")
Make sure API port on TWS/IBG is open
[Errno 61] Connect call failed ('127.0.0.1', 4003)

2. No account ID provided

riaz@Riazs-MacBook-Pro blog % iblncr rebalance
executions request timed out
Account ID not specified. Please specify one of the following accounts: ['DU1144545']

3. No model file provided

riaz@Riazs-MacBook-Pro % iblncr rebalance --account DU1144545
Error: Model file is required. Would you like to create one?
Enter 'y' to create a new model, or 'n' to exit: y
Saving model to model.yaml
NOTE: Saved model.yaml has all default percentage allocations set to 0%
You must edit this file to set your own percentage allocations

The model file generates will include all the holdings that are currently in your portfolio. You can open up the file and specify the percentage weights you want. You can remove entries, and you can add new ones.

name: generated_portfolio
description: Generated from portfolio state
cash:
  percent: 5
positions:
- symbol: GOOG
  exchange: SMART
  currency: USD
  percent: 30
- symbol: VT
  exchange: SMART
  currency: USD
  percent: 30
- symbol: INTC
  exchange: SMART
  currency: USD
  percent: 30
tolerance:
  percent: 10
cooldown:
  days: 365
buy_only: false
created_at: '2025-03-06T08:32:35.787733'
updated_at: '2025-03-06T08:32:35.787747'

4. All required information provided

Here’s an example of a command where all the required parameters are provided.

riaz@Riazs-MacBook-Pro % iblncr rebalance --account DU1144545 --model model.yaml

The rebalancing procedure will:

Get your desired portfolio weights from the model.yaml file
Get your current holdings from the API
Work out how the holdings need to change
Constrain the orders to smaller chunks (I’ve set the max trade size to USD10000, but it’s easy to change)
Price the orders by splitting the spread, and ONLY if the spread is below 2%
Submit the orders to the API
Wait 60 seconds
Cancel any open orders
Repeat

The procedure is not fast, but it’s not slow either. It’s mostly slowed down by frequent interactions with the API - we treat Interactive Brokers as the keeper of our account state, and the state of the world, so we repeatedly query the API to get the state of our holdings, stock prices, or our order statuses. It works most of the time, and when it doesn’t work, it gives up rather than trying to be smart and potentially making the situation worse.

It’s also slow because I’ve avoided using realtime market data. It’s quite simple to use realtime market data (just modify the marketDataType in connection.py), but then you’d need to be subscribed to realtime market data - which costs money. And if you are only rebalancing every quarter or every year, do you really need to be paying for realtime market data? A 15 minute delay works just fine for me. I find that taking a 20 min walk is the best way to rebalance my portfolio.

Each ‘run’ probably takes about 2 minutes, including the 60 second wait, and prints the output to a cleared terminal window. Here is what the terminal window looks like for a single run. You get a printout of your positions before the orders are submitted, a chart that shows how your trackig error changes across each run, and a printout of the orders submitted for the current run.

Loading portfolio model from model.yaml
Fetching current portfolio state
Calculating portfolio targets
Pricing portfolio
Solving portfolio optimization

Portfolio Positions:
  symbol      conid  percent_held  percent_target  position  position_target  percent_deviation   price  optimal_order  optimal_order_value  out_of_band
0     VT   52197301          49.9              50      5039             5048                0.2  120.38              9              1083.42        False
1   TSLA   76792991          15.1              15       658              653                0.7  279.10             -5             -1395.50        False
2   GOOG  208813720          29.9              30      2074             2083                0.5  174.99              9              1574.91        False

Portfolio Cash:
  currency  percent_held  percent_target  position  position_target  percent_deviation  price  optimal_value  out_of_band
0      USD           5.1               5     62305            60773           2.519491      1       61042.21        False

Tracking error over time (lower is better):
(Tracking Error %) ^
       101 |
94.2666667 | ⡇⠀⠀⠀⠀⠀⠘⠛⠛⠛⠛⠛⠛⠛⠛⠛⠛⠛⠛⠛⠛⠛⠛⠛⠛⠛⢻⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
87.5333333 | ⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
80.8000000 | ⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
74.0666667 | ⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
67.3333333 | ⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
60.6000000 | ⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
53.8666667 | ⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
47.1333333 | ⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀
40.4000000 | ⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠀⠀
33.6666667 | ⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⠀⠀⠀⠀
26.9333333 | ⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠀
20.2000000 | ⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⠀⠀⠀
13.4666667 | ⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀
6.73333333 | ⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⠀⠀
         0 | ⣇⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣸⣀⣀⣀⣀⣀⣀
-----------|-|---------|---------|---------|---------|-> (Run)
           | 0         1.5000000 3         4.5000000 6        

Legend:
-------
⠤⠤ VT (deviation: 0.2%)
⠤⠤ TSLA (deviation: 0.7%)
⠤⠤ GOOG (deviation: 0.5%)
⠤⠤ VWRA (deviation: 100.0%)
⠤⠤ USD (deviation: 2.52%)


Portfolio weights are within tolerance. Exiting

Filled Orders:
                                            contract                                          execution                                   commissionReport                      time
0  Stock(conId=375855577, symbol='VWRA', right='?...  Execution(execId='0000e859.67c93188.01.01', ti...  CommissionReport(execId='0000e859.67c93188.01.... 2025-03-06 08:57:24+00:00
1  Stock(conId=375855577, symbol='VWRA', right='?...  Execution(execId='0000e859.67c9318b.01.01', ti...  CommissionReport(execId='0000e859.67c9318b.01.... 2025-03-06 08:57:35+00:00


End of run #5 ----------------------------------

If the tracking error drops to below the tolerance threshold for all positions, OR it does not change for 10 consecutive runs, the application exits.

What this achieves

Mostly, this exists because it allows me to not do things. It automates tedium out of my life.

I now do not have to:

Install IB software on my machine
Manually launch and click and point to get the application running
Copy out my holdings to some spreadsheet to work out the portfolio balance
Create spreadsheet formulae to work out how I need to change my holdings to get into balance
Go and get price data, enter it into the right cells, work out the orders
Manually enter the orders
Monitor the orders
Repeat (5-7) if orders fail

and it probably does it better than I would because ot’s doing smart things like chunking the orders for dollar cost averaging, splitting the spread, making sure spreads are tight etc.

Caveat Emptor

This shouldn’t come as a surprise, but I have made this for my own personal use. You are welcome to try it out at your own risk. This is not a product. It comes with no guarantees that it behaves as expected.

The project will evolve as I uncover edge cases. I’m not sure how this works with other currencies. Or logins that have multiple accounts associated with them. Or holdings across exchanges (especially when the trading times don’t overlap). That’s why I’ve set it up to fail rather than try heal if things start to go awry - better to get a human to go fix things if I hit an edge case.

Possiblities

Back when I made rblncr, I thought I would be able to run a rebalancer via github actions weekly and basically have my own robotrader. The 2FA requirement means I won’t do that - I’ll just run this every quarter in the background while I check my emails or something. I am a simple investor, who basically just wants to keep the weights between my two or three ETFs in balance.

I think the most exciting possibilities that this tool opens up are around programmatic manipulation of the target portfolio. You could write code to alter your model.yaml weights (or holdings) depending on conditions in the real world. As an example, I have a conviction that BRK B (Berkshire Hathaway) is cheap under a Price to Book Value of 1.2, and expensive above a Price to Book Value of 1.5.

I could write a model.yaml modification script that goes and gets the current BRK B P/B from some free stock data site, and specify my BRK B holding to be 70% if P/B is under 1.2, 50% if it’s between 1.2 and 1.5, and 30% if it’s above 1.5. I only have to write that code once.

As another example, there’s this investment principle that you should slowly rotate from stocks into bonds as you get older. This is because your investment horizon shortens as you age, and your tolerance for volatility diminishes. A useful rule of thumb is that the bond percentage of your portfolio should equal your age. So, at 20, put 20% in bonds. At 40, 40% etc. People frequently fail to follow this rule simply because it is tedious. It’s pretty easy to leverage iblncr to do this automatically. Just alter the percentages in your model. Or, if you are worried you’ll forget about the rule, write a bash script that modifies the yaml for you (your birthday will never change) and then rebalances directly afterwards.For ever after, you just need to run yout rebalancer every quarter and your portfolio will dynamically adjust accordingly. I think that’s very powerful.