> [!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
```bash
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](docs/getting-started/installation.md) · [quickstart](docs/getting-started/quickstart.md)
---
## 💡 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 →](https://github.com/Opselon/NexusTradingForexBot/releases)** and run:
```
NexusScalpEngine--win-x64-setup.exe → installer (recommended)
NexusScalpEngine--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:
```powershell
iex (irm https://raw.githubusercontent.com/Opselon/NexusTradingForexBot/main/installer/install.ps1)
```
options — preview, repair, pin
```powershell
# 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
```
Idempotent & repeatable · -DryRun · -Repair · -Commit <sha> · portable Git fallback if needed
#### 👩💻 Developers — from source
See **[🚀 Quick Start](#-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/INSTALL_WINDOWS.md) · [docs/INSTALLER_ARCHITECTURE.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](docs/architecture/overview.md) · [runtime invariants](agents/runtime_invariants.md)
---
## 🏗️ 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 |
- 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](docs/getting-started/first-run.md)
> [!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](docs/architecture/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`).
```text
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](docs/reference/cli-reference.md)
Research / database / forensics commands
```text
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
```bash
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](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](docs/linux_wsl2_mt5_platform.md) · toolkit README → [scripts/linux/README.md](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](docs/research/methodology.md) · [validation](docs/research/validation.md) · [runtime path](docs/architecture/runtime.md)
- **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](docs/TASK-05-70D-SHADOW-FINAL.md) · [TASK-09](docs/TASK-09-70D-CANDIDATE-VALIDATION-FINAL.md) · [status](docs/project/status.md)
---
## 🧪 Engineering Quality
```bash
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 (`: `); `reuse > extend > refactor > create`.
Quality docs → [docs/engineering/quality.md](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:**
| Category | Entry points |
|:---|:---|
| Getting started | [quickstart](docs/getting-started/quickstart.md) · [installation](docs/getting-started/installation.md) |
| Architecture | [overview](docs/architecture/overview.md) · [system map](docs/architecture/system-map.md) |
| Research | [methodology](docs/research/methodology.md) · [validation](docs/research/validation.md) |
| Engineering & quality | [quality gates](docs/engineering/quality.md) · [release process](docs/engineering/release-process.md) |
| Guides | [troubleshooting](docs/guides/troubleshooting.md) · [common workflows](docs/guides/common-workflows.md) |
| Reference | [CLI reference](docs/reference/cli-reference.md) · [FAQ](docs/reference/faq.md) |
| Contributing | [contribution guide](docs/contributing/contribution-guide.md) · [add a language](docs/contributing/add-language.md) |
**Languages:** English (source) · [فارسی](https://opselon.github.io/NexusTradingForexBot/fa/) · [Español](https://opselon.github.io/NexusTradingForexBot/es/) · [العربية](https://opselon.github.io/NexusTradingForexBot/ar/) · [Deutsch](https://opselon.github.io/NexusTradingForexBot/de/) — RTL for Persian/Arabic; partial translations are marked honestly.
Engineering memory & internal maps (maintainers)
- [`agents/skill.md`](agents/skill.md) — authoritative architecture map
- [`agents/bugs.md`](agents/bugs.md) — public forensic bug ledger (BUG-001…)
- [`agents/runtime_invariants.md`](agents/runtime_invariants.md) — INV registry
- [`agents/contracts.md`](agents/contracts.md) · [`agents/taskboard.md`](agents/taskboard.md)
- [`docs/forensics/README.md`](docs/forensics/README.md) — forensic recovery & provenance index
- [`docs/70D_DATA_CONTRACT.md`](docs/70D_DATA_CONTRACT.md) — 70D research contract
Repository structure
```text
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](docs/contributing/contribution-guide.md).
2. Claim a task in [`agents/taskboard.md`](agents/taskboard.md) or open an issue with a `[Research]` / `[Proposal]` tag.
3. Fork & submit a PR — atomic commits (`: `), Ruff, strict mypy, pytest coverage. **Evidence-based changes only.**
---
## 📌 Status & Roadmap
Versioning is single-sourced in [`pyproject.toml`](pyproject.toml) (semver, stamped into every artifact) — the release badge reads the latest tag dynamically.
Current state → **[docs/project/status.md](docs/project/status.md)** · [capabilities](docs/project/capabilities.md)
**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](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.*
---
