Part of a series on building Balance, a portfolio rebalancing app for BR/US/Crypto
investors, as a solo developer. Code in this article is simplified from the real service.

Every investor who makes recurring contributions hits the same wall:

"I have $1,000 to invest this month. What do I buy so my portfolio stays close to my target allocation?"

The textbook answer — "sell what's overweight, buy what's underweight" — has a cost: taxes, brokerage fees, and the emotional discipline to sell things that are going up. There's a gentler approach that most people never formalize: rebalance using only the new deposit.

This is the core algorithm behind Balance. Let's build it.

The idea in one example

Say your target allocation is:

This month, after some price moves, you're actually at 46% stocks and 16% REITs. Stocks are overweight, REITs underweight.

Instead of selling stocks (and triggering a taxable event), you point this month's entire deposit at the underweight categories. The portfolio converges toward target without a single sale.

The algorithm

The whole thing is: figure out how far each category is from where it should be after the deposit, then distribute the deposit proportionally to those gaps.

from collections import defaultdict
from decimal import Decimal

def calculate(self, deposit_amount: Decimal) -> dict:
    deposit = Decimal(deposit_amount).quantize(Decimal('0.01'))

    investments = self._category_investments()   # {category_id: [(kind, item), ...]}
    current_total = self.portfolio.total_value
    new_total = current_total + deposit

    # 1. Current value held in each category
    cat_value = defaultdict(lambda: Decimal('0'))
    for cat_id, rows in investments.items():
        for kind, item in rows:
            cat_value[cat_id] += item.current_value

    # 2. Gap = how much each category is BELOW its post-deposit target
    gaps = {}
    for cat_id, rows in investments.items():
        category = rows[0][1].category
        target_value = new_total * category.target_percentage / Decimal('100')
        gaps[cat_id] = max(Decimal('0'), target_value - cat_value[cat_id])

    total_gap = sum(gaps.values())

    # 3. Split the deposit across categories, proportional to each gap
    cat_budget = {
        cat_id: (deposit * gaps[cat_id] / total_gap).quantize(Decimal('0.01'))
        for cat_id in investments
    }
    ...

Three steps:

1. Value per category — sum what you currently hold in each.
2. Gap per category — max(0, target − current). Categories already at or above target get a gap of zero; they receive nothing.
3. Budget per category — distribute the deposit proportionally to the gaps.

The max(Decimal('0'), ...) is the whole trick: overweight categories simply don't compete for the deposit. The money flows to where it's needed.

Edge case: if every category is already at or above target (total_gap == 0), there's no deficit to fill. We fall back to splitting the deposit by target weight, so the new money keeps the existing allocation rather than dividing by zero.

From budget to actual orders

A budget per category isn't an order yet — you can't buy 3.7 shares of a stock. So each category's budget is divided among its assets and turned into whole-share quantities:

def _buy_suggestion(self, kind, item, budget: Decimal):
    if budget <= 0:
        return None

    if self.portfolio.market == 'CRYPTO':
        quantity = (budget / item.current_price).quantize(Decimal('0.00000001'))
    else:
        quantity = int(budget / item.current_price)   # whole shares only

    if quantity <= 0:
        return None
    cost = (quantity * item.current_price).quantize(Decimal('0.01'))
    return self._asset_suggestion_row(item, quantity, cost)

Note the market branch: stocks buy whole units (int()), crypto buys fractions down to 8 decimal places. That single if is what lets the same engine serve a stock portfolio and a Bitcoin portfolio. (A whole article on that decision is coming later in the series.)

The leftover problem

Rounding to whole shares leaves money on the table. Buy int(500 / 140) = 3 shares at $140 and you've spent $420 — $80 of the deposit is unallocated.

So there's a second pass that spends the remainder, greedily, on whichever category still has the largest deficit:

while remaining > 0:
    # pick the category furthest below target that we can still afford
    best_item = max(
        affordable_items,
        key=lambda it: target(it) - simulated_value[it.category_id],
        default=None,
    )
    if best_item is None:
        break
    # buy one more share (or, for crypto, spend all the remainder as a fraction)
    ...

For stocks this buys one extra share at a time until nothing affordable is left. For crypto it just dumps the remainder into the most-underweight asset as a fraction. Either way, the deposit gets fully deployed instead of leaving idle cash.

Optional: rebalance with sales (and dodge the tax)

Sometimes a deposit isn't enough — a category is so overweight that no realistic contribution will fix it. For those cases the service can optionally suggest sales too, with a twist specific to Brazilian tax law:

if avoid_ir_sells and _is_always_taxed(ticker):
    continue   # never suggest selling an always-taxed asset (ETFs/REITs)

In Brazil, stock sales up to R$20k/month are tax-exempt, but ETFs and REITs (tickers ending in 11) are always taxed. The avoid_ir_sells flag tells the engine to rebalance by selling only the tax-exempt stuff, leaving the taxable assets untouched. The same calculation, made tax-aware.

Why this became the product

The math here isn't fancy — it's proportional distribution with a couple of guards. But wrapped in a UI that fetches live prices, knows your targets, and respects tax rules, it answers a question that real investors ask every single month and currently solve with a spreadsheet and a guess.

That's the lesson I keep relearning building Balance: the valuable part is rarely the algorithm. It's removing the friction around it.

Balance is a portfolio rebalancing tool for BR/US/Crypto investors — it tells you what to buy with your next deposit to stay on target. If you make recurring contributions and want to try it, the link is in my profile. Questions about the approach? Drop them in the comments.