From a shoebox of exports to one trustworthy Bitcoin ledger.

One owner. Many accounts. One ledger.

utxoproof is not a wallet and it is not a bank. It is a local reconciliation tool: you describe one taxpayer and the places value lived, and it builds a reproducible graph from those sources.

Take inventory before you touch the tool.

With a lot of data, the dangerous move is opening every export at once. First sort what you have into three piles: chain ownership, fiat/trade evidence, and human evidence. Then map each pile to one account kind.

Write the inventory down

Make a simple text note before creating folders. For each account, write the id, kind, what source file is authoritative, and which years it covers. This takes ten minutes and saves hours when a parser disagrees with a statement.

# inventory.txt — keep it next to your own notes, not inside input/
ledger-main    wallet       Sparrow export, 2019–2025
sparrow-savings wallet      Sparrow export, 2021–2025
kbc-checking   bank         KBC CSV statements, 2018–2025
kbc-visa       credit_card  KBC card statements, 2018–2025
kraken         exchange     Kraken ledgers + trades, 2018–2025
degiro         broker       holdings screenshot, as of 2025-12-31

The ids above are examples. Use stable, lowercase, URL-safe ids; they become page URLs and account references in reports.

Create a workspace that cannot contaminate itself.

Keep the code checkout, the source data and the generated output mentally separate. In practice, one data root can hold both input/ and generated output, as long as the generated files are never inside input/.

~/utxoproof-data/                  # one root, outside the git checkout
├── input/                         # source of truth — back this up
│   ├── utxoproof.toml
│   └── accounts/
│       ├── ledger-main/
│       │   ├── account.toml
│       │   ├── receive.txt
│       │   ├── change.txt
│       │   └── labels.jsonl
│       ├── kbc-checking/
│       │   ├── account.toml
│       │   └── statements/2023/*.csv
│       ├── kraken/
│       │   ├── account.toml
│       │   ├── ledgers.csv
│       │   └── trades.csv
│       └── degiro/
│           └── account.toml
├── utxoproof.db                   # generated, reproducible
├── imports/                       # generated intermediates
├── reports/                       # static HTML dashboard + tax report
└── evidence/                      # attachments — back this up too

$ export UTXOPROOF_DATA_DIR=~/utxoproof-data
$ mkdir -p "$UTXOPROOF_DATA_DIR/input/accounts"

$ cp utxoproof.example.toml "$UTXOPROOF_DATA_DIR/input/utxoproof.toml"
$ $EDITOR "$UTXOPROOF_DATA_DIR/input/utxoproof.toml"

[owner]
name = "Your name"

[chain]
backend = "electrum"
network = "mainnet"
electrum_url = "ssl://127.0.0.1:50002"
electrum_ca_file = ""

[reporting]
tax_year = "2023"       # or leave empty and use --year

[taxpayer]
communal_surcharge_rate = 0.07  # Brussels 0.0587 · Ghent 0.076 · Antwerp 0.08

Build the owner map, one folder at a time.

Each folder under input/accounts/ is one account. The folder name is the default id; the manifest inside is the source of truth. There is no central account list to keep in sync.

Four manifests to copy

# accounts/ledger-main/account.toml
kind = "wallet"
label = "Ledger main"
network = "mainnet"
gap_limit = 200
descriptor_receive_file = "receive.txt"
descriptor_change_file = "change.txt"
labels_file = "labels.jsonl"
tags = ["cold-storage"]

# accounts/sparrow-savings/account.toml
kind = "wallet"
label = "Sparrow savings"
network = "mainnet"
xpub = "zpub..."
fingerprint = "73c5da0a"
purpose = 84
gap_limit = 200

# accounts/kbc-checking/account.toml
kind = "bank"
label = "KBC checking"
profile = "kbc-bankaccount"
currency = "EUR"
[[balances]]
amount_eur = "12500.00"
as_of = "2023-12-31"
note = "Closing balance"

# accounts/kraken/account.toml
kind = "exchange"
label = "Kraken"
exchange = "kraken"
ledgers = ["ledgers.csv"]
trades = ["trades.csv"]

# accounts/degiro/account.toml
kind = "broker"
label = "DEGIRO"
[[holdings]]
symbol = "IWDA"
quantity = "25"
value_eur = "2125.00"

The id = "..." key can override the folder name. Use it only when the folder name cannot be stable. Tags are optional and inherited by every holding of that account.

Load the chain side: descriptors, not addresses.

A list of addresses is not an ownership model. Export the wallet descriptor from Sparrow, Bitcoin Core or your signer, and let utxoproof derive and register every script for the account.

Connect Electrum

Electrum is the primary chain backend. Bitcoin Core remains optional for diagnosis or fallback. Put the endpoint in input/utxoproof.toml:

[chain]
backend = "electrum"
network = "mainnet"
electrum_url = "ssl://127.0.0.1:50002"
electrum_ca_file = ""          # path to your server's CA, if private

BIP329 labels

Put a Sparrow/Electrum labels.jsonl in the wallet folder. Supported label types are tx, addr, output and input. Imported labels are replaced on re-import; user labels survive. A label is shown beside the output in account and provenance pages — that is all it does.

$ utxoproof label --account ledger-main --type output \
    --ref <txid>:0 --label "cold storage"

Load the fiat side without confusing evidence with tax input.

Banks, cards, exchanges and brokers each tell a different part of the story. The most important distinction: bank rows are evidence for fiat-leg review, while exchange trades feed the BTC cost-basis pool.

Bank and credit-card accounts

Put statement CSVs under the account folder and set the matching profile. The default pattern is statements/**/*.csv; you can set statements explicitly if your export layout differs.

