SimpleFIN Integration

SimpleFIN provides a privacy-focused alternative to Plaid for connecting US bank accounts. It uses the SimpleFIN Protocol, which allows users to connect their banks through SimpleFIN Bridge without sharing credentials with third parties.

What SimpleFIN Connects To

SimpleFIN supports:

Depository Accounts: Checking and savings accounts
Credit Cards: Credit card accounts
Investment Accounts: Some brokerage accounts
Loan Accounts: Mortgages, auto loans, personal loans
Crypto Accounts: Cryptocurrency accounts (via manual configuration)

SimpleFIN requires users to set up their own SimpleFIN Bridge ($1.50/month) or use a SimpleFIN-compatible service. There’s no API key required for app developers.

Prerequisites

User Sets Up SimpleFIN Bridge

Each user needs their own SimpleFIN Bridge subscription:

Sign up at https://beta-bridge.simplefin.org
Cost: $1.50/month per user
Connect banks via SimpleFIN Bridge interface
Generate a Setup Token

No API Keys Required

Unlike Plaid, SimpleFIN doesn’t require developer API keys. Users provide their own access tokens generated from their SimpleFIN Bridge.

Configuration (Optional)

SimpleFIN works out of the box with no configuration, but you can customize behavior:

.env

# Include pending transactions by default (optional)
SIMPLEFIN_INCLUDE_PENDING=1

# Enable debug logging of raw SimpleFIN responses (optional)
SIMPLEFIN_DEBUG_RAW=1

Configuration details: app/models/provider/simplefin_adapter.rb

Connecting a SimpleFIN Account

Get Setup Token from SimpleFIN Bridge

Users must first connect their bank in SimpleFIN Bridge, then generate a Setup Token:

Log into SimpleFIN Bridge
Connect desired financial institutions
Click “Generate Setup Token”
Copy the base64-encoded token

Add Connection in Sure

Navigate to Settings → Providers
Find the SimpleFIN section
Click “Add SimpleFIN Connection”
Paste the Setup Token
Click “Connect”

Setup Accounts

After connecting, SimpleFIN will sync available accounts:

Review the list of discovered accounts
For each account, select the account type:
- Checking or Savings Account (Depository)
- Credit Card
- Investment Account
- Crypto Account
- Loan or Mortgage
- Other Asset
- Skip this account
Choose account subtype if applicable
Set sync start date (optional)
Click “Complete Setup”

Initial Sync

Sure will automatically sync transactions and balances for all linked accounts.

Source: app/controllers/simplefin_items_controller.rb:58

Account Type Detection

SimpleFIN uses intelligent account type detection based on:

Account name patterns
Institution metadata
Holdings data (for investment accounts)
Balance characteristics

The system suggests account types with confidence levels, but users can override any suggestion during setup. Source: app/controllers/simplefin_items_controller.rb:153

Data Syncing

What Gets Synced

Transactions:

Historical transactions (as far back as the institution provides)
Pending transactions (when SIMPLEFIN_INCLUDE_PENDING=1)
Foreign exchange metadata for international transactions
Transaction descriptions and amounts

Balances:

Current balance
Available balance
Balance history

Holdings (for investment accounts):

Security positions
Quantity and cost basis
Current market value

Institution Metadata:

Institution name and domain
Account organization data
Connection status

Sync Frequency

SimpleFIN Bridge refreshes bank data once every 24 hours. You cannot force more frequent syncs.

Sync behavior:

Rate Limited: SimpleFIN enforces a 24-hour refresh limit per account
Manual Sync: Triggers a sync if data is stale (>24 hours old)
Balance-Only Sync: Available for quick balance checks without full transaction sync

Source: app/controllers/simplefin_items_controller.rb:125

Pending Transactions

SimpleFIN detects pending transactions when:

Provider sends pending: true in transaction data
OR posted date is blank/0 and transacted_at is present

Pending metadata is stored at transaction.extra["simplefin"]["pending"]. Source: Repository Guidelines (AGENTS.md)

Foreign Exchange Support

SimpleFIN provides rich FX metadata:

extra["simplefin"]["fx_from"]: Original currency
extra["simplefin"]["fx_date"]: Exchange rate date

Updating a Connection

If your SimpleFIN connection expires or needs to be refreshed:

Generate New Setup Token

In SimpleFIN Bridge, generate a new Setup Token for the existing connection.

Update in Sure

Go to Settings → Providers
Find your SimpleFIN connection
Click “Update Connection”
Paste the new Setup Token
Confirm

Preserve Account Links

Updating preserves all existing account linkages and transaction history.

Source: app/controllers/simplefin_items_controller.rb:18

Handling Stale Accounts

When you remove and re-add an institution in SimpleFIN Bridge, account IDs change. Sure detects this automatically:

Automatic Repair: Sure matches old and new accounts by name
Preserve History: Transactions from the old account are merged into the new one
No Data Loss: Your historical data remains intact

Source: app/models/simplefin_item.rb:119

Connection Management

Balance-Only Sync

For quick balance updates without syncing all transactions:

# Endpoint: POST /simplefin_items/:id/balances
# Source: app/controllers/simplefin_items_controller.rb:126

Useful for dashboard widgets that need current balances without the overhead of full transaction processing.

Unlinking Accounts

To disconnect a SimpleFIN account:

Navigate to Settings → Providers
Find the SimpleFIN connection
Click “Delete”
Confirm deletion

This will:

