⚡ LNBits Demo Wallet

A simple Python command-line interface for interacting with the LNBits Lightning Network wallet API. This tutorial demonstrates how to:

Check wallet balance
Generate Lightning invoices
Send Lightning payments
View payment history

Quick Start

Prerequisites

Python 3.7 or higher
An LNBits wallet (we'll use the demo instance)

1. Clone the Repository

git clone https://github.com/ealvar13/lnbits-demo-wallet.git
cd lnbits-demo-wallet

2. Set Up Virtual Environment

Windows:

python -m venv .venv
.venv\Scripts\activate

macOS/Linux:

python3 -m venv .venv
source .venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Configure Your Wallet

Copy the example environment file:
```
cp .example-env .env
```
Get your LNBits credentials:
- Visit demo.lnbits.com
- Create a new wallet or use an existing one
- Copy your Admin Key and Wallet ID

Edit .env with your credentials:

NODE_URL="https://demo.lnbits.com"
WALLET_ID="your-wallet-id-here"
LNBITS_ADMIN_KEY="your-admin-key-here"

5. Run the Wallet

python main.py

📖 How It Works

Lightning Network Basics

The Lightning Network is a "layer 2" payment protocol built on top of Bitcoin that enables fast, low-cost transactions. Here's what you need to know:

BOLT11 Invoices: Payment requests that contain all the information needed to send a Lightning payment
Satoshis (sats): The smallest unit of Bitcoin (1 BTC = 100,000,000 sats)
Preimage: Proof that a payment was successful

Wallet Features

1. Check Balance

View your current wallet balance in milli-satoshis.

2. Generate Invoice

Create a Lightning invoice to receive payments:

Enter the amount in satoshis
Share the BOLT11 invoice string with the sender
The payment appears in your wallet once paid

3. Send Payment

Pay a Lightning invoice:

Paste the BOLT11 invoice string
The wallet automatically sends the payment
You'll receive a preimage as proof of payment

4. Payment History

View all your incoming and outgoing transactions with details like:

Amount
Timestamp
Payment hash
Status

🔧 API Integration

This demo uses the LNBits REST API. Here are the key endpoints:

# Get wallet balance
GET /api/v1/wallet

# Create invoice (receive payment).
POST /api/v1/payments
{
    "unit": "sat",
    "out": false,
    "amount": 10,
    "memo": "Payment description"
}

# Send payment
POST /api/v1/payments
{
    "out": true,
    "bolt11": "lnbc..."
}

# Get payment history
GET /api/v1/payments

🛡️ Security Notes

Never commit your .env file - it contains sensitive credentials
Use the demo instance for testing only - don't store large amounts - it gets wiped every month!!!
Keep your admin key private - anyone with it can control your wallet

🚨 Demo Wallet Warning

This tutorial uses the LNBits demo instance:

Wallets may be reset monthly
Don't store significant amounts
Perfect for learning and testing
For production, run your own LNBits instance

📚 Learning Resources

🤝 Contributing

Feel free to submit issues and enhancement requests from github.

Happy Lightning! ⚡