## Trading Engine APIs

### Core Trading Operations

```rust
use core::prelude::*;

// Initialize trading operations
let trading_ops = TradingOperations::new();

// Record order submission (performance tracking)
record_order_submission("EURUSD", OrderType::Market, 1000.0)?;

// Record order execution with latency measurement
let execution_result = ExecutionResult {
    order_id: order_id.clone(),
    symbol: "EURUSD".to_string(),
    executed_quantity: 1000.0,
    executed_price: Price::from_str("1.1234")?,
    execution_time: HardwareTimestamp::now(),
    latency_us: 23, // Sub-50μs target
};

record_execution_latency(&execution_result)?;

// Update position and P&L
update_pnl("EURUSD", 156.78)?;
update_open_orders_count(5);
```

### Order Management

```rust
use core::trading::*;

// Initialize order manager
let mut order_manager = OrderManager::new();

// Create and submit order
let order = TradingOrder {
    order_id: OrderId::new(),
    symbol: "EURUSD".to_string(),
    side: OrderSide::Buy,
    quantity: Quantity::from_str("1000")?,
    order_type: OrderType::Market,
    time_in_force: TimeInForce::IOC,
    price: None, // Market order
    stop_price: None,
    timestamp: Timestamp::now(),
    status: OrderStatus::PendingNew,
};

let order_id = order_manager.submit_order(order).await?;
println!("Order submitted: {}", order_id);

// Check order status
let status = order_manager.get_order_status(&order_id).await?;
println!("Order status: {:?}", status);
```

### Position Management

```rust
use core::trading::*;

// Initialize position manager
let mut position_manager = PositionManager::new();

// Get current positions
let positions = position_manager.get_all_positions().await?;
for position in positions {
    println!("Symbol: {}, Size: {}, PnL: {}", 
        position.symbol, 
        position.size, 
        position.unrealized_pnl
    );
}

// Update position from fill
position_manager.update_position_from_fill(
    "EURUSD",
    Side::Buy,
    1000.0,
    Price::from_str("1.1234")?
).await?;
```

### Trading Engine Integration

```rust
use core::trading::*;

// Initialize complete trading engine
let mut trading_engine = TradingEngine::new().await?;

// Start trading engine
trading_engine.start().await?;

// Process market data event
let market_event = MarketDataEvent {
    symbol: "EURUSD".to_string(),
    bid: Price::from_str("1.1232")?,
    ask: Price::from_str("1.1234")?,
    timestamp: Timestamp::now(),
};

trading_engine.handle_market_data(market_event).await?;

// Graceful shutdown
trading_engine.shutdown().await?;
```

## Machine Learning APIs

### Unified ML Model Interface

```rust
use ml::prelude::*;

// Get global model registry
let registry = get_global_registry();

// Register models
registry.register(Arc::new(TLOBModelWrapper::new(tlob_model))).await?;
registry.register(Arc::new(DQNModelWrapper::new(dqn_agent))).await?;

// Make predictions
let features = Features::new(
    vec![1.1234, 1.1235, 1000.0, 500.0], // Price and volume features
    vec!["bid".to_string(), "ask".to_string(), "bid_size".to_string(), "ask_size".to_string()]
).with_symbol("EURUSD".to_string());

// Single model prediction
if let Some(model) = registry.get("TLOB_Transformer").await {
    let prediction = model.predict(&features).await?;
    println!("TLOB prediction: {:.4} (confidence: {:.2})", 
        prediction.value, prediction.confidence);
}

// Parallel ensemble prediction
let model_names = vec!["TLOB_Transformer".to_string(), "DQN_Agent".to_string()];
let predictions = registry.predict_selected(&model_names, &features).await;

for (i, result) in predictions.iter().enumerate() {
    match result {
        Ok(prediction) => println!("Model {}: {:.4}", model_names[i], prediction.value),
        Err(e) => eprintln!("Model {} error: {}", model_names[i], e),
    }
}
```

### Model Training Pipeline

```rust
use ml::training_pipeline::*;

// Initialize production training system
let training_config = ProductionTrainingConfig {
    model_type: ModelType::DQN,
    batch_size: 128,
    learning_rate: 0.001,
    epochs: 1000,
    safety_config: MLSafetyConfig::production_defaults(),
    gradient_config: GradientSafetyConfig::conservative(),
};

let mut training_system = ProductionMLTrainingSystem::new(training_config)?;

// Prepare financial features
let features = FinancialFeatures {
    prices: vec![IntegerPrice::from_f64(1.1234)?],
    volumes: vec![1000],
    technical_indicators: hashmap!{
        "rsi".to_string() => 65.4,
        "macd".to_string() => 0.0012,
    },
    microstructure: MicrostructureFeatures {
        spread_bps: 15,
        imbalance: 0.23,
        trade_intensity: 5.2,
        vwap: IntegerPrice::from_f64(1.1233)?,
    },
    risk_metrics: RiskFeatures {
        var_5pct: 0.0145,
        expected_shortfall: 0.0234,
        max_drawdown: 0.0567,
        sharpe_ratio: 1.45,
    },
    timestamp: chrono::Utc::now(),
};

// Train model with safety controls
let training_result = training_system.train_model(&features).await?;
println!("Training completed: {:?}", training_result.metrics);
```

### Feature Engineering

