nt8-sdk/nt8_integration_guidelines.md

# NT8 Integration Guidelines for AI Agents

## CRITICAL: NinjaTrader 8 Specific Requirements

### NT8 Environment Constraints
- **File Location**: All custom strategies MUST go in `C:\Users\billy\Documents\NinjaTrader 8\bin\Custom\Strategies\`
- **Namespace**: MUST use `namespace NinjaTrader.NinjaScript.Strategies`
- **Base Class**: Custom strategies MUST inherit from `Strategy` (NinjaTrader's base class)
- **Compilation**: Code MUST compile within NT8's NinjaScript Editor

### NT8 Strategy Pattern (REQUIRED)
```csharp
using System;
using NinjaTrader.Cbi;
using NinjaTrader.NinjaScript.Strategies;
using NT8.Core.Common.Interfaces;
using NT8.Core.Common.Models;

namespace NinjaTrader.NinjaScript.Strategies
{
    public class YourStrategyName : Strategy
    {
        // 1. NT8 Properties (show in UI)
        [NinjaScriptProperty]
        [Display(Name = "Parameter Name", Order = 1)]
        public int ParameterName { get; set; } = 8;

        // 2. SDK Components
        private IStrategy _sdkStrategy;
        private IRiskManager _riskManager;
        
        // 3. NT8 Lifecycle Methods
        protected override void OnStateChange()
        {
            if (State == State.SetDefaults)
            {
                // Initialize NT8 strategy settings
                // Initialize SDK components
            }
        }
        
        protected override void OnBarUpdate()
        {
            // Convert NT8 data → SDK format
            // Call SDK strategy logic
            // Convert SDK results → NT8 actions
        }
    }
}
```

### Forbidden NT8 Patterns
- ❌ DO NOT try to replace NT8's Strategy base class
- ❌ DO NOT use different namespaces
- ❌ DO NOT bypass NT8's parameter system
- ❌ DO NOT access NT8 internals directly

### Required Integration Points

#### 1. Data Conversion (NT8 ↔ SDK)
```csharp
// Convert NT8 bar to SDK format
private BarData ConvertToSdkBar()
{
    return new BarData(
        symbol: Instrument.MasterInstrument.Name,
        time: Time[0],
        open: Open[0],
        high: High[0],
        low: Low[0],
        close: Close[0],
        volume: Volume[0],
        barSize: BarsPeriod.Value
    );
}
```

#### 2. Parameter Mapping (UI → SDK Config)
```csharp
private StrategyConfig CreateSdkConfig()
{
    var parameters = new Dictionary<string, object>();
    parameters.Add("StopTicks", StopTicks);
    parameters.Add("TargetTicks", TargetTicks);
    
    return new StrategyConfig(/*...*/);
}
```

#### 3. Order Execution (SDK → NT8)
```csharp
private void ExecuteInNT8(StrategyIntent intent, SizingResult sizing)
{
    if (intent.Side == OrderSide.Buy)
    {
        EnterLong(sizing.Contracts, "SDK_Entry");
        SetStopLoss("SDK_Entry", CalculationMode.Ticks, intent.StopTicks);
    }
}
```

## Implementation Steps for AI Agents

### Step 1: Create NT8 Strategy Wrapper
1. **File**: Create in `NT8Wrappers/` folder in repo
2. **Name**: Use pattern `[StrategyName]NT8Wrapper.cs`
3. **Inherit**: From NinjaTrader's `Strategy` class
4. **Include**: All required NT8 properties and lifecycle methods

### Step 2: Implement Data Conversion Layer
1. **Create**: `NT8DataConverter.cs` utility class
2. **Methods**: Convert between NT8 and SDK data formats
3. **Handle**: Bar data, account info, position data

### Step 3: Create Configuration Bridge
1. **Map**: NT8 parameters to SDK configuration objects
2. **Validate**: All parameters before passing to SDK
3. **Provide**: Sensible defaults for all parameters

### Step 4: Test Integration
1. **Compile**: In NT8 NinjaScript Editor
2. **Test**: On simulation account first
3. **Verify**: All SDK functionality works through NT8

## File Structure for NT8 Integration

```
nt8-sdk/
├── src/NT8.Adapters/
│   ├── NinjaTrader/
│   │   ├── NT8DataAdapter.cs
│   │   ├── NT8OrderAdapter.cs
│   │   └── NT8LoggingAdapter.cs
│   └── Wrappers/
│       ├── SimpleORBNT8Wrapper.cs
│       └── BaseNT8StrategyWrapper.cs
└── deployment/
    ├── NT8/
    │   ├── Strategies/           # Copy these to NT8
    │   └── DLLs/                # Copy SDK DLLs here
    └── install-instructions.md
```

## Testing Requirements

### Unit Tests (In Repository)
- Test data conversion methods
- Test configuration mapping
- Test SDK component initialization

### Integration Tests (In NT8)
- Compile strategy in NT8
- Run on simulation account
- Verify parameter UI works
- Test risk controls trigger
- Validate position sizing

## Common Pitfalls to Avoid

1. **Wrong Namespace**: Must use `NinjaTrader.NinjaScript.Strategies`
2. **Missing Attributes**: Need `[NinjaScriptProperty]` for UI parameters
3. **Wrong Base Class**: Must inherit from NT8's `Strategy`
4. **File Location**: Must place files in correct NT8 directories
5. **DLL References**: Must copy SDK DLLs to NT8 bin folder

## Success Criteria

### Compilation
- [ ] Strategy compiles in NT8 NinjaScript Editor
- [ ] No errors or warnings
- [ ] All SDK DLLs properly referenced

### UI Integration  
- [ ] Parameters show up in NT8 strategy properties
- [ ] All parameters have proper labels and validation
- [ ] Default values are sensible

### Functionality
- [ ] Strategy executes trades through SDK framework
- [ ] Risk management controls work
- [ ] Position sizing calculates correctly
- [ ] Logging integrates with NT8

### Testing
- [ ] Works on simulation account
- [ ] All test scenarios pass
- [ ] Performance is acceptable