Jacob Kiers
53087fa900
- Reduces GoCardless API calls by up to 99% through intelligent caching of transaction data - Secure AES-GCM encryption with PBKDF2 key derivation (200k iterations) for at-rest storage - Automatic range merging and transaction deduplication to minimize storage and API usage - Cache-first approach with automatic fetching of uncovered date ranges - Comprehensive test suite with 30 unit tests covering all cache operations and edge cases - Thread-safe implementation with in-memory caching and encrypted disk persistence Cache everything Gocardless sends back
Banks2FF
A robust command-line tool to synchronize bank transactions from GoCardless (formerly Nordigen) to Firefly III.
✨ Key Benefits
- Automatic Transaction Sync: Keep your Firefly III finances up-to-date with your bank accounts
- Intelligent Caching: Reduces GoCardless API calls by up to 99% through encrypted local storage
- Multi-Currency Support: Handles international transactions and foreign currencies correctly
- Smart Duplicate Detection: Avoids double-counting transactions automatically
- Reliable Operation: Continues working even when some accounts need attention
- Safe Preview Mode: Test changes before applying them to your finances
- Rate Limit Aware: Works within API limits to ensure consistent access
🚀 Quick Start
Prerequisites
- Rust (latest stable)
- GoCardless Bank Account Data account
- Running Firefly III instance
Setup
- Copy environment template:
cp env.example .env - Fill in your credentials in
.env:GOCARDLESS_ID: Your GoCardless Secret IDGOCARDLESS_KEY: Your GoCardless Secret KeyFIREFLY_III_URL: Your Firefly instance URLFIREFLY_III_API_KEY: Your Personal Access TokenBANKS2FF_CACHE_KEY: Required encryption key for secure transaction caching
Usage
# Sync all accounts (automatic date range)
cargo run -p banks2ff
# Preview changes without saving
cargo run -p banks2ff -- --dry-run
# Sync specific date range
cargo run -p banks2ff -- --start 2023-01-01 --end 2023-01-31
📋 What It Does
Banks2FF automatically:
- Connects to your bank accounts via GoCardless
- Finds matching accounts in your Firefly III instance
- Downloads new transactions since your last sync
- Adds them to Firefly III (avoiding duplicates)
- Handles errors gracefully - keeps working even if some accounts have issues
🔐 Secure Transaction Caching
Banks2FF automatically caches your transaction data to make future syncs much faster:
- Faster Syncs: Reuses previously downloaded data instead of re-fetching from the bank
- API Efficiency: Dramatically reduces the number of calls made to GoCardless
- Secure Storage: Your financial data is safely encrypted on your local machine
- Automatic Management: The cache works transparently in the background
The cache requires BANKS2FF_CACHE_KEY to be set in your .env file for secure encryption (see env.example for key generation instructions).
🔧 Troubleshooting
- Account not syncing? Check that the IBAN matches between GoCardless and Firefly III
- Missing transactions? The tool syncs from the last transaction date forward
- Rate limited? The tool automatically handles API limits and retries appropriately
For technical details, see docs/architecture.md