392 lines
15 KiB
Markdown
392 lines
15 KiB
Markdown
> ⚠️ HISTORICAL — see docs/00-governance/ for current state
|
||
|
||
This file may contain outdated or mixed historical information.
|
||
Canonical current-state documentation lives in docs/00-governance/.
|
||
This file is retained for history/reference only.
|
||
|
||
# NT8-SDK — Project Context & Current State
|
||
**Version:** 3.0 | **Date:** 2026-03-27 | **Status:** Sprint 2 Active — SIM Validation
|
||
|
||
> This file supersedes the previous PROJECT_HANDOVER.md and is the live source of truth.
|
||
> See also: `SPRINT_BOARD.md`, `GAP_ANALYSIS_AND_ROADMAP.md`, `CODING_PATTERNS.md`, `KILOCODE_WORKFLOW.md`
|
||
> Full formatted handover: `NT8_SDK_Handover_Package.docx`
|
||
|
||
---
|
||
|
||
## 1. What This Is
|
||
|
||
NT8-SDK is an institutional-grade algorithmic futures trading system built on NinjaTrader 8. It is not a research prototype — it is production trading software where bugs equal real financial losses.
|
||
|
||
The system trades NQ (Nasdaq 100 E-mini futures) using a 30-minute Opening Range Breakout strategy (SimpleORB) with a 10-factor confluence scoring engine that grades each signal A+ through F before allowing execution. A scaler/runner dual-leg architecture captures quick targets on the scaler while the runner trails for extended moves.
|
||
|
||
**Division of labor:** Claude handles architecture, diagnosis, and Kilocode prompt design. Kilocode executes ALL code changes. Mo owns strategy direction and go/no-go decisions.
|
||
|
||
---
|
||
|
||
## 2. Technology Stack
|
||
|
||
| Layer | Technology | Constraint |
|
||
|---|---|---|
|
||
| Language | C# 5.0 | Hard — NinjaScript compiler limit |
|
||
| Framework | .NET Framework 4.8 | Hard — NT8 requirement |
|
||
| Platform | NinjaTrader 8 | Hard — execution environment |
|
||
| Local repo | `C:\dev\nt8-sdk` | Windows path |
|
||
| NT8 deploy | `C:\Users\billy\Documents\NinjaTrader 8\bin\Custom\Strategies\` | Must match source |
|
||
| Deploy script | `deployment\deploy-to-nt8.bat` | Creates timestamped backups |
|
||
| VCS | Gitea (self-hosted) | `https://git.thehussains.org/mo/nt8-sdk` |
|
||
| AI coding | Kilocode | Executes ALL code changes |
|
||
| Automation | n8n (self-hosted) | Deferred to Sprint 4 |
|
||
| ML inference | Ollama (local) | Deferred to Sprint 5 |
|
||
|
||
**Critical C# constraint:** No `$""`, no `?.`, no `=>`, no async/await. Use `string.Format()`, explicit null checks, full method bodies.
|
||
|
||
---
|
||
|
||
## 3. Architecture (Top to Bottom)
|
||
|
||
```
|
||
SimpleORBNT8.cs NT8 entry point — sets defaults, adds daily bar series, builds DailyBarContext
|
||
↓
|
||
NT8StrategyBase.cs Abstract base — bar routing, session management, kill switch, breakeven, runner
|
||
↓
|
||
SimpleORBStrategy.cs Core signal — ORB detection, 10-factor confluence, _tradeTaken session lock
|
||
↓
|
||
NT8OrderAdapter.cs INT8ExecutionBridge — calls EnterLong/EnterShort/SetStopLoss
|
||
↓
|
||
PortfolioRiskManager.cs Singleton — cross-strategy daily loss + contract cap
|
||
↓
|
||
NinjaTrader 8 Execution, fills, order management
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Current Production Parameters (SIM: SimSimple ORB)
|
||
|
||
| Parameter | Value | Notes |
|
||
|---|---|---|
|
||
| Instrument | NQ JUN26 | Primary instrument |
|
||
| Bar type | 13-Range bars | |
|
||
| BarsRequiredToTrade | 50 | Warm-up guard |
|
||
| DailyLossLimit | $1,000 | |
|
||
| MaxTradeRisk | $200 | |
|
||
| RiskPerTrade | $100 | 2 contracts at current NQ prices |
|
||
| MinContracts | 1 | |
|
||
| MaxContracts | 3 | |
|
||
| MaxOpenPositions | 2 | Scaler + runner |
|
||
| EntriesPerDirection | 2 | Scaler slot 1, runner slot 2 |
|
||
| MinTradeGrade | 5 (A) | 4 (B) for broad SIM testing |
|
||
| EnableShortTrades | False | Long-only until short backtest done |
|
||
| BreakevenTriggerTicks | 20 | Tuned from 12 |
|
||
| RunnerTrailTicks | 20 | Tuned from 12 |
|
||
| OpeningRangeMinutes | 30 | 9:30–10:00 ET |
|
||
| StopTicks | 8 | $40 per contract NQ |
|
||
| TargetTicks | 16 (dynamic) | Scales with ORB/ATR ratio |
|
||
|
||
---
|
||
|
||
## 5. Two-Path Deployment Rule
|
||
|
||
Every code change MUST be applied to both:
|
||
1. `C:\dev\nt8-sdk\src\NT8.Adapters\Strategies\` (repo source)
|
||
2. `C:\Users\billy\Documents\NinjaTrader 8\bin\Custom\Strategies\` (NT8 runtime)
|
||
|
||
After deployment, NT8 must recompile: Tools → Edit NinjaScript → open `NT8StrategyBase.cs` → save.
|
||
|
||
---
|
||
|
||
## 6. Key Learnings (Hard-Won)
|
||
|
||
1. **`State.Historical` guard** — `if (State == State.Realtime && !_realtimeBarSeen) return;` in `ProcessStrategyIntent` allows backtest (Historical), blocks replay burst in live.
|
||
|
||
2. **`_realtimeBarSeen` flag** — reset to `false` in `State.Realtime`, set `true` on first bar. Skips catch-up bar on live load to prevent replay burst.
|
||
|
||
3. **`EntriesPerDirection = 2`** — required for scaler + runner. Setting to 1 silently blocks the runner with no error.
|
||
|
||
4. **`SetStopLoss`/`SetProfitTarget` before `EnterLong`/`EnterShort`** — calling after entry is silently ignored in backtest.
|
||
|
||
5. **`Calculate.OnBarClose` backtest** — trades appear to close in under 1 second in logs. NT8 simulation artifact, not a bug. Live trades hold 2–20 minutes.
|
||
|
||
6. **NR7 warm-up** — requires 7 daily bars. Warm-up messages (0/7 bars) are correct behavior.
|
||
|
||
7. **NT8 never auto-recompiles** — always force recompile after file changes via NinjaScript Editor.
|
||
|
||
8. **Dual-path deployment mandatory** — stale deployed files cause phantom bugs where code looks right but behaves wrong.
|
||
|
||
9. **`PortfolioRiskManager` is a singleton** — fully implemented, no changes required. Kill switch, daily loss, contract cap all working.
|
||
|
||
10. **Sizing formula** — `floor(RiskPerTrade / (StopTicks × $5.00))`. NQ: `$100 / (8 × $5) = 2 contracts`. Always verify `RiskPerTrade <= MaxTradeRisk`.
|
||
|
||
---
|
||
|
||
## 7. Validated Backtest Results
|
||
|
||
| Date | Period | Trades | Win% | PF | Net | Config |
|
||
|---|---|---|---|---|---|---|
|
||
| 2026-03-27 | Jan–Mar 2026 | 20 | 75% | **7.00** | $1,200 | 1 ct, trail=20 ✅ Best |
|
||
| 2026-03-27 | Jan–Mar 2026 | 40 | 75% | 3.69 | $1,075 | 1 ct, trail=12 |
|
||
| 2026-03-27 | Mar 2025–Mar 2026 | 148 | 51% | 3.15 | $71,303 | 9 cts (experimental) |
|
||
|
||
The 9-contract run used `RiskPerTrade=$500` — not a production configuration. Runner leg was also blocked (`EntriesPerDirection=1`) for that run. Re-run required after Sprint 2 fixes.
|
||
|
||
---
|
||
|
||
## 8. Immediate Next Actions Before Market Open
|
||
|
||
1. Run Strategy Analyzer (NQ JUN26, Jan 1 2026 → Mar 27 2026) and confirm `PNL_UPDATE Position=Short Qty=2` in session log — validates runner leg
|
||
2. Verify SIM account settings: `RiskPerTrade=$100`, `BreakevenTriggerTicks=20`, `RunnerTrailTicks=20`
|
||
3. Only re-enable BX68915-15 after runner validation passes — long-only, `MaxContracts=2`, `DailyLossLimit=$500`
|
||
|
||
---
|
||
|
||
## 📋 Executive Summary
|
||
|
||
The NT8 SDK is an **institutional-grade algorithmic trading framework** for NinjaTrader 8, designed for automated futures trading (ES, NQ, MES, MNQ, CL, GC). Successfully completed **Phases 0-5** implementing core trading infrastructure, advanced risk management, intelligent position sizing, market microstructure awareness, intelligence layer with confluence scoring, and comprehensive analytics & reporting.
|
||
|
||
**Current State:** Production-ready core trading engine with 240+ passing tests, complete analytics layer, ready for production hardening.
|
||
|
||
---
|
||
|
||
## 🎯 Project Vision & Purpose
|
||
|
||
### Core Mission
|
||
Build an institutional-grade trading SDK that:
|
||
- **Protects Capital First** - Multi-tier risk management before profit
|
||
- **Makes Intelligent Decisions** - Grade trades based on multiple factors
|
||
- **Executes Professionally** - Sub-200ms latency, thread-safe operations
|
||
- **Measures Everything** - Comprehensive analytics and attribution
|
||
|
||
### Why This Matters
|
||
- This is **production trading software** where bugs = real financial losses
|
||
- System runs **24/5** during market hours
|
||
- **Institutional-grade quality** required (not hobbyist code)
|
||
- Must be **deterministic** for backtesting and auditing
|
||
|
||
---
|
||
|
||
## ✅ Completed Phases (0-5)
|
||
|
||
### Phase 0: Foundation (30 minutes)
|
||
**Status:** ✅ Complete
|
||
**Deliverables:** Repository structure, build system, .NET Framework 4.8 setup
|
||
|
||
### Phase 1: Basic OMS (2 hours)
|
||
**Status:** ✅ Complete
|
||
**Tests:** 34 passing
|
||
**Code:** ~1,500 lines
|
||
**Deliverables:** Order state machine, basic order manager, NT8 adapter interface
|
||
|
||
### Phase 2: Enhanced Risk & Sizing (3 hours)
|
||
**Status:** ✅ Complete
|
||
**Tests:** 90+ passing
|
||
**Code:** ~3,000 lines
|
||
**Deliverables:** Multi-tier risk management, intelligent position sizing, optimal-f calculator
|
||
|
||
### Phase 3: Market Microstructure & Execution (3-4 hours)
|
||
**Status:** ✅ Complete
|
||
**Tests:** 120+ passing
|
||
**Code:** ~3,500 lines
|
||
**Deliverables:** Liquidity monitoring, execution quality tracking, slippage calculation
|
||
|
||
### Phase 4: Intelligence & Grading (4-5 hours)
|
||
**Status:** ✅ Complete
|
||
**Tests:** 150+ passing
|
||
**Code:** ~4,000 lines
|
||
**Deliverables:** Confluence scoring, regime detection, grade-based filtering, risk mode management
|
||
|
||
### Phase 5: Analytics & Reporting (3-4 hours)
|
||
**Status:** ✅ **COMPLETE - 2026-02-16**
|
||
**Tests:** 240+ passing (90 new analytics tests)
|
||
**Code:** ~5,000 lines
|
||
**Deliverables:**
|
||
- Trade lifecycle tracking & recording
|
||
- Performance metrics (Sharpe, Sortino, win rate, profit factor)
|
||
- Multi-dimensional P&L attribution (by grade, regime, time, strategy)
|
||
- Drawdown analysis with period detection
|
||
- Grade/Regime/Confluence performance insights
|
||
- Daily/Weekly/Monthly reporting
|
||
- Parameter optimization tools
|
||
- Monte Carlo simulation
|
||
- Portfolio optimization
|
||
|
||
---
|
||
|
||
## 📊 Current Metrics
|
||
|
||
- **Total Production Code:** ~20,000 lines
|
||
- **Total Tests:** 240+
|
||
- **Test Pass Rate:** 100%
|
||
- **Code Coverage:** >85%
|
||
- **Performance:** All benchmarks exceeded
|
||
- **Analytics Components:** 15 major modules
|
||
- **Zero Critical Warnings:** Legacy warnings only (unchanged baseline)
|
||
|
||
---
|
||
|
||
## 🎯 Recommended Next Steps
|
||
|
||
### Option 1: Production Hardening (Recommended)
|
||
**Focus:** Make the system production-ready for live trading
|
||
|
||
**Priority Tasks:**
|
||
1. **CI/CD Pipeline**
|
||
- Automated build verification on commit
|
||
- Automated test execution
|
||
- Code coverage reporting
|
||
- Deployment automation to NinjaTrader 8
|
||
|
||
2. **Integration Testing Enhancement**
|
||
- End-to-end workflow tests
|
||
- Multi-component integration scenarios
|
||
- Performance benchmarking suite
|
||
- Stress testing under load
|
||
|
||
3. **Monitoring & Observability**
|
||
- Structured logging enhancements
|
||
- Health check endpoints
|
||
- Performance metrics collection
|
||
- Alert system for risk breaches
|
||
|
||
4. **Configuration Management**
|
||
- JSON-based configuration system
|
||
- Environment-specific configs (dev/sim/prod)
|
||
- Runtime parameter validation
|
||
- Configuration hot-reload capability
|
||
|
||
5. **Error Recovery & Resilience**
|
||
- Graceful degradation patterns
|
||
- Circuit breaker implementations
|
||
- Retry policies with exponential backoff
|
||
- Dead letter queue for failed orders
|
||
|
||
**Estimated Time:** 2-3 weeks with focused effort
|
||
|
||
---
|
||
|
||
### Option 2: Golden Strategy Implementation
|
||
**Focus:** Build reference strategy to validate all modules
|
||
|
||
**Deliverable:** Complete SimpleORBStrategy implementation that:
|
||
- Uses all Phase 1-5 components
|
||
- Demonstrates best practices
|
||
- Serves as template for future strategies
|
||
- Includes comprehensive backtesting
|
||
|
||
**Estimated Time:** 1 week
|
||
|
||
---
|
||
|
||
### Option 3: Advanced Features (Future Enhancements)
|
||
**Focus:** Add sophisticated trading capabilities
|
||
|
||
**Potential Additions:**
|
||
- Smart order routing across venues
|
||
- Advanced order types (Iceberg, TWAP, VWAP)
|
||
- ML model integration framework
|
||
- Multi-timeframe analysis
|
||
- Correlation-based portfolio management
|
||
|
||
**Estimated Time:** 2-4 weeks per major feature
|
||
|
||
---
|
||
|
||
## 📁 Repository Structure
|
||
|
||
```
|
||
C:\dev\nt8-sdk\
|
||
├── src/
|
||
│ ├── NT8.Core/ # Core business logic (20,000 lines)
|
||
│ │ ├── Analytics/ ✅ Phase 5 - Trade analytics & reporting
|
||
│ │ ├── Intelligence/ ✅ Phase 4 - Confluence & grading
|
||
│ │ ├── Execution/ ✅ Phase 3 - Execution quality
|
||
│ │ ├── MarketData/ ✅ Phase 3 - Market microstructure
|
||
│ │ ├── Sizing/ ✅ Phase 2 - Position sizing
|
||
│ │ ├── Risk/ ✅ Phase 2 - Risk management
|
||
│ │ ├── OMS/ ✅ Phase 1 - Order management
|
||
│ │ ├── Common/ ✅ Phase 0 - Core interfaces
|
||
│ │ └── Logging/ ✅ Phase 0 - Logging infrastructure
|
||
│ ├── NT8.Adapters/ # NinjaTrader 8 integration
|
||
│ ├── NT8.Strategies/ # Strategy implementations
|
||
│ └── NT8.Contracts/ # API contracts
|
||
├── tests/
|
||
│ ├── NT8.Core.Tests/ # 240+ unit tests
|
||
│ ├── NT8.Integration.Tests/ # Integration test suite
|
||
│ └── NT8.Performance.Tests/ # Performance benchmarks
|
||
├── docs/ # Complete documentation
|
||
│ ├── Phase5_Completion_Report.md # NEW: Analytics completion
|
||
│ ├── ARCHITECTURE.md
|
||
│ ├── API_REFERENCE.md
|
||
│ └── DEPLOYMENT_GUIDE.md
|
||
└── .kilocode/ # AI development rules
|
||
```
|
||
|
||
---
|
||
|
||
## 🔑 Key Architecture Highlights
|
||
|
||
### Risk-First Design
|
||
All trading operations flow through multi-tier risk validation before execution. No shortcuts, no bypasses.
|
||
|
||
### Thread-Safe Operations
|
||
Comprehensive locking patterns protect all shared state from concurrent access issues.
|
||
|
||
### Deterministic Replay
|
||
Complete audit trail with correlation IDs enables exact replay of historical sessions.
|
||
|
||
### Modular Component Design
|
||
Clean separation between Core (business logic), Adapters (NT8 integration), and Strategies (trading logic).
|
||
|
||
### Analytics-Driven Optimization
|
||
Full attribution and performance measurement enables data-driven strategy improvement.
|
||
|
||
---
|
||
|
||
## 📞 Support & Documentation
|
||
|
||
- **Architecture Guide:** `docs/ARCHITECTURE.md`
|
||
- **API Reference:** `docs/API_REFERENCE.md`
|
||
- **Deployment Guide:** `docs/DEPLOYMENT_GUIDE.md`
|
||
- **Quick Start:** `docs/QUICK_START.md`
|
||
- **Phase Reports:** `docs/Phase*_Completion_Report.md`
|
||
|
||
---
|
||
|
||
## 🎉 Phase 5 Highlights
|
||
|
||
### What Was Built
|
||
- **15 major analytics components** covering the complete analytics lifecycle
|
||
- **90 new tests** bringing total to 240+ with 100% pass rate
|
||
- **Multi-dimensional attribution** enabling detailed performance breakdown
|
||
- **Optimization toolkit** for systematic strategy improvement
|
||
- **Production-ready reporting** with daily/weekly/monthly summaries
|
||
|
||
### Key Capabilities Added
|
||
1. **Trade Lifecycle Tracking** - Complete entry/exit/partial-fill capture
|
||
2. **Performance Measurement** - Sharpe, Sortino, win rate, profit factor, expectancy
|
||
3. **Attribution Analysis** - By grade, regime, time-of-day, strategy
|
||
4. **Drawdown Analysis** - Period detection, recovery metrics, risk assessment
|
||
5. **Confluence Validation** - Factor analysis, weighting optimization
|
||
6. **Parameter Optimization** - Grid search, walk-forward, sensitivity analysis
|
||
7. **Monte Carlo Simulation** - Confidence intervals, risk-of-ruin calculations
|
||
8. **Portfolio Optimization** - Multi-strategy allocation, portfolio-level metrics
|
||
|
||
### Technical Excellence
|
||
- ✅ Thread-safe in-memory storage
|
||
- ✅ Zero interface modifications (backward compatible)
|
||
- ✅ Comprehensive XML documentation
|
||
- ✅ C# 5.0 / .NET Framework 4.8 compliant
|
||
- ✅ Performance optimized (minimal allocations in hot paths)
|
||
|
||
---
|
||
|
||
## 🚀 Project Status: PHASE 5 COMPLETE
|
||
|
||
**The NT8 SDK now has a complete, production-grade analytics layer ready for institutional trading.**
|
||
|
||
Next recommended action: **Production Hardening** to prepare for live deployment.
|
||
|
||
---
|
||
|
||
**Document Prepared:** February 16, 2026
|
||
**Last Updated:** February 17, 2026
|
||
**Version:** 2.0
|