⚡ Nexus Scalp Engine

Research-driven quantitative trading engine
_{Causal features · Governed models · Invariant risk · Deterministic research · Forensic observability}
^{Hexagonal · Event-driven · MetaTrader 5 · XAUUSD M1 · Python 3.11}

English · فارسی · Español · العربية · Deutsch · 📚 Documentation

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

_{Pick your path — five doors, one engine}

🚀 Quick Start Run in under 5 minutes → Open

🏗️ Architecture System map & data flow → Explore

🔬 Research Claims & evidence → Validate

📖 Reference CLI · API → Lookup

🤝 Contribute Join the research → Join

---

🚀 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 (default, safe) → http://127.0.0.1:8080
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

_{Three paths — same safety guarantee · First run always PAPER, never LIVE silently}

🎁 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)

options — preview, repair, pin

# 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}

Advanced — rollback, manifests, SHA-256

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.

Overview · System Map · Data Flow · Model Pipeline · agents/skill.md

---

🔐 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

• The live adapter refuses a terminal logged into a different account than configured (account-identity fail-safe).
• Recommended path: DEMO MT5 → SHADOW for days → small LIVE → first-run guide

Warning

This bot places REAL trades with REAL money in LIVE mode. Hard clamps protect the strategy — not your capital from market volatility.

---

🖥️ Control Center

nexus start serves the Control Center at http://127.0.0.1:8080 — live M1 chart with Order Block / FVG / swept-liquidity overlays, entry-SL-TP lines with risk tooltips, plus Overview · Strategy Research · News Intelligence · Scalping Rules · Account · Debug Hub.

Telemetry streams over SSE, dashboard over WebSocket, tuner applies without restart. Docs → control-center-ui.md

---

⌨️ CLI

The bundled nexus console is the operational control surface (nse is a legacy alias; from source python -m nexus_scalp.cli.main).

nexus start [--mode paper|shadow|live] [--port N] [--daemon]   # paper default · live needs confirmation
nexus stop / restart                                           # control the background engine
nexus status / health                                          # READY / DEGRADED / NOT READY
nexus doctor                                                   # 19-category diagnostics + suggested fixes
nexus setup / install                                          # first-run wizard
nexus logs [--tail N] [--errors]                               # tail / filter / export logs
nexus config [--validate path]                                 # inspect / validate (secrets masked)
nexus test --mode quick|unit|integration                       # run suites (never live-broker tests)
nexus update check|download|install|verify|rollback            # release lifecycle
nexus export-diagnostics                                       # sanitized diagnostics ZIP (no secrets)

Stable exit codes: 0 success · 1 runtime/validation · 2 usage · 3 environment blocked · 4 release verification · 5 update. Full reference → CLI reference

Research / database / forensics commands

nexus model-dataset-build / -experiment-create / -train / -validate / -replay
                                               # artifact-first model factory (research)
nexus db hygiene status|plan|run               # database hygiene (audit-only by default)
nexus forensic --deploy-gate                   # forensic pre-release gate (wired into beforePush)
nexus incidents list|reports|export            # incident center (sanitized exports)
nexus repair                                   # non-destructive derived-state repair
nexus release info                             # installed release metadata

---

🐳 Docker

cp .env.example .env       # optional — safe defaults exist
docker compose up -d --build

Starts engine + Control Center in container-safe PAPER mode; dashboard at http://localhost:9090; /health readiness (READY/DEGRADED = healthy). Full reference → docs/docker.md

🐧 Linux (WSL2) MT5 test platform

Verified TEST/PAPER environment: MT5 build 6191 under Wine 10.0 in an isolated prefix, headless via Xvfb, lifecycle via scripts/linux/mt5_runtime.sh. Direct Python MetaTrader5 IPC is unsupported under Wine — the supported path is RemoteMT5GatewayAdapter. WSL2 → Windows-host TCP is firewalled by default. Full reference → docs/linux_wsl2_mt5_platform.md · toolkit README → scripts/linux/README.md

---

🔬 Research & Validation

DATA ─► FEATURES ─► MODEL ─► STRATEGY ─► BACKTEST ─► WALK-FORWARD ─► OOS GATE
     ─► ROBUSTNESS ─► COUNTERFACTUAL ─► REPLAY ─► VALIDATION ─► OPERATOR PROMOTION

• Philosophy: reproducibility, no future leakage, deterministic replay, identity/fingerprint tracking, dataset & model provenance, execution fidelity — methodology · validation · runtime path
• Negative results are published, not buried. The flagship 70D series (scalp_v3) was returned NOT_ELIGIBLE by the hard OOS gate on real-data walk-forward and was not promoted. The live contract remains governed. Evidence: TASK-05 · TASK-09 · status

