LNBits Wallet With QR Code: Lightning Network Payments for AI Agents

With over 20,000 downloads, the lnbits-with-qrcode skill by @JamesTsetsekas is the most popular Lightning Network integration on ClawHub. It connects Claude to an LNbits wallet — a free, open-source Bitcoin Lightning wallet system — and adds automatic QR code generation for every invoice, making it ready for real payment workflows out of the box.

The Problem It Solves

Lightning Network payments are fast and cheap, but the workflow has friction: generate a Bolt11 invoice string, convert it to a QR code, display it for scanning. Each step traditionally requires a separate tool. And when an AI agent is involved — helping a user request payment, verify an invoice before paying, or check if funds arrived — there's no native payment interface.

The lnbits-with-qrcode skill collapses the entire Lightning payment workflow into a single Claude-accessible interface. Ask for an invoice, get a Bolt11 string and a scannable QR code in the same response. Ask to pay, get a decoded preview and mandatory confirmation before any funds move.

How It Works

The skill wraps the LNbits REST API (/api/v1) with a Python CLI (lnbits_cli.py). It connects to any LNbits instance — either the public demo server at legend.lnbits.com or a self-hosted node — using your wallet's API key.

QR codes are generated locally using the qrcode[pil] library and saved as temporary PNG files (auto-cleaned after 5 minutes). Claude outputs the QR code path with a MEDIA: prefix so Clawdbot renders it inline in the chat interface.

Commands

Check Balance

python3 lnbits_cli.py balance

Returns current balance in satoshis:

{
  "name": "My Wallet",
  "balance_msat": 25000000,
  "balance_sats": 25000
}

Create an Invoice (Receive Funds)

# With QR code (default)
python3 lnbits_cli.py invoice --amount 5000 --memo "Coffee"
 
# Without QR code
python3 lnbits_cli.py invoice --amount 5000 --memo "Coffee" --no-qr

Response includes:

• payment_request — the Bolt11 string to share or copy
• qr_file — path to the generated QR code PNG
• qr_base64 — base64-encoded image for inline embedding

Claude's response format is strictly defined:

Here is your 5000 sat invoice:

lnbc50u1pxxxxx...

MEDIA:./clawd/.lnbits_qr/invoice_1741234567.png

The MEDIA: line triggers Clawdbot to display the QR image directly in chat.

Generate QR From Existing Invoice

If you already have a Bolt11 string and just need a QR code:

python3 lnbits_cli.py qr lnbc50u1pxxxxx...

Decode an Invoice

Before paying, inspect what an invoice is actually charging:

python3 lnbits_cli.py decode lnbc50u1pxxxxx...

Returns amount, memo, expiry, and destination — so you can verify before committing.

Pay an Invoice

# Step 1 (automatic): Decode to verify amount and memo
python3 lnbits_cli.py decode <bolt11>
 
# Step 2 (automatic): Check wallet balance
python3 lnbits_cli.py balance
 
# Step 3 (user confirms): Claude asks explicitly
# "I am about to send 5000 sats to 'Coffee'. Proceed? (y/n)"
 
# Step 4 (only after Yes): Execute payment
python3 lnbits_cli.py pay <bolt11>

This three-step flow is enforced by the skill — Claude cannot skip the confirmation prompt.

Create a New Wallet

If you're starting from scratch:

python3 lnbits_cli.py create --name "My OpenClaw Wallet"

Creates a wallet on the LNbits demo server. The adminkey and base_url appear in terminal output only — Claude is instructed never to display them in chat.

Security Protocols Built Into the Skill

The skill's skillMd enforces four hard rules that Claude must follow:

1. Never expose secrets: Admin keys, User IDs, and Wallet IDs are never displayed in chat — only in terminal output that the user controls directly.

2. Explicit confirmation before every payment: Claude always asks "I am about to send [Amount] sats to [Memo/Destination]. Proceed? (y/n)" — no exceptions.

