Telegram Crypto Price Bot

Telegram bot for real-time cryptocurrency prices, gas fees, and market data.

• /price <coin> - Get price in USD/JPY with 24h change (supports symbols like BTC, ETH, SOL)
• /gas - Multi-chain gas prices (ETH, Polygon, Arbitrum, Base, BSC, etc.)
• /top10 - Top 10 cryptocurrencies by market cap
• Premium Tier System - Unlimited queries, price alerts, and priority support
• Price Alerts - Set price alerts above/below target (Premium feature)
• Subscription Management - TON blockchain payments, 30-day subscriptions
• In-memory caching (30s TTL) to avoid rate limits
• Error handling for missing tokens and API failures
• User tier tracking (FREE / PREMIUM) with expiration dates

• Python 3.8+
• pip (Python package manager)

1. Open Telegram and search for @BotFather
2. Send /newbot command
3. Choose a name and username for your bot
4. Copy the API token you receive (format: 123456789:ABCdefGHIjklmnoPQRstuvWXYZabcdef)

cp .env.example .env
# Edit .env and paste your token
nano .env
# Add this line:
# TELEGRAM_BOT_TOKEN=your_token_here

export TELEGRAM_BOT_TOKEN=your_token_here
./start.sh

chmod +x start.sh
./start.sh

The bot will start polling for messages. Try sending /start in Telegram to your bot to see the welcome message.

See .env.example for a template configuration file.

The /price command supports full CoinGecko IDs and common symbols:

Usage examples:

• /price bitcoin or /price btc - Get Bitcoin price
• /price ethereum or /price eth - Get Ethereum price

Shows welcome message and command list

Same as /start

Get current price in USD and JPY with 24-hour change percentage

/price bitcoin

Show multi-chain gas prices (requires local gas API running on port 8081)

/gas

Show top 10 cryptocurrencies by market cap

/top10

View your current tier and upgrade to Premium

/premium

Shows your subscription status and generates a TON payment link for upgrades.

Verify TON payment and activate Premium subscription

/verify <tx_hash>

After sending TON payment, use this command with your transaction hash to activate Premium access.

Set, list, and manage price alerts (Premium only)

/alert <coin> above|below <price>  # Set an alert
/alert list                         # Show active alerts
/alert remove <id>                  # Remove an alert

Examples:

• /alert btc above 100000 - Notify when Bitcoin exceeds $100k
• /alert eth below 2000 - Notify when Ethereum drops below $2k
• /alert list - Show all your active price alerts

• /price command: 10 calls per day
• No price alerts
• Basic market data access

• Unlimited /price queries
• Price alerts with /alert command
• Priority support
• 30-day subscription period (renewable via TON payments)

To upgrade, use /premium to see payment details.

• Prices: CoinGecko free API (no authentication required)
• Gas Prices: Local GasTracker.ai API (localhost:8081, optional)

The bot gracefully handles errors:

• Missing Token: Clear error message on startup with setup instructions
• API Failures: Displays user-friendly messages instead of crashing
• Rate Limiting: In-memory cache (30s TTL) reduces API calls

Run unit tests:

pip install pytest pytest-asyncio
pytest tests/ -v  # Run all tests
pytest tests/test_premium.py -v  # Run only premium feature tests

Tests cover:

• Token validation
• Command parsing
• Price formatting
• Error handling
• Caching mechanism
• User tier management (FREE/PREMIUM)
• Rate limiting for FREE tier users
• Price alert creation and management
• TON payment URL generation
• Payment verification stubs
• Database operations with SQLite

• Create .env file: cp .env.example .env
• Add your token: TELEGRAM_BOT_TOKEN=your_token_here
• Run: ./start.sh

• Ensure local gas API is running on http://localhost:8081
• Or modify GAS_API in .env to point to correct endpoint
• Telegram price commands work without local gas API

• Use full CoinGecko ID (e.g., bitcoin instead of BTC)
• Or try common symbol (e.g., /price btc)
• Check supported symbols above

telegram-crypto-bot/
├── bot.py                    # Main bot implementation
├── start.sh                  # Launcher script with environment setup
├── requirements.txt          # Python dependencies
├── .env                      # Configuration (gitignored)
├── .env.example              # Configuration template
├── README.md                 # This file
├── test_bot.py               # Legacy unit tests
├── db/
│   ├── __init__.py           # Package marker
│   ├── database.py           # SQLite database operations
│   └── users.sqlite3         # User database (tier, subscription, alerts)
├── handlers/
│   ├── __init__.py           # Package marker
│   ├── premium.py            # Premium tier and payment handlers
│   └── alert.py              # Price alert management
└── tests/
    ├── __init__.py           # Package marker
    └── test_premium.py       # Premium feature unit tests (38 tests)

• Payment URL Generation: Generates ton://transfer/ deep links for TON Space and @wallet apps
• Subscription Management: 30-day premium subscriptions tracked in SQLite database
• Payment Verification Stub: Ready for TON blockchain API integration

1. User runs /premium → Sees current tier and payment link
2. User clicks TON payment link → Sends TON to bot wallet
3. User runs /verify <tx_hash> → Verifies payment
4. System activates Premium tier for 30 days

• Integrate TON blockchain API (https://toncenter.com/ or https://tonapi.io/)
• Automatic payment verification monitoring
• Recurring subscription renewal via smart contracts
• TON Connect 2.0 integration for seamless in-app payments