How to Set Up Personal Finance Tracking with Firefly III, SimpleFIN, and OpenClaw

By /

Firefly III is a self-hosted personal finance manager that gives you full control over your financial data. SimpleFIN Bridge connects it to real U.S. bank accounts — without screen scraping or third-party credential storage. OpenClaw closes the loop by automating daily syncs so the system runs itself.

This guide covers the full setup: from first connection through opening balance correction, auto-categorization rules, and scheduled automation. Follow it in order — the steps build on each other.

Prerequisites

Before starting, confirm the following are in place:

  • Firefly III is running and accessible (Docker or native install, any port)
  • Firefly III Data Importer is running as a separate service with network access to your Firefly III instance
  • SimpleFIN Bridge account created at [beta-bridge.simplefin.org](https://beta-bridge.simplefin.org)
  • OpenClaw installed and operational on the same host or network
  • A Firefly III Personal Access Token generated under *Profile → OAuth → Personal Access Tokens*
  • Your Firefly III instance URL and Data Importer URL noted

⚠️ Note: The Firefly III Data Importer must be able to reach your Firefly III instance over the network. Verify this before proceeding — a misconfigured URL here causes silent import failures later.

Step 1: Connect SimpleFIN to Your Banks

SimpleFIN Bridge acts as a read-only relay between your financial institutions and your self-hosted tools. It uses your bank’s official OAuth or credential flow — no screen scraping.

1.1 — Create your SimpleFIN account

Navigate to [beta-bridge.simplefin.org](https://beta-bridge.simplefin.org) and register. After confirming your email, log in to the dashboard.

1.2 — Add bank connections

From the SimpleFIN dashboard, click Add Account and follow the authentication flow for each institution. Complete the OAuth or credential handoff for each bank, credit card issuer, or investment account you want to track.

1.3 — Generate your claim token

Once accounts are connected, click Get API Access or the equivalent token generation option. Copy the claim token that appears.

⚠️ Critical: The SimpleFIN claim token is one-time use. It is consumed the moment it is submitted to the Data Importer. Save it to a secure location (password manager, not a plaintext file) before attempting the next step. If you lose it or it gets consumed by a failed setup attempt, generate a new one from the SimpleFIN dashboard.

Step 2: Configure the Firefly III Data Importer

The Data Importer is a standalone web service that handles the translation between SimpleFIN’s transaction format and Firefly III’s API. It does not run inside Firefly III.

2.1 — Open the Data Importer UI

Navigate to your Data Importer URL in a browser. On the home screen, select SimpleFIN as the import source.

2.2 — Paste the claim token

In the SimpleFIN configuration field, paste the claim token generated in Step 1.3. The importer will exchange it for a long-lived access URL and store it for future syncs.

2.3 — Change duplicate detection (critical)

In the importer settings, locate the Duplicate Detection option. Change it from the default Identifier-based to Content-based.

⚠️ Critical: This is the most common misconfiguration. SimpleFIN does not always provide stable transaction identifiers. With Identifier-based detection active, the importer will silently skip the majority of your transactions — often importing only 10–20 out of hundreds. Content-based detection matches on transaction amount, date, and description instead, which works correctly with SimpleFIN’s data format.

2.4 — Set the default import account

Under Default Account, select your primary checking or spending account. This tells the importer where to assign transactions when the source account cannot be determined automatically.

2.5 — Leave “Map data” unchecked (if using rules)

If you plan to use Firefly III’s rules engine for categorization (covered in Step 5), leave the Map data option unchecked. Mapping at import time conflicts with rule-based categorization applied post-import.

2.6 — Run the initial import

Click Import and allow the process to complete. For accounts with several months of history, this may take 30–90 seconds. Verify the transaction count in the importer’s completion summary before moving on.

Step 3: Set Account Types Correctly

Account type configuration in Firefly III must be correct before transactions are imported or before opening balances are set. Getting this wrong causes balance calculations to invert or double-count.

In Firefly III, navigate to Accounts and confirm each account matches the following:

Account Type Firefly III Setting
Checking account Asset account → Role: checkingAccount
Savings account Asset account → Role: savingsAccount
Credit card Liability account → Type: Credit card
Investment/brokerage Asset account → Role: investment

⚠️ Note: Credit cards must be configured as Liability accounts, not Asset accounts. If a credit card is set as an asset, payments and charges will produce inverted balances. This cannot be corrected after the fact without deleting and recreating the account.

Step 4: Fix Opening Balances

Firefly III starts with a zero balance for every account. Imported transactions represent activity from the import start date forward — they do not establish your actual current balance. Without an opening balance, every account will show a running total that bears no relation to your real balance.

The formula:

opening_balance = current_balance − sum_of_imported_transactions

Pull your current balance from your bank (or from the SimpleFIN dashboard, which reflects live balances). Sum all imported transactions for that account. The difference is your opening balance as of the date before your first imported transaction.

Set opening balance via the Firefly III API:

curl -X PUT "$FIREFLY_URL/api/v1/accounts/$ACCOUNT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Checking",
    "type": "asset",
    "account_role": "defaultAsset",
    "opening_balance": "1234.56",
    "opening_balance_date": "2025-01-01"
  }'

Replace $FIREFLY_URL with your instance URL, $ACCOUNT_ID with the numeric account ID from Firefly III (visible in the account URL), $TOKEN with your Personal Access Token, and "1234.56" with your calculated opening balance. Set opening_balance_date to one day before your earliest imported transaction.

Repeat for each account. After patching, verify balances in the Firefly III UI match your bank statements.

Step 5: Set Up Auto-Categorization Rules

Firefly III’s rules engine applies category, budget, and tag assignments to transactions automatically during import. Rules run in priority order and match on conditions like description, amount range, or account.

5.1 — Create a rule

Navigate to Rules → New Rule. Give it a descriptive name (e.g., Tag AMAZON as Shopping).

5.2 — Define trigger conditions

Set the trigger to Description contains and enter the payee keyword (e.g., AMAZON, GEICO, NETFLIX). Rules are case-insensitive.

5.3 — Define actions

Add an action: Set category → select or create the appropriate category (e.g., Shopping, Insurance, Subscriptions).

5.4 — Enable “Apply rules” in the importer

In the Data Importer settings, confirm Apply rules is checked. With this enabled, every import run — including automated syncs — will process all active rules against new transactions automatically.

Start with high-volume, easily identifiable payees. A set of 15–20 rules covers the majority of recurring spending for most households.

Step 6: Automate Daily Sync with OpenClaw

Manual imports require remembering to run the importer, managing token state, and checking for failures. A scheduled sync eliminates all of that. Running twice daily — morning and evening — keeps the ledger current without intervention.

OpenClaw [LINK: post about building an AI ops system] supports cron-based job scheduling with failure alerting built in. Configure a job that calls the Data Importer’s API endpoint to trigger a sync run.

6.1 — Identify the Data Importer sync endpoint

The Data Importer exposes a /autoimport endpoint that runs a headless import using stored credentials. Confirm this endpoint is accessible from your OpenClaw host.

6.2 — Add the cron job to OpenClaw

Create or edit your OpenClaw cron configuration:

crons:
  - name: firefly-daily-sync-am
    schedule: "0 6 * * *"
    job:
      type: http
      method: POST
      url: "http://YOUR_IMPORTER_HOST:PORT/autoimport"
      headers:
        Content-Type: "application/json"
      on_failure:
        notify: telegram
        message: "⚠️ Firefly III morning sync failed. Check Data Importer logs."

  - name: firefly-daily-sync-pm
    schedule: "0 18 * * *"
    job:
      type: http
      method: POST
      url: "http://YOUR_IMPORTER_HOST:PORT/autoimport"
      headers:
        Content-Type: "application/json"
      on_failure:
        notify: telegram
        message: "⚠️ Firefly III evening sync failed. Check Data Importer logs."

Replace YOUR_IMPORTER_HOST:PORT with your Data Importer’s actual host and port. OpenClaw’s crash-resistant gateway [LINK: post about crash-resistant AI gateway] ensures these jobs survive host restarts and network interruptions without requiring manual recovery.

6.3 — Verify the first automated run

After saving the config, trigger a manual run to confirm the job executes successfully before relying on the schedule.

Verification Checklist

Before considering setup complete, confirm each of the following:

  • ☐ Transaction count in Firefly III matches expected volume (not suspiciously low — see Troubleshooting)
  • ☐ Account balances in Firefly III match your bank statements within current-day variance
  • ☐ Categories are being applied to new transactions (check a recent import run)
  • ☐ OpenClaw cron jobs are active and show last-run timestamps
  • ☐ No failure notifications have been triggered since enabling automation

For ongoing accuracy, OpenClaw’s agent memory discipline [LINK: post about AI agent memory discipline] can be applied to store sync state, track balance drift over time, and surface anomalies without re-processing the full transaction history on every run.

Troubleshooting

Symptom Cause Fix
Only 10–20 transactions imported out of hundreds Duplicate detection set to Identifier-based Switch to Content-based in Data Importer settings and re-run
Account balance is negative when it shouldn’t be Missing or incorrect opening balance Apply the formula: current_balance − sum_of_imported_transactions, then PATCH via API
Import worked once, stopped after that No automation configured Add OpenClaw cron jobs as described in Step 6
“Claim token invalid” or 403 error on import Token already consumed Generate a new token at beta-bridge.simplefin.org
Specific bank’s transactions missing SimpleFIN connection broken Re-authenticate the institution from the SimpleFIN dashboard
Credit card balance shows wrong sign Account configured as Asset instead of Liability Delete the account, recreate as Liability → Credit card, re-import

Summary

A working Firefly III + SimpleFIN + OpenClaw setup gives you self-hosted personal finance tracking with automated daily sync, rule-based categorization, and correct account balances — with no dependency on SaaS products or third-party data storage.

The critical configuration points are: Content-based duplicate detection, correct account types before import, and opening balances set via the API formula. Get those three right and the rest of the system follows.

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top