Skip to main content
SimpleFIN is a paid third-party provider focused on US bank account connectivity. It offers a simpler, more affordable alternative to Plaid for personal finance management. See Transaction history and import limits for initial sync defaults, history limits, and options for older transactions.

​
How it works

SimpleFIN uses a setup token system to establish secure access to your bank accounts:
  1. Obtain a setup token from SimpleFIN
  2. Sure claims the setup token to get an access URL with embedded credentials
  3. The access URL is used to fetch account data, balances, and transactions
  4. Data syncs automatically to keep your information current

​
Setting up SimpleFIN

To connect your US bank accounts:
  1. Sign up for a SimpleFIN account at simplefin.org
  2. Generate a setup token from your SimpleFIN dashboard
  3. In Sure, provide the setup token
  4. Sure will claim the token and establish access to your accounts

​
Setup token claiming

The setup token is a base64-encoded claim URL. When you provide it to Sure:
  1. Sure decodes the token to get the claim URL
  2. Makes a POST request to claim the access URL
  3. Receives an access URL with HTTP Basic Auth credentials embedded
  4. Uses this access URL for all subsequent API requests

​
Features

​
Account syncing

  • Account listing: View all connected accounts with current balances
  • Transaction history: Import transactions with date range filtering
  • Pending transactions: Included by default. Not all institutions return pending transactions even when requested — this is a limitation of the institution’s data feed.
  • Multiple accounts: Connect multiple bank accounts from different institutions
  • Localized status messages: Sync status summaries (such as “2 accounts synced” or “1 account needs setup”) display in your chosen language

​
Date range filtering

When syncing transactions, you can specify:
  • Start date: Fetch transactions from this date forward
  • End date: Fetch transactions up to this date
SimpleFIN expects Unix timestamps for date parameters.

​
Pending transaction inclusion

Pending transactions are included by default. Sure resolves whether to request them in this order:
  1. An explicit argument passed internally by the sync flow
  2. The SIMPLEFIN_INCLUDE_PENDING environment variable (1 = include, 0 = exclude)
  3. The shared Include pending transactions setting under Settings → Self-Hosting
The setting and the environment variable both default to 1 (on). To disable pending transactions globally, set:
Note that sending pending=0 to the SimpleFIN API is not the same as omitting the parameter. The low-level client only adds pending=1 when inclusion is enabled and omits the parameter otherwise, because some bridges treat the parameter’s presence — regardless of value — as a request to include pending.

​
Reliability features

Sure’s SimpleFIN integration includes automatic retry logic:
  • Exponential backoff for transient network failures
  • Up to 3 retry attempts for network errors
  • Handles temporary connection issues gracefully
  • Prevents sync failures from intermittent network problems

​
API structure

SimpleFIN uses a simple REST API with embedded authentication:
  • POST /claim: Exchange setup token for access URL
  • GET /accounts: Fetch all accounts with balances and transactions
  • GET /info: Get server information
The access URL contains HTTP Basic Auth credentials, so no separate authentication headers are needed.

​
API reference

For detailed protocol documentation, see the SimpleFIN Protocol.

​
Pricing

SimpleFIN is a paid service, but typically more affordable than alternatives like Plaid. Check simplefin.org for current pricing.

​
Investment holdings and lot aggregation

SimpleFIN reports one record per lot, so a single position can arrive as several records sharing the same security. A 401k that splits employee deferral from employer match is a common example. Sure combines these lots into a single position per security before storing the holding. Quantity and market value are summed across all lots. Cost basis is stored per share, so lots are combined into a share-weighted average — but only when every lot reported a basis. If any lot omits its cost basis, the entire position’s cost basis is left unknown rather than averaging over partial data, which would invent cost and produce incorrect gain/loss figures. If your investment account shows a total value that matches your institution’s balance but individual holdings appear at less than their full value, a manual sync from Settings → Providers → SimpleFIN will re-import the combined positions correctly.

​
Institution-specific cost basis corrections

