SimpleFIN Bank Connection

Connects to bank accounts and fetches financial transactions via the SimpleFIN API. Use when the user wants to check bank balances, review recent transactions, track expenses, or connect to a new bank account using SimpleFIN. It automatically guides the user through the Setup Token claim process if they haven't connected before.

SimpleFIN Bank Connection Skill

Overview

The simplefin skill allows you to connect to the user's bank accounts to retrieve account balances and transaction history using the SimpleFIN Bridge API.

Setup & Authentication (Always do this first!)

Before you can fetch any data, you need the user's SimpleFIN Access URL.

1. Check if you have it: Look for a stored URL in the workspace at memory/simplefin_url.txt or in the environment variables (e.g., openclaw.json under SIMPLEFIN_ACCESS_URL).
2. Prompt the user if missing: If you don't have the Access URL, you must ask the user for a Setup Token.
   • Instruction to provide to the user: "To get started, I need a SimpleFIN Setup Token. If you don't have one yet, here's how to get it:
     1. Go to SimpleFIN Bridge and sign up.
     2. Connect your bank accounts.
     3. Generate a Setup Token (a long string of characters). Please paste that Setup Token here so I can connect!"
3. Claim the Token: Once the user provides the Setup Token, use the script to claim it and get the Access URL:

   node scripts/simplefin_api.js claim "THE_SETUP_TOKEN_HERE"
   

   The script will output the true Access URL (https://username:password@...).
4. Save it: Save the Access URL to memory/simplefin_url.txt so the user doesn't have to provide it again in the future. The Setup Token is single-use and cannot be used again.

Fetching Data

Use the provided Node.js script scripts/simplefin_api.js to interact with the API. It requires the access_url as the first argument.

1. List Accounts & Balances

To view all connected bank accounts and their current balances:

node scripts/simplefin_api.js "https://username:[e-mail]/simplefin" accounts

This will output a JSON array of accounts, including their IDs, names, currencies, and balances.

2. List Transactions

To retrieve the transaction history across accounts:

node scripts/simplefin_api.js "https://username:[e-mail]/simplefin" transactions [options]

Options:

• --start-date YYYY-MM-DD: Filter transactions on or after this date.
• --end-date YYYY-MM-DD: Filter transactions on or before this date.
• --account "Account Name or ID": Filter transactions for a specific account.

Example: Fetching transactions for March 2026

node scripts/simplefin_api.js "https://username:[e-mail]/simplefin" transactions --start-date 2026-03-01 --end-date 2026-03-31

Processing Output

• Always format financial data clearly for the user (e.g., Markdown tables or bulleted lists).
• If the API returns an authentication error, remind the user that their SimpleFIN token might have expired or been revoked, and ask them to generate a new Setup Token.

References

If you need to make changes to the SimpleFIN integration, look up error schemas, or review API limits, consult the developer guide:

• See developer_guide.md for the SimpleFIN setup token flow and API documentation.