scottmckendry/akahu-actual
💸 Import transactions from Akahu into Actual Budget
Akahu to Actual Budget 🚀
A dead-simple script that connects the brilliant Akahu API to the equally brilliant Actual Budget app.
An ideal solution for Kiwis who want to use Actual Budget to manage their finances, but find the manual import process a bit tedious.
🔑 Prerequisites
- An Akahu account with a configured personal app (see Akuhu's documentation)
- Docker (recommended) or Node.js
Note
Only the Transactions permission is required in your Akahu app settings.
⚡ How it Works
- Connects to the Akahu API using your personal app and user tokens
- Pulls transactions from all connected accounts, mapping them to their corresponding Actual Budget accounts
- Transforms the transactions into a format that Actual Budget can understand
- Pushes the transactions to Actual Budget using its API
🛠️ Configuration
Create an .env file with the following settings:
# Akahu API Credentials
AKAHU_APP_TOKEN=app_token_abcd
AKAHU_USER_TOKEN=user_token_1234
# Account Mappings
# Format: {"akahu_account_id": "actual_account_id"}
# - Akahu IDs: Found in URL when viewing account on my.akahu.nz (format: acc_xxx...)
# - Actual IDs: Found in URL when viewing account in Actual Budget (GUID format)
ACCOUNT_MAPPINGS={"akahu_account_id_1":"actual_account_id_1", "akahu_account_id_2":"actual_account_id_2"}
# Actual Budget Configuration
ACTUAL_SERVER_URL=http://localhost:5006 # URL of your Actual server
ACTUAL_PASSWORD=password # Your Actual master password
ACTUAL_SYNC_ID=00000000-0000-0000-0000-000000000000 # Found in Settings -> Advanced Settings
# Optional Settings
DAYS_TO_FETCH=7 # Number of days of transaction history to fetch (default: 7)
ACTUAL_E2E_ENCRYPTION_PASSWORD=password # Actual E2E encryption password, if enabled (default: undefined)
RECONCILE_ACCOUNT_IDS=["akahu_account_id_1","akahu_account_id_2"] # JSON array of Akahu account IDs to reconcile after import (default: [])Tip
Certain accounts may be influenced by factors other than transactions (e.g. investments, KiwiSaver). In which case, relying solely on transaction imports may lead to discrepancies. Use the RECONCILE_ACCOUNT_IDS setting to specify which accounts should be reconciled after import, ensuring their balances align with their real-world counterparts.
🚀 Deployment Options
Option 1: Docker Compose (Recommended)
Create a docker-compose.yml file:
services:
actual_server:
container_name: actual_server
image: docker.io/actualbudget/actual-server:latest
ports:
- "5006:5006"
volumes:
- ./actual-data:/data
restart: unless-stopped
healthcheck:
test: ["CMD-SHELL", "node src/scripts/health-check.js"]
interval: 60s
timeout: 10s
retries: 3
start_period: 20s
akahu-actual:
container_name: akahu-actual
image: ghcr.io/scottmckendry/akahu-actual
env_file:
- .env
depends_on:
actual_server:
condition: service_healthyTip
The akahu-actual container runs once and exits. To run it again:
docker restart akahu-actualConsider setting up a cron job for automatic scheduling.
Note
If you're deploying to Kubernetes, I suggest taking a look at the example in my homelab repo here.
Option 2: Local Node.js Installation
- Clone the repository
- Install dependencies:
npm install- Run the script:
npx tsc && node dist/index.js🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.