```rust
use ml::features::*;

// Initialize unified feature extractor
let extractor = UnifiedFeatureExtractor::new();

// Extract comprehensive features
let market_data = MarketDataPoint {
    symbol: "EURUSD".to_string(),
    bid: 1.1232,
    ask: 1.1234,
    volume: 1000.0,
    timestamp: chrono::Utc::now(),
};

let features = extractor.extract_features(&market_data)?;

// Access different feature categories
let price_features = features.price_features;
let technical_features = features.technical_features;
let volume_features = features.volume_features;

println!("Extracted {} features", features.get_feature_count());
```

## Risk Management APIs

### Risk Engine

```rust
use risk::*;

// Initialize risk engine
let mut risk_engine = RiskEngine::new(RiskConfig::production_defaults())?;

// Pre-trade risk check
let order_request = OrderRequest {
    symbol: "EURUSD".to_string(),
    side: Side::Buy,
    quantity: 1000.0,
    price: Some(1.1234),
};

let risk_result = risk_engine.check_pre_trade_risk(&order_request).await?;
if !risk_result.approved {
    eprintln!("Trade rejected: {}", risk_result.reason);
    return;
}

// Post-trade risk monitoring
risk_engine.update_position("EURUSD", 1000.0, 1.1234).await?;
let portfolio_risk = risk_engine.calculate_portfolio_risk().await?;
println!("Portfolio VaR: {:.4}", portfolio_risk.var_5_percent);
```

### VaR Calculation

```rust
use risk::*;

// Historical VaR calculation
let var_calculator = VarCalculator::new();
let price_history = vec![1.1200, 1.1250, 1.1180, 1.1300, 1.1245];
let var_5_percent = var_calculator.calculate_historical_var(
    &price_history,
    0.05, // 5% VaR
    252   // 1 year lookback
)?;

println!("Daily VaR (5%): {:.4}", var_5_percent);

// Monte Carlo VaR
let monte_carlo_var = var_calculator.calculate_monte_carlo_var(
    &price_history,
    0.05,
    10000 // simulations
)?;

println!("Monte Carlo VaR: {:.4}", monte_carlo_var);
```

### Position Sizing (Kelly Criterion)

```rust
use risk::kelly_sizing::*;

// Kelly criterion position sizing
let kelly_calculator = KellyCalculator::new();
let win_rate = 0.55;        // 55% win rate
let avg_win = 0.012;        // 1.2% average win
let avg_loss = -0.008;      // 0.8% average loss

let kelly_fraction = kelly_calculator.calculate_kelly_fraction(
    win_rate, avg_win, avg_loss
)?;

let portfolio_value = 1_000_000.0;
let position_size = kelly_calculator.calculate_position_size(
    portfolio_value, kelly_fraction, 0.25 // 25% max Kelly
)?;

println!("Optimal position size: ${:.0}", position_size);
```

### Circuit Breaker

```rust
use risk::circuit_breaker::*;

// Initialize circuit breaker
let mut circuit_breaker = CircuitBreaker::new(CircuitBreakerConfig {
    max_daily_loss: 50_000.0,
    max_position_size: 10_000_000.0,
    max_orders_per_second: 100,
    volatility_threshold: 0.05,
});

// Check if trading should be halted
let current_pnl = -45_000.0;
if circuit_breaker.should_halt_trading(current_pnl)? {
    eprintln!("CIRCUIT BREAKER ACTIVATED - TRADING HALTED");
    // Implement emergency shutdown logic
}
```

### Stress Testing

```rust
use risk::stress_tester::*;

// Portfolio stress testing
let stress_tester = StressTester::new();
let portfolio = Portfolio {
    positions: vec![
        Position { symbol: "EURUSD".to_string(), size: 1000.0, price: 1.1234 },
        Position { symbol: "GBPUSD".to_string(), size: -500.0, price: 1.2756 },
    ],
};

// Historical stress scenarios
let stress_scenarios = vec![
    StressScenario::new("2008 Financial Crisis", hashmap!{
        "EURUSD".to_string() => -0.15, // 15% adverse move
        "GBPUSD".to_string() => -0.12, // 12% adverse move
    }),
    StressScenario::new("Brexit Referendum", hashmap!{
        "GBPUSD".to_string() => -0.08,
    }),
];

let stress_results = stress_tester.run_stress_tests(&portfolio, &stress_scenarios)?;
for result in stress_results {
    println!("Scenario: {}, P&L Impact: {:.0}", result.scenario_name, result.pnl_impact);
}
```

## Data Management APIs

### Databento Market Data Integration

```rust
use data::databento::*;

// Initialize Databento client
let databento_client = DatabentaClient::new("your_api_key".to_string()).await?;

// Real-time market data subscription
let symbols = vec!["AAPL".to_string(), "GOOGL".to_string()];
let mut stream = databento_client.subscribe_live(&symbols, Schema::Mbo).await?;

while let Some(message) = stream.next().await {
    let message = message?;
    println!("Market data: {} @ {} ({})", message.symbol, message.price, message.ts_event);

    // Process market data with ultra-low latency
    process_market_data(&message).await?;
}

// Historical data retrieval
let start_date = chrono::Utc::now() - chrono::Duration::days(30);
let end_date = chrono::Utc::now();
let historical_data = databento_client.timeseries_get_range(
    "XNAS.ITCH",
    &symbols,
    Schema::Trades,
    start_date,
    end_date
).await?;

printf!("Retrieved {} historical records", historical_data.len());
```

### Benzinga News & Sentiment Integration