---

🧪 Engineering Quality

pytest tests/unit -q              # unit corpus (critical subset: tests/critical_suite.txt)
pytest tests/unit tests/integration -q
./beforePush.sh -SkipPush         # full gate: ruff · format · mypy · critical suite · forensic deploy gate

CI runs ruff · mypy · pytest (critical suite) · CodeQL · Trivy · OSV · JS tests. Keep commits atomic (<Name>: <summary>); reuse > extend > refactor > create. Quality docs → docs/engineering/quality.md

---

⭐ If Nexus was useful — a star is the best thank you

_{Helped you learn, research, or trade smarter — even a little?}
One click · 2 seconds · fuels months of open research. We'd be truly grateful. 🙏

_{If this project is usable or profitable for you, please consider starring — it helps others discover Nexus and motivates the next release.}

Tip

No sign-up, no cost, no catch — just a ⭐. That one star tells GitHub this research matters, pushes Nexus to more traders and researchers, and is the kindest way to say thank you if Nexus delivered any value to you.

Star History

_{Every ⭐ you gave made this curve — thank you for being part of it.}

---

📚 Documentation

Site: https://opselon.github.io/NexusTradingForexBot/

Category	Entry points
Getting started	quickstart · installation
Architecture	overview · system map
Research	methodology · validation
Engineering & quality	quality gates · release process
Guides	troubleshooting · common workflows
Reference	CLI reference · FAQ
Contributing	contribution guide · add a language

Languages: English (source) · فارسی · Español · العربية · Deutsch — RTL for Persian/Arabic; partial translations are marked honestly.

Engineering memory & internal maps (maintainers)

• agents/skill.md — authoritative architecture map
• agents/bugs.md — public forensic bug ledger (BUG-001…)
• agents/runtime_invariants.md — INV registry
• agents/contracts.md · agents/taskboard.md
• docs/forensics/README.md — forensic recovery & provenance index
• docs/70D_DATA_CONTRACT.md — 70D research contract

Repository structure

src/nexus_scalp/   Core engine (hexagonal packages: domain, ports, adapters, features,
                   models, signals, risk, execution, application, research, shadow, …)
tests/             Unit + integration + golden + js + installer suites
Web/               Control Center UI — buildless vanilla-JS SPA (no Node runtime)
agents/            Engineering memory: architecture map, bug ledger, contracts, taskboard
docs/              Engineering documentation (this platform's IA tree)
site/              GitHub Pages source (multilingual static site)
configs/           base.yaml · live.yaml.example
scripts/           Build/release scripts, quality gates, docs tooling (scripts/docs/)
installer/         PowerShell bootstrap installer (stage protocol)
docker/            entrypoint.sh · healthcheck.sh
pics/              Screenshots

---

🤝 Contributing

Nexus is actively evolving and welcomes contributors in quantitative research · ML / time-series modeling · market microstructure · trading-system engineering · frontend / Control Center · testing / QA · documentation and localization.

1. Read the contribution guide.
2. Claim a task in agents/taskboard.md or open an issue with a [Research] / [Proposal] tag.
3. Fork & submit a PR — atomic commits (<Name>: <summary>), Ruff, strict mypy, pytest coverage. Evidence-based changes only.

---

📌 Status & Roadmap

Versioning is single-sourced in pyproject.toml (semver, stamped into every artifact) — the release badge reads the latest tag dynamically.

Current state → docs/project/status.md · capabilities

Known limitations (published, not hidden):

• 70D research series is candidate-only with negative OOS evidence so far; live contract stays 50D until a candidate clears all gates and an operator promotes it.
• Packaged release is Windows x64 only.
• News engine is opt-in (disabled until a news: config block exists).
• No CLI hot-swap to the PAPER adapter — risk-free validation goes through SHADOW or a demo account.

Current priorities:

• Rebuild 70D candidate evidence under corrected confidence semantics (CHG-0042) — under evaluation
• Counterfactual evidence deepening (CHG-0041) → policy review
• Large-file decomposition with golden tests (CHG-0032-A1)
• 70D promotion decision — operator-gated, or honest retirement

Full roadmap with dependencies & completion gates → docs/project/roadmap.md

---

📄 License & Disclaimer

DISCLAIMER: Algorithmic trading — especially leveraged XAUUSD/Gold scalping — carries immense financial risk. This engine is provided strictly for educational, academic research and simulation purposes; it does not guarantee profit and is not financial advice. Always perform rigorous backtesting and forward paper-trading before committing capital. In LIVE mode it can place real trades — operator responsibility.

Proprietary License — All Rights Reserved. Designed for Quantitative Excellence.

---

Documentation · Roadmap · Status · Issues · Releases