Knox-mgk/aibank

A double-entry banking backend where **humans hold the money and AI agents
spend it under limits they cannot reach.** An account holder signs in, funds a
wallet, allocates money to their agents, and sets each agent's ceilings from a
dashboard. The agent gets an API key that can do exactly one thing with money:
request a payout that the server either allows, holds for approval, or denies.
**You self-host it against your own payment credentials.** aibank never holds
your money and never touches a balance you do not own, so there is no custody
and no payment licence in the picture — the deployment is yours. One command
gets you a running service with TLS, a sweeper, and verified backups.
**Zero third-party dependencies.** Python standard library only, by design.
It ships both ends of that: a **dashboard** for the human and an **MCP server**
so the agent spends through typed tools instead of hand-rolled HTTP.
---
Why
An autonomous agent that can spend money is a liability unless four things are
true: its balance is always correct, its spending is bounded by policy it
cannot bypass, a retried request never moves money twice, and a **human** —
not the agent — decides what the bounds are. The first three are ledger
problems. The fourth is an authorisation problem, and it is the one that makes
this a banking service rather than a wallet library.
The central invariant
> The human sets the limits. The agent operates under them and can never reach
> them.
This is enforced structurally, not by convention. There are three separate
trust domains, and the HTTP layer keeps them apart:
| domain | credential | may do |
|---|---|---|
| **Agent** | Authorization: Bearer sk_agent_… | request payouts, read own balance, add payees |
| **User** | Authorization: Bearer sess_… | set policy, fund wallets, approve/reject/refund, rotate keys |
| **Admin** | X-Admin-Key | pricing, settlement deposits, sweeper, cross-tenant reads |
An agent key presented to a user-domain route is rejected before any handler
runs. POST /v1/agents/ /policy is reachable only with a session token, so
**no sequence of agent API calls can raise an agent's own ceiling.** A test
asserts this against the router's source, and the HTTP smoke test proves it
against a live socket:
The ledger
A general ledger with invariants enforced in code, not convention:
1. **Postings within an entry sum to exactly zero.** An unbalanced entry is
rejected, not corrected.
2. **Postings are immutable.** Corrections are new reversing entries
(ledger.reverse_entry), so history is append-only and auditable. A refund
leaves both the original and its mirror on the books; reversing twice is
refused.
3. **balance = SUM(postings)**, and **available = balance − active holds**.
Balances are never stored, only derived — they cannot drift.
4. **An idempotency key produces at most one entry, ever**, enforced by a
UNIQUE constraint rather than an application check.
Money is integer minor units throughout. No floats touch a balance. Fees use
floor division on basis points, so the same inputs always produce the same fee.
Money flow
A user cannot credit their own wallet (that is the admin/collection path), and
an agent cannot be funded from nothing — allocation debits a real user balance.
Money committed to an in-flight payout is held, so a user cannot withdraw funds
their agent has already promised.
Spend policy
Evaluated server-side before funds are held, deny-by-default:
- per-transaction ceiling
- rolling daily and monthly caps (accumulate across transactions)
- **daily payout count ceiling** — catches a retry loop making a thousand
individually-legal payments, which an amount cap cannot
- **timezone-correct daily reset** — a "daily" cap resetting at UTC midnight
resets at 01:00 in Lagos, handing the agent a second allowance in that hour
- payee allowlist, and the payee's currency must match the payout's
- approval threshold above a configurable amount
- freeze: a frozen agent cannot spend at all
- **suspending the human immediately stops all of their agents**
- **no limits means no spending** — the default is deny, not allow. An agent
needs at least one of the three amount ceilings or an approval threshold;
with none set, every payout is refused rather than permitted. This was a real
bug, not just a design note: create_agent always wrote a policy row, so the
"no policy" deny branch was unreachable and an agent created without limits
could move its entire wallet in one unapproved payout
Payout lifecycle
Funds are held against available balance before the provider is called, so a