```rust
use data::benzinga::*;

// Initialize Benzinga client
let benzinga_client = BenzingaClient::new("your_api_key".to_string()).await?;

// Real-time news subscription
let tickers = vec!["AAPL".to_string(), "GOOGL".to_string()];
let mut news_stream = benzinga_client.subscribe_news(&tickers).await?;

while let Some(news) = news_stream.next().await {
    let news = news?;
    println!("News: {} - Sentiment: {}", news.title, news.sentiment_score);

    // Process news with sentiment analysis
    process_news_sentiment(&news).await?;
}

// Get analyst ratings
let ratings = benzinga_client.get_ratings(
    &["AAPL"],
    None, // All analysts
    Some(30) // Last 30 days
).await?;

printf!("Retrieved {} analyst ratings", ratings.len());```

### Multi-Tier Persistence

```rust
use core::persistence::*;

// Initialize persistence manager (PostgreSQL + InfluxDB + Redis + ClickHouse)
let persistence = PersistenceManager::new(PersistenceConfig::production()).await?;

// Store trading event (PostgreSQL - ACID)
let trading_event = TradingEvent {
    event_id: EventId::new(),
    event_type: TradingEventType::OrderFilled,
    symbol: "EURUSD".to_string(),
    timestamp: Timestamp::now(),
    data: serde_json::to_value(&order_fill)?,
};

persistence.store_trading_event(&trading_event).await?;

// Store metrics (InfluxDB - Time Series)
let metrics = vec![
    DataPoint::new("trading_latency_us")
        .tag("symbol", "EURUSD")
        .field("value", 23i64)
        .timestamp(Timestamp::now()),
    DataPoint::new("pnl_update")
        .tag("symbol", "EURUSD")
        .field("unrealized_pnl", 156.78)
        .timestamp(Timestamp::now()),
];

persistence.store_metrics(&metrics).await?;

// Cache frequent lookups (Redis)
persistence.cache_set("current_position_EURUSD", "1000.0", Some(Duration::seconds(60))).await?;
let cached_position: Option<String> = persistence.cache_get("current_position_EURUSD").await?;

// Analytical queries (ClickHouse)
let query = "SELECT symbol, avg(latency_us) FROM trading_metrics WHERE timestamp >= now() - INTERVAL 1 HOUR GROUP BY symbol";
let analytics_result = persistence.execute_analytics_query(query).await?;
```

## Configuration APIs

### Dynamic Configuration Management

```rust
use core::config::*;

// Initialize configuration manager
let config_manager = ConfigManager::new().await?;

// Load environment-specific configuration
let trading_config: TradingConfig = config_manager.load_config("trading").await?;
let ml_config: MLConfig = config_manager.load_config("ml").await?;
let security_config: SecurityConfig = config_manager.load_config("security").await?;

println!("Max position size: {}", trading_config.max_position_size);
println!("ML inference timeout: {}ms", ml_config.inference_timeout_ms);
println!("TLS enabled: {}", security_config.tls_enabled);

// Hot reload configuration
config_manager.register_reload_callback("trading", |new_config: TradingConfig| {
    println!("Trading config updated: max_position_size = {}", new_config.max_position_size);
    // Apply new configuration without restart
}).await?;

// Watch for configuration changes
let mut config_watcher = config_manager.watch_config_changes().await?;
while let Some(change) = config_watcher.next().await {
    println!("Config changed: {} -> {}", change.key, change.new_value);
}
```

### Environment-Based Configuration

```rust
use core::config::*;

// Load configuration based on environment
let environment = std::env::var("FOXHUNT_ENV").unwrap_or_else(|_| "development".to_string());
let config: FoxhuntConfig = EnvironmentConfig::load(&environment).await?;

// Access nested configuration
let database_url = &config.database.url;
let redis_config = &config.cache.redis;
let monitoring_port = config.monitoring.prometheus_port;

// Validate configuration
config.validate()?;
println!("Configuration loaded and validated for environment: {}", environment);
```

## Health & Monitoring APIs

### Health Monitoring

```rust
use core::events::*;

// Initialize health monitor
let health_monitor = HealthMonitor::new();

// Check component health
let health_status = health_monitor.check_system_health().await?;
match health_status {
    HealthStatus::Healthy => println!("All systems operational"),
    HealthStatus::Degraded => println!("System performance degraded"),
    HealthStatus::Unhealthy => println!("Critical system failure"),
}

// Monitor specific components
let database_health = health_monitor.check_component_health("database").await?;
let ml_health = health_monitor.check_component_health("ml_inference").await?;
let trading_health = health_monitor.check_component_health("trading_engine").await?;

// Register health check callbacks
health_monitor.register_health_check("custom_check", || async {
    // Custom health validation logic
    if is_system_responsive().await {
        HealthStatus::Healthy
    } else {
        HealthStatus::Unhealthy
    }
}).await?;
```

### Performance Metrics

```rust
use core::events::*;

// Event-driven metrics collection
let mut event_processor = EventProcessor::new(EventProcessorConfig::production());

// Record performance events
event_processor.record_event(TradingEvent {
    event_type: EventType::OrderLatency,
    timestamp: Timestamp::now(),
    metadata: hashmap!{
        "symbol".to_string() => "EURUSD".to_string(),
        "latency_us".to_string() => "23".to_string(),
    },
});

// Get aggregated metrics
let metrics_snapshot = event_processor.get_metrics_snapshot();
println!("Events processed: {}", metrics_snapshot.total_events);
println!("Average processing time: {}μs", metrics_snapshot.avg_processing_time_us);
println!("Error rate: {:.2}%", metrics_snapshot.error_rate * 100.0);

// Export metrics for Prometheus
let prometheus_metrics = event_processor.export_prometheus_metrics();
```

