Production-grade basket trading system with risk-first architecture
Architecture · Deployment Guide · Portfolio Spec · Research Reports
A modular, research-driven basket trading system for XAUUSD (Gold) and forex pairs, built around a single principle: prove the alpha before building the system.
Unlike typical trading bots that jump straight to execution, this project follows a disciplined research-first workflow — clean data → validated signals → strict risk management → safe execution → feedback loop → optional ML/LLM augmentation.
- 🔬 Walk-forward validated — every strategy passes out-of-sample testing before promotion
- 🛡️ Risk-first design — drawdown guards, kill switches, position sizing, and daily loss caps enforced at the engine level
- 📊 Multi-strategy basket portfolio — 6 strategy branches across 3 pairs with priority-based conflict resolution
- 🔄 MT5 integration — paper trading, demo, and live execution via MetaTrader 5
- 📱 Telegram alerting — optional real-time notifications for trade events
- 🧪 Audit-driven development — 65-point audit completed, 15 critical fixes applied
- 🤖 ML/LLM roadmap — planned integration for regime detection, feature engineering, and trade analysis
Market Data
│
▼
┌─────────────────────┐
│ Data Validation & │ ← OHLCV cleaning, gap detection, spread sanity
│ Normalization │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ Feature Pipeline │ ← ATR, RSI, session features, candle structure
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ Strategy Engine │ ← Signal candidates with entry/SL/TP + reason tags
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ Risk Engine │ ← Position sizing, exposure caps, drawdown guard, kill switch
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ Execution Adapter │ ← Paper / MT5 dry-run / MT5 live, with idempotent order handling
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ Reporting & │ ← Trade ledger, metrics, Telegram alerts, feedback loop
│ Monitoring │
└─────────────────────┘
Each layer is independent. The strategy engine never touches broker logic. The risk engine is a hard gate before any execution. The execution adapter supports paper → dry-run → live promotion without code changes.
The active portfolio uses session-based strategies — setups triggered by London/NY session dynamics across multiple forex pairs.
| Branch | Strategy | Pair | Risk/Trade | Role |
|---|---|---|---|---|
eurusd_sweep |
Session Sweep + FVG | EURUSD | 1.00% | Primary alpha |
eurusd_continuation |
Session Continuation | EURUSD | 0.75% | Momentum capture |
eurusd_orb |
Opening Range Breakout | EURUSD | 0.50% | Flow engine |
gbpusd_sweep |
Session Sweep (adapted) | GBPUSD | 0.60% | Cross-pair expansion |
gbpusd_continuation |
Session Continuation | GBPUSD | 0.25% | Supplementary |
xauusd_continuation |
Session Continuation | XAUUSD | 0.75% | Gold momentum |
Conflict resolution: One position per symbol, branch priority ordering, cross-symbol overlap allowed.
Latest basket performance: ~4.5 setups/week across all branches, with 95%+ survival rate under single-position execution constraints.
├── src/nexabask/ # Core reusable package
│ ├── backtesting/ # Unified backtest engine (next-bar open, spread-aware)
│ ├── config/ # Path management, config loading
│ ├── execution/ # MT5 adapter, paper trade, portfolio runner, alerts
│ ├── features/ # Indicators (ATR, RSI Wilder's), feature builder
│ ├── models/ # Trade/position models (live, paper, trading)
│ ├── reporting/ # Metrics, trade ledger export
│ ├── risk/ # Risk manager (drawdown, consecutive loss, position cap)
│ └── strategies/ # Strategy implementations + base interface
│
├── research/ # Experiments, walk-forward validation, cross-asset
│ ├── experiments/ # Strategy-specific research (EURUSD sweep, M15, etc.)
│ └── walkforward/ # No-look-ahead validation scripts
│
├── docs/ # Architecture, specs, deploy guides, audit reports
│ └── reports/ # Per-round backtest & basket analysis reports
│
├── runtime/ # Sample configs (secrets excluded via .gitignore)
├── tests/ # Test suite
│
├── run_session_basket_demo_mt5.py # MT5 paper/demo runner
├── run_session_basket_execution_mt5.py # MT5 execution runner (dry-run default)
├── run_basket_backtest.py # Portfolio-level backtest
└── windows_*.bat # Windows RDP launchers
- Python 3.11+
- For MT5 integration: Windows with MetaTrader 5 installed
git clone https://github.com/Yanu403/NexaBask.git
cd NexaBask
pip install -r requirements.txtpython run_basket_backtest.pypython run_paper_trade.py --send-telegram-alertspython run_session_basket_demo_mt5_loop.pypython run_session_basket_execution_mt5_loop.py
# Add --allow-live-send to enable real order submission📖 See Windows Deployment Playbook for full setup instructions.
This project follows a strict dependency chain:
1. Clean data
2. Valid signal — no look-ahead bias
3. Strict risk management
4. Safe execution
5. Feedback & monitoring
6. ML only if it provably adds edge
7. LLM only as support layer (trade journal, regime annotation)
Building ML infrastructure before proving alpha is engineering theater. The current priority is validating the basket portfolio under live market conditions.
- ❌ No look-ahead bias (enforced via backward-only rolling + shift(1))
- ❌ No hidden future leakage
- ❌ No live trading before paper validation
- ❌ No overengineering before reusable core exists
- ✅ Every phase must pass audit before expanding scope
- Shared data loader, indicator pipeline, strategy interface
- Unified backtest engine with realistic execution modeling
- Risk manager with drawdown guards and kill switch
- Trade/position models
- Metrics and trade ledger
- Atomic state persistence (crash-safe)
- MT5 execution adapter with dry-run default
- Portfolio-level conflict resolution
- Telegram alerting hook
- Broker reconciliation for multi-position stateful management
- Restart-safe state handling across process crashes
- Tighter risk caps for live deployment
- Cross-regime validation (2022-2026 stress testing)
- ML Feature Engineering — regime detection, volatility clustering, session classification
- ML Signal Enhancement — model-augmented entry/exit timing (only if proven via walk-forward)
- LLM Trade Analysis — automated trade journaling, performance commentary, anomaly explanation
- LLM Operator Assistant — natural language query over trade history and risk metrics
- Multi-pair scaling with pair-specific parameter optimization
- Web dashboard for portfolio monitoring
- REST API for external signal consumption
- Backtest-as-a-service for strategy research
Every strategy goes through a rigorous validation pipeline:
- Hypothesis — define the market behavior being exploited
- Implementation — code the strategy with strict no-look-ahead rules
- In-sample backtest — initial validation on training data
- Walk-forward validation — out-of-sample testing on unseen data
- Audit — bias detection, execution realism, risk sizing review
- Basket integration — portfolio-level conflict and overlap analysis
- Paper trading — live market validation via MT5 demo
- Promotion — only after all gates pass
Research reports for each round are preserved in docs/reports/ for full transparency.
Contributions are welcome. Please read the architecture docs before submitting changes.
Areas where help is especially valuable:
- Strategy research (new session patterns, additional pairs)
- ML feature engineering for regime detection
- Risk management improvements
- Documentation and testing
MIT — use it, fork it, learn from it.
NexaBask — Built with discipline, not hype.
"Don't build a sophisticated system before the alpha is proven."