Stock & ETF Cost-Basis Example — beancount.io

Stock & ETF Cost-Basis Example — beancount.io

A Beancount ledger demonstrating taxable brokerage accounting: one cash brokerage account holding two individual stocks and a broad-market ETF, bought in identifiable lots between 2024 and 2026.

The method rests on one idea — a share is not a number, it is a lot: a quantity held at a known cost acquired on a known date. Writing a purchase as 120 NWRB {41.80 USD, 2024-03-12} stores the basis with the position instead of in a spreadsheet beside it, so a later sale can name the exact lot it disposes of and Beancount computes the gain rather than trusting you to.

Everything else here is that one idea applied again. A reinvested dividend is a new lot at the reinvestment price. A share split is a rewrite that must preserve total basis and realize nothing. A year-end balance is a share count you can check against the broker's December statement.

The ledger sets option "booking_method" "STRICT", so a sale that does not identify its lot is an error rather than a guess. That refusal is the point: it is what makes the realized gains in this ledger reproducible.

Every issuer, ticker and price in this ledger is fictional. They are chosen to be plausible, never to describe a real security's market history.

Quick Start

make install   # Install beancount + fava via uv
make check     # Verify the ledger has zero errors
make serve     # Open Fava at http://localhost:4741

File Guide

Live prices (preview)

The prices in prices/2024-2026.bean are static and checked in. That is what makes this repository reproducible: clone it in two years and make check still produces the report it produces today. They are also unadjusted — the dates before NWRB's 4-for-1 split carry pre-split per-share prices, the dates from the split onward carry post-split ones, and nothing earlier is restated. The two directives straddling the split value the same holding at $7,440.00 on both sides of it.

A hosted beancount.io ledger will also be able to pull a managed price feed, with one line:

; include "https://beancount.io/prices/ACME-USD"

It ships commented out, and three things are worth knowing before you uncomment it in a ledger of your own:

1. A URL include resolves only inside a hosted beancount.io ledger. Nothing else reads it.
2. A local run does not fetch URLs. bean-check and bea check read files from disk, so that line fails locally with a "does not match any files" error — which is why this repository, meant to be cloned and run, ships static prices.
3. Prices never change quantities, cost basis or realized gains. However they arrive, they move market value and nothing else; every number in transactions/sales.bean is computed from the lots.

And the fact most worth having in advance: your own price directive always wins over a managed one for the same date and commodity pair, whatever the include order. A managed feed is a fallback for dates you have not priced yourself, never an override — so pinning a price you reconciled against a statement is simply a matter of writing it down.

The one thing to copy

A purchase stores its own basis:

2024-03-12 * "Broker" "Buy 120 NWRB @ $41.80"
  Assets:Brokerage:NWRB                    120 NWRB {41.80 USD, 2024-03-12}
  Expenses:Brokerage:Commissions          4.95 USD
  Assets:Brokerage:Cash               -5,020.95 USD

…and a sale names the lot it sells, so the gain and its holding period both follow from the entry rather than from a spreadsheet:

2026-02-20 * "Broker" "Sell 60 ACME from the 2024 lot — long-term gain"
  Assets:Brokerage:ACME                    -60 ACME {68.20 USD, 2024-06-18}
  Assets:Brokerage:Cash                  5,778.00 USD
  Expenses:Brokerage:Commissions             4.95 USD
  Assets:Brokerage:Cash                     -4.95 USD
  Income:CapitalGains:LongTerm          -1,686.00 USD

Nothing anywhere else in the ledger has to remember what those shares cost.

What the numbers come to

Running make check validates every year-end share count below, and bea report income-statement reproduces the realized results: