Slot Bot

A full-featured Discord bot for running a rented "slot channel" marketplace — with tiered plans, automated ping enforcement, recovery keys, moderation tooling, and a live web dashboard.

---

 Overview

Slot Bot is a modular Discord bot (a core/ package + domain cogs/ + a web/ dashboard) that powers a slot-shop style server — where members or merchants rent a private channel ("slot") for a fixed duration to advertise, with a controlled allowance of @everyone / @here pings.

The bot handles the entire lifecycle: channel creation, permission scoping, role assignment, ping tracking, automatic expiry, and revocation — and ships with a Flask web dashboard for real-time monitoring. On top of that, it bundles a complete moderation suite and a set of crypto / utility commands.

Every embed and panel is built with Discord's Components V2 UI system (LayoutView, Container, TextDisplay, Separator, interactive buttons & modals) for a clean, modern look — not legacy embeds.

Note

This project was built entirely by AI. Every line of the bot, the dashboard, and this documentation was generated with AI assistance.

 Key Features

Slot Management Tiered plans — Elite, Standard, Trial Auto-created private channels with scoped permissions Per-plan + per-duration ping limits Hold / pause / resume / extend / transfer / rename Plan migration between tiers	Automated Enforcement Live @everyone / @here ping counting Auto-revoke on ping-limit breach Background expiry & 24h expiry warnings Daily ping-counter reset (22:00 UTC) Secret recovery keys to reclaim slots
Web Dashboard Flask + CORS JSON API on port 25571 Live stats, slots, revoked slots & warnings Per-user slot details & analytics Bot status, latency & system metrics	Moderation & Utility Warn / mute / tempmute / kick / purge / lock Channel transcripts & application accept/reject Calculator & currency converter Litecoin balance & transaction lookup

 Architecture

flowchart TD
    subgraph Discord["Discord Gateway"]
        U[Members / Merchants]
        A[Admins / Staff]
    end

    subgraph Bot["Slot Bot  ·  single process"]
        CMD["Command Cogs<br/>(prefix =)"]
        EVT["Events Cog<br/>Ping Enforcement"]
        LOOPS["Tasks Cog<br/>expiry · warnings · reset"]
        FLASK["Flask Web Server<br/>:25571 (daemon thread)"]
    end

    subgraph Store["JSON Data Store"]
        S[(slots.json)]
        R[(revoked_slots.json)]
        W[(warns.json)]
    end

    U -->|messages / pings| EVT
    A -->|= commands| CMD
    CMD <--> S
    CMD <--> R
    CMD <--> W
    EVT --> S
    LOOPS --> S
    LOOPS --> R
    FLASK -->|reads| S
    FLASK -->|reads| R
    FLASK -->|reads| W
    DASH[Web Dashboard UI] -->|HTTP / REST| FLASK

Loading

 Slot Lifecycle

stateDiagram-v2
    [*] --> Active: =create user dur unit plan name
    Active --> Active: ping within limits
    Active --> Held: =hold  /  =pause
    Held --> Active: =unhold  /  =resume
    Active --> Revoked: ping limit exceeded (auto)
    Active --> Revoked: =revoke (manual)
    Revoked --> Active: =restore
    Active --> Expired: end_ts reached
    Expired --> [*]: channel deleted, roles stripped
    Active --> Recovered: recovery key used
    Recovered --> Active: ownership + roles transferred

Loading

 Ping Enforcement Flow

flowchart LR
    M["Message in slot"] --> O{"Author owns this slot?"}
    O -->|No| X["Ignore"]
    O -->|Yes| H{"Slot held?"}
    H -->|Yes| D["Delete message"]
    H -->|No| P{"Contains @everyone or @here?"}
    P -->|No| K["Allow"]
    P -->|Yes| INC["Increment counter"]
    INC --> L{"Over plan limit?"}
    L -->|No| K
    L -->|Yes| REV["Auto-revoke slot — strip perms and roles, move to revoked"]

Loading

 Commands

Default prefix: =

Slot Management

Command	Aliases	Description
=create <user> <dur> <unit> <plan> <name>	cr, c	Create a slot channel for a user
=revoke <user> [reason]	r, rev	Revoke an active slot
=restore <user>	unrevoke, unr	Restore a revoked slot
=hold <user> <reason> / =unhold <user>	h / unh	Freeze / unfreeze sending
=pause <user> [reason] / =resume <user>	—	Pause / resume a slot
=transfer <old> <new>	—	Transfer slot ownership
=rename <user> <name>	—	Rename a slot channel
=move <user> <plan>	—	Migrate a slot to another plan
=extend <user> <dur> <unit>	—	Extend slot duration
=setpings <user> <here> <lbl> <everyone> <lbl>	—	Override ping limits
=pings / =pingsreset	—	Show / reset ping usage
=slotinfo [user] / =slotstats / =slotowners	—	Inspect slots
=timeleft	—	Time remaining on your slot
=nuke / =clean <user>	—	Purge channel messages
=deleteslot <user>	—	Permanently delete a slot
=resendinfo / =genslotkey / =sendrecoverypanel	—	Info panels & recovery keys
=find <keyword> / =restoreserver	—	Search / bulk-restore

Moderation

