bankroll

Command line interface and notebook utilities to ingest portfolio and other data from multiple brokerages, and analyze it.

This is the frontend to the bankroll project, which is comprised of several libraries that can also be used on their own.

Table of contents:

1. Installation
2. Connecting to brokers
   1. Interactive Brokers
   2. Charles Schwab
   3. Fidelity
   4. Vanguard
   5. (your broker here)
3. Saving configuration
4. Extending bankroll

Installation

To install the bankroll command line utility, select from the list of available brokerage plugins, and run pip install with those brokerages listed as extras.

For example, to install bankroll with support for Interactive Brokers and Charles Schwab:

pip3 install bankroll[ibkr,schwab]

Or from the repository root, if you have cloned the code:

pip3 install .[ibkr,schwab,fidelity]

Once installed (and presuming your Python path is set up correctly), the command line tool can be invoked directly:

bankroll --help

Connecting to brokers

After being set up, bankroll can be used from the command line to bring together data from multiple brokerages.

For example, to show all positions held in both Interactive Brokers and Charles Schwab:

bankroll \
  --ibkr-tws-port 7496 \
  --schwab-positions ~/Positions-2019-01-01.CSV \
  --schwab-transactions ~/Transactions_20190101.CSV \
  positions

Run with --help to see all options:

bankroll --help

Interactive Brokers

Interactive Brokers (sometimes abbreviated as IB or IBKR) offers a well-supported API, which—along with ib_insync—makes it possible to load up-to-date portfolio data and request real-time information about particular securities.

For bankroll, this functionality is implemented via the bankroll-broker-ibkr plugin:

pip3 install bankroll[ibkr]

To load data from Interactive Brokers, one of IB's trading applications—Trader Workstation or IB Gateway—must be running and logged-in to accept API connections. You may wish to use IBC to automate the startup and login of these applications.

Once Trader Workstation or IB Gateway is running, and API connections are enabled, provide the local port number to bankroll like so:

bankroll \
  --ibkr-tws-port 7496 \
  [command]

Querying trade history

IB's Trader Workstation API does not support retrieving information about an account's historical trades, so bankroll must use their Flex Web Service.

To set this up, log in to Account Management, then browse to Settings → Account Settings in the sidebar:

In the Reporting section of this page, click the gear to configure Flex Web Service:

Once configured, copy the Current Token for use on the command line.

Then, you must save a query for bankroll to use. Back in the sidebar, browse to Reports → Flex Queries:

Click the gear to configure Custom Flex Queries:

Create a new Trade Confirmation Flex Query Template:

Pick a name of your choosing, then make sure the Date Period reflects the historical period you care about (e.g., Last 365 Calendar Days):

Under Sections, click Trade Confirmations and enable everything in the dialog which appears:

After saving your query, expand it in the list to view and copy the Query ID for use on the command line.

With the token and the query ID from your account, historical trades can be downloaded:

bankroll \
  --ibkr-flex-token [token] \
  --ibkr-trades [query ID] \
  activity

Querying dividend history

This workflow will be simplified in the future.

To incorporate the history of dividend payments in your portfolio, follow the same steps for the Trade Confirmation Flex Query, but create an Activity Flex Query instead.

The only section which needs to be enabled is Change in Dividend Accruals:

Pass your existing token, and the new query's ID, on the command line:

bankroll \
  --ibkr-flex-token [token] \
  --ibkr-activity [query ID] \
  activity

Charles Schwab

Charles Schwab does not offer an API, but it does provide CSV files for export, which bankroll can then import.

This functionality is implemented via the bankroll-broker-schwab plugin:

pip3 install bankroll[schwab]

Browse to the "Positions" and/or "Transactions" screen:

Click the "Export" link in the top-right:

Then provide the paths of either or both these downloaded files to bankroll:

bankroll \
  --schwab-positions ~/path/to/Positions.CSV \
  --schwab-transactions ~/path/to/Transactions.CSV \
  [command]

Fidelity

Fidelity is supported through a similar facility as Schwab.

This functionality is implemented via the bankroll-broker-fidelity plugin:

pip3 install bankroll[fidelity]

• To export position data, download from the Portfolio Positions page.
• To export transactions data, download from the History page.

More detailed instructions have yet to be written—contributions welcome!

Vanguard

Vanguard is a work in progress, and may not be as fully-featured as the other brokerages listed here. Support is being developed in the bankroll-broker-vanguard plugin:

(your broker here)

bankroll intends to abstract away broker-specific details as much as possible, to minimize the work required to support each one, so if your broker isn't listed above, please consider building a new brokerage plugin! We want the list to grow over time, because it's extremely useful to be able to aggregate and analyze data across multiple brokers at once.

To add a new brokerage, create a new subclass of AccountData, then implement the methods as required by the interface. As long as the new subclass is loaded at runtime, it will be automatically included in functionality like data aggregation.

If the brokerage offers a facility to load market data, consider extending the bankroll-marketdata interfaces as well (though this is optional).

Saving configuration

To preserve settings across runs, all of the command-line arguments demonstrated above can also be saved into an INI file. The configuration file is especially useful to store default values, because when a setting is specified in a configuration file as well as on the command line, the command-line argument will take precedence.

To create a configuration, copy bankroll.default.ini to ~/.bankroll.ini, or leave it in your working directory as bankroll.ini, then edit the file to apply your desired settings.

If you would like to store the configuration somewhere else, you can also provide custom paths via the --config argument on the command line.

Extending bankroll

Although the command-line interface exposes a basic set of functionality, it will never be able to capture the full set of possible use cases. For much greater flexibility, you can write Python code to use bankroll directly, and build on top of its APIs for your own purposes.

For some examples, see the included notebooks.