The SimpleFIN specification says the cost_basis field is a per-share value, but some brokerages populate it with the total position cost instead. Sure detects these cases by institution name or domain and divides by quantity automatically, so the stored per-share figure stays correct. Institutions where Sure applies this correction: Vanguard, Fidelity, Schwab, and E*Trade. If your institution sends a total cost in cost_basis but is not in this list, the holding will show an inflated per-share basis. In that case, you can correct the value by setting a manual cost basis on the holding.

​
Limitations

  • US-focused: Primarily supports US financial institutions
  • Setup token security: Setup tokens can only be claimed once and may expire
  • Pending transactions: Not all institutions return pending transactions, even when requested
  • Rate limits: Subject to SimpleFIN API rate limits
  • Access URL validity: Access URLs can be revoked or expire (returns 403 error)

​
Troubleshooting

​
Incorrect balance sign on credit cards or loans

SimpleFIN reports liability balances from the bank’s perspective (positive = you owe money). Sure converts these into the correct sign for net worth calculations — liabilities reduce net worth, so their balances are stored as negative values. For loans, Sure trusts the bank’s sign directly and stores the absolute value of the reported balance. Earlier versions incorrectly ran a transaction-history heuristic on loans, which could invert the balance and make the loan appear to add to your net worth instead of subtracting from it. This is now fixed. For credit cards, Sure uses recent transaction history to determine whether a positive balance represents debt (normal) or an overpayment credit (unusual). When there is not enough transaction history to decide, Sure falls back to sign-based normalization using both the posted and available balances reported by the institution. If a credit card balance still looks wrong after syncing, you can override the automatic sign detection. Open the account’s edit form (from Settings → Providers → SimpleFIN or the account detail page) and find the SimpleFIN balance meaning dropdown:
  • Automatic (default): Sure uses transaction history and provider balance to determine the correct sign.
  • Debt (you owe the bank): Forces the balance to be treated as a positive debt amount.
  • Credit (bank owes you): Forces the balance to be treated as a credit in your favor (for example, an overpayment).
Use an override only when SimpleFIN consistently reports an ambiguous sign for a specific card. The automatic setting is correct for most accounts. If a credit card or loan balance looks wrong after syncing:
  1. Re-sync the account from Settings → Providers → SimpleFIN.
  2. If the balance is still incorrect, check whether the account type is set to Credit Card or Loan in your account settings. An incorrect account type can cause the wrong normalization to be applied.
  3. For credit cards connected through SimpleFIN, set SimpleFIN balance meaning to Debt or Credit in the account’s edit form if the automatic detection is wrong for your institution.

​
Duplicate accounts with the same name

If you have two accounts at the same institution with identical display names (for example, two accounts both named “CHECKING (0001)”), Sure uses the upstream account ID to distinguish them during sync. Only accounts whose ID is genuinely absent from the upstream response are treated as stale and eligible for re-linking. Ambiguous cases where multiple local accounts share a name are skipped rather than resolved automatically, preventing one account from silently inheriting another’s transaction history. If you notice an account that appears to have lost its transaction history after a sync, check Settings → Debug for any skipped stale-linkage repair entries that may indicate an ambiguous name match.

​
Setup token issues

If you receive a 403 error when claiming a setup token:
  • The token may have already been used
  • The token may have expired
  • The token may have been compromised
Generate a new setup token from your SimpleFIN dashboard.

​
Missing pending transactions

Pending transactions are requested by default. Some institutions don’t return them even when pending=1 is sent. This is a limitation of the institution’s data feed, not a bug in SimpleFIN or Sure. If you want to disable pending transactions entirely, set SIMPLEFIN_INCLUDE_PENDING=0 in your environment or turn off Include pending transactions under Settings → Self-Hosting.

​
Network errors

If you experience intermittent sync failures:
  • Sure automatically retries failed requests up to 3 times
  • Network errors are logged for troubleshooting
  • Manual sync attempts may succeed where automatic syncs fail