Connects to bank accounts and fetches financial transactions via the SimpleFIN API. Use when the user wants to check bank balances, review recent transaction...
---
name: simplefin
description: 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](https://bridge.simplefin.org/) 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:
```bash
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:
```bash
node scripts/simplefin_api.js "https://username:password@beta-bridge.simplefin.org/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:
```bash
node scripts/simplefin_api.js "https://username:password@beta-bridge.simplefin.org/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**
```bash
node scripts/simplefin_api.js "https://username:password@beta-bridge.simplefin.org/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](references/developer_guide.md) for the SimpleFIN setup token flow and API documentation.
don't have the plugin yet? install it then click "run inline in claude" again.