Questrade Portfolio Balancer

A CLI tool that calculates buy orders to rebalance Questrade accounts toward target portfolio allocations.

Features

• Connects to Questrade API to fetch account balances and positions
• Calculates recommended buy orders based on target percentages
• Supports multiple accounts with different target allocations
• Buy-only rebalancing (no sell orders)
• Rounds down to whole shares
• Warns about positions not defined in configuration

Installation

bun install

Configuration

Environment Variables (.env)

Copy .env.example to .env and configure:

QUESTRADE_REFRESH_TOKEN=your_initial_token_here

Variable	Description
QUESTRADE_REFRESH_TOKEN	Your Questrade API refresh token. Obtain this from the Questrade API portal.

Note: The refresh token is automatically updated after each successful connection. The new token is saved to .questrade-token (gitignored) and will be used for subsequent runs.

Account Configuration (accounts.json)

Copy accounts.json.example to accounts.json and configure your accounts:

[
    {
        "accountNumber": "12345678",
        "symbols": [
            {
                "symbol": "VFV.TO",
                "percentage": 40
            },
            {
                "symbol": "XIC.TO",
                "percentage": 30
            },
            {
                "symbol": "XEF.TO",
                "percentage": 20
            },
            {
                "symbol": "ZAG.TO",
                "percentage": 10
            }
        ]
    }
]

Field	Description
accountNumber	Your Questrade account number (string)
symbols	Array of target allocations for this account
symbols[].symbol	Stock or ETF ticker symbol (e.g., "VFV.TO")
symbols[].percentage	Target percentage allocation (must sum to 100 per account)

You can define multiple accounts with different target allocations. Each account's percentages must sum to exactly 100%.

Usage

bun go

The tool will:

1. Connect to Questrade using your refresh token
2. For each configured account:
   • Fetch current cash balance and positions
   • Calculate the total portfolio value (cash + holdings in config)
   • Determine buy orders needed to reach target allocations
   • Display recommended trades

Output Example

=== Account: 12345678 ===

Portfolio Summary:
  Cash:              $5,000.00
  Config Holdings:   $3,000.00
  Total Portfolio:   $8,000.00

Current Allocation:
Symbol      Current Value    Current%     Target%  Difference
VFV.TO         $1,500.00       18.8%       40.0%      -21.2%
XIC.TO         $1,000.00       12.5%       30.0%      -17.5%
XEF.TO           $500.00        6.3%       20.0%      -13.7%
ZAG.TO             $0.00        0.0%       10.0%      -10.0%

Recommended Buys:
Symbol         Shares      Est. Cost      New Value      New%
VFV.TO             12      $1,584.00      $3,084.00     38.6%
XIC.TO             28        $980.00      $1,980.00     24.8%
XEF.TO             22        $770.00      $1,270.00     15.9%
ZAG.TO             44        $660.00        $660.00      8.3%

Total Investment: $3,994.00
Remaining Cash: $1,006.00

How It Works

1. Portfolio Calculation: The tool calculates your total portfolio value as the sum of available cash plus the current value of any holdings that match symbols in your configuration. Holdings not in your configuration are ignored (with a warning).

2. Target Allocation: For each symbol, it calculates the target value based on your percentage allocation and the total portfolio value.

3. Buy Calculation: It determines how many whole shares to buy to move toward the target allocation. Shares are always rounded down to avoid exceeding available cash.

4. Cash Limit: If the calculated buys would exceed available cash, all buy amounts are proportionally reduced.

Testing

bun test

Notes

• This tool only calculates buy orders. It will never recommend selling positions.
• Positions held in your account that are not defined in your configuration are excluded from portfolio calculations.
• All calculations assume CAD currency.
• The Questrade API refresh token becomes invalid after each use. The tool automatically saves the new token for subsequent runs.