Connect SimpleFIN

Accounts, balances and transactions from the banks you link at SimpleFIN Bridge. You paste one token — nothing to install, no developer account.

Before you start

• A SimpleFIN Bridge subscription. You pay SimpleFIN about $1.50 a month at bridge.simplefin.org. The Bridge’s Billing page carries today’s price.
• Your bank sign-in details. You type them at the Bridge. Postern never sees a bank password.
• Your password manager open. The Bridge shows the setup token once, in step 2, and cannot show it again.
• The Console. Open http://localhost:8787 in a browser on the machine Postern runs on. Only this computer can reach these addresses. Nothing on your Wi-Fi, and nothing on the internet, can. If that machine has no screen, set up remote access first.
• About 5 minutes in Postern, once you have linked your banks at the Bridge.

The SimpleFIN Bridge labels below come from the site as it stood on 6 August 2026. SimpleFIN renames these screens, so trust your screen over this page.

Choose your path

If…	Then
You have not linked your banks at SimpleFIN Bridge yet	Start at Link your banks at SimpleFIN Bridge.
You already hold a setup token, or an access URL	Skip to Paste the token into the Console.

1. Link your banks at SimpleFIN Bridge

   Open bridge.simplefin.org. It sends you to beta-bridge.simplefin.org. That is the right site.

   Create an account. Every page then carries the same four links across the top: Home, My account, Billing, Sign out.

   Open Billing and pay for your subscription.

   Open My account. It offers two buttons. New connection adds a bank. New app connection adds an app, which is the next step, not this one.

   Press New connection and follow the Bridge’s own screens for your bank. You type your bank sign-in there. Postern never receives it, during this setup or afterwards.

   Repeat for every bank you want covered, then come back to My account.

   SimpleFIN arrives in Postern as one connection that holds every bank behind it. The Console has no bank picker. To add or drop a bank later, come back to the Bridge. The change reaches Postern on the next sync.

2. Create the setup token at the Bridge

   On My account, press New app connection. The page Connect Application opens, at beta-bridge.simplefin.org/my-account/tokens/create.

   It carries one field, Name / Description, with the helper text Use the name of the application or any other description that will help you identify it in the future. Type Postern.

   Press Create Setup Token. The page Setup Token Created opens. Your setup token sits in a bordered box on it, wrapped across about 4 lines.

   That page says Copy and paste the following SimpleFIN Setup Token into your application. This will be the only time you see this code. It means it. Copy the token before you leave the page — the Bridge cannot show it to you again.

   Press Copy to clipboard. If you select it by hand instead, take every line. A half-copied token fails like a wrong one.

   Treat the setup token like a bank password until you paste it.

   Press Return to My Account. Your new entry now sits in the Apps table, under App, Last used and Status, with Disable and Delete on its row.

   If you lose the token before you paste it, press New app connection again and create another. An unused token costs nothing.

3. Paste the token into the Console

   In the Console, open Sources. Press Add a source, then press SimpleFIN.

   Under the header Paste it here the card has one field, labelled Access URL, with the placeholder https://…@bridge.simplefin.org/….

   Paste your setup token there. The field takes either form — a setup token, or a full access URL.

   The field hides what you paste. It shows dots, not text, so you cannot read it back. That is normal.

   You can use a setup token one time. Postern uses it up when you press Connect SimpleFIN. The same token then fails everywhere, in Postern and in any other SimpleFIN app.

   In exchange the Bridge hands back an access URL, and that line is itself a password: whoever holds it can read every bank you linked. Postern encrypts it on your own machine and never shows it again. Postern stores the access URL, never the setup token

   Postern does not use up an access URL. It stores that line as it stands, so delete the copy you pasted from.

   Press Connect SimpleFIN. The Console shows SimpleFIN connected. and returns you to Sources, with a SimpleFIN row on it.

   Two answers appear in the field itself, before Postern contacts SimpleFIN.

   Paste your SimpleFIN access URL, or the setup token from the Bridge. — the field is empty.

   That’s the bridge address, not your access URL. Yours starts with https:// and carries a token after the //. — you pasted https://bridge.simplefin.org on its own.

   Postern has sent nothing to SimpleFIN. Paste the token and press Connect SimpleFIN again.

   SimpleFIN refused it. over simplefin setup-token claim failed means the claim failed. Postern saved nothing and left no half-connected source behind. Every cause gives that one message, because Postern keeps credential fragments out of error text. Why one message covers every cause

   Go back to the Bridge and create another setup token. Paste that one. If you kept an access URL, paste that instead.

   If SimpleFIN is already connected, the card says so first: SimpleFIN is already connected. Connecting again replaces the stored credential — it won’t create a second copy. Tick Yes — replace the stored credential. to release the button, which then reads Reconnect SimpleFIN.