# accounts/kbc-checking/account.toml
kind = "bank"
label = "KBC checking"
profile = "kbc-bankaccount"
currency = "EUR"
[[balances]]
amount_eur = "12500.00"
as_of = "2023-12-31"
note = "Closing balance"

# accounts/kbc-visa/account.toml
kind = "credit_card"
label = "KBC Visa"
profile = "kbc-creditcard"
currency = "EUR"
[[balances]]
amount_eur = "-420.00"       # owed, not an asset
as_of = "2023-12-31"

The current bank profiles cover common Belgian exports, including KBC bank and card. Other shapes are best-effort: inspect the first converted rows in the bank review page before trusting a full year. Non-EUR rows without a rate abort the parse rather than guessing.

Kraken: two files, one account

Export ledgers.csv and trades.csv for the full period and keep them together. The ledger records movements; the trades file supplies execution prices and margin flags. The runner merges them into imports/manual.csv and the tax report.

# accounts/kraken/account.toml
kind = "exchange"
label = "Kraken"
exchange = "kraken"
ledgers = ["ledgers.csv"]
trades = ["trades.csv"]

Broker accounts are informational

Broker holdings show up in the owner overview so the picture is complete. They do not enter BTC cost basis, disposal math, KYC propagation or the Belgian Bitcoin classifier. Belgian stock-tax rules are not implemented; keep broker statements as evidence and treat the page as a reminder, not a tax calculation.

Validate the tree before you sync.

discover reads every manifest, derives scripts, parses statements and labels, checks for duplicate ownership, and writes nothing. This is where you want to find the typo — not after a two-hour sync.

$ utxoproof discover --input ~/utxoproof-data/input

$ utxoproof discover --input ~/utxoproof-data/input --json

$ utxoproof discover --input ~/utxoproof-data/input --online

$ utxoproof run --input ~/utxoproof-data/input \
    --data-dir ~/utxoproof-data --plan

Stop rules

Pilot one slice. Then scale in rings.

The high-volume failure mode is a big-bang import: ten wallets, eight years and five statement formats at once. Build one slice that exercises each code path, prove it end to end, and only then add the rest.

$ export UTXOPROOF_DATA_DIR=~/utxoproof-pilot
$ mkdir -p "$UTXOPROOF_DATA_DIR/input/accounts"

$ utxoproof discover --input "$UTXOPROOF_DATA_DIR/input"
$ utxoproof run --input "$UTXOPROOF_DATA_DIR/input" \
    --data-dir "$UTXOPROOF_DATA_DIR" --offline --no-zip

$ utxoproof discover --input "$UTXOPROOF_DATA_DIR/input" --online
$ utxoproof run --input "$UTXOPROOF_DATA_DIR/input" \
    --data-dir "$UTXOPROOF_DATA_DIR" --no-zip