3. Balance check before payment: Claude automatically checks balance before attempting to pay, preventing failed transactions from insufficient funds.

4. Invoice + QR always together: When generating an invoice, Claude always provides both the Bolt11 string (for copy/paste) and the QR code image (for mobile scanning). Neither is optional.

Configuration

# Add to your .env file
LNBITS_BASE_URL=https://legend.lnbits.com
LNBITS_API_KEY=your_invoice_key_here

You can use your wallet's Invoice/Read Key rather than the Admin Key — it's sufficient for checking balances and creating invoices, and reduces risk if the key is exposed.

For self-hosted LNbits: replace legend.lnbits.com with your instance URL.

Use Cases

Freelancer invoicing: "Create a 50,000 sat invoice for the logo design project" → Claude generates invoice + QR code for the client to scan.

Point of sale: "Generate a 2,100 sat invoice for coffee" → Customer scans QR, payment received in under a second.

Verify before paying: "What does this invoice say?" followed by the Bolt11 string → Claude decodes and explains the amount, memo, and expiry before you decide to pay.

Balance monitoring: "What's my Lightning balance?" → Instant satoshi count, no wallet app required.

LNbits vs. Alternatives

How to Install

clawdbot install lnbits-with-qrcode

Install the required Python library:

pip install qrcode[pil]

Configure your credentials:

export LNBITS_BASE_URL=https://legend.lnbits.com
export LNBITS_API_KEY=your_key_here

If you don't have an LNbits wallet yet, ask Claude: "Create a new LNbits wallet called [name]." Claude will run the create command and instruct you to copy the credentials from terminal output.

Practical Tips

1. Use Invoice/Read Key, not Admin Key. The skill only needs the invoice key to create and receive payments. Store your Admin Key separately and never put it in a config that Claude can access.

2. Test on the demo server first. legend.lnbits.com is a free public instance — create a demo wallet, test the full flow (invoice → QR → payment → balance), then migrate to your self-hosted instance.

3. QR codes auto-delete after 5 minutes. The temp files at .lnbits_qr/ are cleaned up automatically. If you need a permanent QR code for a static Lightning address, use lnbits_cli.py qr <bolt11> --output receipt.png with an explicit output path.

4. Always decode before paying an unfamiliar invoice. The decode command shows you exactly what you're about to pay — amount, memo, expiry. Use it before paying any invoice you received from an external source.

5. Set LNBITS_BASE_URL to your own node for production. The public demo server is convenient but not suitable for significant amounts. Self-host LNbits against your own Lightning node (LND, CLN, or LDK) for production use.

Considerations

• Demo server funds are not guaranteed: legend.lnbits.com is a community resource. Don't store significant sats on the demo server.
• Python and qrcode[pil] required: The skill is Python-based and requires the qrcode[pil] package for QR generation. Without it, invoices work but QR output is skipped.
• Lightning Network knowledge helps: The skill works best for users who understand basic Lightning concepts (satoshis, Bolt11 invoices, routing). New users may need to learn the ecosystem basics separately.
• No LNURLpay built in: Static payment QR codes (LNURLpay) would enable permanent, reusable payment links. This skill generates per-invoice QR codes only. LNURLpay support would require LNbits extension setup separately.
• Stars vs downloads mismatch: With only 3 stars relative to 20,000 downloads, most users appear to be deploying and using the skill without starring it — common for utility integrations that work quietly in the background.

The Bigger Picture

Lightning Network was designed to make Bitcoin payments instant and nearly free — but the developer experience remained fragmented across wallet apps, CLI tools, and REST APIs. The lnbits-with-qrcode skill collapses that fragmentation into something simpler: talk to Claude in plain language, get a scannable QR code back.

For developers building Bitcoin-native applications, small businesses accepting Lightning payments, or individuals managing a Lightning wallet through an AI interface, this skill makes the gap between "AI assistant" and "payment terminal" disappear.

View the skill on ClawHub: lnbits-with-qrcode