AddressTrackerBot v3

Telegram bot that monitors EVM addresses across multiple chains and sends real-time transaction notifications. Track wallets, check balances (native + ERC-20), view transaction history, and get USD valuations — all from Telegram.

What's New in v3

• Multi-chain support — Ethereum, Polygon, Arbitrum, and Base out of the box
• ERC-20 token tracking — detects Transfer events alongside native transactions
• SQLite database — replaces JSON file storage for reliability and performance
• USD price display — transaction notifications and balance checks show dollar values via CoinGecko
• Token balances — /details shows ERC-20 holdings for known tokens
• Admin system — manage authorized users directly from Telegram (/adduser, /rmuser, /users)
• Transaction thresholds — set minimum value to filter out noise (/threshold)
• Chain selection UI — inline keyboard when adding addresses
• Thread-local connection pooling — efficient SQLite access across threads
• Automatic migration — one-command upgrade from v2 JSON data to SQLite

Features

• Multi-chain monitoring — Ethereum, Polygon, Arbitrum, Base (extensible via config)
• Native + ERC-20 tracking — catches ETH/MATIC transfers and token Transfer events
• USD valuations — real-time prices via CoinGecko with 5-minute cache
• Transaction notifications — automatic alerts with direction, value, USD amount, and explorer links
• Balance check — native balance + known ERC-20 token balances
• Transaction history — paginated history from the database
• Alert thresholds — per-address minimum value to trigger notifications
• User authorization — admin-managed user access via bot commands
• Rate limiting — per-user command rate limiting
• Persistent storage — SQLite with WAL mode for concurrent access
• Graceful shutdown — handles SIGINT/SIGTERM cleanly
• Auto-reconnect — bot polling restarts automatically on connection errors
• Rotating logs — file-based logging with rotation

Supported Chains

Chain	Native Token	Chain ID
Ethereum	ETH	1
Polygon	MATIC	137
Arbitrum	ETH	42161
Base	ETH	8453

Custom RPC endpoints can be configured per chain via environment variables.

Quick Start

git clone https://github.com/SP1R4/AddressTrackerBot.git
cd AddressTrackerBot
./install.sh

The installer handles everything:

• Creates a Python virtual environment
• Installs all dependencies
• Prompts for your Telegram bot token and Infura project ID
• Sets up your initial admin user
• Runs the v2-to-v3 migration if upgrading

Then start the bot:

./run.sh

Manual Setup

1. Clone and install

git clone https://github.com/SP1R4/AddressTrackerBot.git
cd AddressTrackerBot
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. Configure

cp .env.example .env

Edit .env with your credentials:

TELEGRAM_BOT_TOKEN=your_telegram_bot_token
INFURA_PROJECT_ID=your_infura_project_id

Optionally override RPC endpoints:

RPC_ETHEREUM=https://your-custom-rpc.example.com
RPC_POLYGON=https://your-polygon-rpc.example.com

3. Set up initial admin

Create users.json with your first admin user:

{
  "users": [
    {
      "username": "your_telegram_username",
      "chat_id": 123456789
    }
  ]
}

To find your chat ID, message @userinfobot on Telegram.

Then run the migration to initialize the database:

python3 migrate.py

The first user in users.json becomes the admin. After migration, the JSON files are renamed to .bak and all data lives in tracker.db.

4. Run

./run.sh
# or: source venv/bin/activate && python3 main.py

Upgrading from v2

If you have an existing v2 installation with addresses.json and users.json:

git pull
source venv/bin/activate
pip install -r requirements.txt
python3 migrate.py

The migration tool:

• Creates the SQLite database (tracker.db)
• Imports all users (first user becomes admin)
• Imports all monitored addresses (on Ethereum chain)
• Renames JSON files to .bak

Commands

User Commands

Command	Description
/start or /help	Show available commands
/add	Add an address to monitor (with chain selection)
/remove	Remove a monitored address
/list	List all monitored addresses grouped by chain
/details <name>	Show address details, native + token balances, USD value
/history <name>	Show recent transaction history
/threshold <name> <ETH>	Set minimum alert value (e.g., /threshold my_wallet 0.1)
/chains	Show supported chains and connection status

Admin Commands

Command	Description
/adduser <chat_id> <username>	Authorize a new user
/rmuser <chat_id>	Remove a user and all their data
/users	List all authorized users

How It Works

1. Bot polling runs in the main thread, handling Telegram commands
2. Monitoring thread runs in the background, scanning new blocks every 60 seconds
3. For each monitored address, the monitor scans for:
   • Native transactions — direct block scanning for ETH/MATIC transfers
   • ERC-20 transfers — indexed Transfer event log queries
4. Detected transactions are stored in SQLite and sent as notifications with USD values
5. Block pointers only advance when scans succeed — no transactions are skipped on errors

Project Structure

AddressTrackerBot/
  install.sh           # One-step installer (handles v2 migration)
  run.sh               # Start script (created by installer)
  main.py              # Entry point, monitoring loop, signal handling
  bot_handler.py       # Telegram command handlers, inline keyboards
  web3_handler.py      # Multi-chain Web3 interactions, ERC-20, prices
  config.py            # Centralized config, chain definitions, constants
  database.py          # SQLite layer, thread-local connections, rate limiting
  migrate.py           # v2 JSON to v3 SQLite migration tool
  utils.py             # Logging setup
  requirements.txt     # Python dependencies
  .env.example         # Template for environment variables
  .gitignore           # Protects secrets, data files, and database

Configuration

Key settings in config.py:

Setting	Default	Description
POLL_INTERVAL	60s	Seconds between monitoring cycles
MAX_BLOCK_RANGE	50	Max blocks to scan per address per cycle
RATE_LIMIT_COMMANDS	30	Max commands per user per window
RATE_LIMIT_WINDOW	60s	Rate limit window in seconds
PRICE_CACHE_TTL	300s	How long to cache USD prices
HISTORY_PAGE_SIZE	10	Transactions per /history page

License

MIT