nt8-sdk/docs/API_REFERENCE.md

# NT8 SDK - API Reference

**Version:** 0.2.0  
**Last Updated:** February 15, 2026

---

## Table of Contents

- [Core Interfaces](#core-interfaces)
- [Risk Management](#risk-management)
- [Position Sizing](#position-sizing)
- [Order Management](#order-management)
- [Data Models](#data-models)
- [Enumerations](#enumerations)

---

## Core Interfaces

### IStrategy

**Namespace:** `NT8.Core.Common.Interfaces`

Defines the contract for trading strategy implementations.

```csharp
public interface IStrategy
{
    StrategyMetadata Metadata { get; }
    
    void Initialize(
        StrategyConfig config,
        IMarketDataProvider dataProvider,
        ILogger logger);
    
    StrategyIntent? OnBar(BarData bar, StrategyContext context);
    
    StrategyIntent? OnTick(TickData tick, StrategyContext context);
    
    Dictionary<string, object> GetParameters();
    
    void SetParameters(Dictionary<string, object> parameters);
}
```

**Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `Metadata` | `StrategyMetadata` | Strategy metadata (name, version, etc.) |

**Methods:**

#### Initialize
Initializes the strategy with configuration and dependencies.

**Parameters:**
- `config` (`StrategyConfig`) - Strategy configuration
- `dataProvider` (`IMarketDataProvider`) - Market data provider
- `logger` (`ILogger`) - Logging interface

**Example:**
```csharp
public void Initialize(StrategyConfig config, IMarketDataProvider dataProvider, ILogger logger)
{
    _config = config;
    _dataProvider = dataProvider;
    _logger = logger;
    
    LoadParameters(config.Parameters);
    
    _logger.LogInformation("Strategy initialized: {0}", Metadata.Name);
}
```

---

#### OnBar
Processes new bar data and generates trading intent if conditions are met.

**Parameters:**
- `bar` (`BarData`) - New bar data
- `context` (`StrategyContext`) - Current strategy context

**Returns:** `StrategyIntent?` - Trading intent or null

**Example:**
```csharp
public StrategyIntent? OnBar(BarData bar, StrategyContext context)
{
    if (bar.Close > _threshold && context.CurrentPosition.Quantity == 0)
    {
        return new StrategyIntent(
            Symbol: bar.Symbol,
            Side: OrderSide.Buy,
            EntryType: OrderType.Market,
            LimitPrice: null,
            StopTicks: 8,
            TargetTicks: 16,
            Confidence: 0.75,
            Reason: "Breakout above threshold",
            Metadata: new()
        );
    }
    
    return null;
}
```

---

#### OnTick
Processes tick data (optional for high-frequency strategies).

**Parameters:**
- `tick` (`TickData`) - Tick data
- `context` (`StrategyContext`) - Current strategy context

**Returns:** `StrategyIntent?` - Trading intent or null

**Default Implementation:** Returns `null`

---

#### GetParameters / SetParameters
Get/Set strategy parameters for serialization.

**Returns:** `Dictionary<string, object>` - Parameter dictionary

**Example:**
```csharp
public Dictionary<string, object> GetParameters()
{
    return new Dictionary<string, object>
    {
        ["StopTicks"] = _stopTicks,
        ["TargetTicks"] = _targetTicks,
        ["Threshold"] = _threshold
    };
}

public void SetParameters(Dictionary<string, object> parameters)
{
    if (parameters.TryGetValue("StopTicks", out var stop))
        _stopTicks = (int)stop;
    
    if (parameters.TryGetValue("TargetTicks", out var target))
        _targetTicks = (int)target;
}
```

---

## Risk Management

### IRiskManager

**Namespace:** `NT8.Core.Risk`

Validates trading intents against risk parameters.

```csharp
public interface IRiskManager
{
    RiskDecision ValidateOrder(
        StrategyIntent intent,
        StrategyContext context,
        RiskConfig config);
    
    void OnFill(OrderFill fill);
    
    void OnPnLUpdate(double netPnL, double dayPnL);
    
    Task<bool> EmergencyFlatten(string reason);
    
    RiskStatus GetRiskStatus();
}
```

**Methods:**

#### ValidateOrder
Validates order intent against all risk parameters.

**Parameters:**
- `intent` (`StrategyIntent`) - Trading intent to validate
- `context` (`StrategyContext`) - Current context
- `config` (`RiskConfig`) - Risk configuration

**Returns:** `RiskDecision` - Validation result

**Example:**
```csharp
var decision = riskManager.ValidateOrder(intent, context, riskConfig);

if (decision.Allow)
{
    // Proceed with order
    Console.WriteLine($"Order approved: Risk Level={decision.RiskLevel}");
}
else
{
    // Order rejected
    Console.WriteLine($"Order rejected: {decision.RejectReason}");
}
```

---

#### OnFill
Updates risk state after order fill.

**Parameters:**
- `fill` (`OrderFill`) - Fill information

**Example:**
```csharp
var fill = new OrderFill(
    OrderId: orderId,
    Symbol: "ES",
    Quantity: 2,
    FillPrice: 4200.0,
    FillTime: DateTime.UtcNow,
    Commission: 4.50,
    ExecutionId: Guid.NewGuid().ToString()
);

riskManager.OnFill(fill);
```

---

#### OnPnLUpdate
Updates risk state with current P&L.

**Parameters:**
- `netPnL` (`double`) - Net P&L
- `dayPnL` (`double`) - Daily P&L

**Example:**
```csharp
riskManager.OnPnLUpdate(netPnL: 500.0, dayPnL: -150.0);
```

---

#### EmergencyFlatten
Triggers emergency position flatten.

**Parameters:**
- `reason` (`string`) - Reason for emergency flatten

**Returns:** `Task<bool>` - Success indicator

**Example:**
```csharp
var success = await riskManager.EmergencyFlatten("Connection lost");
if (success)
{
    Console.WriteLine("All positions flattened");
}
```

---

#### GetRiskStatus
Returns current risk system status.

**Returns:** `RiskStatus` - Current status

**Example:**
```csharp
var status = riskManager.GetRiskStatus();

Console.WriteLine($"Trading Enabled: {status.TradingEnabled}");
Console.WriteLine($"Daily P&L: {status.DailyPnL:C}");
Console.WriteLine($"Open Positions: {status.OpenPositions}");
```

---

### BasicRiskManager

**Namespace:** `NT8.Core.Risk`

Implements Tier 1 risk controls.

**Features:**
- Daily loss limits with auto-halt
- Per-trade risk caps
- Position count limits
- Emergency flatten

**Constructor:**
```csharp
public BasicRiskManager(ILogger<BasicRiskManager> logger)
```

**Example:**
```csharp
var riskManager = new BasicRiskManager(logger);

var config = new RiskConfig(
    DailyLossLimit: 1000,
    MaxTradeRisk: 200,
    MaxOpenPositions: 3,
    EmergencyFlattenEnabled: true
);

var decision = riskManager.ValidateOrder(intent, context, config);
```

---

### AdvancedRiskManager

**Namespace:** `NT8.Core.Risk`

Implements Tier 2-3 risk controls.

**Additional Features:**
- Weekly rolling loss limits
- Trailing drawdown protection
- Cross-strategy exposure limits
- Correlation-based limits
- Time-based trading windows
- Risk modes and cooldown periods

**Constructor:**
```csharp
public AdvancedRiskManager(
    IRiskManager basicRiskManager,
    ILogger<AdvancedRiskManager> logger)
```

**Example:**
```csharp
var advancedRiskManager = new AdvancedRiskManager(
    new BasicRiskManager(logger),
    logger
);

var advancedConfig = new AdvancedRiskConfig(
    // Tier 1
    dailyLossLimit: 1000,
    maxTradeRisk: 200,
    maxOpenPositions: 3,
    
    // Tier 2
    weeklyLossLimit: 3000,
    trailingDrawdownLimit: 0.15,
    
    // Tier 3
    maxCrossStrategyExposure: 50000,
    correlationThreshold: 0.7,
    tradingHours: new[] { "09:30-16:00" }
);

var decision = advancedRiskManager.ValidateOrder(intent, context, advancedConfig);
```

---

## Position Sizing

### IPositionSizer

**Namespace:** `NT8.Core.Sizing`

Calculates position sizes for trading intents.

```csharp
public interface IPositionSizer
{
    SizingResult CalculateSize(
        StrategyIntent intent,
        StrategyContext context,
        SizingConfig config);
    
    SizingMetadata GetMetadata();
}
```

**Methods:**

#### CalculateSize
Calculates position size based on sizing method.

**Parameters:**
- `intent` (`StrategyIntent`) - Trading intent
- `context` (`StrategyContext`) - Current context
- `config` (`SizingConfig`) - Sizing configuration

**Returns:** `SizingResult` - Calculated size

**Example:**
```csharp
var config = new SizingConfig(
    Method: SizingMethod.FixedDollarRisk,
    MinContracts: 1,
    MaxContracts: 10,
    RiskPerTrade: 200,
    MethodParameters: new()
);

var result = sizer.CalculateSize(intent, context, config);

Console.WriteLine($"Contracts: {result.Contracts}");
Console.WriteLine($"Risk Amount: {result.RiskAmount:C}");
```

---

### BasicPositionSizer

**Namespace:** `NT8.Core.Sizing`

Implements basic sizing methods.

**Methods:**
- Fixed contracts
- Fixed dollar risk

**Constructor:**
```csharp
public BasicPositionSizer(ILogger<BasicPositionSizer> logger)
```

**Example:**
```csharp
var sizer = new BasicPositionSizer(logger);

// Fixed contracts
var fixedConfig = new SizingConfig(
    Method: SizingMethod.FixedContracts,
    MinContracts: 1,
    MaxContracts: 5,
    RiskPerTrade: 200,
    MethodParameters: new() { ["contracts"] = 2 }
);

var result = sizer.CalculateSize(intent, context, fixedConfig);
```

---

### AdvancedPositionSizer

**Namespace:** `NT8.Core.Sizing`

Implements advanced sizing methods.

**Methods:**
- Optimal-f (Ralph Vince)
- Volatility-adjusted (ATR/StdDev)
- Dollar-risk override with rounding

**Constructor:**
```csharp
public AdvancedPositionSizer(ILogger<AdvancedPositionSizer> logger)
```

**Example - Optimal-f:**
```csharp
var optimalFConfig = new SizingConfig(
    Method: SizingMethod.OptimalF,
    MinContracts: 1,
    MaxContracts: 10,
    RiskPerTrade: 500,
    MethodParameters: new()
    {
        ["historicalTrades"] = tradeHistory,
        ["riskOfRuinThreshold"] = 0.01,
        ["confidenceLevel"] = 0.95
    }
);

var result = sizer.CalculateSize(intent, context, optimalFConfig);
```

**Example - Volatility-Adjusted:**
```csharp
var volConfig = new SizingConfig(
    Method: SizingMethod.VolatilityAdjusted,
    MinContracts: 1,
    MaxContracts: 10,
    RiskPerTrade: 300,
    MethodParameters: new()
    {
        ["atr"] = 15.5,
        ["normalATR"] = 12.0,
        ["volatilityWindow"] = 14,
        ["regime"] = "Normal"
    }
);

var result = sizer.CalculateSize(intent, context, volConfig);
```

---

### OptimalFCalculator

**Namespace:** `NT8.Core.Sizing`

Calculates optimal-f (Ralph Vince method).

**Methods:**

#### CalculateOptimalF
```csharp
public OptimalFResult CalculateOptimalF(
    List<TradeResult> trades,
    double capital,
    double riskOfRuinThreshold)
```

**Parameters:**
- `trades` - Historical trade results
- `capital` - Trading capital
- `riskOfRuinThreshold` - Maximum acceptable risk of ruin

**Returns:** `OptimalFResult` - Optimal-f calculation result

**Example:**
```csharp
var calculator = new OptimalFCalculator(logger);

var trades = new List<TradeResult>
{
    new TradeResult(250, DateTime.Now.AddDays(-10)),
    new TradeResult(-100, DateTime.Now.AddDays(-9)),
    new TradeResult(300, DateTime.Now.AddDays(-8)),
    // ... more trades
};

var result = calculator.CalculateOptimalF(
    trades: trades,
    capital: 50000,
    riskOfRuinThreshold: 0.01
);

Console.WriteLine($"Optimal-f: {result.OptimalF}");
Console.WriteLine($"Recommended Contracts: {result.Contracts}");
Console.WriteLine($"Risk of Ruin: {result.RiskOfRuin:P}");
```

---

### VolatilityAdjustedSizer

**Namespace:** `NT8.Core.Sizing`

Calculates volatility-adjusted position sizes.

**Methods:**

#### CalculateATRSize
```csharp
public int CalculateATRSize(
    double targetRisk,
    double atr,
    double normalATR,
    double tickValue,
    int minContracts,
    int maxContracts)
```

**Parameters:**
- `targetRisk` - Target risk amount
- `atr` - Current ATR
- `normalATR` - Historical normal ATR
- `tickValue` - Tick value for symbol
- `minContracts` - Minimum contracts
- `maxContracts` - Maximum contracts

**Returns:** `int` - Calculated contracts

**Example:**
```csharp
var sizer = new VolatilityAdjustedSizer(logger);

var contracts = sizer.CalculateATRSize(
    targetRisk: 300,
    atr: 18.5,
    normalATR: 15.0,
    tickValue: 12.50,
    minContracts: 1,
    maxContracts: 10
);

Console.WriteLine($"ATR-Adjusted Size: {contracts} contracts");
```

---

## Order Management

### IOrderManager

**Namespace:** `NT8.Core.OMS`

Manages complete order lifecycle.

```csharp
public interface IOrderManager
{
    Task<string> SubmitOrderAsync(OrderRequest request);
    
    Task<bool> ModifyOrderAsync(string orderId, OrderModification modification);
    
    Task<bool> CancelOrderAsync(string orderId, string reason);
    
    OrderStatus? GetOrderStatus(string orderId);
    
    List<OrderStatus> GetActiveOrders();
    
    Task<string> FlattenPosition(string symbol, string reason);
    
    void SubscribeToOrderUpdates(Action<OrderStatus> callback);
    
    void UnsubscribeFromOrderUpdates(Action<OrderStatus> callback);
}
```

**Methods:**

#### SubmitOrderAsync
Submits new order.

**Parameters:**
- `request` (`OrderRequest`) - Order details

**Returns:** `Task<string>` - Order ID

**Example:**
```csharp
var request = new OrderRequest(
    Symbol: "ES",
    Side: OrderSide.Buy,
    Quantity: 2,
    Type: OrderType.Market,
    LimitPrice: null,
    StopPrice: null,
    Tif: TimeInForce.Gtc,
    StrategyId: "MyStrategy",
    Metadata: new()
);

var orderId = await orderManager.SubmitOrderAsync(request);
Console.WriteLine($"Order submitted: {orderId}");
```

---

#### ModifyOrderAsync
Modifies working order.

**Parameters:**
- `orderId` (`string`) - Order ID
- `modification` (`OrderModification`) - Modification details

**Returns:** `Task<bool>` - Success indicator

**Example:**
```csharp
var modification = new OrderModification(
    NewQuantity: 3,
    NewLimitPrice: 4205.0,
    NewStopPrice: null,
    Reason: "Adjust position size"
);

var success = await orderManager.ModifyOrderAsync(orderId, modification);
```

---

#### CancelOrderAsync
Cancels order.

**Parameters:**
- `orderId` (`string`) - Order ID
- `reason` (`string`) - Cancellation reason

**Returns:** `Task<bool>` - Success indicator

**Example:**
```csharp
var success = await orderManager.CancelOrderAsync(orderId, "Market conditions changed");
```

---

#### GetOrderStatus
Retrieves order status.

**Parameters:**
- `orderId` (`string`) - Order ID

**Returns:** `OrderStatus?` - Order status or null

**Example:**
```csharp
var status = orderManager.GetOrderStatus(orderId);

if (status != null)
{
    Console.WriteLine($"State: {status.State}");
    Console.WriteLine($"Filled: {status.FilledQuantity}/{status.Quantity}");
    
    if (status.FillPrice.HasValue)
    {
        Console.WriteLine($"Fill Price: {status.FillPrice:F2}");
    }
}
```

---

#### GetActiveOrders
Returns all active orders.

**Returns:** `List<OrderStatus>` - Active orders

**Example:**
```csharp
var activeOrders = orderManager.GetActiveOrders();

Console.WriteLine($"Active Orders: {activeOrders.Count}");

foreach (var order in activeOrders)
{
    Console.WriteLine($"{order.OrderId}: {order.Symbol} {order.Side} {order.Quantity}");
}
```

---

#### FlattenPosition
Emergency position flatten.

**Parameters:**
- `symbol` (`string`) - Symbol to flatten
- `reason` (`string`) - Flatten reason

**Returns:** `Task<string>` - Flatten order ID

**Example:**
```csharp
var orderId = await orderManager.FlattenPosition("ES", "Emergency stop");
Console.WriteLine($"Flatten order submitted: {orderId}");
```

---

#### SubscribeToOrderUpdates / UnsubscribeFromOrderUpdates
Subscribe to real-time order updates.

**Parameters:**
- `callback` (`Action<OrderStatus>`) - Callback function

**Example:**
```csharp
void OnOrderUpdate(OrderStatus status)
{
    Console.WriteLine($"Order {status.OrderId} updated: {status.State}");
    
    if (status.State == OrderState.Filled)
    {
        Console.WriteLine($"Filled at {status.FillPrice:F2}");
    }
}

// Subscribe
orderManager.SubscribeToOrderUpdates(OnOrderUpdate);

// Later... unsubscribe
orderManager.UnsubscribeFromOrderUpdates(OnOrderUpdate);
```

---

## Data Models

### StrategyIntent

**Namespace:** `NT8.Core.Common.Models`

Represents a strategy's trading intent.

```csharp
public record StrategyIntent(
    string Symbol,
    OrderSide Side,
    OrderType EntryType,
    double? LimitPrice,
    int StopTicks,
    int? TargetTicks,
    double Confidence,
    string Reason,
    Dictionary<string, object> Metadata
)
{
    public string IntentId { get; init; }
    public DateTime Timestamp { get; init; }
    public bool IsValid();
}
```

**Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `Symbol` | `string` | Instrument symbol |
| `Side` | `OrderSide` | Buy/Sell/Flat |
| `EntryType` | `OrderType` | Market/Limit/Stop/StopLimit |
| `LimitPrice` | `double?` | Limit price (null for market) |
| `StopTicks` | `int` | Stop loss in ticks |
| `TargetTicks` | `int?` | Profit target in ticks |
| `Confidence` | `double` | Signal confidence (0.0-1.0) |
| `Reason` | `string` | Trade reason (human-readable) |
| `Metadata` | `Dictionary` | Additional strategy-specific data |
| `IntentId` | `string` | Unique identifier (auto-generated) |
| `Timestamp` | `DateTime` | Creation timestamp (auto-generated) |

---

### StrategyContext

**Namespace:** `NT8.Core.Common.Models`

Context information available to strategies.

```csharp
public record StrategyContext(
    string Symbol,
    DateTime CurrentTime,
    Position CurrentPosition,
    AccountInfo Account,
    MarketSession Session,
    Dictionary<string, object> CustomData
);
```

---

### RiskDecision

**Namespace:** `NT8.Core.Risk`

Risk validation result.

```csharp
public record RiskDecision(
    bool Allow,
    string? RejectReason,
    StrategyIntent? ModifiedIntent,
    RiskLevel RiskLevel,
    Dictionary<string, object> RiskMetrics
);
```

**Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `Allow` | `bool` | Whether order is allowed |
| `RejectReason` | `string?` | Reason if rejected |
| `ModifiedIntent` | `StrategyIntent?` | Modified intent (if applicable) |
| `RiskLevel` | `RiskLevel` | Risk level classification |
| `RiskMetrics` | `Dictionary` | Detailed risk metrics |

---

### SizingResult

**Namespace:** `NT8.Core.Sizing`

Position sizing calculation result.

```csharp
public record SizingResult(
    int Contracts,
    double RiskAmount,
    SizingMethod Method,
    Dictionary<string, object> Calculations
);
```

**Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `Contracts` | `int` | Calculated contract quantity |
| `RiskAmount` | `double` | Actual risk amount |
| `Method` | `SizingMethod` | Sizing method used |
| `Calculations` | `Dictionary` | Detailed calculation breakdown |

---

### OrderStatus

**Namespace:** `NT8.Core.OMS`

Current order status.

```csharp
public record OrderStatus(
    string OrderId,
    string Symbol,
    OrderSide Side,
    int Quantity,
    int FilledQuantity,
    OrderState State,
    DateTime SubmitTime,
    DateTime? FillTime,
    double? FillPrice,
    string? RejectReason,
    Dictionary<string, object> Metadata
);
```

**Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `OrderId` | `string` | Unique order identifier |
| `Symbol` | `string` | Instrument symbol |
| `Side` | `OrderSide` | Buy/Sell |
| `Quantity` | `int` | Total quantity |
| `FilledQuantity` | `int` | Filled quantity |
| `State` | `OrderState` | Current state |
| `SubmitTime` | `DateTime` | Submission timestamp |
| `FillTime` | `DateTime?` | Fill timestamp (if filled) |
| `FillPrice` | `double?` | Fill price (if filled) |
| `RejectReason` | `string?` | Rejection reason (if rejected) |
| `Metadata` | `Dictionary` | Additional order data |

---

## Enumerations

### OrderSide

```csharp
public enum OrderSide
{
    Buy = 1,
    Sell = -1,
    Flat = 0
}
```

### OrderType

```csharp
public enum OrderType
{
    Market,
    Limit,
    StopMarket,
    StopLimit
}
```

### OrderState

```csharp
public enum OrderState
{
    Pending,
    Working,
    PartiallyFilled,
    Filled,
    Cancelled,
    Rejected
}
```

### TimeInForce

```csharp
public enum TimeInForce
{
    Gtc,  // Good Till Canceled
    Ioc,  // Immediate Or Cancel
    Fok,  // Fill Or Kill
    Day   // Good For Day
}
```

### SizingMethod

```csharp
public enum SizingMethod
{
    FixedContracts,
    FixedDollarRisk,
    OptimalF,
    VolatilityAdjusted
}
```

### RiskLevel

```csharp
public enum RiskLevel
{
    Low,
    Medium,
    High,
    Critical
}
```

### RoundingMode

```csharp
public enum RoundingMode
{
    Floor,
    Ceiling,
    Nearest
}
```

---

**For more information, see the [main README](README.md) or [examples](../src/NT8.Strategies/Examples/)**