Real-time Telegram bot for monitoring PiggyBank assets and receiving instant notifications about epoch changes, new assets, and TVL changes.
- π Real-time Notifications - Get instant alerts about asset changes
- π Asset Monitoring - Track epoch changes, new assets, and TVL changes
- π― Selective Subscriptions - Choose which assets to monitor with interactive checkboxes (β /π²)
- π Asset Statistics - View current status of all assets with epoch via
/get_stats - π οΈ Admin Dashboard - Export data, view statistics, and monitor logs
- π§ͺ Test Mode - Test bot functionality with local data files
- π³ Docker Support - Easy deployment with Docker Compose
- π Comprehensive Logging - Full logging with file and console output
- β‘ Async Architecture - High-performance asynchronous operations
- Python 3.13+ or Docker
- Telegram Bot Token (@BotFather)
- Telegram User ID (@userinfobot)
- Clone the repository
git clone <repository-url>
cd piggybank_bot- Install dependencies
pip install -r requirements.txt- Configure environment
# Copy example file
cp env.example .env
# Edit .env and add your actual values
nano .env # or use your preferred editorRequired variables:
BOT_TOKEN- Your Telegram bot tokenADMIN_ID- Your Telegram user ID
- Run the bot
python bot.py- Create
.envfile
BOT_TOKEN=your_bot_token_here
ADMIN_ID=your_telegram_user_id
DATA_DIR=data- Create data directory
mkdir -p data- Start the bot
docker-compose up -d- View logs
docker-compose logs -f
# or
tail -f data/bot.logAll data (database, logs, cache) will be persisted in the data/ directory.
Start the bot and configure subscriptions:
/start
The bot will show you:
- A list of available assets with epoch
- Information about notification types you'll receive
- Interactive checkboxes to enable/disable notifications for each asset
Click on any asset to toggle notifications:
- β = Notifications enabled
- π² = Notifications disabled
Notification types you'll receive:
- π Epoch changes for subscribed assets
- ππ Capacity changes (when TVL changes by more than 1)
- π§ Capacity limit changes (when lst_cap changes)
View asset statistics:
/get_stats
Shows all assets with epoch, including:
- Asset name and ticker
- Current epoch number
- Filling status (filled amount / capacity)
- Filling percentage
View demo notifications:
/demo
View asset statistics:
/get_stats
This command shows you all assets with epoch, their current status, filling percentage, and capacity information.
View demo notifications:
/demo
This command sends you all types of notifications so you can see what to expect.
Notification Types:
- π New asset added - Sent to all users when a new asset with epoch appears
- Includes: Asset name, filling status (X / Y), link to platform
- π New Epoch - Sent to subscribed users when epoch number changes
- Includes: Old β New epoch, filling status (X / Y), link to platform
- π/π TVL changed - Sent to subscribed users when TVL changes by more than 1
- Includes: Change amount (with Β± sign, precision to hundredths), filling status (X / Y), link to platform
- π for increase, π for decrease
- π§ Capacity limit changed - Sent to subscribed users when lst_cap changes
- Includes: Change amount (with Β± sign, precision to hundredths), filling status (X / Y), link to platform
All notifications include direct links to the PiggyBank platform.
Get bot data and statistics:
/get_data
This admin-only command exports:
- All database tables as CSV files (
users.csv,user_subscriptions.csv) - Bot usage statistics (users, subscriptions, top assets)
- Log file (
bot.log)
Admin receives:
- β Bot startup confirmation message
- Full access to data export and statistics
Admin Notifications:
- Bot startup confirmation (β )
- Full access to bot data export via
/get_data - All
lst_tvlchanges are logged (but not sent as notifications)
bot.py- Main bot logic, handlers, and background tasksdatabase.py- SQLite database operations and data exportconfig.py- Configuration management and environment variables
users table:
user_id(PRIMARY KEY) - Telegram User IDusername- Telegram usernamefirst_name,last_name- User namescreated_at- Registration timestamp
user_subscriptions table:
id(PRIMARY KEY) - Subscription IDuser_id(FOREIGN KEY) - User IDasset_ticker- Asset ticker symbolasset_name- Asset display namecreated_at- Subscription timestamp- UNIQUE(user_id, asset_ticker)
The bot runs a background task every minute that:
- Fetches current asset data from API (or test file in test mode)
- Compares with saved data to detect changes
- Generates notifications for:
- New assets with epoch - Broadcast to all users when epoch key appears
- Epoch changes - Sent to subscribed users when epoch number changes
- TVL changes - Sent to subscribed users when
lst_tvlchanges by more than 1 (with Β± sign, precision to hundredths) - Capacity limit changes - Sent to subscribed users when
lst_capchanges (with Β± sign, precision to hundredths)
- Sends notifications to subscribed users in background
- Updates saved data cache
Important:
- TVL notifications are only sent if the change is greater than 1 (absolute value)
- Capacity limit (
lst_cap) notifications are sent for any change (not threshold-based) - TVL appearance (when asset first gets
lst_tvl) is not tracked separately (covered by epoch appearance) - All notifications include filling status (filled X / capacity Y)
piggybank_bot/
βββ bot.py # Main bot application
βββ database.py # Database operations
βββ config.py # Configuration
βββ requirements.txt # Python dependencies
βββ Dockerfile # Docker image definition
βββ docker-compose.yml # Docker Compose configuration
βββ env.example # Environment variables example
βββ README.md # This file
β
βββ data/ # Data directory (created automatically)
β βββ users.db # SQLite database
β βββ bot.log # Application logs
β βββ assets_data.json # Asset data cache
β βββ test_api.json # Test data file (for TEST_API mode)
β
βββ .env # Environment variables (not in git)
| Variable | Description | Required | Default |
|---|---|---|---|
BOT_TOKEN |
Telegram bot token from @BotFather | Yes | - |
ADMIN_ID |
Your Telegram User ID | Yes | - |
API_URL |
API endpoint URL | No | (see config.py) |
TEST_API |
Test mode: load data from file instead of API | No | false |
DATA_DIR |
Data directory path (empty = root) | No | empty |
DATA_FILE |
Assets cache file path (only if DATA_DIR empty) | No | assets_data.json |
DB_FILE |
Database file path (only if DATA_DIR empty) | No | users.db |
LOG_FILE |
Log file path (only if DATA_DIR empty) | No | bot.log |
TEST_API_FILE |
Test data file path (only if DATA_DIR empty) | No | test_api.json |
Enable test mode by setting TEST_API=true in .env. In test mode:
- Data is loaded from
test_api.jsoninstead of making API calls - Perfect for testing changes without affecting real data
- Edit
test_api.jsonto simulate different scenarios
- INFO - Important events (startup, changes, notifications)
- DEBUG - Detailed information
- WARNING - Warnings and non-critical errors
- ERROR - Errors with full traceback
Logs are written to:
- File:
data/bot.log(orbot.login root) - Console: Standard output
- Mode: Append (logs persist across restarts)
- All asset changes (epoch, lst_tvl, lst_cap) with details
- User actions (subscriptions, commands)
- Notification sending status
- API requests and responses
- Database operations
- Error details with full traceback
Administrators receive:
- β Bot startup confirmation message
- Access to
/get_datacommand for full export - All
lst_tvlchanges are logged (but not sent as notifications)
- Python 3.13+ - Programming language
- aiogram 3.24.0 - Telegram Bot API framework
- aiohttp 3.13.2 - Async HTTP client
- aiosqlite 0.22.1 - Async SQLite driver
- python-dotenv 1.0.1 - Environment variable management
- β Bot token stored in environment variables
- β
.envfile excluded from version control - β Admin-only commands with ID verification
- β Input validation and error handling
- β Safe type conversions
- β SQL injection protection via parameterized queries
- Broadcast notifications - New assets with epoch sent to all users
- Targeted notifications - Epoch changes, TVL changes, and capacity limit changes sent only to subscribed users
- Threshold-based TVL alerts - Only significant TVL changes (>1) trigger notifications
- Capacity limit tracking - All capacity limit (
lst_cap) changes trigger notifications (no threshold) - Rich formatting - HTML formatting with links, emojis (π, π, π, π, π§), and capacity information
- Precise change tracking - Changes shown with Β± sign and precision to hundredths (e.g., +123.45 or -67.89)
- Automatic caching - Asset data cached locally in JSON format
- Change detection - Compares current vs saved data with precision
- CSV export - Full database export for analysis (admin only)
- Statistics - Real-time bot usage statistics and asset statistics
- Asset status view -
/get_statscommand shows all assets with epoch, filling status, and percentages - Test mode - Local testing without API calls using
test_api.json
- Async operations - Non-blocking I/O operations
- Background tasks - Monitoring runs independently
- Efficient queries - Optimized database operations
- Error resilience - Graceful error handling
- Rate limiting - Delays between notification sends
Bot doesn't start:
- Check
BOT_TOKENin.env(required) - Verify
ADMIN_IDis correct (required) - Check logs in
data/bot.log - Ensure all dependencies are installed
No notifications:
- Ensure bot is running
- Check user subscriptions with
/start - Verify data source is accessible (API or test file)
- Check background task logs
Docker issues:
- Ensure
data/directory exists and is writable - Check
docker-compose logsfor errors - Verify environment variables are set in
.env - Check file permissions
Test mode not working:
- Ensure
TEST_API=truein.env - Verify
test_api.jsonfile exists - Check file path matches
TEST_API_FILEsetting
This project is provided as-is for monitoring PiggyBank assets.
Contributions are welcome! Please ensure:
- Code follows existing style
- All features are tested
- Documentation is updated
- Test mode works correctly
For issues and questions:
- Check logs in
data/bot.log - Review configuration in
.env - Use
/democommand to test notifications - Check Docker logs if using containers
- Verify test mode if testing locally
Made with β€οΈ for PiggyBank community