4. Check the first sync

   Postern syncs the moment it connects, so SimpleFIN connected. also means the first sync worked.

   In the Console, open Sources. The Coverage cell on the SimpleFIN row counts what arrived — 3 accounts, or 1 account — and never 0 accounts. Under the row Postern prints your banks’ names with · between them, then One link carries all <n> — which banks are in it is chosen at SimpleFIN Bridge ↗. With one bank that line reads One link carries it.

   What arrives: accounts with their balances, posted transactions, and investment positions for the accounts that report them.

   The first sync collects 1 year of history, so nothing older arrives. Every later sync asks for what is new, plus the last 3 days again. Those 3 days catch a transaction that posts late. A second read of the same 3 days changes nothing already stored. Pending charges never arrive: a card charge lands once your bank finalises it. Backfill windows, the 3-day overlap, and posted-only reads

   SimpleFIN is connected, but its first sync failed. — the card stays put, with Postern’s own message underneath and a Manage this connection → link below it. The connection is real and Postern rolls nothing back. Press that link, then press Sync now. It answers Synced — <n> updated. or shows the failure word for word.

   A bank you linked at the Bridge is missing from the list, and nothing looks broken. One bank can fail while the others succeed, and the Bridge reports that inside a normal answer. Postern keeps everything that did arrive and does not delete that bank’s holdings. Postern logs the bank that failed and keeps its holdings

   To read the log, open a terminal on the machine Postern runs on. Go to the folder that holds docker-compose.yml. Run:

   docker compose logs -f app
   

   Look for lines that start simplefin:. Press Ctrl-C to stop.

5. Choose how often Postern checks

   In the Console, open Sources. On the SimpleFIN row, press Manage →, the last cell on the right.

   Under Controls, Poll cadence is a row of chips: 2h, 6h, 12h, 1d. That is how often Postern checks for new data. A new connection sits on 6h. Press another chip to change it. The gloss under the chips reads How often Postern re-syncs this connection. Minimum 2h — a faster override is clamped to that floor.

   2h is the floor, and the Console offers nothing faster. SimpleFIN caps how many times a day a token may ask, and disables a token that goes past that cap. Its own data refreshes about once a day, so a faster check returns rows you already hold. The daily cap, and why 2h is the floor

   Your choice takes effect within about a minute. No restart. If the Console answers Cadence rejected., the change did not take: press the chip again.

Confirm it works

• Sources shows a SimpleFIN row whose Coverage cell reads more than 0 accounts.
• The line under that row names every bank you linked at the Bridge.
• The Last heard cell reads just now, or a time in minutes — not never.
• The connection page shows one Poll cadence chip already chosen.
• Sync now on that page answers Synced — <n> updated.; a second run a minute later answers with a smaller number, or 0.

If something went wrong

What you see	What to do
SimpleFIN refused it.	The claim failed and Postern saved nothing. At the Bridge, press New app connection, then Create Setup Token, then Copy to clipboard. Paste that new setup token.
SimpleFIN is connected, but its first sync failed.	Press Manage this connection →, then Sync now. It answers Synced — <n> updated. or shows the failure word for word.
A bank is missing from the list under the SimpleFIN row	That bank failed this sync. Press Sync now on the connection page. If it is still missing, link that bank again at the Bridge with New connection.
http://localhost:8787 does not open	Postern runs on another machine. Set up remote access, then return to Paste the token into the Console.

What you have now

One finance connection now covers every bank you linked at the Bridge: accounts and balances, posted transactions, and investment positions where the bank reports them. Any agent you grant finance reads it from your own machine.

Postern can only read your finances. It can never move money. Finance has no action catalogue; only Home Assistant can act

Four things decide whether an agent’s answer is right:

• Money out is a negative number, so a plain sum nets spending against income.
• SimpleFIN sends no categories. An absent category means not categorised.
• Investment positions are a snapshot, not a list of trades.
• A cost basis of 0.00 means unknown, not free.

What an agent must know about these fields

Your subscription renews whether or not Postern runs, and SimpleFIN bills it. Which banks this connection covers stays your decision at the Bridge.

To remove the connection, open Sources and press Manage → on the SimpleFIN row. Scroll to Lifecycle, to the row Disconnect Finance, and press Disconnect. A confirm panel opens. It names what it removes: Removes Finance's cached data and this connection. Re-add it anytime. Type disconnect in the field under Type disconnect to confirm, then press Disconnect Finance. Postern deletes this connection’s cached rows and the encrypted access URL. It sends nothing to the Bridge, so your subscription and your linked banks stay as they are.

Add Plaid later for a bank the Bridge cannot reach. Postern merges an account that arrives through both, but only when both report the last 4 digits. Otherwise it asks you to settle it on its own screen. Postern never merges two accounts on a resemblance

Next

Connect an agent

a key you created, and an agent that can reach the machine Postern runs on · a few minutes, plus a restart of that agent

Connect Apple Health

Health Auto Export on your iPhone · about 10 minutes · push, not pull

Other sources: Home Assistant, iCloud, Microsoft, WHOOP.