Appearance
SPEC-019: Live bank balances (read-only, owner-held credentials, local only)
DRAFT, blocked until a Product Owner decision amends ADR 0035.
This conflicts with the repo as it stands today:
docs/not-doing.mdlists "Connecting to banks: logins, tokens, screen scraping, open banking" and "Our own FCA licence" as not doing.- ADR 0035 (
docs/decisions/0035-statement-files-only.md, accepted 2026-10-08) made statement files the only bank source. It withdrew the Starling live source and the Finexer aggregator, andsrc/banks/source.tssays so.- Anything added to scope needs a Product Owner decision recorded in
docs/decisions/.The summary of ADR 0035 above comes from the spec's author, who could not read the file at the time. Read ADR 0035 itself before relying on it.
Instructions for Claude Code
- Read
CLAUDE.md,docs/not-doing.md, ADR 0035, ADR 0032, SPEC-003, SPEC-011 and SPEC-013 first. - This conflicts with
not-doing.mdand ADR 0035. Do slice 0 only (draft the ADR amendment). Build nothing else until it is accepted. - Follow the existing rules: integer pence (ADR 0025), row-level security per entity, one agent/branch/worktree, no write tool, and no tool that accepts a credential.
Intent
The owner asks "what's in my accounts now?" and "does Xero match the bank?" and gets the bank's live balance next to Xero's. This is the balance-level companion to SPEC-003 (ADR 0013). Reading only, never payment initiation.
The decision being asked for
This is a question for the Product Owner, not a legal conclusion: does this design stay on the same side of ADR 0035's line as statement files?
- The owner creates the credential at their bank and keeps it on their own machine. GetMy never receives or stores it.
- The capability exists only in the local stdio server (Claude Code or Desktop). It is not on the web endpoint
mcp.getmy.group, and sits behind aliveBanking: falserelease gate likexeroWrites. - Balances go to the owner's own Claude session and nowhere else.
Scope v1
Business accounts only.
| Source | Credential | To confirm in the bank's own docs |
|---|---|---|
starling_token (re-introduces what ADR 0035 removed) | Personal Access Token, read scopes only | Third-party pages say it does not expire and is free. One token per account |
revolut_business_api | Certificate + signed JWT, READ scope | One connection covers all sub-accounts. A third-party page says it needs the Grow plan or above, so check the cost |
Not in v1: transactions, personal accounts, credit cards and any aggregator. Enable Banking's free tier is for accounts you link yourself and is not licensed for a product, so personal accounts belong in a separate tool outside this repo.
Design
- A new
BalanceSourceinterface returns{accountRef, currency, balancePence, asAt}. It does not feed the reconciliation pipeline. - One new read tool,
bank_balances, returns the bank balance, Xero's Bank Summary balance and the difference. It extendsbank_accounts_listandconnection_checkrather than adding more tools (SPEC-011). - No tool accepts a credential. The owner supplies it through the OS keychain, a 0600 file or environment variables.
- Credentials with payment or write scopes are refused where the provider exposes scopes.
- Nothing is stored: no balances or account numbers in the database, logs or activity log. The activity log records only that a read happened.
- A failed read shows no figure. It never falls back to Xero's number (as SPEC-013 S11).
- Account names and provider text are treated as data, to guard against prompt injection.
Scenarios
- S1: balance and Xero difference.
- S2: two banks, sub-accounts listed separately, no cross-currency sums.
- S3: payment-scope credential refused.
- S4: tool absent from the web endpoint.
- S5: no input schema accepts a secret.
- S6: nothing stored.
- S7: failures are explicit (revoked token, expired certificate, no API plan, timeout).
- S8: companies are isolated.
- S9: injected text in account names does nothing.
Slices
- 0: ADR amendment draft.
- 1: interface, gate, S4-S6.
- 2: Starling, S1/S3/S7/S8.
- 3: Revolut, S2/S3/S7.
- 4:
connection_checkandbank_accounts_listchanges, S9, and a setup guide.
Open questions
These need registering in docs/sge/questions.md with QD numbers when the spec moves out of draft.
- QD-a: does the Product Owner accept amending ADR 0035 for owner-held, local-only, balance-only reads? If not, withdraw this spec.
- QD-b: SPEC-013 calls Revolut Business "WealthTechPros' bank". Which entity's books does each account belong to? Keep each entity's credential separate. Also settle the Revolut plan cost.
- QD-c: where is each Starling token held, and what happens when one is revoked?
- QD-d: should regulatory advice be taken before deciding?
Exit test
On real data, the owner asks Claude for live balances and the Xero difference for Starling and Revolut Business. Both work, a payment-scope token is refused, the web endpoint shows no banking tool, and the database holds no balance.