This tool comes with NO WARRANTY. It was developed to work with my investment portfolio and may not work with yours. I use to aid my investment decisions, but I closely monitor its output to make sure it doesn't do anything "weird". I never blindly do anything it says. You shouldn't either.
I invest in some of the Securities in the default database. If you choose to do so you should read and understand the prospectus of that Security. I am not recommending that you invest in any of them.
The default asset allocation is a high-risk, high-volatility one comprised of large percentages of US Stock, International Stock, and Long-term Bonds. Investing is a highly personal activity, and decisions should be carefully made based on your own personal financial situation and risk tolerance. The Bogleheads forum is a good place to start for general knowledge. For more specialized information better suited to your particular financial and tax situation, consult a professional Financial Advisor, CPA, or Tax Professional.
Rebalancer is a web-based service for managing an investment portfolio of index funds using the csv files generated by the Fidelity web interface. It was inspired by some of the concepts I learned about by lurking on the Bogleheads forum.
The central idea behind the program is that one has an investment portfolio with multiple securities each comprising a portion of the portfolio. This can be defined as a fixed percentage, a fixed amount, or a fixed percentage of the remainder in the event the sum of the fixed percentages and fixed amounts are less than 100% of the total portfolio value. Typically the latter option is used in portfolios with fixed amount allocations. As money flows into the portfolio, the tool is able to calculate which securities to buy to maintain these percentages. This tool additionally attempts to maintain a target ratio of securities within a broad grouping (eg. stocks, bonds). There are three main concepts the tool uses to maintain a portfolio: Securities, Asset Classes, and Asset Groups.
Securities are a stock or mutual fund/ETF share. They have a specific symbol with which they are traded on a public exchange.
An Asset Class is a broader classification for a Security. An example of an Asset Class is a US Total Stock Market Index Fund. A portfolio may have multiple Securities which map to an Asset Class (eg. a TSM mutual fund and TSM ETF). The tool treats Securities with the same Asset Class as functionally* equivalent and interchangeable. If one has individual stocks in their portfolio, each stock should have its own Asset Class as two stocks would not be considered functionally equivalent since they would not necessarily have similar performance characteristics.
* I have deliberately avoided using the term "substantially equivalent" as that is a term the IRS uses when defining a "wash sale". I make no claims as to whether or not two Securities of the same Asset Class meet the IRS definition of "substantially equivalent". That's between you and your CPA. This tool does not attempt to shield you from wash sales (or capital gains taxes in general)
An Asset Group is a broader classification for an Asset Class. An example of an Asset Group is a Stock or Bond. The tool computes a target ratio between Asset Groups based on the target percentages for each component Asset Class. The tool will attempt to maintain this target Asset Group ratio even if there is an imbalance in the component Asset Classes. For example, if a portfolio has multiple Bond Assets and one is below its target, the tool will de-prioritize a purchase of that Asset if the overall target percentage for Bond Assets is met.
These concepts are all basic to the Bogleheads investment philosophy, and the original version of rebalancer was a command line tool which managed my taxable investment portfolio. An advanced topic of portfolio management deals with placing assets in different accounts in such a way as to reduce one's tax burden. For example, bond dividends are non-qualified and are taxed as regular income. Thus it may* be preferable that bonds go into tax-advantaged accounts (IRA, 401(k)). Many stock index fund dividends are qualified and therefore are taxed at capital gains rates. Some stock index funds may never pay dividends. Thus it may be preferable that stocks go into taxable accounts.
* Consult your CPA or Tax Professional for advice which is most advantageous to your particular tax situation.
This tool allows one to classify each of their investment accounts with a specified Tax Group (eg. Tax-deferred, Taxable, Roth). They also can specify an "affinity" for each Asset Class, and the tool will attempt to place each Security into the account with the highest affinity.
This enables one to not think about a 401(k) or an IRA as a "retirement account" but a component of one's overall investment portfolio with different tax characteristics. When looking at a single account in isolation its composition may not make sense, but when looking at them all holistically it does.
For accounts which use ETF shares which unlike mutual funds do not allow fractional shares to be purchased, the tool will attempt to slightly adjust its recommendations to minimize the remaining balance in the sweep account.
The contents of the csv files are never saved. That is why any operation requires a separate upload. The tool does use a database to store the Tax Group and Description for each account as well as the target percentages for each Asset Class and the Tax Affinity for each Asset Class. The Description is encrypted in the database, and the account numbers are stored in such a way that it is not possible to retrieve them without having one of the csv files.
Operations also require a "token" which is a randomly generated number used as part of the encryption and scrambling process. Without this token the data in the database is irretrievable. With this token, one still needs a csv file with account numbers to access the data in the database. Although the "token" field will allow any value to be entered, it is highly recommended that a value from the "Get Token" link be used. The values returned by that link are randomly generated and never stored.
Each installation also uses a different system-level random number used to scramble certain fields in the database. This random number is not saved in the database, therefore a database cannot be shared between two installations unless this random number is shared.
Nevertheless, it is recommended one not put personally identifiable information in the database.
Clone or download the repository and run rebalance_server.py. The server will generate a file named ".salt" in the current working directory and a database file named "rebalance.db" in the "rebalancer" subdirectory.
It is not recommended that this software be installed in such a way that it accepts connections from the public internet. It was designed to be installed on a computer connected to a home network behind a firewall.
By default the server will bind to port 8090 and accept connections from localhost. This can be changed with the "--bind" and "--port" command line arguments, respectively. These connections are not encrypted with HTTPS, and the server does not support HTTPS. If HTTPS is desired, the recommended configuration is to configure the server to only accept local connections and use a program like stunnel to listen to outside connections on HTTPS and forward them. This configuration is outside the scope of this document but is how the author runs the program on his home network.
When accessing the site for the first time, it is highly recommended that a token be obtained using the "Get Token" link. Once a token is saved, input it into the "Token" field in the "Configure" section and select a csv file to upload. The tool will display a page with all the accounts and their underlying securities to allow a Tax Group and Description to be assigned. Select "Ignore" to have the tool skip over the account when performing its calculations.
The tool will also list out all the Asset Classes it found and allow target percentages to be assigned. The sum of these percentages must add up to 100. The tool also lists out each Asset Class under each Tax Group and allow Affinities to be set. If "Disable" is selected, the tool will not attempt to allocate that Asset Class into that Tax Group. A checkbox is also provided to disable the recommendation of the sale of assets in an Asset Class within a specified Tax Group. This can be useful to prevent the sale of assets which have not been held for at least a year, or to prevent wash sales, or for other individual situations.
Once everything is set up correctly, click the "Update Config" button to have the values save in the database.
Once configuration has completed, go back to the home page and enter a token and csv file under the "Rebalance" section. There are three rebalancing modes
- Rebalance without selling will only rebalance using funds in a sweep account (or credits specified in the "Credit" fields)
- Rebalance everything will rebalance all accounts using the target asset allocations and tax affinities configured earlier. This feature should be used with caution as it will recommend transactions they may completely change your investment portfolio and result in extremely high capital gains.
- Rebalance without selling in Taxable will rebalance the accounts in such a way that it will only recommend selling assets in tax-advantaged (ie. IRA, 401(k)) accounts. This is slightly safer than "Rebalance everything" but still should be used with caution as it too will recommend transactions that may completely change your portfolio.
Regardless of the mode selected, if you have disabled the sale of an Asset Class in the Configure page, it will not be recommended for sale.
The "Credit to taxable account" and "Credit to tax-deferred account" allow dollar amounts to be added to the sweep accounts of the taxable and tax-deferred accounts, respectively. This is useful to buy securities using funds which have not settled* yet, as the csv files only show settled funds in the sweep accounts. A side effect of this behavior is that, after a purchase is made, the sweep account entries in the csv file will show the funds which were used to make the purchase until that purchase settles. Negative credits can be used to compensate for this.
* Trading with unsettled funds can result in cash account trading violations and should be done with caution. Read and understand all warnings shown on the Fidelity site.