### Buffer Management

```rust
use core::events::*;

// High-performance event buffering
let buffer_manager = BufferManager::new(8192); // 8K events capacity

// Write events with ultra-low latency
let event = TradingEvent::new(EventType::MarketData, "EURUSD", serde_json::Value::Null);
buffer_manager.write_event(event)?;

// Batch read for efficiency
let events = buffer_manager.read_batch(256)?; // Read up to 256 events
for event in events {
    process_event(&event).await?;
}

// Monitor buffer performance
let buffer_stats = buffer_manager.get_stats();
if buffer_stats.utilization > 0.8 {
    println!("Warning: Event buffer utilization high: {:.1}%", buffer_stats.utilization * 100.0);
}
```

## Security & Authentication APIs

### JWT Authentication

```rust
use tli::auth::*;

// Generate JWT token
let token_payload = TokenPayload {
    user_id: "trader001".to_string(),
    roles: vec!["trader".to_string(), "risk_manager".to_string()],
    permissions: vec![
        Permission::SubmitOrders,
        Permission::ViewPositions,
        Permission::ModifyRiskLimits,
    ],
    expires_at: chrono::Utc::now() + chrono::Duration::hours(8),
};

let jwt_token = generate_jwt_token(&token_payload, &jwt_secret)?;
println!("JWT token: {}", jwt_token);

// Validate JWT token
let validation_result = validate_jwt_token(&jwt_token, &jwt_secret)?;
if validation_result.is_valid {
    println!("User authenticated: {}", validation_result.payload.user_id);
} else {
    eprintln!("Authentication failed: {}", validation_result.error);
}
```

### Role-Based Access Control

```rust
use tli::auth::*;

// Check permissions
let user_context = UserContext {
    user_id: "trader001".to_string(),
    roles: vec!["trader".to_string()],
    permissions: vec![Permission::SubmitOrders, Permission::ViewPositions],
};

// Permission checks
if user_context.has_permission(Permission::SubmitOrders) {
    // Allow order submission
    submit_order(&order_request).await?;
} else {
    return Err(AuthError::InsufficientPermissions);
}

// Role-based resource access
if user_context.has_role("risk_manager") {
    let risk_metrics = get_sensitive_risk_metrics().await?;
    // Provide access to risk management functions
}
```

### TLS/mTLS Configuration

```rust
use tli::security::*;

// Configure TLS server
let tls_config = TlsConfig {
    cert_path: "/opt/foxhunt/certs/production/foxhunt-cert.pem".to_string(),
    key_path: "/opt/foxhunt/certs/production/foxhunt-key.pem".to_string(),
    ca_path: Some("/opt/foxhunt/certs/production/ca-cert.pem".to_string()),
    require_client_cert: true, // mTLS
    verify_client_cert: true,
};

let tls_acceptor = create_tls_acceptor(&tls_config)?;

// TLS client configuration
let client_config = TlsClientConfig {
    ca_path: "/opt/foxhunt/certs/production/ca-cert.pem".to_string(),
    client_cert_path: Some("/opt/foxhunt/certs/client/client-cert.pem".to_string()),
    client_key_path: Some("/opt/foxhunt/certs/client/client-key.pem".to_string()),
    verify_server_cert: true,
};

let tls_connector = create_tls_connector(&client_config)?;
```

---

## Error Handling Patterns

All APIs use consistent error handling patterns with the `Result<T, E>` type:

```rust
// Core error types
use core::{CoreError, CoreResult};
use ml::{MLError, MLResult};
use risk::{RiskError, RiskResult};
use data::{DataError, DataResult};

// Error handling example
let result: CoreResult<Price> = Price::from_str("invalid_price");
match result {
    Ok(price) => println!("Price: {}", price),
    Err(CoreError::ParseError { input, reason }) => {
        eprintln!("Failed to parse price '{}': {}", input, reason);
    }
    Err(e) => eprintln!("Unexpected error: {}", e),
}

// Using the ? operator for error propagation
fn trading_operation() -> CoreResult<()> {
    let price = Price::from_str("100.50")?;
    let quantity = Quantity::from_str("1000")?;
    let order = create_order(price, quantity)?;
    submit_order(order)?;
    Ok(())
}
```

## Performance Considerations

### Latency Optimization

```rust
// Measure critical path latency
let measurement = HftLatencyTracker::start_measurement();

// Critical trading operation
let order_result = submit_order_fast_path(&order).await?;

let latency_ns = measurement.end();
if latency_ns > MAX_CRITICAL_LATENCY_NS {
    tracing::warn!("Latency exceeded target: {}ns", latency_ns);
}

record_latency_metric("order_submission", latency_ns);
```

### Memory Management

```rust
// Use stack allocation for hot paths
let mut price_buffer: [f64; 1024] = [0.0; 1024];
process_prices_simd(&mut price_buffer)?;

// Minimize allocations in critical sections
let order_pool = ObjectPool::<TradingOrder>::new(1000);
let order = order_pool.get();
// ... use order ...
order_pool.return_object(order);
```

### Batch Processing

```rust
// Batch operations for efficiency
let orders = vec![order1, order2, order3];
let results = submit_orders_batch(&orders).await?;

// Process results in batch
for (order, result) in orders.iter().zip(results.iter()) {
    handle_order_result(order, result)?;
}
```

