Skip to content

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.md lists "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, and src/banks/source.ts says 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 ​

  1. Read CLAUDE.md, docs/not-doing.md, ADR 0035, ADR 0032, SPEC-003, SPEC-011 and SPEC-013 first.
  2. This conflicts with not-doing.md and ADR 0035. Do slice 0 only (draft the ADR amendment). Build nothing else until it is accepted.
  3. 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 a liveBanking: false release gate like xeroWrites.
  • Balances go to the owner's own Claude session and nowhere else.

Scope v1 ​

Business accounts only.

SourceCredentialTo confirm in the bank's own docs
starling_token (re-introduces what ADR 0035 removed)Personal Access Token, read scopes onlyThird-party pages say it does not expire and is free. One token per account
revolut_business_apiCertificate + signed JWT, READ scopeOne 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 BalanceSource interface 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 extends bank_accounts_list and connection_check rather 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_check and bank_accounts_list changes, 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.