@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