One Express process.
Five money providers. One ledger of truth.

The whole system, one diagram.

Express is the single Node process. A handful of external providers handle money, identity, comms, and AI. Postgres is the system of record; an HSM holds crypto keys.

One process, by design. No microservices. No queue. No Redis (yet). The advisory lock on master-balance allocation lives in Postgres. Widget approval state lives in a single in-memory Map — and yes, it's lost on restart. The Redis migration is tracked.

The ledger is the truth

Balance is never stored. It's computed by aggregation against the append-only agent_wallet_transactions table:

SELECT SUM(amount) FILTER (WHERE type IN ('credit','refund','release','transfer_in','settlement_credit','settlement_refund')AND status = 'completed') -SUM(amount) FILTER (WHERE type IN ('debit','hold','transfer_out','settlement_debit')AND status = 'completed') AS balanceFROM agent_wallet_transactionsWHERE agent_identity_id = $1;

Transaction types

Wallet service. Two implementations. One ledger.

Two wallet implementations coexist: the legacy WalletStorage and the canonical agent-wallet.storage.ts. New code uses the canonical path. Both write to agent_wallet_transactions.

allocateWalletFunds — the canonical credit path

This is the function that enforces master-balance headroom. It uses a Postgres advisory lock to serialize concurrent allocations against the same client master:

async function allocateWalletFunds(params) {return db.transaction(async tx => {// 1. Acquire advisory lock on the clientawait tx.execute(sql`SELECT pg_advisory_xact_lock(${hashClientId})`);// 2. Re-read master balance INSIDE the lockconst master = await getClientMasterBalance(tx, clientId);if (master.available < amountCents) {throw new Error('INSUFFICIENT_MASTER_BALANCE');}// 3. Insert ledger credit (atomic with the lock)await tx.insert(agentWalletTransactions).values({agentIdentityId, clientId, type: 'credit', amount: amountCents / 100, status: 'completed', reference, description,});});}

Why aggregate? Why not store balance?

• Single source of truth. The ledger row IS the change. No reconciliation between a balance column and the entries that made it.
• Audit-perfect by construction. Every cent is a row. Balance discrepancies become "find the missing row," not "which is right."
• Concurrent-safe. Inserts are atomic. Aggregate reads run inside the same SERIALIZABLE transaction as the headroom check — no negative-balance race.

Funding paths. Six ways money lands.

An agent's wallet receives funds through six distinct paths. Each writes a row to agent_wallet_transactions with a reference that traces back to the source.

One activity feed. Every system, in order.

The Activity tab in the Agent Portal shows a unified timeline merging six sources: ledger entries, payouts, card transactions, inbound/outbound messages, MCP tool calls, and approvals. Each row references the underlying record.

Sources merged into the unified feed

Card-level filter

To answer "how much did Agent 009 spend on its card last month," the unified feed filters agent_wallet_transactions by cardId IS NOT NULL and aggregates:

SELECT SUM(amount) AS card_spendFROM agent_wallet_transactionsWHERE agent_identity_id = $1AND card_id IS NOT NULLAND status = 'completed'AND created_at >= date_trunc('month', now());