@framers/agentos-ext-wallet 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,146 @@
+/**
+ * @fileoverview Wallet types, spending policy, and category definitions
+ * for the Agent Personal Wallet system.
+ *
+ * Enables Wunderland agents to autonomously spend within user-configured
+ * guardrails — covering crypto (Solana + EVM) and virtual cards (Lithic).
+ *
+ * @module wunderland/wallet/types
+ */
+export type ChainId = 'solana' | 'ethereum' | 'base' | 'polygon';
+export type TokenSymbol = 'SOL' | 'ETH' | 'USDC' | 'USDT';
+/** Token metadata for a specific chain deployment. */
+export interface TokenInfo {
+    symbol: TokenSymbol;
+    chain: ChainId;
+    /** Mint address (Solana SPL) or contract address (ERC-20). Empty for native tokens. */
+    address: string;
+    decimals: number;
+    /** CoinGecko ID for price lookups. */
+    coingeckoId?: string;
+}
+/**
+ * Spend categories used for budget enforcement and card MCC mapping.
+ *
+ * Crypto categories: api_costs, web_services, subscriptions, transfers, defi
+ * Card categories: shopping, dining, travel, entertainment, utilities
+ * Catch-all: other
+ */
+export type SpendCategory = 'api_costs' | 'web_services' | 'shopping' | 'subscriptions' | 'transfers' | 'defi' | 'dining' | 'travel' | 'entertainment' | 'utilities' | 'other';
+export interface CategoryBudget {
+    category: SpendCategory;
+    /** Max daily spend in USD for this category. */
+    dailyLimitUsd: number;
+    /** Max monthly spend in USD for this category. */
+    monthlyLimitUsd: number;
+}
+export interface SpendingPolicyConfig {
+    /** Global daily spending cap in USD across all categories. */
+    dailyLimitUsd: number;
+    /** Max single transaction amount in USD. */
+    perTransactionLimitUsd: number;
+    /** Global monthly spending cap in USD. */
+    monthlyLimitUsd: number;
+    /** Per-category budget overrides. Categories not listed inherit global limits. */
+    categoryBudgets: CategoryBudget[];
+    /** Transactions above this USD amount require human approval. */
+    requireApprovalAboveUsd: number;
+    /** Categories the agent is completely blocked from spending in. */
+    blockedCategories: SpendCategory[];
+    /** Crypto address whitelist — if set, only these addresses can receive funds. */
+    allowedAddresses?: string[];
+    /** Crypto address blacklist — these addresses are always blocked. */
+    blockedAddresses?: string[];
+}
+export interface WalletConfig {
+    /** Master switch for wallet functionality. */
+    enabled: boolean;
+    /** Which chains the agent has wallets on. */
+    chains: ChainId[];
+    /**
+     * Key custody mode:
+     * - hot: plaintext in memory (dev/testing only)
+     * - encrypted-hot: AES-256-GCM encrypted at rest, decrypted on sign
+     */
+    custodyMode: 'hot' | 'encrypted-hot';
+    /** Tokens the agent is allowed to hold/send. */
+    allowedTokens: TokenSymbol[];
+    /** Spending guardrails. */
+    spendingPolicy: SpendingPolicyConfig;
+    /** Virtual card configuration (Lithic). */
+    card?: import('./cards/types.js').CardConfig;
+}
+export type WalletDirection = 'inbound' | 'outbound';
+export type WalletTxStatus = 'pending' | 'confirmed' | 'failed';
+export interface AgentWalletRecord {
+    id: string;
+    agentId: string;
+    chain: ChainId;
+    /** Public address (base58 for Solana, 0x-prefixed hex for EVM). */
+    address: string;
+    /** AES-256-GCM encrypted private key (base64). */
+    encryptedKey: string;
+    /** Salt used for key derivation (hex). */
+    keyDerivationSalt: string;
+    createdAt: number;
+}
+export interface WalletTransactionRecord {
+    id: string;
+    walletId: string;
+    txHash?: string;
+    direction: WalletDirection;
+    toAddress?: string;
+    fromAddress?: string;
+    /** Raw token amount as string (lamports, wei, etc.). */
+    amountRaw: string;
+    /** USD equivalent at time of transaction. */
+    amountUsd?: number;
+    token: TokenSymbol;
+    category?: SpendCategory;
+    status: WalletTxStatus;
+    description?: string;
+    createdAt: number;
+}
+export interface SpendingLedgerEntry {
+    id: string;
+    agentId: string;
+    category: SpendCategory;
+    amountUsd: number;
+    /** Date key: 'YYYY-MM-DD' for daily, 'YYYY-MM' for monthly. */
+    periodKey: string;
+    createdAt: number;
+}
+export interface SpendCheckResult {
+    allowed: boolean;
+    /** Human-readable reason if blocked. */
+    reason?: string;
+    /** True if the transaction needs explicit human approval (above threshold but within limits). */
+    requiresApproval?: boolean;
+    /** Remaining daily budget in USD after this transaction (if allowed). */
+    remainingDailyUsd?: number;
+    /** Remaining monthly budget in USD after this transaction (if allowed). */
+    remainingMonthlyUsd?: number;
+}
+export interface IChainWalletAdapter {
+    readonly chain: ChainId;
+    /** Generate a new keypair. Returns { publicKey, secretKey (raw bytes) }. */
+    generateKeypair(): Promise<{
+        publicKey: string;
+        secretKey: Uint8Array;
+    }>;
+    /** Get native token balance in raw units (lamports, wei). */
+    getBalance(address: string): Promise<bigint>;
+    /** Get SPL/ERC-20 token balance in raw units. */
+    getTokenBalance(address: string, tokenMint: string): Promise<bigint>;
+    /** Build and sign a native transfer transaction. Returns serialized signed tx. */
+    signTransfer(secretKey: Uint8Array, to: string, amountRaw: bigint): Promise<Uint8Array>;
+    /** Build and sign a token transfer. Returns serialized signed tx. */
+    signTokenTransfer(secretKey: Uint8Array, to: string, tokenMint: string, amountRaw: bigint): Promise<Uint8Array>;
+    /** Broadcast a signed transaction and return the tx hash. */
+    broadcast(signedTx: Uint8Array): Promise<string>;
+    /** Check if a transaction is confirmed. */
+    getTransactionStatus(txHash: string): Promise<WalletTxStatus>;
+}
+export declare const DEFAULT_SPENDING_POLICY: SpendingPolicyConfig;
+export declare const DEFAULT_WALLET_CONFIG: WalletConfig;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AACA;;;;;;;;GAQG;AAMH,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,SAAS,CAAC;AAEjE,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1D,sDAAsD;AACtD,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,uFAAuF;IACvF,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAMD;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,cAAc,GACd,UAAU,GACV,eAAe,GACf,WAAW,GACX,MAAM,GACN,QAAQ,GACR,QAAQ,GACR,eAAe,GACf,WAAW,GACX,OAAO,CAAC;AAEZ,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,aAAa,CAAC;IACxB,gDAAgD;IAChD,aAAa,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,eAAe,EAAE,MAAM,CAAC;CACzB;AAMD,MAAM,WAAW,oBAAoB;IACnC,8DAA8D;IAC9D,aAAa,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,sBAAsB,EAAE,MAAM,CAAC;IAC/B,0CAA0C;IAC1C,eAAe,EAAE,MAAM,CAAC;IACxB,kFAAkF;IAClF,eAAe,EAAE,cAAc,EAAE,CAAC;IAClC,iEAAiE;IACjE,uBAAuB,EAAE,MAAM,CAAC;IAChC,mEAAmE;IACnE,iBAAiB,EAAE,aAAa,EAAE,CAAC;IACnC,iFAAiF;IACjF,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B;AAMD,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,6CAA6C;IAC7C,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB;;;;OAIG;IACH,WAAW,EAAE,KAAK,GAAG,eAAe,CAAC;IACrC,gDAAgD;IAChD,aAAa,EAAE,WAAW,EAAE,CAAC;IAC7B,2BAA2B;IAC3B,cAAc,EAAE,oBAAoB,CAAC;IACrC,2CAA2C;IAC3C,IAAI,CAAC,EAAE,OAAO,kBAAkB,EAAE,UAAU,CAAC;CAC9C;AAMD,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,UAAU,CAAC;AACrD,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEhE,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,eAAe,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,MAAM,EAAE,cAAc,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,aAAa,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iGAAiG;IACjG,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,yEAAyE;IACzE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,2EAA2E;IAC3E,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAMD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAExB,4EAA4E;IAC5E,eAAe,IAAI,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,UAAU,CAAA;KAAE,CAAC,CAAC;IAEzE,6DAA6D;IAC7D,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE7C,iDAAiD;IACjD,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAErE,kFAAkF;IAClF,YAAY,CACV,SAAS,EAAE,UAAU,EACrB,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,CAAC,CAAC;IAEvB,qEAAqE;IACrE,iBAAiB,CACf,SAAS,EAAE,UAAU,EACrB,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,CAAC,CAAC;IAEvB,6DAA6D;IAC7D,SAAS,CAAC,QAAQ,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEjD,2CAA2C;IAC3C,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC/D;AAMD,eAAO,MAAM,uBAAuB,EAAE,oBAOrC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,YAMnC,CAAC"}

