discord-lnbits-bot/README.md

Discord LNbits Bot

A full-stack Dockerized membership engine that lets users purchase Discord roles via Bitcoin Lightning (LNbits). It provides:

• A Discord bot that dynamically registers slash-commands per membership “plan”
• A Flask web UI (port 3000) for configuring your Discord/LNbits credentials and creating/editing membership plans
• A Postgres backend to persist plans, subscriptions, and payment logs
• Automated expiry logic (calendar-month, rolling-days, fixed-date) with scheduled role revocation

---

🚀 Features

• 🔧 One-click Docker Compose: bot + web UI + database
• ✅ Dynamic slash-commands for each plan (no code changes needed)
• ⚡ Lightning invoices via LNbits REST API
• 🌐 WebSocket listener for incoming payments
• 👤 Automatic role assignment on payment
• ⏰ Scheduled cleanup of expired subscriptions
• 📊 Persistent audit log in Postgres (raw JSON, timestamps, statuses)

---

📋 Requirements

• A Discord Bot Token (from the Developer Portal)
• LNbits Wallet Invoice Key
• A running LNbits instance (e.g., Sats.Love)
• Docker Engine (v20+)
• Docker Compose (v1.29+ or the built-in docker compose)

---

1️⃣ Setting Up Your Bot

Generate a Proper Bot Invite Link

1. Go to: Discord Developer Portal
2. Click New Application
3. Go to OAuth2 > URL Generator
4. Check these Scopes:
   • ✅ bot
   • ✅ applications.commands (for slash commands)
5. Under Bot Permissions, check:
   • ✅ Manage Roles
   • ✅ Send Messages
   • ✅ Embed Links
   • ✅ Read Message History
6. Copy & paste the generated link into your browser.
7. Select your Discord server and click Authorize.

---

Enable Privileged Intents

1. Go to Discord Developer Portal.
2. Select your bot application.
3. Navigate to Bot in the left sidebar.
4. Scroll down to Privileged Gateway Intents.
5. Enable the following:
   • ✅ Presence Intent
   • ✅ Server Members Intent
   • ✅ Message Content Intent
6. Click Save Changes.

---

Ensure Correct Role Permissions

1. Go to Server Settings → Roles.
2. Drag the bot’s role ABOVE the role it needs to assign.
3. Ensure the bot has these permissions:
   • ✅ Manage Roles
   • ✅ Read Messages
   • ✅ Send Messages

---

2️⃣ Installation Guide

1. Install System Dependencies

sudo apt update && sudo apt upgrade -y
sudo apt install python3 python3-pip python3-venv -y

2. Clone the Repository

git clone https://code.rustysats.com/saulteafarmer/discord-lnbits-bot
cd discord-lnbits-bot

3. Copy & Edit .env

cp .env.example .env
nano .env

4. Buld & run

docker-compose up -d --build

5. Open the web UI

Visit: http://localhost:3000

• Configure your Discord Bot Token, Guild ID, LNbits URL, LNbits Invoice Key
• Define membership plans (command name, role ID, channel ID, price, expiry policy)

---

3️⃣ Find Your Discord Guild ID & Role ID

Before configuring the bot, retrieve your Guild ID and Role ID.

🔹 How to Find Your Guild ID (Server ID):

1. Open Discord → Go to User Settings (⚙️).
2. Scroll down to Advanced → Enable Developer Mode.
3. Right-click your server name (left sidebar) → Click Copy ID.
4. Save this ID for later (guild_id).

🔹 How to Find Your Role ID:

1. Open your Discord Server.
2. Go to Server Settings → Roles.
3. Right-click on the role you want to assign → Click Copy ID.
4. Save this ID for later (role_id).

---

4️⃣ Configure the Bot

Edit the config.json file inside the bot directory:

sudo nano config.json

{
  "discord_token": "YOUR_DISCORD_BOT_TOKEN",
  "guild_id": "YOUR_GUILD_ID",
  "role_id": "YOUR_ROLE_ID",
  "lnbits_url": "https://sats.love",
  "lnbits_api_key": "YOUR_INVOICE_READ_KEY",
  "channelid": "YOUR_CHANNELID_FOR_PURCHASE_ROOM",
  "price": 1000,
  "command_name": "support",
  "invoicemessage": "Invoice for your purchase."
}

🔹 What Each Setting Does:

• discord_token → Your bot token from Discord Developer Portal
• guild_id → Your Discord server ID
• role_id → The Discord role the bot will assign
• lnbits_url → Base URL of your LNbits instance
• lnbits_api_key → Invoice-only key from LNbits (⚠️ NOT an admin key)
• price → Price in satoshis (e.g., 1000 = 1000 sats)
• command_name → Name of the command (default: support)
• invoicemessage → Message to be sent with invoice
• channelid → Discord channel where invoices and confirmations post

---

5️⃣ Run the Bot

python3 discord_lnbits_bot.py

---

6️⃣ Running the Bot in the Background

nohup python3 discord_lnbits_bot.py &

🔹 To stop the bot:

pkill -f discord_lnbits_bot.py

---

License

This project is open-source and free to use. Contributions welcome!