Crypto Signal Scanner

A real-time market scanner for cryptocurrency pairs that combines technical indicators, macro signals (BTC dominance, cross-pair correlations), and AI-generated summaries via a local LLM. Includes filtered Telegram alerts and a web dashboard.

Built to monitor 10+ liquid pairs on Kraken every 5 minutes without false-alert spam.

What it does

• Technical indicator engine — RSI (1h / 4h / 1d), EMA alignment (20/50/200), Bollinger position, ATR percentile, volume spike detection, 24h structure, signal convergence scoring
• MarketPulse module — BTC dominance tracking (CoinGecko), rolling 30-day correlations between pairs, decorrelation event detection
• Smart alerts — dedupe windows, rate limits (max 20/day), severity tiers; alerts fire on convergence (3+ signals), RSI extremes, volume spikes, price moves, trend changes, dominance flips, correlation breaks
• AI summarizer — local Ollama LLM (Llama 3.2 3B) generates plain-English market summaries on demand via Telegram /summary command
• Web dashboard — FastAPI server on port 8082 showing live indicator snapshot, pulse banner, recent alerts
• Terminal dashboard — rich-formatted live view for shell users
• Telegram commands — /summary, /check PAIR, /top, /pulse, /help

Tech stack

• Python 3.12
• ccxt (Kraken exchange data)
• pandas, NumPy (indicator calculations)
• SQLite (persistence)
• FastAPI + Uvicorn (web dashboard)
• Rich (terminal dashboard)
• Ollama (local LLM)
• python-telegram-bot
• PyYAML (config)

Architecture

scanner.py            Main polling loop — fetches OHLCV, computes signals, persists
alerts.py             Filtering, dedupe, rate-limiting, Telegram delivery
market_pulse.py       Cross-market signals (BTC dominance, correlations)
summarizer.py         Telegram daemon for AI summaries + on-demand pair queries
web_app.py            FastAPI dashboard (port 8082)
terminal_dashboard.py Rich-formatted live terminal view
config.yaml           Pair whitelist, thresholds, Telegram credentials
state.sqlite          Trade history, alert log, scanner run history

Setup

# 1. Clone & install
git clone https://github.com/OfficialGIGA/crypto-signal-scanner.git
cd crypto-signal-scanner
pip install -r requirements.txt

# 2. Copy and edit config
cp config.example.yaml config.yaml
# Edit: add your Telegram bot token, chat_id, and pair whitelist

# 3. Install Ollama (optional, only for /summary command)
brew install ollama
ollama pull llama3.2:3b

# 4. Run
python3 scanner.py           # Main scanner loop
python3 web_app.py           # Dashboard (separate terminal)
python3 summarizer.py --daemon  # Telegram bot (separate terminal)

Notes on design decisions

• 5-minute polling cadence chosen as the sweet spot between freshness and Kraken rate limits. 1-minute polling on 17 pairs would burn the rate limit budget.
• Per-pair indicator state stored in SQLite so the scanner can survive restarts and pick up trend-change comparisons against the previous reading.
• Alert dedupe at 2h per (pair, alert_type) — prevents the same RSI-oversold from firing every 5 minutes during sustained extremes.
• Local LLM instead of OpenAI — keeps costs at zero, runs on consumer hardware (8GB MacBook Air), and avoids sending market data to a third party.
• MarketPulse is a separate module that scanner imports — if CoinGecko goes down, pulse fails silently without crashing the scanner.

Status

Production-ready for personal use. Currently running on a Mac Mini in a continuous loop monitoring my own market awareness.

License

MIT — feel free to fork and adapt. If you ship something useful, a star is appreciated.