AgentWallet ·

Documentation

The Master Technical Reference for AgentWallet — 18 chapters covering every route, every schema, every mandate type, every rail, every gate, every idempotency rule and every edge case actually in production. Written by the engineers who shipped it. Each chapter is tagged with status — ✓ shipped (in production right now, pen-tested where applicable, used in customer pipelines), ◔ partial / known gap (two paths exist; one is canonical and one is being aligned; we name the bypass and link the task), ○ planned / tracked (defined, scoped in .local/tasks/, not deployed, we don't claim it). 192 Postgres tables, 1,100+ platform tools, ~15 per-agent MCP tools, 4 payment rails, 3 mandate types — all documented with the same honesty.

  • Chapter 01 — Product Overview & Domain Model. Actors, agent lifecycle, multi-tenant scoping, RBAC, capability cascade. Principals, clients, RBAC roles (viewer / funder / policy / approver / admin).
  • Chapter 02 — Data Model. ~192 Postgres tables. agent_identities (the core entity with 12 FK children), fiat ledger, AP2 mandates, communication tables. Drizzle ORM throughout.
  • Chapter 03 — Wallet Service. Double-entry ledger. Balance is computed by SUM-with-FILTER aggregation, never stored. Postgres advisory locks for master-balance headroom. Two implementations coexist; canonical is agent-wallet.storage.ts.
  • Chapter 04 — Funding, Top-up & Payouts. Six funding paths (manual Principal, manual admin, bank inbound, settlement credit, card refund, opening balance). Payout rails: ACH, SEPA, Pix, UPI, Wire, SWIFT and 11 more. USDC on/off-ramps via Bridge.xyz.
  • Chapter 05 — Approvals & Execution Gates. Per-transaction → daily (rolling 24h) → monthly (rolling 30d) velocity caps evaluated in order. Auto-approve under threshold. Force-approve admin override with double audit logging.
  • Chapter 06 — Agent Portal Frontend. React + TanStack Query. Magic-link OTP auth (no passwords). 17 tabs from Overview through Settings, all driven by the same Principal-scoped API.
  • Chapter 07 — Agent Portal Backend. Express routes mounted at /api/agent-portal, gated by verifyAgentAccess middleware (Principal session + agent_principal_links role check on every request).
  • Chapter 08 — Communication Channels. Per-agent phone (E.164), SMS, email (IMAP+SMTP), WhatsApp Business with template approval handled. AgentSim for phone/SMS, AgentMail for email. Inbound routed into the unified activity feed.
  • Chapter 09 — MCP Surface. The per-agent MCP server at /mcp/agent. JSON-RPC over HTTP. Discovery via /.well-known/agent.json. ~15 typed tools per agent, scoped to one agent_identities row, authenticated by pak_… bearer.
  • Chapter 10 — ACP, A2A & External Tool APIs. x402 over EIP-3009 USDC on Base. Shared Payment Tokens for card-rail merchants. PCI-vaulted card tokens for everyone else. /.well-known/agent.json discovery contract.
  • Chapter 11 — AP2 & Payment Rails. ES256 mandate chain: IntentMandate → CartMandate → PaymentMandate. JWS structure, sign/verify with jose, inbound verification flow (resolve issuer → strict ES256 verify → chain check → policy check → audit → execute). EIP-3009 USDC on Base for x402.
  • Chapter 12 — Invoice & Purchase Pipelines. Invoice ingestion via email parse / manual upload / bulk CSV (up to 500 invoices in one CSV). Five-state machine: received → blocked → pending → scheduled → paid. KYB blockers for incomplete vendor verification.
  • Chapter 13 — Activity & Ledger. Unified activity feed merging seven append-only sources: agent_wallet_transactions, payouts, cards.transactions, agent_inbox_messages, agent_outbox_messages, agent_identity_activity_log, ap2_mandate_audit. Card-level filters via cardId IS NOT NULL.
  • Chapter 14 — Security, Secrets & Compliance. Three secret classes (card PAN / crypto key / AP2 key). VGS tokenization. CDP HSM custody. AES-256-GCM for AP2 keys. Append-only audit. SOC 2 Type II.
  • Chapter 15 — Operations. Deployment topology (one Node process, Postgres serverless, no queue, no Redis yet). Environment variables (DATABASE_URL, CDP_API_KEY_NAME, CDP_PRIVATE_KEY, X402_WALLET_ADDRESS, AP2_KEY_ENCRYPTION_KEY, STRIPE_SECRET_KEY, AIRWALLEX_API_KEY, AGENTSIM_API_KEY, AGENTMAIL_API_KEY, VGS_VAULT_ID, etc.). Runbooks for every common failure.
  • Chapter 16 — Testing & QA. AP2 smoke test (happy path) shipped. Wallet allocateFunds advisory lock concurrency test shipped. RBAC verifyAgentAccess unit matrix (6 roles × 12 endpoints) shipped. x402 EIP-3009 sign roundtrip partial (manual + Base Sepolia). End-to-end Playwright, chaos tests, 1k MCP load test all planned and tracked.
  • Chapter 17 — Roadmap & Open Work. Everything we've shipped, what's in flight, what's tracked. Honest list with status flags. Includes the 5 published open risks (R-01 through R-05).
  • Chapter 18 — Glossary & Index. Principal vs Client. Agent vs Tenant. The terms we use, consistently, with cross-references back to the chapter that defines each.

Frequently asked questions

How are the AgentWallet docs structured?
18 chapters grouped into four paths — developer (Chapters 01, 02, 09, 10, 11), security (14, 15, 16), operations (15 runbooks, 17 roadmap), and architecture (03, 04, 13). Each chapter is tagged ✓ shipped, ◔ partial / known gap, or ○ planned / tracked. You can read in order, follow a path, or land on the chapter that matches your question via /docs/ch/<n>.
What's the difference between ✓ shipped, ◔ partial, and ○ planned?
✓ shipped = in production right now, pen-tested where applicable, used in customer pipelines. ◔ partial = two paths exist (canonical + legacy) and we're aligning them; we name the bypass in the docs. ○ planned = scoped in our task tracker, not deployed; we don't claim it works. We use the same tags in chapter 17 (Roadmap) and on every code-reference in the technical chapters.
Where is the API reference?
Per-route in the chapter that owns the route (e.g. /agents under Chapter 07, /mcp/agent under Chapter 09, /ap2/v1/payment under Chapter 11), plus a machine-readable OpenAPI spec at /docs/openapi.yaml that you can generate idiomatic clients from in any language. The TypeScript SDK is generated from the same spec.
Are the open risks really in the public docs?
Yes — Chapter 14 (Security) lists R-01 through R-05 with descriptions, mitigations and fix plans. Why? Because every payments platform has known-knowns and most pretend they don't; we'd rather be the platform whose customer security review goes 'we already saw all of this in the public docs' than the one whose risks surface during a procurement red-team.