---

## Conclusion

The Foxhunt HFT system provides a comprehensive, production-ready API suite designed for ultra-low latency trading operations. All APIs are built with:

- **Performance First**: Sub-50μs latency targets with 14ns timing precision
- **Type Safety**: Unified financial types preventing precision loss
- **Mathematical Safety**: NaN/Infinity detection and gradient clipping
- **Enterprise Security**: mTLS, JWT, RBAC, and audit trails
- **Operational Excellence**: Health monitoring, metrics, and observability

For additional information:
- [ML Training Service API](./ML_TRAINING_SERVICE_API.md)
- [TLI Operations Manual](./TLI_OPERATIONS_MANUAL.md)
- [Performance Tuning Guide](./PERFORMANCE_TUNING.md)
- [Deployment Guide](./COMPREHENSIVE_DEPLOYMENT_GUIDE.md)

#### Lock-Free Structures

```rust
use core::prelude::*;

// High-performance concurrent structures
let ring_buffer = LockFreeRingBuffer::<HftMessage>::new(8192);
let spsc_queue = SPSCQueue::<TradingOrder>::new(1024);
let mpsc_queue = MPSCQueue::<MarketEvent>::new(4096);

// Atomic operations for metrics
let counter = AtomicCounter::new();
counter.increment();
let metrics = AtomicMetrics::new();
metrics.record_latency(latency_ns);
```

#### CPU Affinity and Real-Time Scheduling

```rust
use core::prelude::*;

#[cfg(target_os = "linux")]
{
    // Initialize HFT CPU optimizations
    initialize_hft_cpu_optimizations()?;

    // Manual CPU affinity management
    let affinity_manager = CpuAffinityManager::new();
    let assignment = HftCoreAssignment {
        trading_cores: vec![0, 1, 2, 3],
        ml_cores: vec![4, 5, 6, 7],
        io_cores: vec![8, 9],
    };
    affinity_manager.apply_assignment(&assignment)?;
}
```

#### Small Batch Optimization

```rust
use core::prelude::*;

// Optimized batch processing for HFT
let mut processor = SmallBatchProcessor::new();
let orders = vec![
    OrderRequest::new("EURUSD", Side::Buy, 1000.0)?,
    OrderRequest::new("GBPUSD", Side::Sell, 500.0)?,
];

let result = processor.process_batch(&orders)?;
let metrics = processor.get_metrics();
println!("Batch latency: {}μs", metrics.avg_latency_us);
```

## TLI gRPC Services

The Terminal Interface provides comprehensive gRPC services for system management and real-time operations.

### Trading Service

```protobuf
// Trading operations and order management
service TradingService {
  // Order lifecycle management
  rpc SubmitOrder(OrderRequest) returns (OrderResponse);
  rpc CancelOrder(CancelRequest) returns (CancelResponse);
  rpc ModifyOrder(ModifyRequest) returns (ModifyResponse);

  // Real-time streaming
  rpc StreamOrderUpdates(OrderStreamRequest) returns (stream OrderUpdate);
  rpc StreamPositions(PositionStreamRequest) returns (stream PositionUpdate);
  rpc StreamPnL(PnLStreamRequest) returns (stream PnLUpdate);

  // System management
  rpc GetSystemStatus(Empty) returns (SystemStatusResponse);
  rpc GetPerformanceMetrics(MetricsRequest) returns (PerformanceMetricsResponse);
}
```

**Usage Example:**
```rust
use tli::trading_service_client::TradingServiceClient;

let mut client = TradingServiceClient::connect("http://localhost:50051").await?;

// Submit high-frequency order
let order_request = OrderRequest {
    symbol: "EURUSD".to_string(),
    side: OrderSide::Buy as i32,
    quantity: 1000.0,
    order_type: OrderType::Market as i32,
    time_in_force: TimeInForce::Ioc as i32,
    client_order_id: uuid::Uuid::new_v4().to_string(),
};

let response = client.submit_order(tonic::Request::new(order_request)).await?;
let order_id = response.into_inner().order_id;
println!("Order submitted: {}", order_id);

// Stream real-time order updates
let stream_request = OrderStreamRequest {
    symbols: vec!["EURUSD".to_string()],
    include_fills: true,
};

let mut stream = client.stream_order_updates(
    tonic::Request::new(stream_request)
).await?.into_inner();

while let Some(update) = stream.next().await {
    let update = update?;
    println!("Order update: {:?}", update);
}
```

### Configuration Service

```protobuf
// Dynamic configuration management
service ConfigService {
  // Configuration operations
  rpc GetConfig(ConfigRequest) returns (ConfigResponse);
  rpc UpdateConfig(UpdateConfigRequest) returns (UpdateConfigResponse);
  rpc ReloadConfig(ReloadConfigRequest) returns (ReloadConfigResponse);

  // Real-time configuration streaming
  rpc WatchConfigChanges(WatchRequest) returns (stream ConfigChangeEvent);

  // Configuration validation
  rpc ValidateConfig(ValidateConfigRequest) returns (ValidationResponse);
}
```

