# cashu-agent

Cashu ecash wallet for AI agents. Privacy-preserving payments, offline transfers, multi-mint support.

## Why Cashu?

Lightning is great for direct payments. Cashu adds what Lightning can't:

- **Privacy** — blind signatures mean the mint can't link sender to receiver
- **Offline transfers** — send ecash tokens without either party being online
- **No channel management** — no inbound liquidity, no routing failures
- **Microtransactions** — sub-sat precision, no minimum amounts
- **Bearer tokens** — tokens are like digital cash, whoever holds them owns them

Use `lightning-agent` for direct payments. Use `cashu-agent` for privacy and offline transfers. Use both together with the bridge.

## Install

```bash
npm install cashu-agent
```

## Quick Start

```javascript
const { createWallet } = require('cashu-agent');

const wallet = await createWallet({
  mintUrl: 'https://mint.minibits.cash/Bitcoin',
  storePath: './my-proofs.json'  // persists ecash to disk
});

// Check balance
const { balance } = await wallet.getBalance();
console.log(`${balance} sats`);

// Send ecash to another agent (offline!)
const { token } = await wallet.send(21);
console.log(token); // cashuB... — give this string to anyone

// Receive ecash from another agent
const { amount } = await wallet.receive('cashuB...');
console.log(`Received ${amount} sats`);

// Pay a Lightning invoice with ecash
await wallet.payInvoice('lnbc...');
```

## Minting Ecash

To get ecash, you pay a Lightning invoice to the mint:

```javascript
// Step 1: Get a Lightning invoice
const quote = await wallet.mintQuote(100); // 100 sats
console.log('Pay this invoice:', quote.invoice);

// Step 2: After paying, claim the ecash
const result = await wallet.claimMint(quote.quote, 100);
console.log(`Minted ${result.proofs.length} proofs`);

// Or do it all at once (waits for payment):
const result = await wallet.mint(100, { timeoutMs: 60000 });
```

## Lightning Bridge

Move funds between Lightning and Cashu wallets:

```javascript
const { createWallet, createBridge } = require('cashu-agent');
const { createWallet: createLNWallet } = require('lightning-agent');

const lightning = await createLNWallet(process.env.NWC_URL);
const cashu = await createWallet({ mintUrl: 'https://mint.minibits.cash/Bitcoin' });

const bridge = createBridge({ lightning, cashu });

// Move 1000 sats from Lightning → Cashu
await bridge.toCashu(1000);

// Move 500 sats from Cashu → Lightning
await bridge.toLightning(500);

// Check both balances
const { lightning: ln, cashu: cs, total } = await bridge.getBalances();

// Auto-rebalance (keep 30% in Cashu)
await bridge.rebalance({ cashuTarget: 0.3 });
```

## Multi-Mint

Don't trust a single mint with all your ecash:

```javascript
const { createMultiWallet } = require('cashu-agent');

const wallet = await createMultiWallet({
  mints: [
    'https://mint.minibits.cash/Bitcoin',
    'https://mint.coinos.io',
    'https://legend.lnbits.com/cashu/api/v1/xyz'
  ],
  storeDir: './cashu-proofs/',  // separate file per mint
  preferredMint: 'https://mint.minibits.cash/Bitcoin'
});

// Aggregated balance across all mints
const { balance, byMint } = await wallet.getBalance();

// Sends from the mint with most funds
const { token } = await wallet.send(50);

// Receives auto-detect the token's mint
await wallet.receive(token);

// Health check
const health = wallet.getHealth();
```

## CLI

```bash
# Set default mint
export CASHU_MINT=https://mint.minibits.cash/Bitcoin

# Check balance
cashu-agent balance

# Mint ecash (prints invoice to pay)
cashu-agent mint 100

# Claim after paying
cashu-agent claim <quoteId> 100

# Send ecash (prints token)
cashu-agent send 21

# Receive ecash
cashu-agent receive cashuB...

# Pay Lightning invoice
cashu-agent pay lnbc...

# Clean spent proofs
cashu-agent check

# Decode a token
cashu-agent decode cashuB...

# Mint info
cashu-agent info
```

## Storage

Proofs are stored as JSON. Three options:

```javascript
// In-memory (lost on restart)
const wallet = await createWallet({ mintUrl });

// File storage
const wallet = await createWallet({ mintUrl, storePath: './proofs.json' });

// Custom store (database, S3, etc.)
const wallet = await createWallet({
  mintUrl,
  store: {
    load: async () => db.get('proofs'),
    save: async (proofs) => db.set('proofs', proofs)
  }
});
```

## When to Use What

| Scenario | Use |
|----------|-----|
| Pay a Lightning invoice | `lightning-agent` |
| Receive a Lightning payment | `lightning-agent` |
| Send sats to an agent privately | `cashu-agent` |
| Transfer sats while recipient is offline | `cashu-agent` |
| Micropayments (< 1 sat) | `cashu-agent` |
| Pay for an API endpoint (L402) | `lightning-toll` + `lightning-agent` |
| Move funds between LN ↔ ecash | `cashu-agent` bridge |
| Don't trust one custodian | `cashu-agent` multi-mint |

## How It Works

Cashu uses **Chaumian blind signatures**. When you mint ecash:

1. You send the mint a Lightning payment
2. The mint signs blinded tokens (can't see the values)
3. You unblind the tokens — now you have ecash
4. To spend, you give tokens to the mint to verify
5. The mint can verify they're real but can't link them to you

The mint is custodial (holds the backing funds), but can't track who spends what. Multi-mint support means you spread risk across custodians.

## License

MIT