package/dist/types.js

@@ -0,0 +1,29 @@
+// @ts-nocheck
+/**
+ * @fileoverview Wallet types, spending policy, and category definitions
+ * for the Agent Personal Wallet system.
+ *
+ * Enables Wunderland agents to autonomously spend within user-configured
+ * guardrails — covering crypto (Solana + EVM) and virtual cards (Lithic).
+ *
+ * @module wunderland/wallet/types
+ */
+// ---------------------------------------------------------------------------
+// Default spending policy
+// ---------------------------------------------------------------------------
+export const DEFAULT_SPENDING_POLICY = {
+    dailyLimitUsd: 50,
+    perTransactionLimitUsd: 20,
+    monthlyLimitUsd: 500,
+    categoryBudgets: [],
+    requireApprovalAboveUsd: 10,
+    blockedCategories: [],
+};
+export const DEFAULT_WALLET_CONFIG = {
+    enabled: false,
+    chains: ['solana'],
+    custodyMode: 'encrypted-hot',
+    allowedTokens: ['SOL', 'USDC'],
+    spendingPolicy: DEFAULT_SPENDING_POLICY,
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,cAAc;AACd;;;;;;;;GAQG;AAyMH,8EAA8E;AAC9E,0BAA0B;AAC1B,8EAA8E;AAE9E,MAAM,CAAC,MAAM,uBAAuB,GAAyB;IAC3D,aAAa,EAAE,EAAE;IACjB,sBAAsB,EAAE,EAAE;IAC1B,eAAe,EAAE,GAAG;IACpB,eAAe,EAAE,EAAE;IACnB,uBAAuB,EAAE,EAAE;IAC3B,iBAAiB,EAAE,EAAE;CACtB,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAiB;IACjD,OAAO,EAAE,KAAK;IACd,MAAM,EAAE,CAAC,QAAQ,CAAC;IAClB,WAAW,EAAE,eAAe;IAC5B,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC;IAC9B,cAAc,EAAE,uBAAuB;CACxC,CAAC"}

package/manifest.json

@@ -0,0 +1,98 @@
+{
+  "$schema": "https://agentos.sh/schemas/extension-manifest-v1.json",
+  "id": "com.framers.tools.wallet",
+  "name": "Agent Personal Wallet",
+  "version": "0.2.0",
+  "description": "Give agents their own personal wallet with configurable spending guardrails. Supports Solana, Ethereum, Base, and Polygon with per-category budgets, daily/monthly limits, human-in-the-loop approval thresholds, and Lithic virtual card integration.",
+  "author": {
+    "name": "Frame.dev",
+    "email": "support@frame.dev",
+    "url": "https://github.com/framersai"
+  },
+  "license": "MIT",
+  "keywords": ["wallet", "crypto", "solana", "ethereum", "spending-policy", "guardrails", "defi", "card", "lithic", "virtual-card"],
+  "agentosVersion": "^2.0.0",
+  "categories": ["tool", "finance"],
+  "platforms": [],
+  "sdk": "none",
+  "extensions": [
+    {
+      "kind": "tool",
+      "id": "check_wallet_balance",
+      "displayName": "Check Wallet Balance",
+      "description": "Check the balance of the agent's personal wallet on a given blockchain",
+      "entry": "./dist/tools/CheckBalanceTool.js"
+    },
+    {
+      "kind": "tool",
+      "id": "send_crypto",
+      "displayName": "Send Crypto",
+      "description": "Send cryptocurrency with spending policy enforcement",
+      "entry": "./dist/tools/SendCryptoTool.js"
+    },
+    {
+      "kind": "tool",
+      "id": "wallet_transaction_history",
+      "displayName": "Wallet Transaction History",
+      "description": "View recent transaction history for the agent's wallet",
+      "entry": "./dist/tools/WalletHistoryTool.js"
+    },
+    {
+      "kind": "tool",
+      "id": "issue_virtual_card",
+      "displayName": "Issue Virtual Card",
+      "description": "Issue a new Lithic virtual debit card for the agent with configurable spending limits",
+      "entry": "./dist/tools/IssueCardTool.js"
+    },
+    {
+      "kind": "tool",
+      "id": "card_status",
+      "displayName": "Card Status",
+      "description": "Get the current status of the agent's virtual card",
+      "entry": "./dist/tools/CardStatusTool.js"
+    },
+    {
+      "kind": "tool",
+      "id": "freeze_card",
+      "displayName": "Freeze Card",
+      "description": "Temporarily freeze the agent's virtual card to pause all transactions",
+      "entry": "./dist/tools/FreezeCardTool.js"
+    },
+    {
+      "kind": "tool",
+      "id": "unfreeze_card",
+      "displayName": "Unfreeze Card",
+      "description": "Resume the agent's virtual card after it was frozen",
+      "entry": "./dist/tools/UnfreezeCardTool.js"
+    },
+    {
+      "kind": "tool",
+      "id": "card_spending_summary",
+      "displayName": "Card Spending Summary",
+      "description": "Get a spending breakdown by category for the agent's virtual card",
+      "entry": "./dist/tools/CardSpendingSummaryTool.js"
+    },
+    {
+      "kind": "tool",
+      "id": "pay_with_card",
+      "displayName": "Pay With Card",
+      "description": "Retrieve card details (PAN, CVV, expiry) for online payments with spending policy enforcement",
+      "entry": "./dist/tools/PayWithCardTool.js"
+    }
+  ],
+  "requiredSecrets": ["WALLET_MASTER_SECRET"],
+  "optionalSecrets": ["LITHIC_API_KEY", "LITHIC_WEBHOOK_SECRET"],
+  "features": [
+    "Multi-chain support (Solana, Ethereum, Base, Polygon)",
+    "AES-256-GCM encrypted key storage",
+    "Configurable spending guardrails per category",
+    "Daily, monthly, and per-transaction limits",
+    "Human-in-the-loop approval for high-value transactions",
+    "Address whitelists and blacklists",
+    "Native token and SPL/ERC-20 token transfers",
+    "Lithic virtual debit card issuance",
+    "MCC-based category mapping for card transactions",
+    "Card freeze/unfreeze controls",
+    "Card spending summary by category"
+  ]
+}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@framers/agentos-ext-wallet",
+  "version": "0.2.0",
+  "description": "Agent Personal Wallet — autonomous crypto spending with guardrails, multi-chain support (Solana + EVM), and virtual card integration.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "sideEffects": true,
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./manifest.json": "./manifest.json",
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "agentos",
+    "extension",
+    "wallet",
+    "crypto",
+    "solana",
+    "ethereum",
+    "spending-policy",
+    "guardrails"
+  ],
+  "author": {
+    "name": "Frame.dev",
+    "email": "support@frame.dev",
+    "url": "https://github.com/framersai"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "uuid": "^9.0.0"
+  },
+  "peerDependencies": {
+    "@framers/agentos": "^0.5.2",
+    "@solana/web3.js": "^1.0.0",
+    "@solana/spl-token": "^0.3.0",
+    "ethers": "^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@solana/web3.js": {
+      "optional": true
+    },
+    "@solana/spl-token": {
+      "optional": true
+    },
+    "ethers": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@types/uuid": "^9.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/framersai/agentos-extensions.git",
+    "directory": "registry/curated/tools/wallet"
+  },
+  "homepage": "https://github.com/framersai/agentos-extensions/tree/master/registry/curated/tools/wallet#readme",
+  "bugs": {
+    "url": "https://github.com/framersai/agentos-extensions/issues"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist"
+  }
+}

