This bot tracks and monitors transactions across multiple blockchains and currencies, including their native tokens and popular stablecoins like USDT, USDC, and DAI. The bot is capable of notifying users about transactions, wallet updates, and more. It supports multiple blockchains like Ethereum, Solana, Avalanche, Osmosis, Cosmos, and more.
The bot currently supports the following blockchains and currencies:
- Ethereum (ETH)
- Binance Smart Chain (BNB)
- Arbitrum (ARB)
- PulseChain (PLS)
- Polygon (POL)
- Avalanche (AVAX)
- Optimism (OP)
- Fantom (FTM)
- Custom EVM Blockchain integration
- Solana (SOL)
- Tron (TRX)
- Dogecoin (DOGE)
- Polkadot (DOT)
- NEAR Protocol (NEAR)
- Algorand (ALGO)
- TON (TON)
- EOS (EOS)
- Pi Network (PI)
- Cosmos (ATOM)
- Osmosis (OSMO)
- Custom Web3 Blockchain integration
- Tether (USDT)
- USD Coin (USDC)
- Dai (DAI)
- Native Coin (All Blockchain)
- Real-time transaction tracking: The bot tracks all transactions in real-time for the supported blockchains and currencies.
- Wallet Address Support: The bot allows users to track specific multiple wallet addresses and their transaction history in a same time .
- Currency and Token Support: Supports both native blockchain tokens (e.g., ETH, PI, BNB) and stablecoins (e.g., DAI, USDT, USDC).
- Transaction Notifications: The bot sends notifications via Telegram with details about transactions, including amount, USD value, and a link to the blockchain explorer.
- Admin Controls: The bot includes various admin commands to manage settings like tracking configurations, adding/removing wallets, updating rates, and more.
Before running the bot, ensure you have the following installed:
- Python 3.8+
pip(Python package installer)- Redis (optional, for caching - bot will use in-memory cache if Redis is unavailable)
-
Clone the repository:
git clone https://github.com/Shahrukhahamed/py_tbot.git cd py_tbot -
Install the required dependencies:
pip install -r requirements.txt
-
Create a
.envfile in the root directory (copy from example):cp .env.example .env # Edit .env with your actual credentials -
Required environment variables in
.env:TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here SUPABASE_URL=your_supabase_url_here SUPABASE_KEY=your_supabase_key_here REDIS_URL=redis://localhost:6379 # Optional -
Test the build:
python test_build.py
This will verify all components are working correctly.
-
Run the bot:
python main.py
✅ All components successfully built and tested!
- ✅ Core imports working
- ✅ Configuration loading
- ✅ Database abstraction (with graceful fallback)
- ✅ Cache system (Redis + in-memory fallback)
- ✅ Blockchain adapters (20+ chains supported)
- ✅ Telegram bot handlers
- ✅ Logging system
- ✅ Error handling and resilience
The bot follows a modular architecture with clear separation of concerns:
py_tbot/
├── config/ # Configuration management
│ ├── settings.py # Application settings
│ └── blockchains.json # Blockchain configurations
├── src/
│ ├── core/ # Core business logic
│ │ └── blockchain/ # Blockchain adapters
│ ├── infrastructure/ # External services
│ │ ├── database.py # Database abstraction
│ │ └── cache.py # Caching system
│ ├── interface/ # User interfaces
│ │ └── telegram/ # Telegram bot
│ └── utils/ # Utilities and helpers
├── main.py # Application entry point
├── test_build.py # Build verification script
└── requirements.txt # Python dependencies
- Resilient Design: Graceful fallbacks for Redis and database connections
- Modular Adapters: Easy to add new blockchain support
- Comprehensive Logging: Detailed logging for debugging and monitoring
- Error Handling: Robust error handling throughout the application
-
Configure the blockchain settings in
config/blockchains.json. This file contains information about each supported blockchain, its RPC URLs, and explorer URLs.Example structure:
{ "Ethereum": { "rpc": "https://mainnet.infura.io/v3/YOUR_INFURA_KEY", "usdt_contract": "0xdac17f958d2ee523a2206206994597c13d831ec7", "usdc_contract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "dai_contract": "0x6b175474e89094c44da98b954eedeac495271d0f" }, "BNB": { "rpc": "https://bsc-dataseed.binance.org", "usdt_contract": "0x55d398326f99059fF775485246999027B3197955", "usdc_contract": "0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d", "dai_contract": "0x1AF3F329e8BE154074D8769D1FFa4eE058B1DBc3" }, ... } -
Redis Setup: If you don't have Redis installed, you can run it using Docker:
docker run -p 6379:6379 redis:alpine
-
Run the bot:
python main.py
You can also run the bot using Docker for easy deployment.
-
Build the Docker image:
docker-compose build
-
Start the bot and Redis services:
docker-compose up
The bot supports the following admin commands to manage blockchain tracking and notifications:
/start: Start the bot./pause_tracking: Pause transaction tracking./resume_tracking: Resume transaction tracking./start_tracking: Start tracking transactions for a specific blockchain./set_media: set image ,animated video , gif etc ./stop_tracking: Stop tracking transactions for a specific blockchain./add_wallet: Add a wallet address for a blockchain./remove_wallet: Remove a wallet address from tracking./add_currency: Add a currency (token) for tracking./remove_currency: Remove a currency (token) from tracking./update_rate: Update the exchange rate (USD value)./help: Show available commands./status: Show the bot's current status./add_blockchain: Add a new blockchain to the tracking list./remove_blockchain: Remove a blockchain from the tracking list./set_message_format: Set the notification format for transactions./clear_cache: Clear cached data for tracking./set_group_id: Set the group ID for notifications./set_admin_id: Set the admin ID for controlling the bot./set_rpc_url: Set the RPC URL for a specific blockchain./fallback_rpc: Set a fallback RPC URL if the primary one fails.
- The bot connects to each blockchain using its RPC URL.
- It monitors new blocks and transactions, fetching them in real-time.
- The bot checks the tracked wallet addresses and the specific currencies (like USDT, USDC, etc.).
- When a transaction is detected, the bot sends a notification to a specified Telegram channel with details like:
- Amount of tokens/coins
- USD value of the transaction (based on the latest rate)
- A link to the transaction on the blockchain explorer
- A link of Decentralized exchanges.
The bot supports the following blockchain types:
- Ethereum
- Binance Smart Chain (BNB)
- Arbitrum
- Polygon
- Avalanche
- Optimism
- Fantom
- PulseChain
- Base(Coinbase)
- Custom EVM Blockchain integration
- Solana
- Tron
- Dogecoin
- Polkadot
- NEAR Protocol
- Algorand
- TON
- Pi Network
- Cosmos
- Osmosis
- Eos
- Custom Web3 Blockchain integration
- USDT (Tether)
- USDC (USD Coin)
- DAI (Dai)
- Native coin of each Blockchain
This project is licensed under the MIT License - see the LICENSE file for details.