A decentralized e-commerce Telegram bot with role-based access control, secure payment processing, and location-based delivery management.

Telegram Chain Store is a comprehensive marketplace bot built on the Telegram platform. It provides a secure, multi-role system for managing product sales, payments, and deliveries with built-in verification mechanisms and location-based coordination.

• Buyer: Browse products, manage cart, place orders, and make payments through wallet or direct payment methods
• Seller: Add and manage products, handle initial payment verification, and coordinate deliveries at assigned locations
• Cardholder: Verify payments and wallet top-ups, manage payment method distribution for payouts
• Admin: Final payment approval, location management, user administration, and system-wide control

• Two-step payment verification (Cardholder → Admin)
• Multiple payment methods: wallet balance, direct payment, cryptocurrency
• Secure wallet management with transaction history
• Payment gateway integration support
• Automatic payment timeout handling

• Location-based delivery system with city-level organization
• Secure drop-off location assignment
• Time-delayed location disclosure (15 minutes after drop-off)
• Delivery code validation for order confirmation
• Address expiry management

• Role-based permission system
• Two-factor payment verification
• Input validation and sanitization
• Rate limiting and request throttling
• Secure token management
• Comprehensive logging and error handling

• Framework: Python 3.12+
• Telegram Library: Telethon 1.34.0
• Database: MySQL 8.0 with SQLAlchemy ORM
• Cache: Redis 5.0.1
• Migrations: Alembic
• Configuration: Pydantic Settings
• Security: python-jose, passlib, cryptography

• Python 3.12 or higher
• MySQL 8.0 or compatible database
• Redis server
• Telegram Bot Token and API credentials

1. Clone the repository:

git clone <repository-url>
cd Telegram-Chain-Store

2. Create and activate virtual environment:

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

3. Install dependencies:

pip install -r requirements.txt

4. Configure environment variables:

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

Required environment variables:

• API_ID: Telegram API ID
• API_HASH: Telegram API Hash
• BOT_TOKEN: Telegram Bot Token
• BOT_USERNAME: Bot username
• HEAD_ADMIN_ID: Admin user ID
• SUPPORT_ID: Support user ID
• SUPPORT_USERNAME: Support username
• DB_USER: Database username
• DB_PASSWORD: Database password
• DB_NAME: Database name
• SECRET_KEY: Application secret key
• CRYPTO_WALLET_ADDRESS: Cryptocurrency wallet address

5. Initialize database:

alembic upgrade head

6. Run the application:

python -m src.main

1. Configure environment variables in .env file

2. Build and start services:

docker-compose up --build -d

3. Run database migrations:

docker exec -it telegram-chain-store-bot alembic upgrade head

4. View logs:

docker-compose logs -f telegram-bot

The application uses Pydantic Settings for configuration management. All settings are loaded from environment variables or a .env file in the project root.

Key configuration categories:

• App Settings: Debug mode, logging level
• Telegram Settings: API credentials, bot configuration
• Database Settings: Connection parameters, pool configuration
• Redis Settings: Cache and session management
• Security Settings: Secret keys, token expiration
• Crypto Settings: Wallet address, network, payment timeout

Telegram-Chain-Store/
├── src/
│ ├── bot/ # Bot handlers and client
│ │ ├── handlers/ # Message and callback handlers
│ │ ├── keyboards/ # Inline keyboard definitions
│ │ └── utils/ # Bot utilities
│ ├── config/ # Configuration management
│ ├── core/ # Core business logic
│ │ ├── models/ # Database models
│ │ ├── services/ # Business logic services
│ │ └── repositories/ # Data access layer
│ ├── integrations/ # External service integrations
│ │ ├── delivery/ # Delivery service integration
│ │ ├── notifications/# Notification services
│ │ └── payment/ # Payment gateway integrations
│ └── utils/ # Utility functions
├── migrations/ # Database migration scripts
├── scripts/ # Setup and utility scripts
├── translations/ # Localization files
├── docker-compose.yml # Docker orchestration
├── Dockerfile # Container definition
└── requirements.txt # Python dependencies

The project uses:

• black for code formatting
• isort for import sorting
• flake8 for linting

Run formatting:

black src/
isort src/

Create a new migration:

alembic revision --autogenerate -m "description"

Apply migrations:

alembic upgrade head

Run tests:

pytest

[Specify license if applicable]