Crypto Analyser — Rule-Based Market Decision Engine

Crypto Analyser

A quantitative, rule-based market-analysis and decision-support system for crypto and FX — with transparent signal logic, full backtesting, a Telegram bot front-end, and a machine-learning pipeline in active development.

Status: Working (rule engine + backtester + bot) · ML layer in progress Role: Sole developer — design, quant logic, data engineering, deployment Stack: Python 3.12 · pandas · NumPy · matplotlib / mplfinance · python-telegram-bot · DuckDB · scikit-learn (planned)

1. What It Is

Crypto Analyser ingests market candle data, scores each bar against a stack of 10 deterministic quantitative rules, and produces a clear BUY / WAIT decision — with every rule’s individual pass/fail shown. Nothing is hidden behind a black box: if the tool says WAIT, you can see exactly which rule(s) failed and why.

It is deliberately a decision-support tool, not an autotrader. It does the maths, quantifies the risk, and presents the evidence; the human makes the final call. This design choice keeps the logic auditable and the user accountable — which is also what makes it a good base for layering machine learning on top.

The project is now being extended from purely hand-tuned thresholds toward a data-driven model that learns which setups historically led to profitable outcomes.

2. The Problem It Solves

Most retail trading tools fall into two camps: opaque “signal” services that just print BUY/SELL with no reasoning, or raw charting tools that leave all the analysis to you. Both make it hard to learn why a decision is good or bad.

Crypto Analyser sits in between:

Explainable — every signal is decomposed into its component rules.
Risk-aware — position sizing and stop-losses are first-class, not an afterthought.
Falsifiable — a backtester lets you check whether the rules actually worked on historical data before risking real money.

3. How It Works (End to End)

 ┌─────────────┐   ┌──────────────────┐   ┌─────────────────┐   ┌──────────────┐
 │  Candle     │   │  Indicator       │   │  10-Rule        │   │  Decision +  │
 │  data       │──▶│  computation     │──▶│  scoring        │──▶│  risk sizing │
 │ (API+cache) │   │ (SMA, RSI, vol)  │   │ (all-pass = BUY)│   │  + breakdown │
 └─────────────┘   └──────────────────┘   └─────────────────┘   └──────────────┘
        │                                                                │
        └────────────────────────▶  Backtester  ◀──────────────────────┘
                                  (validate on history)

Step 1 — Data ingestion

Candles are fetched from public market APIs (Binance / Coinbase for crypto, yfinance for FX) — no account or API key required for the core analysis. Results are cached to local CSVs (data/{SYMBOL}_{INTERVAL}.csv) so repeated runs are fast and work offline. Supports BTC, ETH and FX pairs across timeframes from 1-minute to 1-day.

Step 2 — Indicator computation

From the raw OHLCV candles the engine derives:

SMA (short & long) — trend direction and longer-term market regime.
RSI — momentum / overbought detection, using Wilder-style EWMA smoothing.
True-range volatility — (high − low) / close, plus rolling averages over several windows to detect volatility contraction (a calm market about to move).
Volume vs. rolling median — confirms real participation behind a move.
Rolling price range — detects sideways / “calm” markets vs. chop.

Step 3 — The 10-rule scoring engine

This is the heart of the system (src/signal.py). Each bar is graded against 10 independent rules. All 10 must pass to produce a BUY; a single failure yields WAIT. Each rule is also exported as its own column (r_trend, r_rsi, …) so the output is fully transparent.

#	Rule	What it checks	Why it matters
1	Trend	Close above short SMA and SMA rising	Only buy when momentum is up
2	Entry band	Price within X% above the short SMA	Don’t chase an overextended candle
3	Stability	Today’s range ≤ recent average range × multiplier	Avoid abnormally volatile bars
4	Regime	Close above long SMA (with tolerance)	Confirm the broader uptrend
5	Volatility contraction	Short-window range ≤ long-window range	Enter as volatility coils, not expands
6	Volume	Volume ≥ rolling median	Require genuine participation
7	Price rising	Close ≥ close N bars ago	Confirm price has stopped falling
8	Sideways filter	5-bar range/mean below threshold	Prefer calm, range-bound setups
9	Not stuck	Fewer than N consecutive closes below SMA	Reject persistently weak assets
10	RSI	RSI below overbought threshold	Avoid buying into an exhausted rally

A WAIT is also returned for the warm-up period until enough history exists (min_history) for the indicators to be valid.

Step 4 — Risk management

Signals are useless without sizing. The risk module (src/risk.py) implements fixed-fractional position sizing:

risk_usd      = portfolio_value × risk_per_trade%        (e.g. 2%)
risk_per_unit = entry_price − stop_price                 (e.g. 3% below entry)
quantity      = risk_usd / risk_per_unit

So you always risk a fixed fraction of your portfolio per trade, regardless of the asset’s price. The module also tracks every exit condition:

Hard stop-loss — fixed % below entry.
Trailing stop — % below the highest price since entry (locks in gains).
Max hold days — forces a review if a position drifts too long.
Net P&L — including round-trip fees (entry + exit).

Step 5 — Backtesting

