[!IMPORTANT]
Research and engineering platform — not a promise of profit. Every status claim is evidence-graded, and this repository publishes its negative results alongside wins. Leveraged XAUUSD scalping carries extreme financial risk.
🧭 Start here
🚀 Quick Start
git clone https://github.com/Opselon/NexusTradingForexBot.git
cd NexusTradingForexBot
python -m venv .venv
# Windows PowerShell: .\.venv\Scripts\Activate.ps1
# Linux / macOS: source .venv/bin/activate
pip install -e ".[dev]"
nexus doctor # read-only diagnostics + suggested fixes
nexus repair --model # fresh clone only: provision the PAPER starter model bundle
nexus start # PAPER mode (safe) → auto-opens Control Center in default browser
nexus start --no-browser # start runtime without launching browser (headless / CI / automation)
nexus start --mode shadow # live feed, ZERO order authority — recommended for evaluation
nexus stop
Control Center opens at http://127.0.0.1:8080 — live M1 chart, Order Blocks, FVGs, risk overlays, and tuner.
More entry paths + first-run wizard → installation · quickstart
💡 What is Nexus?
Nexus Scalp Engine (NSE) unifies deep-learning inference, market-microstructure analysis, and high-frequency execution into one auditable pipeline:
Causal Feature Engine → Dual-path TCN + Self-Attention (ScalpNet) → SMC Policy Matrix (Order Blocks · Fair Value Gaps · Liquidity Sweeps) → Invariant Risk Engine → Hard-Clamped Execution Router — all on a hexagonal core that talks to MetaTrader 5 via Win32 IPC, ZMQ gateway, or a paper simulator.
What makes Nexus different is not a claim of alpha — it's how claims are treated:
identity fingerprints on every dataset / model / run · hard out-of-sample gates · bit-exact replay · immutable ledgers · public forensic bug ledger — rejected candidates stay published.
📦 Installation
🎁 End users — packaged release
No Python needed · Windows x64 · double-click install
Download from Releases → and run:
NexusScalpEngine-<version>-win-x64-setup.exe → installer (recommended)
NexusScalpEngine-<version>-win-x64-portable.zip → unzip & run
First-run wizard defaults to PAPER mode. Upgrades preserve your config.
⚡ PowerShell bootstrap — zero prerequisites
No Python · No Git · No admin · installs to %LOCALAPPDATA%\Nexus
Paste in PowerShell — click top-right copy button:
iex (irm https://raw.githubusercontent.com/Opselon/NexusTradingForexBot/main/installer/install.ps1)
# Preview what it will do (no changes)
iex (irm https://raw.githubusercontent.com/Opselon/NexusTradingForexBot/main/installer/install.ps1) -DryRun
# Heal a broken install
.\install.ps1 -Repair
# Pin to an exact commit
.\install.ps1 -Commit <sha>
Idempotent & repeatable · -DryRun · -Repair · -Commit <sha> · portable Git fallback if needed
👩💻 Developers — from source
See 🚀 Quick Start above — clone, venv, pip install -e ".[dev]", nexus start.
Requires Python 3.11 + Git. Full dev setup → installation guide
Full reference: docs/INSTALL_WINDOWS.md · docs/INSTALLER_ARCHITECTURE.md
The release pipeline ships SHA-256 manifests + SBOM with post-publish verification; nexus update verify|rollback covers the installed lifecycle.
🛡️ Why Nexus — Engineering Philosophy
Enforced in code and contracts, not just stated:
| Principle | Guarantee |
|---|
| 📊 Evidence before claims | Metrics without evidence render n/a, never fake zeros; runtime claims are graded |
| ⏳ No lookahead | Purged + embargoed walk-forward; strictly causal features — INV-008 |
| 🔄 Causal parity | live = replay = training feature semantics, protected by schema hashing |
| 🎯 Runtime truth | Broker truth wins over stale local state; gates are runtime authorities, settings are intent — INV-011 |
| 🧱 Layered isolation | Hexagonal ports/adapters; research holds zero order authority — INV-002; hot path never blocks on DB/training/network — INV-001 |
| ✅ Validation before promotion | OOS failure ⇒ REJECTED; promotion is strictly operator-gated; candidates never promote themselves |
Deep dive → architecture overview · runtime invariants
🏗️ Architecture at a glance
Market Data ( MT5 · ZMQ gateway · paper )
↓
Causal Features ── 50D live contract (scalp_v1) · governed 70D research assembly
↓
Inference Validator ── schema hash · scaler dim · bounds (loud rejection, never silent)
↓
ScalpNet ( TCN + self-attention ) ── 4 logits → confidence gate → Regime Guardian
↓
SMC Policy Matrix ──► Risk Engine ( Kelly sizing · margin / tier clamps )
↓
OrderManager ── scenario router · position-state machine · hard clamps
↓
IMT5Port adapter ──► MetaTrader 5 (live) · paper simulator · zero-order shadow
↓
Accounting ( immutable SQLite WAL ledger ) ──► Experience & autopsy intelligence
↓
Observability ( logs · incidents · forensics ) ↔ Research loop
↓ ( walk-forward → OOS gate → operator promotion )
Control Center ( FastAPI · REST / SSE / WS dashboard )
Every stage is isolated behind hexagonal ports — every promotion requires an operator decision on reproducible evidence.
🔐 Safety & Operating Modes
| Mode | Market data | Orders | Purpose |
|---|
| PAPER (default) | simulated | simulated | First run, development, UI work |
| SHADOW | live feed | none — zero order authority | Evaluate signals on real data, risk-free |
| LIVE | live feed | real | Real financial risk — explicit confirmation + full risk panel |
This is the beginning of the README. Read the rest at the original. Read the full README ↗