Command	Description
=warn <user> <reason>	Issue a warning
=listwarns <user> / =removewarns <user>	View / clear warnings
=modlog <user>	View moderation history
=mute / =unmute / =tempmute <user> <dur>	Mute controls
=kick <user> [reason]	Kick a member
=purge <args>	Bulk-delete messages
=lock / =unlock [channel]	Lock / unlock a channel

Utility & Crypto

Command	Aliases	Description
=whois [user]	—	Member info card
=calc <equation>	—	Calculator
=convert <amt> <from> <to>	exch	Currency converter
=bal [ltc_address]	—	Litecoin wallet balance
=tx <txid>	txinfo, transaction	Litecoin transaction lookup
=transcript [user] [limit]	—	Export a channel transcript
=appaccept / =appreject	—	Application decisions
=botinfo / =help	—	Bot & help info
=dm / =dmall / =say	—	Messaging utilities

 Web Dashboard

A Flask app runs in a daemon thread alongside the bot on http://0.0.0.0:25571, exposing a REST API consumed by templates/dashboard.html.

Endpoint	Returns
GET /api/stats	Active / revoked counts + plan breakdown
GET /api/slots	All active slots
GET /api/revoked-slots	All revoked slots
GET /api/warnings	Warning records
GET /api/slot-details/<user_id>	Full detail for one slot
GET /api/analytics	Creation trends, ping usage, lifespans, expiring soon
GET /api/users	All guild members + cross-referenced slot/warn data
GET /api/bot-status	Status, latency, uptime, guild/user counts
GET /api/system-info	CPU / memory / disk / file sizes
GET /api/config	Non-sensitive config

 Tech Stack

Layer	Technologies
Language	Python 3.10+
Bot framework	discord.py
UI system	Discord Components V2 (LayoutView, Container, TextDisplay, modals)
Web	Flask, Flask-CORS, Jinja2
Async / HTTP	aiohttp, requests
Utilities	pytz, psutil
Storage	Flat-file JSON
Frontend	HTML, CSS, JavaScript (dashboard)

 Project Structure

.
├── slot.py                  # Thin entry point — builds the bot, loads cogs, runs
├── core/                    # Shared infrastructure
│   ├── config.py            #   config load, constants, ping limits, intents
│   ├── storage.py           #   JSON load/save + data file paths
│   ├── console.py           #   banner, ANSI colours, log() helper
│   ├── checks.py            #   permission check decorators
│   ├── helpers.py           #   duration parsing, DM sending
│   ├── embeds.py            #   Components V2 view builders
│   └── views.py             #   recovery / emoji / LTC modals & views
├── cogs/                    # Commands grouped by domain (discord.py cogs)
│   ├── slots_admin.py       #   create, revoke, restore, hold, transfer, …
│   ├── slots_user.py        #   pings, slotinfo, timeleft, find, nuke
│   ├── moderation.py        #   warn, mute, kick, purge, lock
│   ├── utility.py           #   help, whois, calc, botinfo, transcript
│   ├── crypto.py            #   convert, bal, tx
│   ├── communication.py     #   dm, dmall, app accept/reject
│   ├── events.py            #   on_ready / on_message / on_member_join listeners
│   └── tasks_cog.py         #   expiry, expiry-warnings, daily ping reset loops
├── web/
│   └── dashboard.py         # Flask dashboard + REST API (bot injected at runtime)
├── config.example.json      # Template config — copy to config.json
├── requirements.txt         # Python dependencies
├── templates/
│   └── dashboard.html       # Web dashboard UI
├── data/                    # Runtime store (gitignored)
│   ├── slots.json
│   └── revoked_slots.json
├── warns.json               # Moderation warnings (gitignored)
└── transcripts/             # Saved transcripts (gitignored)

 Getting Started

1. Clone & install

git clone https://github.com/iamirtasam/discord-slots-bot.git
cd discord-slots-bot
pip install -r requirements.txt

2. Configure

cp config.example.json config.json

Open config.json and fill in:

• YOUR_BOT_TOKEN — your Discord bot token
• All category / role / channel IDs
• SERVER_VANITY, LTC_ADDRESS, and custom emoji IDs

3. Run

python slot.py

The bot logs in and the dashboard starts on http://localhost:25571.

Requirements: A Discord application with the Server Members, Message Content, and Presence privileged intents enabled.

 Configuration Reference

Key	Description
CATEGORY_1_ID / CATEGORY_2_ID	Categories for Elite / Standard & Trial slots
*_ROLE_ID	Role IDs (elite, standard, member, staff, access, mod…)
ADMIN_LOG_CHANNEL	Channel for audit logs
PING_RESET_CHANNEL	Channel for daily ping-reset announcements
REVOKED_SLOT_CATEGORY_ID	Where revoked channels are moved
SERVER_VANITY	Vanity invite shown in embeds
EMOJIS	Custom emoji mappings used across embeds

 Security Notes

• config.json, data/, warns.json, and transcripts/ are gitignored — they hold the bot token, real user IDs, recovery keys, and chat logs. Never commit them.
• The dashboard API has no authentication and binds to 0.0.0.0. Run it behind a reverse proxy / firewall, or bind it to localhost, before exposing it.
• Rotate your bot token immediately if it is ever exposed.

 License

Released under the MIT License.

_{Built with using Python & discord.py}