Binance Bot

Python Binance Spot trading bot with a Flask dashboard, SQLite trade journal, backtesting, and an optional ML-assisted V7 decision layer.

Version

• Current version: V7
• Strategy core: rule-based SMA + RSI + regime/scoring engine
• ML role: optional second-stage trade quality filter and score booster
• Dashboard port: 8081
• Deployment target: Docker / Synology NAS compatible

Sitemap

Project root:

• Dockerfile
• docker-compose.yml
• requirements.txt
• README.md
• app/.env
• data/
• logs/

Application modules:

• app/bot.py

Main live trading loop.

• app/dashboard.py

Flask dashboard and /health endpoint.

• app/backtest.py

Rule-only and ML-assisted backtesting.

• app/train_model.py

CLI training entrypoint for the V7 ML model.

• app/strategy.py

Rule-based entry/exit logic, multi-timeframe checks, regime-aware exits.

• app/risk.py

Risk sizing, exposure caps, duplicate setup protection.

• app/scanner.py

Symbol universe filtering and candidate scanning.

• app/tracker.py

SQLite schema, migrations, journal queries, backtest/model registry.

• app/state.py

JSON runtime state, opportunities, rejections.

• app/feature_engineering.py

Shared market/setup feature extraction for live and backtest.

• app/ml_model.py

Local model loading, training, inference, metadata.

• app/decision_fusion.py

Rule score + ML score fusion logic.

• app/market_regime.py

Explainable regime classification.

• app/signal_ranker.py

Deterministic internal scoring engine.

• app/symbol_stats.py

Symbol memory and performance penalties.

• app/config_validator.py

Startup validation.

• app/indicators.py

Technical indicators and volatility helpers.

• app/alerts.py

Telegram notifications.

• app/env_utils.py

Shared .env loading helper.

Version Notes

V6.5

• Multi-timeframe confirmation
• Explainable market regime detection
• Deterministic internal scoring/confidence engine
• Adaptive risk sizing
• ATR-style dynamic stops and targets
• Symbol memory and loss-streak protection
• Improved dashboard and trade journal

V7

• ML-assisted feature extraction
• Historical label generation from SQLite trades
• Local model training pipeline
• Optional ML inference layer for live bot and backtest
• Decision fusion between rule engine and ML score
• Dashboard sections for ML model status and ML decisions

How It Works

1. The scanner finds eligible symbols.
2. The rule engine in app/strategy.py evaluates entry quality.
3. V7 feature extraction builds a structured snapshot.
4. If ML is enabled and a trained model exists, the ML layer scores the setup.
5. Decision fusion combines rule score and ML score.
6. Risk management sizes the trade.
7. Trades, signals, features, and equity are stored in SQLite and JSON state files.

Running

Install dependencies locally:

pip install -r requirements.txt

Run the live bot:

python app/bot.py

Run the dashboard:

python app/dashboard.py

Open:

http://localhost:8081

Backtesting

Rule-only mode:

python app/backtest.py --symbol BTCUSDT --days 90 --mode rule

ML-assisted mode:

python app/backtest.py --symbol BTCUSDT --days 90 --mode ml

Training the V7 ML Model

Important:

• The model only trains on V7 trades that have stored feature_snapshot data.
• Old trades from earlier versions are not enough unless they were logged with V7 feature snapshots.
• If no trained model exists, the bot safely falls back to rule-only behavior.

Recommended process:

1. Run the V7 bot and collect completed trades.
2. Make sure trades are being logged with feature snapshots.
3. Install dependencies:

pip install -r requirements.txt

1. Train the model:

python app/train_model.py

Optional training flags:

python app/train_model.py --lookback-days 365 --min-samples 50
python app/train_model.py --label-mode binary
python app/train_model.py --model-path /data/models/trade_quality_model.pkl

Training output includes:

• model version
• training sample count
• metrics
• top feature importances

After training:

1. Set ML_ENABLED=true in app/.env
2. Restart the bot and dashboard
3. Review the ML section in the dashboard
4. Compare rule-only vs ML backtests before trusting live filtering

Minimum ML Readiness

Suggested minimum before enabling live ML filtering:

• 50-100 completed V7 trades: enough to experiment
• 100-200 completed V7 trades: reasonable for paper testing
• 200+ completed V7 trades: better for serious evaluation

Quality matters more than count:

• include winners and losers
• include multiple symbols
• include multiple market regimes
• avoid training only on one narrow market phase

Main Data Files

• SQLite DB: data/trades.db
• Runtime status: data/status.json
• Open positions: data/positions.json
• Signals cache: data/signals.json
• Opportunities cache: data/opportunities.json
• Rejections cache: data/rejections.json
• Logs: logs/bot.log

Key Environment Areas

See app/.env for:

• Binance / mode settings
• strategy and timeframe settings
• regime/scoring settings
• risk settings
• dashboard settings
• ML settings

Docker

Rebuild after dependency changes:

docker compose build --no-cache
docker compose up -d

Safety Notes

• ML does not place trades by itself.
• Hard risk limits remain rule/risk managed.
• If the model is missing or inference fails, the bot continues in rule-only fallback mode.
• Never commit real secrets from .env.