Table of Contents

FinTS Connector

Required Inputs
comdirect
Local State
Commands
TAN Handling
Ledger Mapping

Mirrored from /mnt/DATA/git/mousehold/docs/fints.md. Origin: repository. Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.

FinTS Connector

The FinTS connector can run embedded in the main API or in the separate local agent. Embedded mode is the default for local/self-hosted installs, so users do not need to start a second process.

The privacy tradeoff is explicit:

Embedded mode: the API process receives PIN/TAN inputs while a FinTS job runs.
Separate local-agent mode: PIN/TAN inputs stay in the separate local process.

In both modes, PINs are not stored in the database. Normalized observations are stored only when you import them.

Required Inputs

--blz or MOUSEHOLD_FINTS_BLZ: bank identifier/BLZ.
--server or MOUSEHOLD_FINTS_SERVER: FinTS endpoint URL.
--bank-user-id or MOUSEHOLD_FINTS_USER_ID: your bank login ID.
PIN: prompted interactively by default, or provided through MOUSEHOLD_FINTS_PIN.
--product-id or MOUSEHOLD_FINTS_PRODUCT_ID: required by python-fints 4+. Register a product ID with Deutsche Kreditwirtschaft/ZKA before connecting.
Optional --customer-id, --tan-medium, and --product-version.

comdirect

The web UI has a comdirect preset.

Current values:

BLZ: 20041111
FinTS endpoint: https://fints.comdirect.de/fints
Bank user ID: your comdirect Zugangsnummer
Customer ID: leave empty

If your account uses a different comdirect/Commerzbank GF comdirect BLZ, replace the preset BLZ before fetching accounts.

Local State

The connector stores non-PIN client state in:

~/.config/mousehold/fints/<profile>.json

This caches bank parameter data, selected TAN mechanism, and selected TAN medium so repeated syncs do not ask the same setup questions. The file is written with mode 0600.

Use --no-state for a one-off session without reading or writing that cache.

Commands

The browser UI uses the embedded API route by default:

http://127.0.0.1:8001/agent/fints/...

To use a separate local-agent HTTP bridge instead:

mousehold-agent serve --host 127.0.0.1 --port 8765

Then set VITE_LOCAL_AGENT_URL=http://127.0.0.1:8765 in apps/web/.env.development.

List accounts:

mousehold-agent fints-accounts \
  --profile my-bank \
  --blz <bank-blz> \
  --server <fints-endpoint-url> \
  --bank-user-id <bank-login-id> \
  --with-balances

Display transactions:

mousehold-agent fints-transactions \
  --profile my-bank \
  --blz <bank-blz> \
  --server <fints-endpoint-url> \
  --bank-user-id <bank-login-id> \
  --iban <iban> \
  --start-date 2026-06-01 \
  --end-date 2026-06-27

Sync transactions into Mousehold:

mousehold-agent sync-fints \
  --api-url http://127.0.0.1:8001 \
  --connection-id <connection-id> \
  --household-id <household-id> \
  --owner-user-id <user-id> \
  --source-account-id <account-id> \
  --profile my-bank \
  --blz <bank-blz> \
  --server <fints-endpoint-url> \
  --bank-user-id <bank-login-id> \
  --iban <iban> \
  --days 30 \
  --display

TAN Handling

If the bank returns a TAN challenge, the CLI prints the challenge text and asks for the TAN. Decoupled app confirmation flows prompt you to confirm in the banking app and press Enter. Binary challenge images are written under:

~/.config/mousehold/fints/challenges/

Ledger Mapping

FinTS transactions are imported as source_type = "fints" and status = "confirmed".

Positive bank movements become income.
Ordinary negative bank movements become expense.
Negative movements mentioning PayPal, Klarna, or credit-card providers become liability_payment, so they can later be linked to prior obligations instead of becoming duplicate household expenses.