Before trusting the rules, you can simulate them on historical data (src/backtest.py). The backtester is built to avoid the usual beginner traps:

Next-bar entry — a BUY signal on bar i enters on bar i+1, never on the same bar that generated the signal (no look-ahead bias).
Real fees — taker fees charged on both entry and exit.
Full exit logic — hard stop, trailing stop, max-hold, and a fall back below the SMA all close positions, mirroring live behaviour.
Capital constraints — caps position size to available capital (≤95%).

It reports the metrics that actually matter:

Strategy return vs. a buy-and-hold benchmark (did the rules add value?)
Win rate, total trades, average hold time
Maximum drawdown (peak-to-trough equity decline)
Full trade log with per-trade P&L and exit reasons

4. Machine Learning (In Progress)

The current engine relies on hand-tuned thresholds. The next phase replaces fixed thresholds with a model that learns entry quality from historical outcomes.

Built so far — a labelled dataset pipeline (ml/prepare_dataset.py) that:

Replays the rule engine across historical 1h candles.
Engineers features for each bar: RSI, multi-horizon returns (1h / 6h / 24h), close-vs-SMA ratios, volume-vs-median, and raw OHLCV.
Generates forward-looking labels (entry = bar close):
- fwd_peak_return / fwd_trough_return — best high / worst low over the next 168 hours (7 days).
- label_hit_3pct / label_hit_5pct — did price reach the +3% / +5% target?
- first-touch stop-vs-target outcomes (did it hit the stop or the target first?).
Flags rows with a complete forward window (label_valid_window) so partial rows at the end of the series are dropped cleanly.

Planned — time-based train/test split (no shuffling, to respect causality) and scikit-learn models that predict the probability of a successful entry. This turns the binary BUY/WAIT output into a ranked, probability-weighted signal, and lets the system learn relationships the fixed rules can’t express.

5. Telegram Bot & Deployment

The analysis runs as a live monitoring service via Telegram (monitor.py, src/telegram_bot.py):

Polls the market on a schedule, runs hourly checks, and sends a daily summary (08:00 London time).
Renders candlestick charts (matplotlib / mplfinance in headless Agg mode).
Interactive commands and inline buttons for on-demand analysis.

Deployment — runs as a background worker on Railway or any VPS via the included Procfile (worker: python monitor.py) and runtime.txt (Python 3.12). A persistent volume mounted at /app/data keeps trade history (my_trades.json), bot state (alert_state.json), and cached candles across redeploys.

6. Architecture

crypto-analyser/
├── run.py            # CLI entry point
├── config.py         # ALL tuneable strategy parameters (single source of truth)
├── monitor.py        # Telegram monitoring bot / scheduler
├── src/
│   ├── data.py       # API fetching + CSV caching
│   ├── signal.py     # 10-rule deterministic scoring engine
│   ├── risk.py       # Position sizing + stop-loss / exit logic
│   ├── backtest.py   # Historical simulation (next-bar entry, real fees)
│   ├── display.py    # Terminal dashboard
│   ├── chart*.py     # Chart rendering
│   └── telegram_*.py # Bot commands, callbacks, charts
├── ml/
│   └── prepare_dataset.py  # Feature + label pipeline for ML
└── data/             # Cached candle CSVs + trade/state JSON

Design principles

Explainability first — no signal without a visible per-rule breakdown.
Config-driven — every threshold lives in one config.py; the engine also accepts per-call overrides for per-timeframe chart analysis, without touching engine code.
Separation of concerns — data / signal / risk / backtest / presentation are independent, testable modules.
Reproducible — local caching means analyses and backtests are deterministic and work offline.

7. Example Usage

# Install
pip install -r requirements.txt

# Today's analysis (ETH by default)
python run.py

# Analyse BTC on 4-hour candles
python run.py --symbol BTCUSDT --interval 4h

# Backtest the strategy over 2 years of history
python run.py --backtest --days 730

# Check exit conditions for a position you're already holding
python run.py --holding 2500 --peak 2800 --held-days 12

# Run the live Telegram monitoring bot
python monitor.py

# Build the ML training dataset
python -m ml.prepare_dataset --days 400 --symbols ETHUSDT

8. Tech Stack

Area	Tools
Core / quant	Python 3.12, pandas, NumPy
Visualisation	matplotlib, mplfinance
Bot / delivery	python-telegram-bot, Railway deployment
Market data	Binance & Coinbase APIs, yfinance (FX)
Analytical store	DuckDB, PyArrow / Parquet
ML (in progress)	scikit-learn (planned)

9. What I Learned / Demonstrates

Quantitative strategy design — translating trading intuition into precise, testable mathematical rules.
Backtesting rigour — avoiding look-ahead bias, modelling fees, benchmarking against buy-and-hold, and measuring drawdown.
Risk management — fixed-fractional sizing and multi-condition exit logic.
Data engineering — API ingestion, caching, and a feature/label pipeline for ML.
Productionisation — packaging the system as a deployable, scheduled Telegram bot with persistent state.

⚠️ Disclaimer

Educational analysis tool only. Not financial advice. Always do your own research and never risk more than you can afford to lose.