**Usage Example:**
```rust
// Get current trading configuration
let config_request = ConfigRequest {
    namespace: "trading".to_string(),
    keys: vec!["max_position_size".to_string(), "risk_limits".to_string()],
};

let response = client.get_config(tonic::Request::new(config_request)).await?;
for config_item in response.into_inner().items {
    println!("{}: {}", config_item.key, config_item.value);
}

// Hot reload trading parameters
let update_request = UpdateConfigRequest {
    namespace: "trading".to_string(),
    updates: vec![
        ConfigUpdate {
            key: "max_position_size".to_string(),
            value: "2000000".to_string(),
            apply_immediately: true,
        }
    ],
};

let response = client.update_config(tonic::Request::new(update_request)).await?;
println!("Config updated: {}", response.into_inner().success);
```

### Health Service

```protobuf
// System health monitoring and diagnostics
service HealthService {
  // Health checks
  rpc Check(HealthCheckRequest) returns (HealthCheckResponse);
  rpc Watch(HealthCheckRequest) returns (stream HealthCheckResponse);

  // Component health
  rpc GetComponentHealth(ComponentRequest) returns (ComponentHealthResponse);
  rpc GetSystemDiagnostics(DiagnosticsRequest) returns (DiagnosticsResponse);
}
```

**Usage Example:**
```rust
// System health check
let health_request = HealthCheckRequest {
    service: "trading".to_string(),
};

let response = client.check(tonic::Request::new(health_request)).await?;
match response.into_inner().status() {
    ServingStatus::Serving => println!("System healthy"),
    ServingStatus::NotServing => println!("System unhealthy"),
    _ => println!("Unknown health status"),
}

// Continuous health monitoring
let mut health_stream = client.watch(
    tonic::Request::new(HealthCheckRequest::default())
).await?.into_inner();

while let Some(health_update) = health_stream.next().await {
    let health = health_update?;
    if health.status() != ServingStatus::Serving {
        eprintln!("Health alert: {:?}", health);
    }
}
```

## ML Training Service APIs

Comprehensive machine learning training and model management APIs. See [ML Training Service API Documentation](./ML_TRAINING_SERVICE_API.md) for complete details.

### Training Job Management

```rust
use tli::ml_training_service_client::MlTrainingServiceClient;

// Start model training
let training_request = StartTrainingRequest {
    model_name: "DQN_EURUSD_v3".to_string(),
    dataset_id: "market_data_q3_2024".to_string(),
    hyperparameters: Some(TrainingHyperparameters {
        learning_rate: 0.0001,
        batch_size: 64,
        epochs: 2000,
        dropout_rate: Some(0.15),
        custom_params: hashmap!{
            "epsilon_decay".to_string() => "0.995".to_string(),
        },
    }),
    resource_requirements: Some(ResourceRequirements {
        gpu_count: 1,
        cpu_cores: 8,
        memory_gb: 32,
        gpu_type: Some("A100".to_string()),
        disk_gb: 200,
    }),
    tags: vec!["production".to_string(), "eurusd".to_string()],
    auto_deploy: true,
};

let job = client.start_training(tonic::Request::new(training_request)).await?.into_inner();
println!("Training started: {}", job.job_id);
```

### Real-Time Training Monitoring

```rust
// Monitor training progress
let watch_request = WatchTrainingRequest {
    job_id: job.job_id.clone(),
    include_logs: true,
    include_metrics: true,
};

let mut stream = client.watch_training_progress(
    tonic::Request::new(watch_request)
).await?.into_inner();

while let Some(update) = stream.next().await {
    let update = update?;

    if let Some(metrics) = &update.metrics {
        println!("Epoch {}/{}: Loss={:.4}, Acc={:.2}%",
            update.current_epoch,
            update.total_epochs,
            metrics.loss,
            metrics.accuracy * 100.0
        );
    }

    if update.status() == TrainingStatus::Completed {
        println!("Training completed successfully!");
        break;
    }
}
```# Foxhunt HFT Trading System - Complete API Documentation

**Version**: 1.0.0 Production  
**Last Updated**: 2025-09-24  
**Performance Target**: Sub-50μs latency, 14ns timing precision

## Overview

The Foxhunt HFT system provides a comprehensive suite of APIs designed for ultra-low latency trading operations. All APIs are built with mathematical safety guarantees, financial type safety, and enterprise-grade error handling.

## Table of Contents

