@te-btc/agent-wallet

Agent-native Cashu wallet for Node.js/Bun. Purpose-built for AI agent micropayments — not a browser wallet.

What

A programmatic Cashu wallet designed for machine-to-machine payments. Handles proof-of-service token generation, budget enforcement, streaming micropayments, and conditional token workflows. Built on Coco for multi-mint state management with better-sqlite3 for high-velocity proof storage.

Status

v0.1.0 — Production-ready (169 tests passing, dual ESM/CJS build)

Quick Start

import { AgentWallet } from '@te-btc/agent-wallet';

const wallet = new AgentWallet({
  mintUrl: 'https://mint.arxmint.io',
  budget: { dailySats: 10000, perRequestSats: 500 },
  storage: 'sqlite', // or 'memory' for ephemeral agents
});

await wallet.fund(50000);                        // mint via LN invoice
await wallet.payL402(invoiceUrl);                 // atomic L402 payment
const receipt = await wallet.payForService(task); // PoS-locked conditional payment
wallet.exportAuditLog();                          // every sat accounted for

Key Features

| Feature | Description | |---------|-------------| | Proof pool management | Background consolidation/splitting to maintain exact-change capability for streaming micropayments | | Policy engine | Hold → settle → release lifecycle. Hard spend caps, capability allowlists, velocity circuit breakers | | Budget enforcement | Daily/per-request sat limits. Rejects operations exceeding limits before any network call | | Conditional tokens | PoS (proof-of-service), escrow (2-of-3 multisig), time-locked subscriptions — when connected to ArxMint mint | | Key isolation | Private keys never share memory with LLM. LN: Remote Signer (restricted Macaroon over LNC). Cashu: TEE/MPC for bearer proof protection | | Disaster recovery | NIP-60/NIP-61 encrypted proof backup to Nostr relays. Container crash → restore from Nostr | | Audit logging | Structured log of every satoshi in/out. Conditional vs. unconditional spend tracking | | Multi-mint ready | Coco handles per-mint proof isolation. Swap backend to @te-btc/multi-mint-router when scaling |

Architecture

src/
├── core/
│   ├── wallet.ts          # AgentWallet class — main entry point
│   ├── types.ts           # Config, budget, audit types
│   └── errors.ts          # Typed error hierarchy
├── storage/
│   ├── interface.ts       # IProofStore abstraction
│   ├── sqlite.ts          # better-sqlite3 implementation
│   └── memory.ts          # In-memory Map for ephemeral agents
├── policy/
│   ├── budget.ts          # Daily/per-request limit enforcement
│   ├── velocity.ts        # Circuit breaker for recursive spending loops
│   └── allowlist.ts       # Capability allowlists (which endpoints/mints)
├── proofs/
│   ├── pool.ts            # Proof pool manager — consolidation, splitting, denomination tracking
│   └── backup.ts          # NIP-60/NIP-61 Nostr relay backup/restore
├── conditions/
│   ├── pos.ts             # Proof-of-service token generation
│   ├── escrow.ts          # 2-of-3 multisig escrow participation
│   └── timelock.ts        # Time-locked subscription tokens
├── audit/
│   └── logger.ts          # Structured audit log (every sat in/out)
└── index.ts               # Public API

Dependencies

| Package | Role | |---------|------| | @cashu/coco | Multi-mint state management, proof lifecycle, NUT-13 derivation counters | | @cashu/cashu-ts | Core wallet crypto, BDHKE (via Coco) | | @noble/curves | Schnorr signing for P2PK/escrow witness generation | | @noble/hashes | SHA-256 for PoS output hashing | | better-sqlite3 | Synchronous SQLite — zero context-switching for micropayment streams |

Docs

| Document | Location | |----------|----------| | Full project spec | internal/docs/projects/agent-wallet.md | | Research #3 (Agent + L402) | internal/docs/BUILD_POSSIBILITIES/research/3-Agent Cashu L402 Integration Research.md | | Build Possibilities | internal/docs/BUILD_POSSIBILITIES/BUILD_POSSIBILITIES.md |

License

MIT