GiftCatcher Bot

🎁 Automated Telegram gift monitoring and purchasing bot

Overview

GiftCatcher Bot is a Python application that automatically monitors new gifts in Telegram and purchases them according to specified criteria. The bot supports flexible filter configuration, automatic gift distribution among recipients, and status notifications.

Features

• 🎁 Automatic monitoring of new Telegram gifts
• 💰 Flexible filters by price, limited edition status, supply
• 👥 Gift distribution among multiple recipients
• 📊 Prioritization of low-supply gifts
• 🔔 Notifications about purchases and status
• 🌍 Multi-language support (Russian, English)
• ⚡ Balance checking before each purchase
• 🛡️ Safe operation with file locking and error handling

Quick Start

1. Install dependencies:

   pip install -r requirements.txt
   

2. Configure settings:

   • Copy .env.example to .env
   • Fill in required parameters (API_ID, API_HASH, RECIPIENTS)

3. Run the bot:

   python main.py
   

Documentation

• 🚀 Quick Start Guide - Fast setup for all platforms
• 📖 Installation Guide (English) - Detailed instructions
• 📖 Руководство по установке (Русский) - Подробные инструкции

Configuration

Key parameters in .env file:

# Telegram API credentials
API_ID=your_api_id
API_HASH=your_api_hash

# Gift recipients (usernames or IDs)
RECIPIENTS=@username1,@username2,123456789

# Purchase settings
GIFT_QUANTITY=5
GIFT_PRICE_RANGES=1-50,100-500

# Filters (only limited gifts are purchased)
PRIORITIZE_LOW_SUPPLY=true
GIFT_MAX_SUPPLY=0

# Monitoring
CHECK_INTERVAL=5
NOTIFICATION_CHAT_ID=me
LANGUAGE=en

Requirements

• Python 3.8+
• Active Telegram account
• Telegram API keys (get from https://my.telegram.org/apps)

Project Structure

gift_catcher/
├── gift_catcher/           # Main application code
│   ├── core/              # Core system (monitoring, processing, purchasing)
│   ├── services/          # Services (config, logging, notifications)
│   └── bot.py             # Main bot class
├── locales/               # Localization files
├── data/                  # Application data
├── main.py                # Entry point
└── requirements.txt       # Dependencies

Security

• Keep API keys secure
• Never share the .env file
• Use two-factor authentication
• Regularly check active sessions in Telegram

License

This project is for educational purposes. Use responsibly and in accordance with Telegram's terms of service.