uniswap_auto_clp/tools/README_TELEGRAM.md

CLP Telegram Notification Monitor

Overview

Standalone Python script that monitors your CLP (Concentrated Liquidity Pool) positions and sends Telegram notifications when new positions are opened.

Features

• 🔍 File-based Monitoring: Watches hedge_status.json every 60 seconds
• 📊 Rich Notifications: Shows last closed position vs currently opened position
• 🔧 Zero Integration: No modifications to existing trading logic required
• 🛡️ Safe Operation: Graceful error handling, won't affect trading system
• 📈 Performance Tracking: Compares entry prices, values, and hedge PnL

Setup Instructions

1. Install Dependencies

pip install requests python-dotenv

2. Create Telegram Bot

1. Open Telegram and search for @BotFather
2. Send: /newbot
3. Choose a name for your bot (e.g., "CLP Position Monitor")
4. Choose a username (must end with 'bot', e.g., "clp_monitor_bot")
5. Copy the HTTP API token from BotFather

3. Get Your Chat ID

1. Send any message to your new bot first
2. Run the setup script: python tools/telegram_setup.py
3. Choose option "2. Get Chat ID" and enter your bot token
4. Copy your Chat ID

4. Configure Environment

Add to your .env file:

# Enable Telegram notifications
TELEGRAM_MONITOR_ENABLED=True

# Your bot credentials
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
TELEGRAM_CHAT_ID=123456789

# Optional settings
TELEGRAM_CHECK_INTERVAL_SECONDS=60
TELEGRAM_TIMEOUT_SECONDS=10
TELEGRAM_STATE_FILE=telegram_monitor_state.json
HEDGE_STATUS_FILE=hedge_status.json

5. Run the Monitor

python tools/telegram_monitor.py

Usage

Running as Background Process

Option 1: Simple Background

nohup python tools/telegram_monitor.py > logs/telegram_monitor.log 2>&1 &

Option 2: Screen Session

screen -S telegram_monitor
python tools/telegram_monitor.py
# Press Ctrl+A, D to detach

Option 3: Systemd Service (Linux) Create /etc/systemd/system/clp-telegram-monitor.service:

[Unit]
Description=CLP Telegram Monitor
After=network.target

[Service]
Type=simple
User=your_username
WorkingDirectory=/path/to/uniswap_auto_clp
ExecStart=/usr/bin/python3 tools/telegram_monitor.py
Restart=always
RestartSec=30

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable clp-telegram-monitor
sudo systemctl start clp-telegram-monitor

Message Format Example

When a new position opens, you'll receive:

🚀 NEW CLP POSITION DETECTED

📊 LAST CLOSED POSITION:
• Token ID: 5171687
• Entry: $3043.86
• Target Value: $1985.02
• Duration: 2h 14m
• Hedge PnL: -$20.99
• Hedge Fees: $2.30

🔥 CURRENTLY OPENED:
• Token ID: 5173016
• Entry: $2993.72
• Target Value: $1935.04
• Range: $2849.80 - $3140.07
• Initial: 0.3181 ETH + 982.71 USDC
• Time: 2h 15m ago

📈 PERFORMANCE COMPARISON:
• Entry Change: -$50.14 (-1.65%)
• Value Change: -$49.98 (-2.52%)
• Hedge PnL Trend: -$20.99 → $2.75 (+$23.74)

Configuration Options

Variable	Default	Description
TELEGRAM_MONITOR_ENABLED	False	Enable/disable notifications
TELEGRAM_BOT_TOKEN	Required	Your bot's HTTP API token
TELEGRAM_CHAT_ID	Required	Your personal chat ID
TELEGRAM_CHECK_INTERVAL_SECONDS	60	How often to check for changes
TELEGRAM_TIMEOUT_SECONDS	10	Telegram API timeout
TELEGRAM_STATE_FILE	telegram_monitor_state.json	Internal state tracking
HEDGE_STATUS_FILE	hedge_status.json	File to monitor

Troubleshooting

Bot Not Receiving Messages

• Ensure you've sent a message to your bot first
• Check that TELEGRAM_CHAT_ID is correct (no quotes)
• Verify bot token has no extra spaces

No Notifications When Position Opens

• Check TELEGRAM_MONITOR_ENABLED=True
• Verify the script is running: ps aux | grep telegram_monitor
• Check logs: tail -f logs/telegram_monitor.log
• Ensure hedge_status.json path is correct

Telegram API Errors

• Verify bot token format (should have colon: 123:ABC)
• Check internet connectivity
• Try running setup script to test connection

File Not Found Errors

• Make sure you're running from project root directory
• Verify hedge_status.json exists and has correct permissions
• Check that your trading system is generating the status file

Security Notes

• Never share your bot token - it's like a password
• Store credentials in .env - never commit to git
• Limit bot permissions - only send messages, no admin rights
• Monitor logs regularly for any unusual activity

Files Created

• tools/telegram_monitor.py - Main monitoring script
• tools/telegram_setup.py - Setup helper script
• tools/.env.example - Environment template
• telegram_monitor_state.json - Internal state (auto-created)
• logs/telegram_monitor.log - Monitor logs (auto-created)

Integration Notes

This monitor is completely standalone and:

• ✅ Does not modify your trading logic
• ✅ Does not interfere with uniswap_manager.py
• ✅ Does not affect clp_hedger.py
• ✅ Safe to run alongside existing processes
• ✅ Can be stopped/started independently
• ✅ Uses minimal system resources

The monitor simply reads the status file that your existing trading system already generates, making it safe and non-intrusive.