Bank connections

Connect a real bank or credit-card account and transactions flow in automatically — categorized and booked to your ledger — instead of exporting and importing CSVs by hand. Powered by Plaid.

Connecting a bank

Go to Banking in the dashboard and click Connect a bank. This opens Plaid Link (a secure browser widget) where you log in to your institution. Because Link runs in the browser, connecting is a human-only flow — an agent cannot initiate it. After connecting:

Each account in the connection appears under the institution.
Map each account to a GL account — a checking/savings account maps to a cash (asset) account; a credit card maps to a liability account; a loan maps to a loan liability. Transactions can't book until the account is mapped.
The first sync pulls up to 24 months of history in the background.

Credentials never touch our servers

Plaid handles the bank login. We receive an access token (encrypted at rest with AES-256-GCM) and never see your bank password.

How transactions are categorized and booked

The feed is the source of truth: every transaction is staged first, then — if it's settled (posted) and we can categorize it — booked to the GL. The contra (category) account is resolved in this order:

a memorized payee rule (merchant → account), else
a Plaid category mapping (PFC → account, seeded sensibly per book type and override-able), else
the direction-aware default — money out → an expense account, money in → an income account.

Auto-post vs. review

Confident transactions post automatically: a memorized payee rule matched, or Plaid's category confidence is HIGH/VERY_HIGH on a clean income/expense class.
Everything else lands in the review queue as a draft or an unbooked staged row. Transfers and credit-card/loan payments never auto-post — they're not income or expense, so they always go to review.

Pending transactions are shown but not booked; when they settle, the posted transaction supersedes the pending one (no phantom duplicate).

The review queue

The Review queue on the Banking page lists drafts to confirm and staged rows that need an account. Pick an account, optionally check Remember payee to auto-book this merchant next time, and Post. Modified or removed bank transactions are reconciled automatically — a draft is updated, a posted entry is reversed and re-created (into the current open period if the original period is closed).

Staying in sync

New transactions arrive via Plaid webhooks and a periodic background sync, so the ledger stays current. You can also Sync now on any connection.

Reconnect alerts

Banks occasionally require re-authentication (expired consent or a password change). When that happens the connection is flagged Reconnect needed, a banner appears on the Banking page, and a bank.reconnect_required webhook event fires. Click Reconnect to repair it via Plaid Link update mode.

For agents (MCP / REST)

Connecting is human-only, but the rest of the feed is available to agents:

Tool (MCP)	Scope	Purpose
`list_bank_connections`	read	Connected banks, accounts, GL mapping, status.
`list_bank_transactions`	read	Staged transactions; filter by `review_status`.
`get_bank_transaction`	read	One staged transaction.
`categorize_bank_transaction`	write	Set the account + post; optionally memorize the payee.
`sync_bank_account`	write	Queue a sync for a connection.

POST /api/v1/plaid/items/{id}/sync queues a sync over REST. An agent working the books can list review_status=needs_review / draft_review, categorize each with categorize_bank_transaction (setting memorize: true to learn the merchant), and the rules compound over time.

Configuration

Bank connections require PLAID_CLIENT_ID, PLAID_SECRET, PLAID_ENV, PLAID_WEBHOOK_URL, and ENCRYPTION_KEY (a base64 32-byte key). Without them the app runs normally and the Banking page shows a "not configured" notice.