$ utxoproof reconcile --input "$UTXOPROOF_DATA_DIR/input" \
    --db "$UTXOPROOF_DATA_DIR/utxoproof.db"

$ utxoproof run --input "$UTXOPROOF_DATA_DIR/input" \
    --data-dir "$UTXOPROOF_DATA_DIR" --only labels,sync,portfolio

The full run: one command, one data directory.

Once the tree validates and the pilot reconciles, run the real thing. The command is idempotent: it imports labels, syncs wallets, parses statements, builds the tax report and renders the account dashboard.

$ utxoproof discover --input ~/utxoproof-data/input --online
$ utxoproof run --input ~/utxoproof-data/input \
    --data-dir ~/utxoproof-data --year 2023

Use --no-zip while iterating; drop it for the run you intend to archive. Use --price or --as-of only when you deliberately want an override; otherwise the bundled daily price history is used offline.

What the run writes

Reconcile, review, and only then file.

A report is not done because it renders. It is done when the on-chain balances reconcile to the server and the numbers agree with your own arithmetic for the year.

$ utxoproof reconcile --input ~/utxoproof-data/input \
    --db ~/utxoproof-data/utxoproof.db

The expected result is RECONCILED (gap 0). A nonzero gap means stop. Rerun sync, then --force-rescan, then check that the descriptor, network and Electrum endpoint all match the wallet. Reconcile compares DB-owned unspent outputs against the server's scripthash balances, so a silent missed spend shows up here.

The previews below open the synthetic demo, not real holdings. They show the shape of each page; your text and figures will differ.

Evidence: the part a reviewer opens

The year ZIP contains the account-folder sources, merged intermediates, attachments, the report and a hash manifest. The root input/utxoproof.toml is deliberately excluded because it may contain RPC credentials. Open the ZIP once yourself, verify manifest.json, and check that the source paths are the ones you expect.

$ utxoproof attach --file ~/withdrawal-mail.png \
    --tx <txid> --note "Kraken withdrawal confirmation" --year 2023
$ utxoproof attach --file ~/annual-statement.pdf \
    --note "Bank 2023 totals"

Attachments are content-hashed and stored under data/evidence/; originals stay untouched. Re-attaching identical content is a no-op. This is also why evidence/ belongs in your backup, while the DB can be rebuilt.

Scaling playbook for a lot of data.

The tool is built for one owner with many accounts and many years. These are the habits that keep a large archive reproducible instead of fragile.

Honest limits, before you trust a number.

A good guide says what the tool does not do. These are current boundaries, not aspirations.

Troubleshooting the usual suspects.

The printable checklist.

Work top to bottom. Stop at any failed checkpoint. The goal is not to finish the archive today; it is to make the next run boring.

Workspace

• Code and data are separate. The data root is outside the git checkout; UTXOPROOF_DATA_DIR points there.
• Fresh data dir. No old v7 DB, no experiments. A rollback is one folder delete.
• Config reviewed. Owner, chain backend, reporting year and communal surcharge are intentional.
• Backup plan. input/ and evidence/ are backed up encrypted; a restore was tested.

Input tree

• One folder per account. Ids are stable, lowercase and URL-safe.
• Wallets are watch-only. No seed phrases, no private keys, no xprv.
• Descriptors are complete. Receive and change match; multisig includes all cosigners.
• Labels are BIP329 JSONL in the wallet folder and scoped to that account.
• Bank/card statements are under statements/ and the profile matches the export.
• Kraken has both ledgers and trades. All years are present; refids are unique.
• Broker holdings are informational. They are not expected in the BTC tax math.

Validate, pilot, file

• discover offline is clean. Zero errors and no duplicate scripts.
• discover --online reaches the backend. The network and endpoint are right.
• run --plan is expected. The steps and selected actions match your intent.
• Pilot offline run is sane. The report and imports make sense without chain data.
• Pilot live run reconciles. reconcile says gap 0.
• Tax totals match your arithmetic. One year is independently checked before scaling.
• Full run includes the evidence ZIP. It opens; manifest.json verifies; root config is excluded.
• Reports reviewed. Overview, account pages, provenance and bank review are all inspected.
• Archive sealed. Report, full report, ZIP and a backup manifest are stored together.