package/src/AgentWalletManager.ts

@@ -0,0 +1,324 @@
+// @ts-nocheck
+/**
+ * @fileoverview Core wallet lifecycle manager for agent personal wallets.
+ *
+ * Handles keypair generation, encrypted storage, balance queries, transaction
+ * signing, and broadcasting across multiple chains. Works with the
+ * SpendingPolicyEnforcer for guardrailed autonomous spending.
+ *
+ * @module wunderland/wallet/AgentWalletManager
+ */
+
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'node:crypto';
+import { v4 as uuidv4 } from 'uuid';
+
+import type {
+  AgentWalletRecord,
+  ChainId,
+  IChainWalletAdapter,
+  SpendCategory,
+  TokenSymbol,
+  WalletConfig,
+  WalletTransactionRecord,
+  WalletTxStatus,
+} from './types.js';
+import type { SpendingPolicyEnforcer } from './SpendingPolicyEnforcer.js';
+
+// ---------------------------------------------------------------------------
+// DB store interface (agnostic — callers provide SQLite/Postgres impl)
+// ---------------------------------------------------------------------------
+
+export interface IWalletStore {
+  getWallet(agentId: string, chain: ChainId): Promise<AgentWalletRecord | null>;
+  getAllWallets(agentId: string): Promise<AgentWalletRecord[]>;
+  saveWallet(record: AgentWalletRecord): Promise<void>;
+  insertTransaction(record: WalletTransactionRecord): Promise<void>;
+  updateTransactionStatus(id: string, status: WalletTxStatus, txHash?: string): Promise<void>;
+  getTransactions(walletId: string, limit?: number): Promise<WalletTransactionRecord[]>;
+}
+
+// ---------------------------------------------------------------------------
+// Encryption helpers
+// ---------------------------------------------------------------------------
+
+const ALGO = 'aes-256-gcm';
+const KEY_LEN = 32;
+const IV_LEN = 12;
+const TAG_LEN = 16;
+const SCRYPT_N = 16384;
+
+/** Derive a 256-bit key from a master secret + salt. */
+function deriveKey(masterSecret: string, salt: Buffer): Buffer {
+  return scryptSync(masterSecret, salt, KEY_LEN, { N: SCRYPT_N }) as Buffer;
+}
+
+/** Encrypt raw bytes → base64 string (IV + ciphertext + authTag). */
+function encrypt(data: Uint8Array, masterSecret: string, salt: Buffer): string {
+  const key = deriveKey(masterSecret, salt);
+  const iv = randomBytes(IV_LEN);
+  const cipher = createCipheriv(ALGO, key, iv);
+  const encrypted = Buffer.concat([cipher.update(data), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  // Pack: IV (12) + Tag (16) + Ciphertext
+  return Buffer.concat([iv, tag, encrypted]).toString('base64');
+}
+
+/** Decrypt base64 string → raw bytes. */
+function decrypt(packed: string, masterSecret: string, salt: Buffer): Uint8Array {
+  const buf = Buffer.from(packed, 'base64');
+  const iv = buf.subarray(0, IV_LEN);
+  const tag = buf.subarray(IV_LEN, IV_LEN + TAG_LEN);
+  const ciphertext = buf.subarray(IV_LEN + TAG_LEN);
+  const key = deriveKey(masterSecret, salt);
+  const decipher = createDecipheriv(ALGO, key, iv);
+  decipher.setAuthTag(tag);
+  const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+  return new Uint8Array(decrypted);
+}
+
+// ---------------------------------------------------------------------------
+// AgentWalletManager
+// ---------------------------------------------------------------------------
+
+export interface AgentWalletManagerOptions {
+  /** Master secret for key encryption. Should come from env (WALLET_MASTER_SECRET). */
+  masterSecret: string;
+  walletConfig: WalletConfig;
+  store: IWalletStore;
+  policyEnforcer: SpendingPolicyEnforcer;
+  /** Chain adapters keyed by ChainId. */
+  adapters: Map<ChainId, IChainWalletAdapter>;
+}
+
+export class AgentWalletManager {
+  private readonly masterSecret: string;
+  readonly walletConfig: WalletConfig;
+  private readonly store: IWalletStore;
+  private readonly policy: SpendingPolicyEnforcer;
+  private readonly adapters: Map<ChainId, IChainWalletAdapter>;
+
+  /** In-memory balance cache: `${agentId}:${chain}:${token}` → { value, ts }. */
+  private balanceCache = new Map<string, { value: bigint; ts: number }>();
+  private readonly cacheTtlMs = 30_000;
+
+  constructor(opts: AgentWalletManagerOptions) {
+    this.masterSecret = opts.masterSecret;
+    this.walletConfig = opts.walletConfig;
+    this.store = opts.store;
+    this.policy = opts.policyEnforcer;
+    this.adapters = opts.adapters;
+  }
+
+  // -----------------------------------------------------------------------
+  // Wallet lifecycle
+  // -----------------------------------------------------------------------
+
+  /** Create a new wallet for the agent on the specified chain. */
+  async createWallet(agentId: string, chain: ChainId): Promise<AgentWalletRecord> {
+    const adapter = this.getAdapter(chain);
+
+    // Check if wallet already exists
+    const existing = await this.store.getWallet(agentId, chain);
+    if (existing) {
+      throw new Error(`Agent ${agentId} already has a ${chain} wallet at ${existing.address}`);
+    }
+
+    const { publicKey, secretKey } = await adapter.generateKeypair();
+
+    // Encrypt the secret key
+    const salt = randomBytes(32);
+    const encryptedKey = encrypt(secretKey, this.masterSecret, salt);
+
+    const record: AgentWalletRecord = {
+      id: uuidv4(),
+      agentId,
+      chain,
+      address: publicKey,
+      encryptedKey,
+      keyDerivationSalt: salt.toString('hex'),
+      createdAt: Date.now(),
+    };
+
+    await this.store.saveWallet(record);
+    return record;
+  }
+
+  /** Get an existing wallet or null. */
+  async getWallet(agentId: string, chain: ChainId): Promise<AgentWalletRecord | null> {
+    return this.store.getWallet(agentId, chain);
+  }
+
+  /** Get all wallets for an agent. */
+  async getAllWallets(agentId: string): Promise<AgentWalletRecord[]> {
+    return this.store.getAllWallets(agentId);
+  }
+
+  // -----------------------------------------------------------------------
+  // Balance queries (cached)
+  // -----------------------------------------------------------------------
+
+  /** Get native token balance (e.g. SOL, ETH). */
+  async getBalance(agentId: string, chain: ChainId): Promise<bigint> {
+    const wallet = await this.requireWallet(agentId, chain);
+    const cacheKey = `${agentId}:${chain}:native`;
+    const cached = this.balanceCache.get(cacheKey);
+    if (cached && Date.now() - cached.ts < this.cacheTtlMs) return cached.value;
+
+    const adapter = this.getAdapter(chain);
+    const balance = await adapter.getBalance(wallet.address);
+    this.balanceCache.set(cacheKey, { value: balance, ts: Date.now() });
+    return balance;
+  }
+
+  /** Get token balance (e.g. USDC on Solana). */
+  async getTokenBalance(agentId: string, chain: ChainId, tokenMint: string): Promise<bigint> {
+    const wallet = await this.requireWallet(agentId, chain);
+    const cacheKey = `${agentId}:${chain}:${tokenMint}`;
+    const cached = this.balanceCache.get(cacheKey);
+    if (cached && Date.now() - cached.ts < this.cacheTtlMs) return cached.value;
+
+    const adapter = this.getAdapter(chain);
+    const balance = await adapter.getTokenBalance(wallet.address, tokenMint);
+    this.balanceCache.set(cacheKey, { value: balance, ts: Date.now() });
+    return balance;
+  }
+
+  // -----------------------------------------------------------------------
+  // Spending (with policy enforcement)
+  // -----------------------------------------------------------------------
+
+  /**
+   * Send native token with spending policy enforcement.
+   * Returns the transaction record (pending until broadcast confirms).
+   */
+  async sendNative(
+    agentId: string,
+    chain: ChainId,
+    to: string,
+    amountRaw: bigint,
+    amountUsd: number,
+    category: SpendCategory,
+    description?: string,
+  ): Promise<WalletTransactionRecord> {
+    // Enforce spending policy
+    const check = await this.policy.canSpend(agentId, amountUsd, category, to);
+    if (!check.allowed) {
+      throw new SpendingPolicyViolation(check.reason || 'Spending policy violation');
+    }
+    if (check.requiresApproval) {
+      throw new ApprovalRequiredError(amountUsd, category);
+    }
+
+    const wallet = await this.requireWallet(agentId, chain);
+    const adapter = this.getAdapter(chain);
+    const secretKey = this.decryptKey(wallet);
+
+    // Create pending transaction record
+    const txRecord: WalletTransactionRecord = {
+      id: uuidv4(),
+      walletId: wallet.id,
+      direction: 'outbound',
+      toAddress: to,
+      fromAddress: wallet.address,
+      amountRaw: amountRaw.toString(),
+      amountUsd,
+      token: nativeTokenForChain(chain),
+      category,
+      status: 'pending',
+      description,
+      createdAt: Date.now(),
+    };
+    await this.store.insertTransaction(txRecord);
+
+    try {
+      // Sign and broadcast
+      const signedTx = await adapter.signTransfer(secretKey, to, amountRaw);
+      const txHash = await adapter.broadcast(signedTx);
+
+      // Update record
+      await this.store.updateTransactionStatus(txRecord.id, 'confirmed', txHash);
+      txRecord.status = 'confirmed';
+      txRecord.txHash = txHash;
+
+      // Record in spending ledger
+      await this.policy.recordSpend(agentId, amountUsd, category);
+
+      // Invalidate balance cache
+      this.balanceCache.delete(`${agentId}:${chain}:native`);
+    } catch (err) {
+      await this.store.updateTransactionStatus(txRecord.id, 'failed');
+      txRecord.status = 'failed';
+      throw err;
+    }
+
+    return txRecord;
+  }
+
+  /** Get recent transactions for a wallet. */
+  async getTransactionHistory(agentId: string, chain: ChainId, limit = 20): Promise<WalletTransactionRecord[]> {
+    const wallet = await this.requireWallet(agentId, chain);
+    return this.store.getTransactions(wallet.id, limit);
+  }
+
+  // -----------------------------------------------------------------------
+  // Internal helpers
+  // -----------------------------------------------------------------------
+
+  private getAdapter(chain: ChainId): IChainWalletAdapter {
+    const adapter = this.adapters.get(chain);
+    if (!adapter) {
+      throw new Error(`No wallet adapter registered for chain: ${chain}`);
+    }
+    return adapter;
+  }
+
+  private async requireWallet(agentId: string, chain: ChainId): Promise<AgentWalletRecord> {
+    const wallet = await this.store.getWallet(agentId, chain);
+    if (!wallet) {
+      throw new Error(`No ${chain} wallet found for agent ${agentId}. Create one first.`);
+    }
+    return wallet;
+  }
+
+  private decryptKey(wallet: AgentWalletRecord): Uint8Array {
+    const salt = Buffer.from(wallet.keyDerivationSalt, 'hex');
+    return decrypt(wallet.encryptedKey, this.masterSecret, salt);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Error classes
+// ---------------------------------------------------------------------------
+
+export class SpendingPolicyViolation extends Error {
+  constructor(reason: string) {
+    super(reason);
+    this.name = 'SpendingPolicyViolation';
+  }
+}
+
+export class ApprovalRequiredError extends Error {
+  constructor(
+    public readonly amountUsd: number,
+    public readonly category: SpendCategory,
+  ) {
+    super(
+      `Transaction of $${amountUsd.toFixed(2)} in category "${category}" requires human approval.`,
+    );
+    this.name = 'ApprovalRequiredError';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Utility
+// ---------------------------------------------------------------------------
+
+function nativeTokenForChain(chain: ChainId): TokenSymbol {
+  switch (chain) {
+    case 'solana': return 'SOL';
+    case 'ethereum': return 'ETH';
+    case 'base': return 'ETH';
+    case 'polygon': return 'ETH'; // MATIC wraps to ETH for simplicity
+    default: return 'ETH';
+  }
+}