A powerful Telegram bot for monitoring your IQ Agents portfolio. Get real-time notifications about portfolio value changes, price movements, agent statistics, and IQ token price fluctuations.
- 📊 Advanced Portfolio Monitoring: Track your total holdings value with configurable USD and percentage change thresholds
- 📈 Modular Price Watching: Monitor specific agent tokens with granular threshold levels (minor/major/critical)
- 🪙 IQ Token Monitoring: Dedicated monitoring for the base IQ token that affects all agent prices
- 🎯 Smart Multi-Level Alerts: Customizable severity-based notifications with fine-grained control
- 📱 Rich Interactive Bot: Comprehensive Telegram interface with inline buttons and advanced commands
- 🔄 Real-time Updates: Automatic monitoring with configurable intervals and intelligent alerting
- 💰 Comprehensive Agent Analytics: Get detailed information about any IQ Agent token
- 🗄️ Persistent Storage: SQLite-based data persistence for configurations, price history, and alerts
- ⚙️ Maximum Customizability: Extensive configuration options with sensible defaults
- Node.js 18+ and pnpm
- Telegram Bot Token (from @BotFather)
- Your wallet address
-
Clone the repository
git clone https://github.com/GPSxtreme/atp-watcher.git cd atp-watcher -
Install dependencies
pnpm install
Note: The bot uses SQLite for persistent storage. If you encounter issues with
better-sqlite3compilation, make sure you have:- Node.js 18+
- Python 3.x (for native module compilation)
- Build tools for your platform (Visual Studio Build Tools on Windows, Xcode on macOS)
-
Set up environment variables Create a
.envfile in the root directory:# Telegram Bot Configuration TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here # Your wallet address to monitor holdings WALLET_ADDRESS=0xYourWalletAddressHere # IQ API Configuration (default: https://app.iqai.com/api) IQ_API_BASE_URL=https://app.iqai.com/api # Monitoring Intervals (in seconds) HOLDINGS_CHECK_INTERVAL=300 # 5 minutes PRICE_CHECK_INTERVAL=60 # 1 minute # Default thresholds DEFAULT_HOLDINGS_THRESHOLD=1000 # USD DEFAULT_PRICE_CHANGE_THRESHOLD=5 # Percentage # Application Configuration NODE_ENV=development LOG_LEVEL=info
-
Build and run
pnpm run build pnpm start
Or for development:
pnpm run dev
📊 /portfolio- View your complete portfolio with current values, holdings breakdown, and total worth🎯 /set_threshold <amount>- Set USD threshold for portfolio alerts (e.g.,/set_threshold 1000)📊 /set_change_threshold <percentage>- Set percentage change threshold (e.g.,/set_change_threshold 10)⏰ /set_interval <seconds>- Set monitoring interval (e.g.,/set_interval 300)▶️ /start_holdings- Begin continuous portfolio monitoring with automatic alerts⏹️ /stop_holdings- Stop portfolio monitoring and alerts
👁️ /watch <token_address>- Add token to watchlist for price change alerts🎯 /watch_config <address> <threshold> [interval]- Configure token with custom settings🔧 /watch_advanced <address> <minor%> <major%> <critical%> [interval]- Advanced threshold configuration🔔 /alert_config <address> <minor:on/off> <major:on/off> <critical:on/off>- Configure alert types🚫 /unwatch <token_address>- Remove token from watchlist📈 /watched- View all tokens you're monitoring with latest prices▶️ /start_price- Enable price monitoring service for all watched tokens⏹️ /stop_price- Disable price monitoring service
🪙 /iq_price- Current IQ token price (base token for all agents)▶️ /start_iq- Start IQ token price monitoring⏹️ /stop_iq- Stop IQ token price monitoring⚙️ /iq_config <minor%> <major%> <critical%> [interval]- Configure IQ price thresholds🔔 /iq_alerts <minor:on/off> <major:on/off> <critical:on/off>- Configure IQ alert types📊 /iq_status- View IQ monitoring status and configuration
📈 /top [mcap|holders|inferences] [limit]- Show top performing agents (default: top 10 by market cap)ℹ️ /info <token_address>- Get detailed agent profile including bio, stats, and creation date📊 /stats <token_address>- View comprehensive statistics: price, market cap, holders, inferences💰 /price <token_address>- Get real-time price for any agent token
⚙️ /config- View current configuration and monitoring settings📊 /status- System health check: monitoring status, database stats, tracked tokens📊 /history <token_address> [limit]- View price history for any token (default: last 10 prices)🚨 /alerts- View your recent alert history and notifications⚙️ /settings- View current configuration and available customization options👤 /myid- Get your Telegram user ID for bot authorization setup❓ /help- Show complete command guide with examples
This bot is designed as a personal monitoring assistant for a single user. By default, it responds to any user, but you should restrict it to only yourself for privacy and security.
- Get your Telegram User ID: Send
/myidto your bot to get your user ID - Configure single-user access: Set the
AUTHORIZED_USER_IDenvironment variable with your user ID - Restart the bot: Changes take effect after restart
# Restrict to only yourself (replace with your actual user ID)
AUTHORIZED_USER_ID=123456789
# Allow all users (not recommended for personal use)
AUTHORIZED_USER_ID=Once configured with your user ID, the bot will:
- Send you direct messages for all portfolio changes and price alerts
- Deny access to any other users with a clear message
- Store your chat ID automatically when you first interact with it
- Deliver real-time notifications about your investments directly to your DMs
- Send
/myidto your bot - The bot will respond with your Telegram user ID
- Use this ID in the
AUTHORIZED_USER_IDenvironment variable
- You (Authorized User): Full access to all commands + receive DM notifications
- Other Users: Receive "Access Denied" message for any command
- No Configuration: If
AUTHORIZED_USER_IDis empty, all users can interact (not recommended)
🔒 Privacy: Once configured, only you can access your portfolio data and monitoring settings. All alerts and notifications are sent directly to your private chat with the bot.
Set up comprehensive portfolio tracking with multiple alert levels:
/set_threshold 1000 # USD milestone threshold
/set_change_threshold 5 # 5% change alerts
/set_interval 300 # Check every 5 minutes
/start_holdingsMonitor tokens with different sensitivity levels:
# Basic monitoring
/watch_config 0x4dBcC239b265295500D2Fe2d0900629BDcBBD0fB 5 60
# Advanced multi-threshold monitoring
/watch_advanced 0x4dBcC239b265295500D2Fe2d0900629BDcBBD0fB 2 10 20 30
# Customize alert types
/alert_config 0x4dBcC239b265295500D2Fe2d0900629BDcBBD0fB on off onMonitor the base token for market-wide insights:
/iq_config 2 10 20 60 # Minor: 2%, Major: 10%, Critical: 20%, 60s interval
/iq_alerts on on on # Enable all alert types
/start_iqGet everything running with optimal configuration:
# Portfolio monitoring
/set_threshold 5000
/set_change_threshold 8
/start_holdings
# Price monitoring
/start_price
# IQ token monitoring
/iq_config 3 12 25
/start_iq
# Check status
/status
/configAll environment variables now include detailed descriptions with units and context:
| Variable | Description | Default | Units |
|---|---|---|---|
TELEGRAM_BOT_TOKEN |
Telegram bot token obtained from @BotFather for authenticating with Telegram API | Required | - |
WALLET_ADDRESS |
Ethereum wallet address (0x format) to monitor for IQ agent investments on Fraxtal network | Required | - |
IQ_API_BASE_URL |
Base URL for IQ AI API endpoints used to fetch agent data and prices | https://app.iqai.com/api |
URL |
HOLDINGS_CHECK_INTERVAL |
Interval in seconds between portfolio holdings checks | 300 |
seconds |
PRICE_CHECK_INTERVAL |
Interval in seconds between price checks for watched tokens | 60 |
seconds |
DEFAULT_HOLDINGS_THRESHOLD |
Default threshold in USD for portfolio value change notifications | 1000 |
USD |
DEFAULT_PRICE_CHANGE_THRESHOLD |
Default percentage threshold for price change notifications | 5 |
% |
AUTHORIZED_USER_ID |
Single authorized Telegram user ID who can interact with the bot (empty = allow all users) | `` (allow all) | - |
NODE_ENV |
Runtime environment mode affecting logging and error handling behavior | development |
- |
LOG_LEVEL |
Minimum log level to output (debug < info < warn < error) | info |
- |
- USD Thresholds: Set milestone values for portfolio alerts
- Percentage Thresholds: Configure sensitivity for portfolio value changes
- Monitoring Intervals: Customize how frequently holdings are checked
- Alert Types: Enable/disable different notification types
- Minor Thresholds: 1-5% price changes (default: 2%)
- Major Thresholds: 5-15% price changes (default: 10%)
- Critical Thresholds: 15%+ price changes (default: 20%)
- Individual Intervals: Custom check frequencies per token
- Alert Granularity: Enable/disable minor, major, or critical alerts per token
- Base Token Tracking: Monitor the fundamental token affecting all agent prices
- Market Impact Alerts: Notifications about potential market-wide price movements
- Configurable Sensitivity: Independent thresholds for IQ price monitoring
src/
├── env.ts # Enhanced environment configuration & validation with descriptions
├── index.ts # Main bot entry point with comprehensive command handling
└── services/
├── agents.ts # IQ Agents API service with retry logic and caching
├── database.ts # SQLite database service with enhanced schema
├── holdings-watcher.ts # Advanced portfolio monitoring with configurable thresholds
├── price-watcher.ts # Multi-level price monitoring with modular alerts
└── iq-price-watcher.ts # Dedicated IQ token price monitoring service- AgentsApiService: Handles all API calls to IQ Agents platform with intelligent retry logic and response caching
- DatabaseService: Enhanced SQLite-based persistent storage with advanced schema for modular configurations
- HoldingsWatcher: Advanced portfolio monitoring with USD and percentage thresholds, configurable intervals
- PriceWatcher: Multi-level token price monitoring with granular threshold control and per-token configuration
- IQPriceWatcher: Dedicated service for monitoring the base IQ token with market impact awareness
- Telegram Bot: Comprehensive command interface with advanced configuration and help systems
- price_history: Historical price data for all tracked tokens including IQ token
- alerts: Comprehensive alert history with severity levels and categorization
- user_preferences: Enhanced bot configuration storage with detailed preference management
- watched_tokens: Advanced token watch list with modular threshold configurations and alert settings
The bot uses SQLite for comprehensive persistent storage, optimized for Railway deployment:
- ✅ Modular Configurations: Store complex threshold configurations per token
- ✅ Alert History: Complete audit trail of all notifications with severity levels
- ✅ Price Analytics: Comprehensive price history for trend analysis
- ✅ User Preferences: Granular storage of all customization options
- ✅ Configuration Persistence: All settings survive restarts and deployments
- Price History: Track price movements over time for all tokens including IQ
- Alert Management: Complete history with categorization and severity levels
- Configuration Storage: Modular threshold settings, intervals, and alert preferences
- Token Management: Advanced watchlist with per-token configuration persistence
# Development with hot reload
pnpm run dev
# Build TypeScript
pnpm run build
# Start production server
pnpm start
# Lint code
pnpm run lint
# Fix linting issues
pnpm run lint:fix
# Format code
pnpm run format
# Clean build files
pnpm run clean- New Commands: Add command handlers in
src/index.tswith comprehensive help integration - New Monitoring Services: Create new watcher services in
src/services/following the modular pattern - API Integration: Extend
src/services/agents.tsfor new endpoints with proper caching - Database Extensions: Update
src/services/database.tsschema for new data requirements
- USD Milestone Alerts: When your portfolio hits specific dollar values
- Percentage Change Alerts: Configurable sensitivity for portfolio value fluctuations
- Continuous Monitoring: Real-time tracking with customizable check intervals
-
Minor Alerts (🔵): 1-5% price changes for subtle market movements
-
Major Alerts (🟠): 5-15% price changes for significant movements
-
Critical Alerts (🔴): 15%+ price changes for major market events
-
Per-Token Configuration: Independent settings for each monitored token
-
Alert Type Control: Enable/disable specific severity levels per token
-
Base Token Monitoring: Track the fundamental token that affects all agent prices
-
Market Impact Notifications: Alerts about potential market-wide price movements
-
Severity-Based Messaging: Different alert styles based on price change magnitude
-
Cross-Market Insights: Understanding how IQ price changes affect the entire ecosystem
- Automatic retry logic with exponential backoff for API calls
- Graceful error handling with user-friendly notifications
- Comprehensive logging with configurable levels for debugging
- Circuit breaker patterns for API reliability
- Comprehensive environment variables validation using Zod with detailed error messages
- Input validation and sanitization for all user commands
- Rate limiting and request throttling through axios-retry
- Secure database operations with prepared statements
- No sensitive data persistence in memory or logs
- Intelligent API caching and retry mechanisms with circuit breakers
- Configurable monitoring intervals to balance responsiveness and resource usage
- Optimized database queries with proper indexing
- Memory-efficient operations for continuous monitoring
- Asynchronous processing for all monitoring services
The bot is optimized for Railway deployment with enhanced configuration:
-
Fork this repository
-
Connect to Railway: Link your GitHub repo to Railway
-
Set environment variables in Railway dashboard:
TELEGRAM_BOT_TOKEN=your_bot_token WALLET_ADDRESS=your_wallet_address NODE_ENV=production LOG_LEVEL=info
-
Deploy: Railway will automatically build and deploy
-
IMPORTANT: Ensure you add Python as language provider to build better-sqlite3 binaries
Create a railway.json file for optimal deployment:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"build": {
"builder": "NIXPACKS"
},
"deploy": {
"startCommand": "pnpm start",
"restartPolicyType": "ALWAYS"
}
}The SQLite database will be stored in Railway's persistent filesystem with automatic optimization.
- Bot not responding: Check if
TELEGRAM_BOT_TOKENis correct and bot is running - No portfolio data: Verify
WALLET_ADDRESSis correct and has holdings on Fraxtal - API errors: Check if IQ API is accessible and rate limits aren't exceeded
- Database errors: Ensure proper file permissions and storage availability
- Compilation issues: Install platform-specific build tools (see installation notes)
- Configuration issues: Use
/configcommand to verify all settings - Alert spam: Use
/alert_configand/iq_alertsto fine-tune notification levels
Set LOG_LEVEL=debug in your .env file for comprehensive logging including:
- API request/response details
- Database operation logs
- Monitoring service status updates
- Configuration change tracking
- Monitoring Status: Use
/statusto check all service health - Configuration Review: Use
/configfor complete settings overview - Alert History: Use
/alertsto review recent notification patterns - Database Health: Built-in database optimization and maintenance routines
- Start Conservative: Begin with higher thresholds and longer intervals
- Gradual Tuning: Reduce thresholds based on your noise tolerance
- Layered Monitoring: Use different sensitivity levels for different tokens
- IQ Integration: Always monitor IQ token for market-wide insights
- Regular Review: Use
/configand/statusto review and optimize settings
# High-value portfolio with sensitive monitoring
/set_threshold 10000
/set_change_threshold 3
/set_interval 180
# Major tokens with graduated alerts
/watch_advanced 0xTOKEN1 1 5 15 30
/watch_advanced 0xTOKEN2 2 8 20 60
# IQ market intelligence
/iq_config 1 5 12 45
/iq_alerts on on onMIT License - see LICENSE file for details.