Unlink all associated Sure accounts
Schedule data cleanup
Not affect your SimpleFIN Bridge setup

Source: app/controllers/simplefin_items_controller.rb:104

Troubleshooting

”Rate Limited” or “Make Fewer Requests”

Cause: SimpleFIN Bridge enforces a 24-hour refresh limit. Solution: Wait until the bridge refreshes (up to 24 hours). This is a SimpleFIN limitation, not a Sure limitation. Source: app/models/simplefin_item.rb:344

No New Transactions

Checklist:

Check last sync time (must be >24 hours ago for refresh)
Verify connection status in SimpleFIN Bridge
Ensure accounts are still active in your bank
Check for stale account warnings in Sure

Stale Sync Detection

Sure monitors sync health:

Warns if last sync was >3 days ago
Alerts if no new transactions in 14+ days
Prompts to check SimpleFIN Bridge connections

Source: app/models/simplefin_item.rb:366

Invalid Setup Token

Cause: Token was miscopied or has already been claimed. Solution: Generate a fresh Setup Token from SimpleFIN Bridge and try again. Source: app/controllers/simplefin_items_controller.rb:42

Accounts Need Setup

After initial connection, you may see “Accounts need setup” badge:

Click the badge
Select account types for each discovered account
Complete setup process
Sync will begin automatically

Source: app/controllers/simplefin_items_controller.rb:137

Privacy & Security

Why SimpleFIN?

No Credential Sharing: You never share bank passwords with Sure
User-Controlled: Each user manages their own SimpleFIN Bridge
Direct Connection: SimpleFIN Bridge connects directly to your banks
Encrypted Tokens: Access URLs are encrypted in Sure’s database
Read-Only: SimpleFIN can only read data, never initiate transactions

Data Storage

SimpleFIN access URLs are encrypted using Rails’ ActiveRecord Encryption:

# Source: app/models/simplefin_item.rb:11
encrypts :access_url, deterministic: true
encrypts :raw_payload

API Reference

Creating a Connection

# Source: app/controllers/simplefin_items_controller.rb:68
Current.family.create_simplefin_item!(
  setup_token: setup_token,
  item_name: "SimpleFIN Connection"
)

Processing Accounts

# Source: app/models/simplefin_item.rb:48
def import_latest_simplefin_data(sync: nil)
  SimplefinItem::Importer.new(
    self, 
    simplefin_provider: simplefin_provider, 
    sync: sync
  ).import
end

Supported Account Types

# Source: app/controllers/simplefin_items_controller.rb:232
valid_types = [
  "Depository",    # Checking/Savings
  "CreditCard",    # Credit cards
  "Investment",    # Brokerage accounts
  "Loan",          # Mortgages, auto loans
  "Crypto",        # Cryptocurrency
  "OtherAsset"     # Other assets
]

Best Practices

Educate Users: Explain that SimpleFIN requires their own Bridge subscription
Set Expectations: Communicate the 24-hour sync limitation upfront
Monitor Staleness: Use the built-in stale sync detection to prompt users
Handle Relinks: SimpleFIN account IDs change when institutions are re-added; rely on automatic repair
Use Balance Sync: For real-time dashboards, use balance-only sync instead of full sync

Comparison: SimpleFIN vs Plaid

Feature	SimpleFIN	Plaid
Cost	$1.50/month per user	Per-item fees
Privacy	User-controlled bridge	Credential sharing
Sync Frequency	Once per 24 hours	Real-time with webhooks
Setup	User sets up Bridge	Developer gets API keys
Coverage	US banks	US, Canada, EU banks
API Complexity	Simple token-based	Full OAuth + webhooks
Pending Transactions	✅ Supported	✅ Supported
FX Metadata	✅ Rich FX data	Limited

Get Started

Self-Hosting

Core Features

Integrations

Mobile App

​What SimpleFIN Connects To

​Prerequisites

​Configuration (Optional)

​Connecting a SimpleFIN Account

​Account Type Detection

​Data Syncing

​What Gets Synced

​Sync Frequency

​Pending Transactions

​Foreign Exchange Support

​Updating a Connection

​Handling Stale Accounts

​Connection Management

​Balance-Only Sync

​Unlinking Accounts

​Troubleshooting

​”Rate Limited” or “Make Fewer Requests”

​No New Transactions

​Stale Sync Detection

​Invalid Setup Token

​Accounts Need Setup

​Privacy & Security

​Why SimpleFIN?

​Data Storage

​API Reference

​Creating a Connection

​Processing Accounts

​Supported Account Types

​Best Practices

​Comparison: SimpleFIN vs Plaid

​Additional Resources

SimpleFIN Bridge

SimpleFIN Protocol

Plaid Alternative

Build docs developers (and LLMs) love

What SimpleFIN Connects To

Prerequisites

Configuration (Optional)

Connecting a SimpleFIN Account

Account Type Detection

Data Syncing

What Gets Synced

Sync Frequency

Pending Transactions

Foreign Exchange Support

Updating a Connection

Handling Stale Accounts

Connection Management

Balance-Only Sync

Unlinking Accounts

Troubleshooting

”Rate Limited” or “Make Fewer Requests”

No New Transactions

Stale Sync Detection

Invalid Setup Token

Accounts Need Setup

Privacy & Security

Why SimpleFIN?

Data Storage

API Reference

Creating a Connection

Processing Accounts

Supported Account Types

Best Practices

Comparison: SimpleFIN vs Plaid

Additional Resources