TG Listings Bot

Tracks Telegram collectible gift listings and native marketplace sales, then posts updates to a Telegram channel.

The collector uses a Telegram user session. The bot token is used for channel posts and private admin commands. You need both.

Requirements

• Python 3.11 or newer
• A Telegram bot from BotFather
• A channel where the bot can post
• Telegram API credentials from my.telegram.org
• A Telegram account that can open the collectible marketplace

This repository does not contain tokens, API credentials, sessions, databases, or production data.

Windows setup

git clone https://github.com/dev-nic-codes/tg-listings-bot.git
cd tg-listings-bot
powershell -ExecutionPolicy Bypass -File .\setup.ps1

Log in with the Telegram account used for collecting marketplace data:

.\.venv\Scripts\python.exe scripts\login.py

Check the configuration and start the bot:

.\.venv\Scripts\python.exe scripts\doctor.py
.\start.ps1

Install the optional Windows scheduled task if the bot should start after logon and restart after a failure:

powershell -ExecutionPolicy Bypass -File .\install-windows-task.ps1

Remove it with:

powershell -ExecutionPolicy Bypass -File .\uninstall-windows-task.ps1

Linux setup

git clone https://github.com/dev-nic-codes/tg-listings-bot.git
cd tg-listings-bot
chmod +x setup.sh start.sh
./setup.sh
.venv/bin/python scripts/login.py
.venv/bin/python scripts/doctor.py
./start.sh

An example systemd unit is included in deploy/tg-listings-bot.service.example. Update its user and paths before installing it.

Configuration

Run the setup wizard again whenever the configuration needs to change:

python scripts/configure.py

The main .env values are:

Variable	Used for
BOT_TOKEN	Posting and admin commands
BOT_USERNAME	Checks that the correct bot token is being used
API_ID, API_HASH	Telegram user-session login
COLLECTOR_USER_ID	Account allowed to run the collector
PUBLISH_CHAT	Channel username or numeric chat ID
ADMIN_IDS	User IDs allowed to control the bot
POLL_SECONDS	Time between marketplace scans
REQUEST_DELAY_SECONDS	Delay between marketplace requests

Runtime files are kept in state/ by default. That folder is ignored by Git.

Admin commands

• /status shows collector, database, delivery, and channel status.
• /scan starts a marketplace scan.
• /pause pauses collection.
• /resume resumes collection.
• /retry retries failed channel posts.
• /help shows the command list.

Only IDs in ADMIN_IDS can use these commands.

Notes

• The first full scan saves the current marketplace as a baseline. It does not post old listings as new activity.
• SQLite stores scan state and queued posts, so a normal restart does not lose progress.
• Telegram does not provide a complete public marketplace event history. A listing created and removed between scans cannot be recovered.
• Private offers are not visible globally.

Checks

python -m unittest discover -v
python -m compileall -q main.py src tests scripts