README.md

Multi-Asset Real-Time Price Alert Bot 📈🔔

A production-ready Python bot that monitors commodities, cryptocurrencies, and stocks in real-time, and sends instant Telegram alerts when prices enter your defined ranges.

✨ Features

Feature	Details
Multi-asset tracking	Gold, Silver, Crude Oil, BTC, ETH, XRP, SOL, NVIDIA, Tesla, Google, Amazon, Oracle, S&P 500
Real-time crypto	Binance WebSocket streaming with REST fallback
Smart polling	yfinance batch polling every 15s for stocks/commodities
Dedup alerts	State-machine logic — alerts only on range entry, resets on exit
Telegram commands	/add, /remove, /list, /status, /help
Dry-run mode	Test without Telegram via --dry-run
Error handling	Exponential backoff, auto-reconnect, structured logging

📁 Project Structure

photonic-perigee/
├── main.py                  # Entry point & orchestrator
├── config.py                # Configuration & environment
├── alert_engine.py          # State-machine alert logic
├── telegram_bot.py          # Telegram commands & notifications
├── logger.py                # Rotating log setup
├── fetchers/
│   ├── __init__.py
│   ├── stock_fetcher.py     # yfinance polling
│   └── crypto_fetcher.py    # Binance WebSocket + REST
├── tests/
│   └── test_alert_engine.py # Unit tests
├── requirements.txt
├── .env.example
└── README.md

🚀 Quick Start

1. Prerequisites

• Python 3.10+ installed
• A Telegram account

2. Create a Telegram Bot

1. Open Telegram and search for @BotFather
2. Send /newbot and follow the prompts
3. You'll receive a Bot Token like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
4. Get your Chat ID:
   • Search for @userinfobot on Telegram
   • Send /start — it will reply with your Chat ID
   • Alternatively, send a message to your bot, then visit:

     https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
     

     Look for "chat":{"id": YOUR_CHAT_ID}

3. Install & Configure

# Clone / navigate to the project
cd photonic-perigee

# Create a virtual environment (recommended)
python -m venv venv
venv\Scripts\activate        # Windows
# source venv/bin/activate   # macOS/Linux

# Install dependencies
pip install -r requirements.txt

# Configure environment
copy .env.example .env       # Windows
# cp .env.example .env       # macOS/Linux

# Edit .env with your Telegram credentials
notepad .env

Fill in your .env:

TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
TELEGRAM_CHAT_ID=987654321

4. Run the Bot

# Live mode (sends Telegram alerts)
python main.py

# Dry-run mode (console alerts only, no Telegram needed)
python main.py --dry-run

5. Run Tests

python -m pytest tests/ -v

💬 Telegram Commands

Command	Description	Example
/add <ASSET> <MIN> <MAX>	Start tracking an asset	/add BTC 60000 62000
/remove <ASSET>	Stop tracking an asset	/remove BTC
/list	Show all tracked assets	/list
/status	Bot health check & uptime	/status
/help	Show all commands	/help

Supported Asset Names

Category	Assets
Commodities	GOLD, SILVER, CRUDE_OIL
Crypto	BTC, ETH, XRP, SOL
Stocks	NVIDIA, TESLA, GOOGLE, AMAZON, ORACLE
Indices	SP500

🔔 How Alerts Work

The bot uses a state machine to avoid duplicate alerts:

Price OUTSIDE range → enters range → 🔔 ALERT sent
Price INSIDE range  → stays inside  → no alert (dedup)
Price INSIDE range  → exits range   → state resets
Price OUTSIDE range → re-enters     → 🔔 ALERT sent again

Sample Alert Message

🔔 Price Alert — BTC
━━━━━━━━━━━━━━━━━━━━━━━
💰 Current Price: $61,234.5600
📊 Target Range: $60,000.0000 – $62,000.0000
🕐 Time (UTC): 2026-03-22 06:15:30
━━━━━━━━━━━━━━━━━━━━━━━
Price has entered your defined range!

⚙️ Configuration

Edit config.py to customise:

Setting	Default	Description
STOCK_POLL_INTERVAL	15	Seconds between yfinance polls
CRYPTO_WS_RECONNECT_DELAY	5	Seconds before WebSocket reconnect
DEFAULT_RANGES	See file	Pre-loaded price ranges

☁️ Deployment

Option A: Run on a VPS (e.g., DigitalOcean, AWS EC2)

# SSH into your server
ssh user@your-server

# Clone the project, install dependencies
git clone <your-repo-url>
cd photonic-perigee
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

# Configure .env
nano .env

# Run with nohup (persists after disconnecting)
nohup python main.py > output.log 2>&1 &

# Or use systemd for auto-restart (create /etc/systemd/system/pricealert.service):

systemd service file (/etc/systemd/system/pricealert.service):

[Unit]
Description=Price Alert Bot
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/photonic-perigee
ExecStart=/home/ubuntu/photonic-perigee/venv/bin/python main.py
Restart=always
RestartSec=10
EnvironmentFile=/home/ubuntu/photonic-perigee/.env

[Install]
WantedBy=multi-user.target

sudo systemctl enable pricealert
sudo systemctl start pricealert
sudo systemctl status pricealert

Option B: Run on Replit

1. Create a new Python Repl
2. Upload all project files
3. Add TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID in Replit's Secrets tab
4. Set the run command to python main.py
5. Click Run — the bot will stay alive as long as the Repl is active
6. Use Replit's Always On feature (paid) for 24/7 uptime

📝 Logging

• Console: INFO level and above
• File (bot.log): DEBUG level, rotating at 5MB with 3 backups
• Log format: 2026-03-22 06:15:30 | INFO | main | Bot started

🛡️ Error Handling

Scenario	Behaviour
yfinance API failure	Exponential backoff (max 120s)
Binance WebSocket disconnect	Auto-reconnect with backoff (5 attempts)
WebSocket fails repeatedly	Falls back to REST API polling
Telegram send failure	Logged, retried on next alert
Invalid command input	User-friendly error message

License

MIT