Samuel-Sendzul/shapshap-ex-bot

Telegram chat bot for offramping USDT into African currencies. # ShapShapEx Bot A full cryptocurrency exchange, all within Telegram. Buy & Sell USDT for local currency (GHS and NGN) and send and receive USDT from a dedicated TRON wallet. KYC yourself within Telegram to access trading functionality immediately. ## Table of Contents - Architecture Overview - Project Structure - Local Development - Testing - How It Works ## Architecture Overview The application follows a layered architecture with three main components: ### 1. User Interaction Layer **Telegram Bot** (python-telegram-bot) - Handles user conversations via ConversationHandler pattern - Multi-step flows for trading, KYC, account linking - Located in src/app/chat_bot/ **Management REST API** (Flask on port 8081) - Administrative endpoints for monitoring, configuration - API key authentication via middleware - Located in src/app/api/ ### 2. Business Logic Layer Core services that implement domain logic: - **trade.py** - Quote generation, fee calculation - **funding.py** - Balance management, withdrawals, settlements - **wallet.py** - TRON wallet operations - **rates.py** - Exchange rate management - **identity_verification.py** - KYC verification flow - **monitoring.py** - Provider health checks ### 3. Data & Integration Layer **Persistence** - Firebase Firestore for user data, balances, trades, settlements - Cloud Storage for KYC photos **External Integrations** - Payment Providers: ogateway/ (Ghana), fincra/ (Nigeria) - Identity Verification: smile_id/, youverify/, qore_id/ - Blockchain: tronpy for TRON, itrx/ for energy rental - Market Data: binancep2p/, bybit_p2p/, ovex/ ### Background Jobs APScheduler runs periodic tasks (src/app/jobs.py): | Job | Interval | Purpose | |-----|----------|---------| | `get_and_save_new_usdt_deposits` | 2 min | Scan TRON wallets for deposits | | `process_outstanding_withdrawals` | 4 min | Send USDT withdrawals | | `process_outstanding_settlements` | 2 min | Create payouts via payment providers | | `poll_payout_status` …