cocod

cocod is a Cashu wallet CLI with a local daemon.

If you like simple tools: run commands in your terminal, and let the daemon handle wallet state in the background.

What it does

• Initialize and secure a Cashu wallet
• Check balances and transaction history
• Send and receive Cashu tokens
• Send and receive Lightning payments (BOLT11)
• Handle HTTP 402 payments with X-Cashu
• Manage trusted mints

Install

bun install --global cocod

Or from source:

git clone <repository-url>
cd cocod
bun install

Quick start

# Check daemon status
cocod status

# Create a wallet (auto-generates mnemonic)
cocod init

# If encrypted during init, unlock it
cocod unlock "your-passphrase"

# Check balance
cocod balance

Most common commands

# Receive
cocod receive cashu "cashuA..."
cocod receive bolt11 1000

# Send
cocod send cashu 500
cocod send bolt11 "lnbc..."

# Mints
cocod mints add https://mint.example.com/Bitcoin
cocod mints list

# History
cocod history --limit 10
cocod history --watch

NPC (Lightning Address)

# Your NPC address
cocod npc address

# Check username price, then confirm purchase
cocod npc username myname
cocod npc username myname --confirm

HTTP 402 / X-Cashu

# Inspect request from a 402 response
cocod x-cashu parse "<encoded-x-cashu-request>"

# Settle and get header value for retry
cocod x-cashu handle "<encoded-x-cashu-request>"

How it works

• CLI: src/cli.ts
• Daemon: src/daemon.ts
• Routes: src/routes.ts
• IPC transport: HTTP over UNIX socket

Defaults:

• Socket: ~/.cocod/cocod.sock (or COCOD_SOCKET)
• PID file: ~/.cocod/cocod.pid (or COCOD_PID)
• Config: ~/.cocod/config.json
• Database: ~/.cocod/coco.db

Development

# Run CLI from source
bun src/index.ts --help

# Run daemon directly
bun run daemon

# Typecheck
bun run lint

# Tests
bun test

# Isolated daemon smoke test
bun run smoke:daemon

Docs

• API and command reference
• Machine-readable daemon contract

License

MIT