Beancount Tools Collection

🧮 My personal collection of beancount tools including importers, price fetchers, plugins, and utilities for various financial institutions.

Features

📥 Data Importers

Swiss Institutions:

• Yuh - CSV exports
• Viseca - JSON transaction exports (including Migros Cumulus Credit Card)
• VIAC - JSON transaction exports (pillar 2 & 3a)
• Finpension - CSV transaction reports (pillar 3a)

International Institutions:

• Interactive Brokers - FlexQuery XML reports (global); fetch/credential failures surface as errors in Fava and exit non-zero in the CLI (a genuinely empty statement still shows "No entries to import")
• Revolut - CSV exports (multi-country)

Other Formats:

• Firefly III - CSV exports

💰 Price Fetchers

• Interactive Brokers - Real-time prices from FlexQuery

🔌 Beancount Plugins

• Crickets chirping 🦗 - This section is as empty as my wallet after buying crypto at the peak

🛠️ Utility Scripts

• Transaction Processor - Example transaction processing with ImporterProtocolAdapter and TransactionInspector for automatic categorization and payee standardization

Installation

From PyPI

pip install beancount-tools-collection

From Source

git clone https://github.com/mekanics/beancount-tools-collection.git
cd beancount-tools-collection
pip install -e .

Quick Start

Basic Importer Configuration

from beancount_tools_collection.importers import (
    finpension, ibkr, revolut,
    viac, viseca, yuh
)

# Example configuration
CONFIG = [
    # Swiss institutions
    finpension.FinpensionImporter(
        root_account="Assets:Pension:S3:Finpension:Portfolio1",
        deposit_account="Assets:Checking",
        isin_lookup={
            "CH0132501898": "CH0132501898",  # Example ISIN mapping
            # ... more ISINs
        }
    ),

    viac.ViacImporter(
        root_account="Assets:Pension:S3a:Viac:Portfolio1",
        deposit_account="Assets:Checking",
        share_lookup={
            "UBS SMI": {"isin": "CH0033782431", "symbol": "CH0033782431"},
            # ... more share mappings
        }
    ),

    yuh.YuhImporter(
        account="Assets:Cash:Yuh:CHF",
        goals_base_account="Assets:Savings:Yuh"
    ),

    # International institutions
    ibkr.IBKRImporter(
        Mainaccount="Assets:Invest:InteractiveBrokers",
        DivAccount="Income:Dividends:InteractiveBrokers",
        WHTAccount="Expenses:Taxes:WithholdingTax",
        PnLAccount="Income:Invest:Gains",
        FeesAccount="Expenses:Invest:Fees",
        configFile="ibkr.yaml"  # Your IBKR FlexQuery config
    ),

    revolut.RevolutImporter(
        "revolut_chf",
        "Assets:Cash:Revolut:CHF",
        "CHF"
    ),
]

Price Fetcher Configuration

# In your beancount price configuration
from beancount_tools_collection.prices import ibkr

# The IBKR price source will be available for bean-price

Documentation

Importer-Specific Setup

Each importer has specific requirements and configuration options:

• Finpension - CSV transaction reports
• Interactive Brokers - FlexQuery configuration
• VIAC - JSON export setup
• Yuh - CSV export configuration

Account Structure Examples

The importers work best with structured account hierarchies:

Assets:
  Cash:
    Yuh:
      CHF
      USD
    Revolut:
      CHF
      EUR
  Invest:
    InteractiveBrokers:
      Long-Term:
        VTI
        VXUS
        USD
  Pension:
    S3a:
      Finpension:
        Portfolio1:
          CHF
      Viac:
        Portfolio1:
          CH0132501898

Income:
  Dividends:
    InteractiveBrokers:
      Long-Term:
        USD
  Pension:
    S3a:
      Finpension:
        Portfolio1:
          Interest:
            CHF

Expenses:
  Invest:
    Fees:
      CHF
      USD
  Taxes:
    WithholdingTax

Notes

Interactive Brokers errors (v1.1.0+)

IBKR Flex fetch and credential failures (expired/invalid token, bad ibkr.yaml, network errors, unparseable statements) now raise typed errors instead of returning an empty entry list. In Fava this surfaces as an import/API error (rather than the yellow "No entries to import from this file." warning that used to appear on hard failures). The CLI exits non-zero with a short remediation message.

Exception messages, log lines, and raised tracebacks redact the Flex token (and do not chain secret-bearing upstream exceptions). If older logs were shared while a token was still live, rotate the token under Reports > Flex Web Service.

Contributing

We welcome contributions! Here's how you can help:

1. Add new importers for financial institutions
2. Improve existing importers with bug fixes and features
3. Add price fetchers for different data sources
4. Create plugins for common beancount workflows
5. Improve documentation and examples

Development Setup

git clone https://github.com/mekanics/beancount-tools-collection.git
cd beancount-tools-collection
pip install -e ".[dev]"

Running Tests

pytest

Code Formatting

black src/
isort src/

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• The beancount project for the excellent accounting framework
• Various open-source beancount importers that served as inspiration

Support

• 📖 Documentation
• 🐛 Bug Reports
• 💬 Discussions

Made with ❤️ for personal finance tracking