botwallets

Bitcoin ecash wallets for bots. Simple Cashu wallet API for Telegram, Slack, CLI, and autonomous agents.

Install

npm install botwallets
npx botwallets init

Quick Start

Telegram Bot

import { createBot } from 'botwallets';
import { TelegramAdapter } from 'botwallets/telegram';

const bot = createBot({
  adapter: new TelegramAdapter({ token: process.env.BOT_TOKEN! }),
});

await bot.start();

Users get /balance, /send, /receive, /fund, /claim, and /history commands automatically.

Direct Wallet API

import { addWallet, destroyAll } from 'botwallets';

const alice = await addWallet({ walletId: 'alice' });
const bob   = await addWallet({ walletId: 'bob' });

const token = await alice.send(10, { sender: 'alice', receiver: 'bob' });
const received = await bob.receive(token, { sender: 'alice', receiver: 'bob' });
console.log('Bob received:', received, 'sats');

destroyAll();

CLI (for scripts and Lobster workflows)

npx botwallets cli balance                    # {"balance": 500}
npx botwallets cli send 100 --receiver alice  # {"amount": 100, "token": "cashuA..."}
npx botwallets cli receive <token>            # {"received": 100, "balance": 600}
npx botwallets cli mint 1000                  # {"quoteId": "...", "invoice": "lnbc..."}
npx botwallets cli pay <invoice>              # {"paid": true, "fee": 1}

Platform Adapters

Built-in support for Telegram and Slack. Add any platform by implementing the Adapter interface:

import { createBot } from 'botwallets';
import type { Adapter } from 'botwallets';

class MyAdapter implements Adapter {
  readonly platform = 'my-platform';
  register(handler) { /* wire events to handler */ }
  async start() { /* connect */ }
  async stop() { /* disconnect */ }
}

const bot = createBot({ adapter: new MyAdapter() });
await bot.start();

Generate starter code:

npx botwallets generate telegram
npx botwallets generate slack
npx botwallets generate custom
npx botwallets generate lobster

API

Top-level

| Function | Description | |---|---| | addWallet(config) | Create or open a wallet by ID | | createBot(config) | Create a bot with a platform adapter | | destroyAll() | Close all open wallets and DB connections |

BotWallet

| Method | Returns | Description | |---|---|---| | getBalance() | number | Current balance in sats | | send(amount, memo?) | Promise<string> | Send ecash, returns a token | | receive(token, memo?) | Promise<number> | Receive ecash, returns amount | | createMintInvoice(amount) | Promise<MintInvoice> | Lightning invoice to fund wallet | | checkMintQuote(quoteId) | Promise<number \| null> | Check if funding invoice was paid | | payInvoice(invoice, memo?) | Promise<MeltResult> | Pay a Lightning invoice | | getTransactions(options?) | Promise<TransactionRecord[]> | Query transaction history | | getInfo() | WalletInfo | Wallet metadata | | destroy() | void | Close this wallet |

Error Types

• InsufficientBalanceError — balance too low for send/pay
• MintConnectionError — can't reach the mint
• InvalidTokenError — token is malformed or already spent

How It Works

botwallets uses Cashu ecash — bearer tokens backed by Bitcoin on the Lightning Network. Wallets hold ecash proofs locally in SQLite. Sending means giving a token; receiving means swapping it at the mint for fresh proofs.

Your Bot  →  botwallets  →  Cashu Mint  →  Lightning Network

The default test mint (testnut.cashu.space) uses fake sats for development. For production, connect to a mint you trust.

License

MIT