botwallets — Bitcoin ecash wallets for bots

Why botwallets

Give any bot a bitcoin wallet in minutes.

⚡

Zero Config

Run npx botwallets init and start building. Defaults to a test mint so you can develop immediately.

💬

Multi-Platform Bots

Built-in adapters for Telegram and Slack. Implement the Adapter interface to support any platform.

🤖

Autonomous Agents

JSON CLI for Lobster workflows. Designed for AI agents that need to hold and transact bitcoin.

⚡

Lightning Bridge

Fund wallets and pay invoices over the Lightning Network. Cashu ecash backed by real BTC.

Quick Start

Two ways to get going.

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();
process.once('SIGINT', () => bot.stop());

Direct Wallet API

import { addWallet, destroyAll } from 'botwallets';

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

// Alice sends 10 sats — returns an ecash token
const token = await alice.send(10, { sender: 'alice', receiver: 'bob' });

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

destroyAll();

Set up a testnet with Claude Code

Have Claude Code scaffold a local testnet with two wallets and verify ecash transfers work end to end.

claude "Set up a botwallets testnet: run npx botwallets init with the test mint at testnut.cashu.space, create two wallets (alice and bob), send ecash between them, and verify the balances"

Paste in your terminal — requires Claude Code

How It Works

Cashu ecash, backed by Bitcoin, orchestrated by your bot.

Your Bot

decides intent

→

botwallets

moves money

→

Cashu Mint

holds bitcoin

→

Lightning

settles payments

Ecash tokens are bearer instruments. Your bot holds them locally in a SQLite database. Sending means giving a token to another wallet; receiving means swapping it at the mint for fresh proofs.

The mint is the server that backs ecash with real bitcoin. Use the default test mint for development, or connect to a production mint you trust.

Lightning bridge lets wallets fund themselves by creating invoices and pay external invoices. Funds enter and exit through the Lightning Network.

API Overview

The BotWallet interface and top-level exports.

Method	Returns	Description
`addWallet(config)`	`Promise<BotWallet>`	Create or open a wallet by ID
`createBot(config)`	`BotInstance`	Create a bot with a platform adapter
`getBalance()`	`number`	Current balance in sats
`send(amount, memo?)`	`Promise<string>`	Send ecash, returns a token
`receive(token, memo?)`	`Promise<number>`	Receive an ecash token, returns amount
`createMintInvoice(amount)`	`Promise<MintInvoice>`	Create a Lightning invoice to fund the wallet
`checkMintQuote(quoteId)`	`Promise<number \| null>`	Check if a funding invoice has been paid
`payInvoice(invoice, memo?)`	`Promise<MeltResult>`	Pay a Lightning invoice from the wallet
`getTransactions(options?)`	`Promise<TransactionRecord[]>`	Query transaction history
`getInfo()`	`WalletInfo`	Wallet metadata (id, mint URL, etc.)
`destroy()`	`void`	Close this wallet's DB connection
`destroyAll()`	`void`	Close all open wallets

Error Types

BotWalletError

Base error class for all botwallets errors

InsufficientBalanceError

Thrown when a send or pay exceeds the available balance

MintConnectionError

Thrown when the wallet can't reach the mint

InvalidTokenError

Thrown when a received token is malformed or already spent