1. [Core Performance APIs](#core-performance-apis)
2. [TLI gRPC Services](#tli-grpc-services)
3. [ML Training Service APIs](#ml-training-service-apis)
4. [Trading Engine APIs](#trading-engine-apis)
5. [Machine Learning APIs](#machine-learning-apis)
6. [Risk Management APIs](#risk-management-apis)
7. [Data Management APIs](#data-management-apis)
8. [Configuration APIs](#configuration-apis)
9. [Health & Monitoring APIs](#health--monitoring-apis)
10. [Security & Authentication APIs](#security--authentication-apis)

## Core Performance APIs

### Module: `core::prelude`

The core performance infrastructure providing sub-50μs latency operations.

#### Types

```rust
use core::prelude::*;

// High-precision financial types (unified across system)
let price = Price::from_str("100.50")?;           // Safe decimal representation
let quantity = Quantity::from_str("1000")?;       // Prevents overflow
let order_id = OrderId::new();                    // Unique identifiers
let timestamp = Timestamp::now();                 // Microsecond precision
```

#### Timing Operations (14ns Precision)

```rust
use core::prelude::*;

// Ultra-low latency timing infrastructure
let timestamp = HardwareTimestamp::now();         // RDTSC-based timing
let latency_tracker = HftLatencyTracker::new();

// Critical path measurement
let measurement = latency_tracker.start_measurement();
// ... ultra-fast operation ...
let latency_ns = measurement.end();               // Nanosecond precision

// Timing safety validation
if !is_tsc_reliable() {
    eprintln!("Warning: TSC timing may be unreliable");
}
```

#### SIMD Operations (Production-Ready)

```rust
use core::prelude::*;

#[cfg(target_arch = "x86_64")]
if std::arch::is_x86_feature_detected!("avx2") {
    let simd_ops = SimdPriceOps::new()?;
    let prices = vec![100.0, 101.0, 102.0, 103.0];
    let result = simd_ops.vectorized_multiply(&prices, 1.01)?;
    println!("SIMD result: {:?}", result);
}

// Adaptive SIMD dispatcher (runtime detection)
let dispatcher = SafeSimdDispatcher::new();
let result = dispatcher.execute_price_calculation(&input_data)?;

// Check SIMD support
if core::performance::check_simd_support() {
    let simd_ops = SimdPriceOps::new()?;
    
    // Vectorized price calculations
    let prices = vec![100.0, 101.0, 102.0, 103.0];
    let adjusted_prices = simd_ops.apply_adjustment(&prices, 0.001)?;
}
```

#### CPU Affinity

```rust
use core::prelude::*;

// Initialize CPU optimizations (Linux only)
#[cfg(target_os = "linux")]
{
    let affinity_manager = CpuAffinityManager::new()?;
    affinity_manager.bind_to_hft_core()?;
}
```

#### Lock-Free Data Structures

```rust
use core::prelude::*;

// High-performance message passing
let (sender, receiver) = SPSCQueue::new(1024);

// Atomic counters
let counter = AtomicCounter::new();
counter.increment();

// Sequence generation
let seq_gen = SequenceGenerator::new();
let sequence = seq_gen.next();
```

## Trading Engine APIs

### Module: `core::trading`

Core trading operations and order management.

#### Order Management

```rust
use core::prelude::*;

let trading_ops = TradingOperations::new(config)?;

// Create and submit order
let order = TradingOrder {
    order_id: OrderId::new(),
    symbol: Symbol::from_str("AAPL")?,
    side: OrderSide::Buy,
    order_type: OrderType::Market,
    quantity: Quantity::from_str("100")?,
    price: Some(Price::from_str("150.00")?),
    time_in_force: TimeInForce::Day,
};

let result = trading_ops.submit_order(order).await?;
```

#### Execution Handling

```rust
use core::prelude::*;

// Handle execution results
match result {
    ExecutionResult::Filled { execution_id, filled_quantity, avg_price, .. } => {
        println!("Order filled: {} shares at ${}", filled_quantity, avg_price);
    },
    ExecutionResult::PartialFill { remaining_quantity, .. } => {
        println!("Partial fill, {} shares remaining", remaining_quantity);
    },
    ExecutionResult::Rejected { reason, .. } => {
        println!("Order rejected: {}", reason);
    },
}
```

#### Position Management

```rust
use core::prelude::*;

let position_manager = PositionManager::new(config)?;

// Get current positions
let positions = position_manager.get_all_positions().await?;

// Get position for specific symbol
let aapl_position = position_manager.get_position(&Symbol::from_str("AAPL")?).await?;

// Calculate PnL
let unrealized_pnl = position_manager.calculate_unrealized_pnl(&market_data).await?;
```

## Machine Learning APIs

### Module: `ml`

Advanced machine learning models for trading decisions.

#### TLOB Transformer

```rust
use ml::tlob::TlobTransformer;

let model = TlobTransformer::new(config)?;
let predictions = model.predict(&order_book_data).await?;
```

#### MAMBA State Space Model

```rust
use ml::mamba::MambaModel;

let mamba = MambaModel::new(config)?;
let sequence_prediction = mamba.forward(&time_series_data).await?;
```

#### DQN Reinforcement Learning

```rust
use ml::dqn::DQNAgent;

let agent = DQNAgent::new(config)?;
let action = agent.select_action(&state).await?;
agent.update_experience(state, action, reward, next_state).await?;
```

#### Feature Engineering

```rust
use ml::features::FeatureExtractor;

let extractor = FeatureExtractor::new(config)?;
let features = extractor.extract_market_features(&market_data).await?;
```

## Risk Management APIs

### Module: `risk`

Comprehensive risk management and compliance.

#### Risk Engine

```rust
use risk::RiskEngine;

let risk_engine = RiskEngine::new(config)?;

// Pre-trade risk check
let risk_check = risk_engine.pre_trade_check(&order).await?;
if !risk_check.approved {
    return Err(RiskError::OrderRejected(risk_check.reason));
}

// Post-trade risk monitoring
risk_engine.post_trade_update(&execution).await?;
```

#### Position Sizing

```rust
use risk::kelly_sizing::KellySizer;

let kelly_sizer = KellySizer::new(config)?;
let optimal_size = kelly_sizer.calculate_position_size(
    &signal_strength,
    &historical_returns,
    &current_portfolio
).await?;
```

#### VaR Calculation

```rust
use risk::var_calculator::VarCalculator;

let var_calc = VarCalculator::new(config)?;
let portfolio_var = var_calc.calculate_portfolio_var(
    &positions,
    &market_data,
    VarMethod::MonteCarlo
).await?;
```

#### Circuit Breaker

```rust
use risk::circuit_breaker::CircuitBreaker;

let circuit_breaker = CircuitBreaker::new(config)?;

// Check if trading should be halted
if circuit_breaker.should_halt_trading().await? {
    trading_engine.emergency_halt().await?;
}
```

## Data Management APIs

### Module: `data`

Real-time and historical market data management.

#### Databento Integration

```rust
use data::databento::DatabentaClient;

let client = DatabentaClient::new(api_key)?;

// Real-time market data
let stream = client.subscribe_live(&["AAPL", "GOOGL"], Schema::Trades).await?;
while let Some(trade) = stream.next().await {
    // Process trade data with institutional-grade quality
}

// Historical data with MBO (Market by Order) support
let records = client.timeseries_get_range(
    "XNAS.ITCH",
    &["AAPL"],
    Schema::Mbo,
    start_date,
    end_date
).await?;
```

#### Benzinga Integration

```rust
use data::benzinga::BenzingaClient;

let client = BenzingaClient::new(api_key)?;

// Real-time news and sentiment
let news_stream = client.subscribe_news(&["AAPL", "GOOGL"]).await?;
while let Some(news) = news_stream.next().await {
    // Process news with sentiment analysis
}

// Analyst ratings and unusual options activity
let ratings = client.get_ratings(&["AAPL"], None, Some(7)).await?;
let uoa = client.get_unusual_options_activity(&["AAPL"]).await?;
```

#### Data Providers

```rust
use data::providers::DataProvider;

// Configure dual-provider architecture
let provider = DataProvider::new()
    .add_databento(databento_config)    // Market microstructure data
    .add_benzinga(benzinga_config)      // News and sentiment
    .add_alpaca(alpaca_config)          // Backup/alternative data
    .build()?;

// Unified data access with automatic provider selection
let market_data = provider.get_latest_quote(&symbol).await?;
let latest_news = provider.get_recent_news(&symbol, 10).await?;
let sentiment = provider.get_sentiment_analysis(&symbol).await?;
```

## TLI Interface APIs

### Module: `tli`

Terminal interface for remote system management.

#### gRPC Client

```rust
use tli::client::TliClient;

let client = TliClient::connect("http://localhost:50051").await?;

// System health check
let health = client.get_system_health().await?;

// Trading operations
let order_status = client.get_order_status(order_id).await?;

// Configuration management
client.update_config(config_updates).await?;
```

#### Dashboard Integration

```rust
use tli::dashboard::Dashboard;

let dashboard = Dashboard::new(config)?;

// Real-time metrics
dashboard.update_latency_metrics(&metrics).await?;
dashboard.update_pnl_display(&pnl_data).await?;
```

## Configuration APIs

### Module: `core::config`

Environment-based configuration management.

#### Configuration Loading

```rust
use core::config::ConfigManager;

let config_manager = ConfigManager::new()?;
let config = config_manager.load_config().await?;

// Environment-specific settings
match config.environment {
    Environment::Production => {
        // Production-specific initialization
    },
    Environment::Development => {
        // Development-specific initialization
    },
}
```

#### Performance Configuration

```rust
use core::config::PerformanceConfig;

let perf_config = PerformanceConfig {
    max_latency_us: 50,
    enable_simd: true,
    cpu_affinity: Some(vec![2, 3, 4, 5]),
    memory_pool_size: 1024 * 1024 * 1024, // 1GB
};
```

## Performance Monitoring APIs

### Latency Tracking

```rust
use core::timing::HftLatencyTracker;

let tracker = HftLatencyTracker::new();

// Track order submission latency
let measurement = tracker.start_measurement();
let result = submit_order(order).await?;
let latency = measurement.end();

if latency.as_nanos() > 50_000 { // 50μs threshold
    log::warn!("High latency detected: {}ns", latency.as_nanos());
}
```

### Metrics Collection

```rust
use core::lockfree::AtomicMetrics;

let metrics = AtomicMetrics::new();

// Increment counters
metrics.increment_counter("orders_submitted");
metrics.record_latency("order_latency", latency);

// Get snapshot
let snapshot = metrics.get_snapshot();
```

## Error Handling

All APIs use consistent error handling patterns:

```rust
use core::error::CoreResult;
use risk::error::RiskResult;
use ml::error::MLResult;

// Standard error handling
match trading_ops.submit_order(order).await {
    Ok(result) => {
        // Handle success
    },
    Err(TradingError::RiskCheckFailed { reason }) => {
        // Handle risk rejection
    },
    Err(TradingError::BrokerError { broker, error }) => {
        // Handle broker communication error
    },
}
```

## Performance Guarantees

### Latency Targets

- **Order submission**: < 50μs (50 microseconds)
- **Risk checks**: < 10μs (10 microseconds)  
- **Market data processing**: < 5μs (5 microseconds)
- **Timing operations**: < 14ns (14 nanoseconds)

### Throughput Targets

- **Orders per second**: > 10,000
- **Market data messages**: > 100,000/sec
- **Risk calculations**: > 1,000/sec

### Memory Usage

- **Lock-free structures**: Zero allocation in hot paths
- **SIMD operations**: Cache-line aligned (64-byte)
- **Memory pools**: Pre-allocated for consistent performance

## Authentication & Security

All TLI API calls require proper authentication:

```rust
use tli::auth::AuthToken;

let token = AuthToken::from_env("TLI_AUTH_TOKEN")?;
let client = TliClient::with_auth("http://localhost:50051", token).await?;
```

## Examples

See the `/examples` directory for complete working examples of each API.

## Support

For API support and questions:
- Documentation: `/docs`
- Examples: `/examples` 
- Issues: Create GitHub issue with reproduction steps