Opal Discord Bot 💎

A powerful Discord token-gating bot that allows creators to gate access to channels, roles, and content using cryptographic tokens, NFTs, or access passes.

Features 🚀

Core Features

• Token & NFT Verification: Verify wallet ownership via Web3 connections
• Automatic Role Assignment: Auto-assign Discord roles based on token/NFT ownership
• Multi-Chain Support: Ethereum, Polygon, BSC, Avalanche
• Real-time Analytics: Track verification success rates and usage
• Web Dashboard: Easy-to-use interface for configuration
• Event Pass Validation: Check passes for timed events
• Audit Logs: Complete verification history

Token Types Supported

• ERC-20 Tokens: Minimum balance requirements
• ERC-721 NFTs: Collection ownership verification
• ERC-1155 Tokens: Multi-token standard support

Quick Start 🏁

1. Discord Bot Setup

1. Go to Discord Developer Portal
2. Create a new application
3. Go to "Bot" section and create a bot
4. Copy the bot token
5. Go to "OAuth2" → "General" and add your redirect URL: https://your-app.onrender.com/auth/callback
6. Copy Client ID and Client Secret

2. Deploy to Render

1. Fork this repository
2. Connect your GitHub account to Render
3. Create a new Web Service from your forked repo
4. Set the following environment variables:

DISCORD_BOT_TOKEN=your_bot_token_here
DISCORD_CLIENT_ID=your_client_id_here
DISCORD_CLIENT_SECRET=your_client_secret_here
DISCORD_REDIRECT_URI=https://your-app.onrender.com/auth/callback
WEB_URL=https://your-app.onrender.com

3. Invite Bot to Your Server

Use this URL (replace YOUR_CLIENT_ID):

https://discord.com/api/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=268435456&scope=bot%20applications.commands

Required Permissions:

• Manage Roles
• Read Messages
• Send Messages
• Use Slash Commands

4. Configure Token Gates

1. Visit your deployed app URL
2. Login with Discord
3. Select your server
4. Add token gates with contract addresses and role IDs

Discord Commands 🤖

User Commands

• /verify [wallet_address] - Verify wallet and get roles
• /status - Check your verification status

Admin Commands

• /setup - Get setup instructions and dashboard link

Environment Variables 📝

Variable	Description	Required
DISCORD_BOT_TOKEN	Your Discord bot token	Yes
DISCORD_CLIENT_ID	Discord application client ID	Yes
DISCORD_CLIENT_SECRET	Discord application client secret	Yes
DISCORD_REDIRECT_URI	OAuth2 redirect URI	Yes
DATABASE_URL	Database connection string	No (defaults to SQLite)
WEB_URL	Your app's public URL	Yes
ETHEREUM_RPC	Ethereum RPC endpoint	No (default provided)
POLYGON_RPC	Polygon RPC endpoint	No (default provided)
BSC_RPC	BSC RPC endpoint	No (default provided)
AVALANCHE_RPC	Avalanche RPC endpoint	No (default provided)

API Endpoints 🔌

Authentication

• GET / - Dashboard (requires login)
• GET /login - Login page
• GET /auth/callback - OAuth2 callback
• GET /logout - Logout

Server Management

• GET /server/{server_id} - Server configuration page
• POST /api/token-gate - Create new token gate
• GET /api/analytics/{server_id} - Get server analytics

Verification

• POST /api/verify-wallet - Verify wallet ownership
• GET /api/user/profile - Get user profile

Local Development 💻

Prerequisites

• Python 3.9+
• Discord Bot Token
• Discord Application (Client ID & Secret)

Setup

1. Clone the repository

git clone <your-repo-url>
cd opal-discord-bot

2. Create virtual environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

cd backend
pip install -r requirements.txt

4. Create environment file

cp .env.example .env
# Edit .env with your values

5. Run the application

python main.py

The bot and web dashboard will start on http://localhost:8000

Architecture 🏗️

backend/
├── main.py              # FastAPI application & Discord bot startup
├── bot.py               # Discord bot commands and events
├── database.py          # Database configuration
├── models.py            # SQLAlchemy models
├── services/
│   ├── discord_oauth.py    # Discord OAuth2 implementation
│   ├── token_verification.py # Web3 token verification
│   └── analytics.py        # Analytics service
├── templates/           # Jinja2 HTML templates
└── static/             # CSS and static assets

Supported Blockchains ⛓️

Chain	Chain ID	RPC Endpoint
Ethereum	1	https://eth.llamarpc.com
Polygon	137	https://polygon.llamarpc.com
BSC	56	https://bsc-dataseed.binance.org
Avalanche	43114	https://api.avax.network/ext/bc/C/rpc

Pricing Tiers 💰

Free Tier

• Basic verification for 1 token gate per server
• Up to 100 verifications/month
• Community support

Pro Tier ($19/month)

• Up to 10 token gates per server
• Unlimited verifications
• Custom role mappings
• Priority support

Enterprise Tier ($99/month)

• Unlimited token gates
• White-label branding
• Custom integrations
• Dedicated support
• Analytics dashboard

Contributing 🤝

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support 🆘

• Documentation: Check this README and inline code comments
• Issues: Use GitHub Issues for bug reports
• Discord: Join our support server (link in bio)
• Email: [email protected]

License 📄

This project is licensed under the MIT License - see the LICENSE file for details.

Roadmap 🗺️

• Multi-server management
• Custom webhook integrations
• Scheduled token verification
• Mobile app companion
• Advanced analytics dashboard
• Integration with more chains (Solana, etc.)
• Subscription management via Stripe

---

Built with ❤️ for Web3 communities by the Opal team.