Orderbook Monitor

Real-time Binance orderbook monitoring system with anomaly detection and Telegram alerts.

Features

• Real-time orderbook sync — WebSocket connection with Binance's recommended sync protocol
• Volume tracking — Calculates bid/ask volumes within ±2% of mid price
• Anomaly detection — Detects unusual volume changes and bid/ask imbalances
• Telegram alerts — Sends notifications for detected anomalies (LOW/MEDIUM/HIGH levels)
• PostgreSQL storage — Saves all data points and alerts with batch inserts
• Session reports — Generates performance report on shutdown

Quick Start

1. Start PostgreSQL:

   docker-compose up -d

2. Install dependencies:

   pip install -r requirements.txt

3. Configure:

   cp env.example .env
   # Edit .env with your settings

4. Run:

   cd src
   python main.py

Configuration

Key settings in .env:

Variable	Default	Description
SYMBOLS	BTCUSDT,ETHUSDT,SOLUSDT	Trading pairs to monitor
BAND_PCT	0.02	Price band for volume calculation (±2%)
WS_UPDATE_SPEED	1000ms	WebSocket update frequency
ANOMALY_WINDOW_SEC	60	Rolling window for anomaly detection
ALERT_LOW_PCT	15	Volume deviation threshold for LOW alerts
ALERT_MEDIUM_PCT	30	Volume deviation threshold for MEDIUM alerts
ALERT_HIGH_PCT	50	Volume deviation threshold for HIGH alerts

Project Structure

src/
├── main.py              # Entry point
├── config.py            # Configuration loader
├── models.py            # Data models (VolumePoint, Alert, BookPoint)
├── report.py            # Session report generator
├── binance/
│   ├── client.py        # Binance REST/WebSocket client
│   └── orderbook.py     # Local orderbook with sync protocol
├── core/
│   ├── metrics.py       # Metrics collection
│   ├── health.py        # Health monitoring
│   └── rate_limiter.py  # API rate limiting
├── db/
│   └── async_db.py      # PostgreSQL operations
├── detection/
│   ├── anomaly.py       # Anomaly detectors (Volume + Imbalance)
│   └── aggregator.py    # Time-series aggregation
├── notifications/
│   └── telegram.py      # Telegram client
└── workers/
    ├── symbol_worker.py # Per-symbol WebSocket worker
    ├── consumer.py      # Alert processing
    └── db_writers.py    # Batch DB writers

Anomaly Detection

Two types of anomalies are detected:

1. Volume anomaly — When bid or ask volume deviates significantly from rolling average
2. Imbalance anomaly — When bid/ask ratio becomes significantly unbalanced

Alert levels with cooldowns:

• LOW (15%+ deviation) — 60s cooldown
• MEDIUM (30%+ deviation) — 30s cooldown
• HIGH (50%+ deviation) — 10s cooldown

Session Report

On shutdown, generates session_report.txt with:

• Uptime and data loss statistics
• Anomaly detection summary
• Connection stability metrics
• Latency percentiles (P50, P95, P99)
• Performance assessment