Spaces:

fabrit
/

assets-tracker-api

Configuration error

somilsadana

Initial commit of full-stack assets tracker bot

83bcbe3 8 months ago

6.51 kB

# 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

```bash
# 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`:
```env
TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
TELEGRAM_CHAT_ID=987654321
```

### 4. Run the Bot

```bash
# 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

```bash
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)

```bash
# 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`):
```ini
[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
```

```bash
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

	# 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

	```bash
	# 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`:
	```env
	TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
	TELEGRAM_CHAT_ID=987654321
	```

	### 4. Run the Bot

	```bash
	# 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

	```bash
	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)

	```bash
	# 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`):
	```ini
	[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
	```

	```bash
	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