foxhunt/API_DOCUMENTATION.md

Foxhunt API Documentation

Version: 1.0 Last Updated: 2025-10-16 API Gateway: localhost:50051 Protocol: gRPC with TLS/mTLS (RSA 4096-bit)

---

Table of Contents

1. Overview
2. Authentication & Authorization
3. Rate Limiting
4. Error Handling
5. Service APIs
   • Trading Service (7 methods)
   • Trading Agent Service (18 methods)
   • ML Training Service (12 methods)
   • Backtesting Service (6 methods)
   • Risk Management Service (6 methods)
   • Monitoring Service (10 methods)
   • Configuration Service (4 methods)
6. TLI Command Reference
7. Common Data Types

---

Overview

The Foxhunt HFT Trading System exposes 37 gRPC methods across 7 microservices, all accessible through a single API Gateway at port 50051. The API Gateway provides:

• Authentication: JWT + MFA (multi-factor authentication)
• Rate Limiting: Token bucket algorithm (100 req/sec default)
• Audit Logging: All requests logged to PostgreSQL
• Request Routing: Automatic service discovery and load balancing
• TLS Encryption: RSA 4096-bit certificates for all connections

Service Architecture

┌──────────────────────────────────────────────────────────────┐
│                   API Gateway (Port 50051)                    │
│         Auth, Rate Limiting, Audit Logging, Routing           │
└──┬──────────────┬──────────────┬──────────────┬──────────────┘
   │              │              │              │
   ▼              ▼              ▼              ▼
Trading      Trading Agent  ML Training   Backtesting
Service      Service        Service        Service
(50052)      (50055)        (50054)        (50053)

---

Authentication & Authorization

JWT Authentication

All API requests require a valid JWT token in the authorization metadata header:

authorization: Bearer <jwt_token>

Obtaining a JWT Token (via TLI)

# Login with username and password
tli auth login --username <username> --password <password>

# MFA verification (if enabled)
tli auth verify-mfa --code <6-digit-code>

# Token is automatically stored in ~/.config/foxhunt-tli/tokens/

Token Lifetime

• Access Token: 1 hour (3600 seconds)
• Refresh Token: 7 days (604800 seconds)
• MFA Grace Period: 10 minutes after login

Required Permissions

Operation	Required Role
Submit Order	TRADER, ADMIN
Cancel Order	TRADER, ADMIN
Get Positions	TRADER, VIEWER, ADMIN
Emergency Stop	ADMIN only
Update Config	ADMIN only
View Metrics	TRADER, VIEWER, ADMIN

---

Rate Limiting

The API Gateway enforces rate limits using a token bucket algorithm:

Default Limits

Endpoint Type	Requests/Second	Burst Capacity
Trading Operations	100	200
Market Data Streams	10 streams	20 streams
Backtesting	5	10
ML Training	2	5
Configuration	10	20

Rate Limit Headers

Response headers indicate rate limit status:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1729123456

Rate Limit Exceeded Error

{
  "code": "RESOURCE_EXHAUSTED",
  "message": "Rate limit exceeded: 100 requests/second",
  "details": {
    "retry_after_seconds": 1
  }
}

---

Error Handling

gRPC Status Codes

gRPC Code	HTTP Equivalent	Description
OK (0)	200	Success
INVALID_ARGUMENT (3)	400	Invalid request parameters
UNAUTHENTICATED (16)	401	Missing or invalid JWT token
PERMISSION_DENIED (7)	403	Insufficient permissions
NOT_FOUND (5)	404	Resource not found
ALREADY_EXISTS (6)	409	Resource already exists
RESOURCE_EXHAUSTED (8)	429	Rate limit exceeded
INTERNAL (13)	500	Internal server error
UNAVAILABLE (14)	503	Service temporarily unavailable

Error Response Format

message ErrorResponse {
  string code = 1;           // gRPC status code name
  string message = 2;        // Human-readable error message
  map<string, string> details = 3; // Additional error context
  int64 timestamp = 4;       // Error timestamp (nanoseconds)
}

---

Service APIs

Trading Service

Base Package: trading Backend Port: 50052 Total Methods: 15 (12 core + 3 ML)

Core Trading Operations

1. SubmitOrder

Submit a new trading order with validation and risk checks.

Method: TradingService.SubmitOrder

Request:

message SubmitOrderRequest {
  string symbol = 1;                    // Trading symbol (e.g., "AAPL", "BTC-USD", "ES.FUT")
  OrderSide side = 2;                   // BUY or SELL
  double quantity = 3;                  // Number of shares/units to trade
  OrderType order_type = 4;             // MARKET, LIMIT, STOP, STOP_LIMIT
  optional double price = 5;            // Limit price (required for LIMIT orders)
  optional double stop_price = 6;       // Stop price (required for STOP orders)
  string account_id = 7;                // Trading account identifier
  map<string, string> metadata = 8;     // Additional order metadata (strategy, tags, etc.)
}

Response:

message SubmitOrderResponse {
  string order_id = 1;                  // Unique order identifier
  OrderStatus status = 2;               // PENDING, SUBMITTED, etc.
  string message = 3;                   // Status message or error description
  int64 timestamp = 4;                  // Order submission timestamp (nanoseconds)
}

TLI Command: tli trade submit --symbol <symbol> --side <BUY|SELL> --quantity <qty> --type <MARKET|LIMIT>

Example:

tli trade submit --symbol ES.FUT --side BUY --quantity 10 --type MARKET

Performance: P99 latency ~15.96ms (target: <100ms)

---

2. CancelOrder

Cancel an existing order by order ID.

Method: TradingService.CancelOrder

Request:

message CancelOrderRequest {
  string order_id = 1;                  // Order ID to cancel
  string account_id = 2;                // Account ID for verification
}

Response:

message CancelOrderResponse {
  bool success = 1;                     // True if cancellation was successful
  string message = 2;                   // Success confirmation or error message
  int64 timestamp = 3;                  // Cancellation timestamp (nanoseconds)
}

TLI Command: tli trade cancel --order-id <order_id>

Example:

tli trade cancel --order-id "550e8400-e29b-41d4-a716-446655440000"

---

3. GetOrderStatus

Get current status of a specific order.

Method: TradingService.GetOrderStatus

Request:

message GetOrderStatusRequest {
  string order_id = 1;                  // Order ID to query
}

Response:

message GetOrderStatusResponse {
  Order order = 1;                      // Complete order details with current status
}

TLI Command: tli trade status --order-id <order_id>

Example:

tli trade status --order-id "550e8400-e29b-41d4-a716-446655440000"

---

4. StreamOrders

Stream real-time order events for monitoring order lifecycle.

Method: TradingService.StreamOrders (Server Streaming)

Request:

message StreamOrdersRequest {
  optional string account_id = 1;       // Filter by account (all accounts if not specified)
  optional string symbol = 2;           // Filter by symbol (all symbols if not specified)
}

Response Stream:

message OrderEvent {
  string order_id = 1;                  // Order identifier
  Order order = 2;                      // Complete order details
  OrderEventType event_type = 3;        // CREATED, UPDATED, FILLED, CANCELLED, etc.
  int64 timestamp = 4;                  // Event timestamp (nanoseconds)
  string message = 5;                   // Event message or additional details
}

TLI Command: tli trade stream --type orders [--symbol <symbol>]

---

5. GetPositions

Get current positions for account and/or symbol.

Method: TradingService.GetPositions

Request:

message GetPositionsRequest {
  optional string account_id = 1;       // Filter by account (all accounts if not specified)
  optional string symbol = 2;           // Filter by symbol (all symbols if not specified)
}

Response:

message GetPositionsResponse {
  repeated Position positions = 1;      // List of current positions
}

TLI Command: tli trade positions [--symbol <symbol>]

Example:

tli trade positions --symbol ES.FUT

---

6. StreamPositions

Stream real-time position updates as trades execute.

Method: TradingService.StreamPositions (Server Streaming)

Request:

message StreamPositionsRequest {
  optional string account_id = 1;       // Filter by account (all accounts if not specified)
}

Response Stream:

message PositionEvent {
  string symbol = 1;                    // Trading symbol
  Position position = 2;                // Updated position details
  PositionEventType event_type = 3;     // OPENED, UPDATED, CLOSED
  int64 timestamp = 4;                  // Event timestamp (nanoseconds)
  double quantity = 5;                  // Position quantity (quick access)
  double average_price = 6;             // Average entry price (quick access)
  double unrealized_pnl = 7;            // Unrealized P&L (quick access)
}

TLI Command: tli trade stream --type positions

---

7. GetPortfolioSummary

Get comprehensive portfolio summary with P&L and risk metrics.

Method: TradingService.GetPortfolioSummary

Request:

message GetPortfolioSummaryRequest {
  string account_id = 1;                // Account ID for portfolio summary
}

Response:

message GetPortfolioSummaryResponse {
  double total_value = 1;               // Total portfolio value in USD
  double unrealized_pnl = 2;            // Unrealized profit/loss
  double realized_pnl = 3;              // Realized profit/loss for the day
  double day_pnl = 4;                   // Total P&L for the current trading day
  double buying_power = 5;              // Available buying power
  double margin_used = 6;               // Amount of margin currently used
  repeated Position positions = 7;      // Detailed position information
}

TLI Command: tli trade portfolio

---

Market Data Operations

8. StreamMarketData

Stream real-time market data (trades, quotes, order book).

Method: TradingService.StreamMarketData (Server Streaming)

Request:

message StreamMarketDataRequest {
  repeated string symbols = 1;          // List of symbols to subscribe to
  repeated MarketDataType data_types = 2; // TRADE, QUOTE, ORDER_BOOK
}

Response Stream:

message MarketDataEvent {
  string symbol = 1;                    // Trading symbol
  MarketDataType data_type = 2;         // Type of market data
  oneof data {
    Trade trade = 3;                    // Trade data (when data_type = TRADE)
    Quote quote = 4;                    // Quote data (when data_type = QUOTE)
    OrderBook order_book = 5;           // Order book data (when data_type = ORDER_BOOK)
  }
  int64 timestamp = 6;                  // Market data timestamp (nanoseconds)
}

TLI Command: tli market stream --symbols <symbols> --types <TRADE|QUOTE|BOOK>

---

9. GetOrderBook

Get current order book snapshot for a symbol.

Method: TradingService.GetOrderBook

Request:

message GetOrderBookRequest {
  string symbol = 1;                    // Symbol to get order book for
  optional int32 depth = 2;             // Number of price levels (default: full book)
}

Response:

message GetOrderBookResponse {
  OrderBook order_book = 1;             // Current order book snapshot
}

TLI Command: tli market book --symbol <symbol> [--depth <depth>]

---

Execution Operations

10. StreamExecutions

Stream real-time trade executions as they occur.

Method: TradingService.StreamExecutions (Server Streaming)

Request:

message StreamExecutionsRequest {
  optional string account_id = 1;       // Filter by account (all accounts if not specified)
  optional string symbol = 2;           // Filter by symbol (all symbols if not specified)
}

Response Stream:

message ExecutionEvent {
  string execution_id = 1;              // Execution identifier
  Execution execution = 2;              // Execution details
  int64 timestamp = 3;                  // Event timestamp (nanoseconds)
  string order_id = 4;                  // Associated order ID (quick access)
  string symbol = 5;                    // Trading symbol (quick access)
  double quantity = 6;                  // Executed quantity (quick access)
  double price = 7;                     // Execution price (quick access)
}

TLI Command: tli trade stream --type executions

---

11. GetExecutionHistory

Get historical execution data with filtering options.

Method: TradingService.GetExecutionHistory

Request:

message GetExecutionHistoryRequest {
  optional string account_id = 1;       // Filter by account (all accounts if not specified)
  optional string symbol = 2;           // Filter by symbol (all symbols if not specified)
  optional int64 start_time = 3;        // Start time for query (nanoseconds)
  optional int64 end_time = 4;          // End time for query (nanoseconds)
  optional int32 limit = 5;             // Maximum number of executions to return
}

Response:

message GetExecutionHistoryResponse {
  repeated Execution executions = 1;    // List of historical executions
}

TLI Command: tli trade history [--symbol <symbol>] [--limit <n>]

---

ML Trading Operations

12. SubmitMLOrder

Submit ML-generated trading order with ensemble predictions.

Method: TradingService.SubmitMLOrder

Request:

message MLOrderRequest {
  string symbol = 1;                    // Trading symbol (e.g., "ES.FUT")
  string account_id = 2;                // Trading account identifier
  bool use_ensemble = 3;                // Use ensemble voting or specific model
  optional string model_name = 4;       // Specific model name if not using ensemble
  repeated double features = 5;         // Feature vector for ML prediction (26 features: OHLCV + technicals)
}

Response:

message MLOrderResponse {
  string order_id = 1;                  // Order ID if executed
  string prediction_id = 2;             // Prediction ID from ensemble_predictions table
  string action = 3;                    // Action taken: BUY, SELL, HOLD
  double confidence = 4;                // Prediction confidence (0.0-1.0)
  string message = 5;                   // Status message
  bool executed = 6;                    // True if order was executed
}

TLI Command: tli trade ml submit --symbol <symbol> [--model <DQN|PPO|MAMBA2|TFT>]

Example:

# Submit ensemble ML order
tli trade ml submit --symbol ES.FUT

# Submit order using specific model
tli trade ml submit --symbol ES.FUT --model DQN

Performance: Inference latency ~200μs (DQN), ~500μs (MAMBA-2)

---

13. GetMLPredictions

Get ML prediction history with outcomes.

Method: TradingService.GetMLPredictions

Request:

message MLPredictionsRequest {
  string symbol = 1;                    // Trading symbol to filter by
  optional string model_name = 2;       // Filter by specific model
  int32 limit = 3;                      // Maximum predictions to return (default: 100)
  optional int64 start_time = 4;        // Start time filter (nanoseconds)
  optional int64 end_time = 5;          // End time filter (nanoseconds)
}

Response:

message MLPredictionsResponse {
  repeated MLPrediction predictions = 1; // List of predictions with outcomes
}

TLI Command: tli trade ml predictions --symbol <symbol> [--model <model>] [--limit <n>]

Example:

tli trade ml predictions --symbol ES.FUT --limit 50

---

14. GetMLPerformance

Get ML model performance metrics.

Method: TradingService.GetMLPerformance

Request:

message MLPerformanceRequest {
  optional string model_name = 1;       // Filter by specific model (or all if not specified)
  optional int64 start_time = 2;        // Start time for metrics (nanoseconds)
  optional int64 end_time = 3;          // End time for metrics (nanoseconds)
}

Response:

message MLPerformanceResponse {
  repeated ModelPerformance models = 1; // Performance metrics per model
}

TLI Command: tli trade ml performance [--model <model>]

Example:

# Get all model performance
tli trade ml performance

# Get specific model performance
tli trade ml performance --model MAMBA2

---

Trading Agent Service

Base Package: trading_agent Backend Port: 50055 Total Methods: 18

The Trading Agent Service orchestrates portfolio management decisions through universe selection, asset ranking, capital allocation, and order generation.

Universe Management

1. SelectUniverse

Select tradable universe based on liquidity, volatility, and ML signals.

Method: TradingAgentService.SelectUniverse

Request:

message SelectUniverseRequest {
  UniverseCriteria criteria = 1;       // Selection criteria
  optional uint32 max_instruments = 2; // Maximum instruments in universe
  bool force_refresh = 3;              // Force recalculation
}

Response:

message SelectUniverseResponse {
  repeated Instrument instruments = 1; // Selected instruments
  UniverseMetrics metrics = 2;         // Universe quality metrics
  int64 timestamp = 3;                 // Selection timestamp (nanoseconds)
  string universe_id = 4;              // Unique universe identifier
}

TLI Command: tli agent universe select [--max-instruments <n>]

Performance: <1s (target met)

---

2. GetUniverse

Get current trading universe configuration.

Method: TradingAgentService.GetUniverse

Request:

message GetUniverseRequest {
  optional string universe_id = 1;     // Get specific universe, or current if not specified
}

Response:

message GetUniverseResponse {
  string universe_id = 1;
  repeated Instrument instruments = 2;
  UniverseCriteria criteria = 3;
  UniverseMetrics metrics = 4;
  int64 created_at = 5;
  int64 updated_at = 6;
}

TLI Command: tli agent universe show

---

3. UpdateUniverseCriteria

Update universe selection criteria.

Method: TradingAgentService.UpdateUniverseCriteria

Request:

message UpdateUniverseCriteriaRequest {
  UniverseCriteria criteria = 1;
}

Response:

message UpdateUniverseCriteriaResponse {
  bool success = 1;
  string message = 2;
  string universe_id = 3;              // New universe ID after update
}

TLI Command: tli agent universe update --min-liquidity <val> --min-volatility <val>

---

Asset Selection

4. SelectAssets

Select specific assets to trade within universe using ML-driven ranking.

Method: TradingAgentService.SelectAssets

Request:

message SelectAssetsRequest {
  string universe_id = 1;              // Universe to select from
  AssetSelectionCriteria criteria = 2; // Selection criteria
  uint32 max_assets = 3;               // Maximum assets to select
}

Response:

message SelectAssetsResponse {
  repeated AssetScore assets = 1;      // Selected assets with scores
  SelectionMetrics metrics = 2;        // Selection quality metrics
  int64 timestamp = 3;
}

TLI Command: tli agent assets select --max-assets <n>

Performance: <2s (target met)

Multi-Factor Scoring:

• ML Score: 40% weight
• Momentum Score: 30% weight
• Value Score: 20% weight
• Liquidity Score: 10% weight

---

5. GetSelectedAssets

Get current asset selection with scores.

Method: TradingAgentService.GetSelectedAssets

Request:

message GetSelectedAssetsRequest {
  optional string universe_id = 1;
}

Response:

message GetSelectedAssetsResponse {
  repeated AssetScore assets = 1;
  SelectionMetrics metrics = 2;
  int64 timestamp = 3;
}

TLI Command: tli agent assets show

---

Portfolio Allocation

6. AllocatePortfolio

Allocate capital across selected assets using one of 5 strategies.

Method: TradingAgentService.AllocatePortfolio

Request:

message AllocatePortfolioRequest {
  repeated AssetScore assets = 1;      // Assets to allocate across
  AllocationStrategy strategy = 2;     // EQUAL_WEIGHT, RISK_PARITY, MEAN_VARIANCE, ML_OPTIMIZED, KELLY
  RiskConstraints risk_constraints = 3; // Risk limits
  double total_capital = 4;            // Total capital to allocate
}

Response:

message AllocatePortfolioResponse {
  repeated AssetAllocation allocations = 1; // Allocation per asset
  AllocationMetrics metrics = 2;       // Allocation quality metrics
  int64 timestamp = 3;
  string allocation_id = 4;
}

TLI Command: tli agent allocate --strategy <EQUAL|RISK_PARITY|ML|KELLY> --capital <amount>

Performance: <500ms (target met)

Supported Allocation Strategies:

1. Equal Weight: 1/N allocation
2. Risk Parity: Equal risk contribution per asset
3. Mean-Variance: Markowitz optimization
4. ML-Optimized: ML model-driven allocation
5. Kelly Criterion: Optimal bet sizing

---

7. GetAllocation

Get current portfolio allocation.

Method: TradingAgentService.GetAllocation

Request:

message GetAllocationRequest {
  optional string allocation_id = 1;   // Get specific allocation, or current if not specified
}

Response:

message GetAllocationResponse {
  string allocation_id = 1;
  repeated AssetAllocation allocations = 2;
  AllocationMetrics metrics = 3;
  int64 created_at = 4;
  double total_capital = 5;
}

TLI Command: tli agent allocate show

---

8. RebalancePortfolio

Rebalance portfolio based on target allocation.

Method: TradingAgentService.RebalancePortfolio

Request:

message RebalancePortfolioRequest {
  string allocation_id = 1;            // Target allocation
  double rebalance_threshold = 2;      // Min deviation to trigger rebalance (%)
  bool force_rebalance = 3;            // Force rebalance regardless of threshold
}

Response:

message RebalancePortfolioResponse {
  repeated RebalanceAction actions = 1; // Required rebalancing actions
  RebalanceMetrics metrics = 2;
  bool rebalance_required = 3;
  int64 timestamp = 4;
}

TLI Command: tli agent rebalance [--threshold <pct>] [--force]

---

Order Generation

9. GenerateOrders

Generate orders based on allocation and ML signals.

Method: TradingAgentService.GenerateOrders

Request:

message GenerateOrdersRequest {
  string allocation_id = 1;            // Target allocation
  repeated MLSignal ml_signals = 2;    // ML predictions for timing
  OrderGenerationStrategy strategy = 3; // Order generation algorithm
}

Response:

message GenerateOrdersResponse {
  repeated GeneratedOrder orders = 1;  // Generated order instructions
  OrderGenerationMetrics metrics = 2;
  int64 timestamp = 3;
  string order_batch_id = 4;
}

TLI Command: tli agent orders generate

---

10. SubmitAgentOrders

Submit generated orders to Trading Service.

Method: TradingAgentService.SubmitAgentOrders

Request:

message SubmitAgentOrdersRequest {
  string order_batch_id = 1;           // Batch ID from GenerateOrders
  repeated GeneratedOrder orders = 2;  // Orders to submit
  bool dry_run = 3;                    // Test without actual submission
}

Response:

message SubmitAgentOrdersResponse {
  repeated OrderSubmissionResult results = 1; // Submission results per order
  OrderSubmissionMetrics metrics = 2;
  int64 timestamp = 3;
}

TLI Command: tli agent orders submit --batch-id <id> [--dry-run]

---

Strategy Coordination

11. RegisterStrategy

Register a trading strategy with the agent.

Method: TradingAgentService.RegisterStrategy

Request:

message RegisterStrategyRequest {
  string strategy_name = 1;            // Unique strategy name
  StrategyType strategy_type = 2;      // ML_ENSEMBLE, MEAN_REVERSION, MOMENTUM, ARBITRAGE, MARKET_MAKING
  StrategyConfig config = 3;           // Strategy configuration
  bool auto_enable = 4;                // Enable immediately after registration
}

Response:

message RegisterStrategyResponse {
  bool success = 1;
  string strategy_id = 2;
  string message = 3;
}

TLI Command: tli agent strategy register --name <name> --type <type>

---

12. ListStrategies

Get list of active strategies.

Method: TradingAgentService.ListStrategies

Request:

message ListStrategiesRequest {
  optional StrategyStatus status_filter = 1; // ENABLED, DISABLED, PAUSED, ERROR
}

Response:

message ListStrategiesResponse {
  repeated Strategy strategies = 1;
}

TLI Command: tli agent strategy list [--status <ENABLED|DISABLED>]

---

13. UpdateStrategyStatus

Enable/disable a strategy.

Method: TradingAgentService.UpdateStrategyStatus

Request:

message UpdateStrategyStatusRequest {
  string strategy_id = 1;
  StrategyStatus new_status = 2;       // ENABLED, DISABLED, PAUSED
  optional string reason = 3;
}

Response:

message UpdateStrategyStatusResponse {
  bool success = 1;
  string message = 2;
  Strategy updated_strategy = 3;
}

TLI Command: tli agent strategy update --id <id> --status <ENABLED|DISABLED>

---

Agent Monitoring

14. GetAgentStatus

Get comprehensive agent status and performance.

Method: TradingAgentService.GetAgentStatus

Request:

message GetAgentStatusRequest {
  bool include_performance = 1;        // Include performance metrics
  bool include_positions = 2;          // Include current positions
}

Response:

message GetAgentStatusResponse {
  AgentStatus status = 1;
  optional AgentPerformanceMetrics performance = 2;
  optional PositionSummary positions = 3;
  int64 timestamp = 4;
}

TLI Command: tli agent status [--with-performance] [--with-positions]

---

15. StreamAgentActivity

Stream real-time agent decisions and actions.

Method: TradingAgentService.StreamAgentActivity (Server Streaming)

Request:

message StreamAgentActivityRequest {
  repeated ActivityType activity_types = 1; // UNIVERSE_SELECTION, ASSET_SELECTION, ALLOCATION, ORDER_GENERATION, STRATEGY
}

Response Stream:

message AgentActivityEvent {
  ActivityType activity_type = 1;
  oneof event {
    UniverseSelectionEvent universe_event = 2;
    AssetSelectionEvent asset_event = 3;
    AllocationEvent allocation_event = 4;
    OrderGenerationEvent order_event = 5;
    StrategyEvent strategy_event = 6;
  }
  int64 timestamp = 7;
}

TLI Command: tli agent stream [--types <types>]

---

16. GetAgentPerformance

Get agent performance metrics.

Method: TradingAgentService.GetAgentPerformance

Request:

message GetAgentPerformanceRequest {
  optional int64 start_time = 1;       // Performance window start (nanoseconds)
  optional int64 end_time = 2;         // Performance window end (nanoseconds)
  bool include_strategy_breakdown = 3; // Include per-strategy performance
}

Response:

message GetAgentPerformanceResponse {
  AgentPerformanceMetrics metrics = 1;
  repeated StrategyPerformance strategy_performance = 2;
  int64 timestamp = 3;
}

TLI Command: tli agent performance [--start <time>] [--end <time>]

---

17. HealthCheck

Check Trading Agent Service health.

Method: TradingAgentService.HealthCheck

Request:

message HealthCheckRequest {}

Response:

message HealthCheckResponse {
  bool healthy = 1;
  string message = 2;
  map<string, string> details = 3;
}

TLI Command: tli agent health

---

ML Training Service

Base Package: ml_training Backend Port: 50054 Total Methods: 12

The ML Training Service manages model training jobs (MAMBA-2, DQN, PPO, TFT, TLOB), hyperparameter tuning with Optuna, and batch training workflows.

Training Job Management

1. StartTraining

Initiates a new training job and returns job ID immediately.

Method: MLTrainingService.StartTraining

Request:

message StartTrainingRequest {
  string model_type = 1;                // TLOB, MAMBA_2, DQN, PPO, LIQUID, TFT
  DataSource data_source = 2;           // Training data source configuration
  Hyperparameters hyperparameters = 3;  // Model-specific training parameters
  bool use_gpu = 4;                     // Whether to use GPU acceleration
  string description = 5;               // Optional job description
  map<string, string> tags = 6;         // Optional categorization tags
}

Response:

message StartTrainingResponse {
  string job_id = 1;
  TrainingStatus status = 2;            // PENDING, RUNNING, COMPLETED, FAILED, STOPPED
  string message = 3;
}

TLI Command: tli ml train --model <DQN|PPO|MAMBA2|TFT> [--gpu]

Example:

tli ml train --model DQN --epochs 50 --batch-size 256 --gpu

Performance:

• DQN: ~15s for 50 epochs
• PPO: ~7s for 10 epochs
• MAMBA-2: ~1.86min for 200 epochs
• TFT: ~5-7 days for production training

---

2. SubscribeToTrainingStatus

Subscribe to real-time training progress and status updates.

Method: MLTrainingService.SubscribeToTrainingStatus (Server Streaming)

Request:

message SubscribeToTrainingStatusRequest {
  string job_id = 1;
}

Response Stream:

message TrainingStatusUpdate {
  string job_id = 1;
  TrainingStatus status = 2;
  float progress_percentage = 3;        // Training progress (0.0 to 100.0)
  uint32 current_epoch = 4;
  uint32 total_epochs = 5;
  map<string, float> metrics = 6;       // loss, accuracy, sharpe_ratio, etc.
  string message = 7;
  int64 timestamp = 8;
  FinancialMetrics financial_metrics = 9;
  ResourceUsage resource_usage = 10;
}

TLI Command: tli ml train --model <model> --watch

---

3. StopTraining

Stop a running training job (idempotent operation).

Method: MLTrainingService.StopTraining

Request:

message StopTrainingRequest {
  string job_id = 1;
  string reason = 2;                    // Optional reason for stopping
}

Response:

message StopTrainingResponse {
  bool success = 1;
  string message = 2;
}

TLI Command: tli ml stop --job-id <job_id>

---

4. ListAvailableModels

List available ML models with their training parameters.

Method: MLTrainingService.ListAvailableModels

Request:

message ListAvailableModelsRequest {}

Response:

message ListAvailableModelsResponse {
  repeated ModelDefinition models = 1;
}

TLI Command: tli ml list-models

---

5. ListTrainingJobs

Get paginated list of training job history.

Method: MLTrainingService.ListTrainingJobs

Request:

message ListTrainingJobsRequest {
  uint32 page = 1;
  uint32 page_size = 2;
  TrainingStatus status_filter = 3;
  string model_type_filter = 4;
  int64 start_time = 5;                 // Unix timestamp in seconds
  int64 end_time = 6;
}

Response:

message ListTrainingJobsResponse {
  repeated TrainingJobSummary jobs = 1;
  uint32 total_count = 2;
  uint32 page = 3;
  uint32 page_size = 4;
}

TLI Command: tli ml jobs [--status <RUNNING|COMPLETED|FAILED>] [--model <model>]

---

6. GetTrainingJobDetails

Get comprehensive details for a specific training job.

Method: MLTrainingService.GetTrainingJobDetails

Request:

message GetTrainingJobDetailsRequest {
  string job_id = 1;
}

Response:

message GetTrainingJobDetailsResponse {
  TrainingJobDetails job_details = 1;
}

TLI Command: tli ml job-details --job-id <job_id>

---

Hyperparameter Tuning

7. StartTuningJob

Start a new hyperparameter tuning job using Optuna.

Method: MLTrainingService.StartTuningJob

Request:

message StartTuningJobRequest {
  string model_type = 1;                // Model type to tune
  uint32 num_trials = 2;                // Number of tuning trials to run
  string config_path = 3;               // Path to tuning configuration file
  DataSource data_source = 4;           // Training data source
  bool use_gpu = 5;                     // Whether to use GPU acceleration
  string description = 6;
  map<string, string> tags = 7;
}

Response:

message StartTuningJobResponse {
  string job_id = 1;
  TuningJobStatus status = 2;           // TUNING_PENDING, TUNING_RUNNING, TUNING_COMPLETED, TUNING_FAILED, TUNING_STOPPED
  string message = 3;
}

TLI Command: tli tune start --model <DQN|PPO|MAMBA2|TFT> --trials <n> [--watch]

Example:

tli tune start --model DQN --trials 50 --watch

Performance: 5-10 minutes per trial, 4-8 hours for 50 trials

---

8. GetTuningJobStatus

Get current status and best parameters from a tuning job.

Method: MLTrainingService.GetTuningJobStatus

Request:

message GetTuningJobStatusRequest {
  string job_id = 1;
}

Response:

message GetTuningJobStatusResponse {
  string job_id = 1;
  TuningJobStatus status = 2;
  uint32 current_trial = 3;
  uint32 total_trials = 4;
  map<string, float> best_params = 5;   // Best hyperparameters found so far
  map<string, float> best_metrics = 6;  // sharpe_ratio, training_loss, etc.
  repeated TrialResult trial_history = 7;
  string message = 8;
  int64 started_at = 9;
  int64 updated_at = 10;
}

TLI Command: tli tune status --job-id <job_id>

---

9. StopTuningJob

Stop a running hyperparameter tuning job.

Method: MLTrainingService.StopTuningJob

Request:

message StopTuningJobRequest {
  string job_id = 1;
  string reason = 2;
}

Response:

message StopTuningJobResponse {
  bool success = 1;
  string message = 2;
  TuningJobStatus final_status = 3;
}

TLI Command: tli tune stop --job-id <job_id>

---

10. StreamTuningProgress

Stream real-time tuning progress updates (trial completion events).

Method: MLTrainingService.StreamTuningProgress (Server Streaming)

Request:

message StreamProgressRequest {
  string job_id = 1;
}

Response Stream:

message ProgressUpdate {
  string job_id = 1;
  uint32 current_trial = 2;
  uint32 total_trials = 3;
  map<string, string> trial_params = 4;
  float trial_sharpe = 5;               // Current trial's Sharpe ratio
  float best_sharpe_so_far = 6;
  uint32 estimated_time_remaining = 7;  // Seconds until completion
  TuningJobStatus status = 8;
  string message = 9;
  int64 timestamp = 10;
  UpdateType update_type = 11;          // TRIAL_COMPLETE, HEARTBEAT, JOB_COMPLETE
}

TLI Command: tli tune start --model <model> --trials <n> --watch

---

11. BatchStartTuningJobs

Start batch tuning job for multiple models with automatic dependency resolution.

Method: MLTrainingService.BatchStartTuningJobs

Request:

message BatchStartTuningJobsRequest {
  repeated string model_types = 1;      // List of models to tune
  uint32 trials_per_model = 2;          // Number of trials for each model
  string config_path = 3;
  DataSource data_source = 4;
  bool use_gpu = 5;
  bool auto_export_yaml = 6;            // Automatically export best params to YAML
  string yaml_export_path = 7;          // Custom YAML export path
  string description = 8;
  map<string, string> tags = 9;
}

Response:

message BatchStartTuningJobsResponse {
  string batch_id = 1;
  repeated string execution_order = 2;  // Model execution order (after dependency resolution)
  string message = 3;
  BatchTuningStatus status = 4;         // BATCH_PENDING, BATCH_RUNNING, BATCH_COMPLETED, etc.
}

TLI Command: tli tune batch --models <DQN,PPO,MAMBA2,TFT> --trials <n>

---

12. GetBatchTuningStatus

Get batch tuning job status with per-model results.

Method: MLTrainingService.GetBatchTuningStatus

Request:

message GetBatchTuningStatusRequest {
  string batch_id = 1;
}

Response:

message GetBatchTuningStatusResponse {
  string batch_id = 1;
  BatchTuningStatus status = 2;
  uint32 current_model_index = 3;
  uint32 total_models = 4;
  repeated ModelTuningResult results = 5;
  string current_model = 6;
  int64 started_at = 7;
  int64 updated_at = 8;
  int64 estimated_completion_time = 9;
  string yaml_export_path = 10;
}

TLI Command: tli tune batch-status --batch-id <batch_id>

---

Backtesting Service

Base Package: foxhunt.tli.BacktestingService (defined in TLI proto) Backend Port: 50053 Total Methods: 6

Backtest Execution Management

1. StartBacktest

Start a new strategy backtest with historical data.

Method: BacktestingService.StartBacktest

Request:

message StartBacktestRequest {
  string strategy_name = 1;
  repeated string symbols = 2;
  int64 start_date_unix_nanos = 3;
  int64 end_date_unix_nanos = 4;
  double initial_capital = 5;
  map<string, string> parameters = 6;
  bool save_results = 7;
  string description = 8;
}

Response:

message StartBacktestResponse {
  bool success = 1;
  string backtest_id = 2;
  string message = 3;
  int64 estimated_duration_seconds = 4;
}

TLI Command: tli backtest start --strategy <name> --symbols <symbols> --start <date> --end <date> --capital <amount>

Example:

tli backtest start --strategy moving_average_crossover --symbols ES.FUT,NQ.FUT --start 2024-01-01 --end 2024-03-31 --capital 100000

Performance: DBN data loading in 0.70ms for 1,674 bars (14x faster than target)

---

2. GetBacktestStatus

Get current status of a running backtest.

Method: BacktestingService.GetBacktestStatus

Request:

message GetBacktestStatusRequest {
  string backtest_id = 1;
}

Response:

message GetBacktestStatusResponse {
  string backtest_id = 1;
  BacktestStatus status = 2;            // QUEUED, RUNNING, COMPLETED, FAILED, CANCELLED, PAUSED
  double progress_percentage = 3;
  string current_date = 4;
  uint64 trades_executed = 5;
  double current_pnl = 6;
  int64 started_at_unix_nanos = 7;
  optional int64 completed_at_unix_nanos = 8;
  optional string error_message = 9;
}

TLI Command: tli backtest status --id <backtest_id>

---

3. GetBacktestResults

Get comprehensive backtest results and analytics.

Method: BacktestingService.GetBacktestResults

Request:

message GetBacktestResultsRequest {
  string backtest_id = 1;
  bool include_trades = 2;
  bool include_metrics = 3;
}

Response:

message GetBacktestResultsResponse {
  string backtest_id = 1;
  BacktestMetrics metrics = 2;
  repeated Trade trades = 3;
  repeated EquityCurvePoint equity_curve = 4;
  repeated DrawdownPeriod drawdown_periods = 5;
}

TLI Command: tli backtest results --id <backtest_id> [--with-trades]

---

4. ListBacktests

List historical backtest runs with filtering.

Method: BacktestingService.ListBacktests

Request:

message ListBacktestsRequest {
  uint32 limit = 1;
  uint32 offset = 2;
  optional string strategy_name = 3;
  optional BacktestStatus status_filter = 4;
}

Response:

message ListBacktestsResponse {
  repeated BacktestSummary backtests = 1;
  uint32 total_count = 2;
}

TLI Command: tli backtest list [--strategy <name>] [--status <COMPLETED|RUNNING>]

---

5. SubscribeBacktestProgress

Subscribe to real-time backtest progress updates.

Method: BacktestingService.SubscribeBacktestProgress (Server Streaming)

Request:

message SubscribeBacktestProgressRequest {
  string backtest_id = 1;
}

Response Stream:

message BacktestProgressEvent {
  string backtest_id = 1;
  double progress_percentage = 2;
  string current_date = 3;
  uint64 trades_executed = 4;
  double current_pnl = 5;
  double current_equity = 6;
  BacktestStatus status = 7;
  int64 timestamp_unix_nanos = 8;
}

TLI Command: tli backtest start --strategy <name> --watch

---

6. StopBacktest

Stop a running backtest and optionally save partial results.

Method: BacktestingService.StopBacktest

Request:

message StopBacktestRequest {
  string backtest_id = 1;
  bool save_partial_results = 2;
}

Response:

message StopBacktestResponse {
  bool success = 1;
  string message = 2;
  bool results_saved = 3;
}

TLI Command: tli backtest stop --id <backtest_id> [--save-partial]

---

Risk Management Service

Base Package: risk Backend Port: 50052 (co-located with Trading Service) Total Methods: 6

Value at Risk (VaR) Calculations

1. GetVaR

Calculate current portfolio VaR using specified method and parameters.

Method: RiskService.GetVaR

Request:

message GetVaRRequest {
  repeated string symbols = 1;          // Symbols to include (empty = all positions)
  double confidence_level = 2;          // e.g., 0.95 for 95% VaR
  int32 lookback_days = 3;              // Historical data period
  VaRMethod method = 4;                 // HISTORICAL, PARAMETRIC, MONTE_CARLO
}

Response:

message GetVaRResponse {
  double portfolio_var = 1;             // Total portfolio VaR value
  repeated SymbolVaR symbol_vars = 2;   // Individual symbol VaR contributions
  double confidence_level = 3;
  int32 lookback_days = 4;
  VaRMethod method = 5;
  int64 calculated_at = 6;
}

TLI Command: tli risk var [--symbols <symbols>] [--confidence 0.95] [--lookback 30]

---

2. StreamVaRUpdates

Stream real-time VaR updates as market conditions change.

Method: RiskService.StreamVaRUpdates (Server Streaming)

Request:

message StreamVaRRequest {
  double confidence_level = 1;
  int32 update_frequency_seconds = 2;
}

Response Stream:

message VaREvent {
  double portfolio_var = 1;
  repeated SymbolVaR symbol_vars = 2;
  VaRChangeType change_type = 3;        // INCREASED, DECREASED, BREACH
  int64 timestamp = 4;
}

TLI Command: tli risk stream --type var

---

3. GetPositionRisk

Get comprehensive risk analysis for current positions.

Method: RiskService.GetPositionRisk

Request:

message GetPositionRiskRequest {
  optional string symbol = 1;           // Filter by symbol
  optional string account_id = 2;       // Filter by account
}

Response:

message GetPositionRiskResponse {
  repeated PositionRisk position_risks = 1;
  double portfolio_risk_score = 2;      // Overall score (0-100)
}

TLI Command: tli risk positions [--symbol <symbol>]

---

4. ValidateOrder

Validate order against risk limits before execution.

Method: RiskService.ValidateOrder

Request:

message ValidateOrderRequest {
  string symbol = 1;
  double quantity = 2;
  double price = 3;
  string side = 4;                      // BUY or SELL
  string account_id = 5;
}

Response:

message ValidateOrderResponse {
  bool is_valid = 1;                    // True if order passes all risk checks
  repeated RiskViolation violations = 2;
  RiskScore risk_score = 3;
  string message = 4;
}

TLI Command: tli risk validate --symbol <symbol> --side <BUY|SELL> --quantity <qty> --price <price>

---

5. GetRiskMetrics

Get comprehensive portfolio risk metrics and statistics.

Method: RiskService.GetRiskMetrics

Request:

message GetRiskMetricsRequest {
  optional string portfolio_id = 1;
}

Response:

message GetRiskMetricsResponse {
  RiskMetrics metrics = 1;
  int64 calculated_at = 2;
}

TLI Command: tli risk metrics

---

6. EmergencyStop

Trigger emergency stop to halt trading activities.

Method: RiskService.EmergencyStop

Request:

message EmergencyStopRequest {
  EmergencyStopType stop_type = 1;      // ALL_TRADING, SYMBOL, ACCOUNT, STRATEGY
  string reason = 2;
  optional string symbol = 3;
  optional string account_id = 4;
}

Response:

message EmergencyStopResponse {
  bool success = 1;
  string message = 2;
  int64 timestamp = 3;
  repeated string affected_orders = 4;
}

TLI Command: tli risk emergency-stop [--type <ALL|SYMBOL|ACCOUNT>] --reason <reason>

Required Permission: ADMIN only

---

Monitoring Service

Base Package: monitoring Backend Port: 50052 (co-located with Trading Service) Total Methods: 10

Health and Status Monitoring

1. GetSystemStatus

Get overall system status and individual service health.

Method: MonitoringService.GetSystemStatus

Request:

message GetSystemStatusRequest {
  repeated string service_names = 1;    // Empty for all services
}

Response:

message GetSystemStatusResponse {
  SystemStatus overall_status = 1;
  repeated ServiceStatus service_statuses = 2;
  int64 timestamp = 3;
}

TLI Command: tli monitor status [--services <services>]

---

2. StreamSystemStatus

Stream real-time system status changes.

Method: MonitoringService.StreamSystemStatus (Server Streaming)

Request:

message StreamSystemStatusRequest {
  repeated string service_names = 1;
  optional int32 update_frequency_seconds = 2;
}

Response Stream:

message SystemStatusEvent {
  SystemStatus system_status = 1;
  SystemStatusChangeType change_type = 2; // HEALTH_IMPROVED, HEALTH_DEGRADED, SERVICE_STARTED, etc.
  int64 timestamp = 3;
}

TLI Command: tli monitor stream --type status

---

3. GetHealthCheck

Perform detailed health checks on services.

Method: MonitoringService.GetHealthCheck

Request:

message GetHealthCheckRequest {
  optional string service_name = 1;
}

Response:

message GetHealthCheckResponse {
  HealthStatus health_status = 1;       // HEALTHY, DEGRADED, UNHEALTHY, CRITICAL
  repeated HealthCheck health_checks = 2;
  int64 timestamp = 3;
}

TLI Command: tli monitor health [--service <service>]

---

4. GetMetrics

Get system and application metrics.

Method: MonitoringService.GetMetrics

Request:

message GetMetricsRequest {
  repeated string metric_names = 1;
  optional int64 start_time = 2;
  optional int64 end_time = 3;
  optional MetricAggregation aggregation = 4; // SUM, AVG, MIN, MAX, COUNT
}

Response:

message GetMetricsResponse {
  repeated Metric metrics = 1;
  int64 timestamp = 2;
}

TLI Command: tli monitor metrics [--names <names>] [--start <time>] [--end <time>]

---

5. StreamMetrics

Stream real-time performance metrics.

Method: MonitoringService.StreamMetrics (Server Streaming)

Request:

message StreamMetricsRequest {
  repeated string metric_names = 1;
  optional int32 update_frequency_seconds = 2;
}

Response Stream:

message MetricsEvent {
  repeated Metric metrics = 1;
  int64 timestamp = 2;
}

TLI Command: tli monitor stream --type metrics --names <names>

---

6. GetLatencyMetrics

Get detailed latency performance metrics.

Method: MonitoringService.GetLatencyMetrics

Request:

message GetLatencyMetricsRequest {
  optional string service_name = 1;
  optional string operation_name = 2;
  optional int64 start_time = 3;
  optional int64 end_time = 4;
}

Response:

message GetLatencyMetricsResponse {
  repeated LatencyMetric latency_metrics = 1;
}

TLI Command: tli monitor latency [--service <service>] [--operation <op>]

Performance Benchmarks:

• Authentication: 4.4μs P99 (target: <10μs)
• Order Matching: 1-6μs P99 (target: <50μs)
• Order Submission: 15.96ms P99 (target: <100ms)
• API Gateway Proxy: 21-488μs (target: <1ms)

---

7. GetThroughputMetrics

Get throughput and capacity metrics.

Method: MonitoringService.GetThroughputMetrics

Request:

message GetThroughputMetricsRequest {
  optional string service_name = 1;
  optional string operation_name = 2;
  optional int64 start_time = 3;
  optional int64 end_time = 4;
}

Response:

message GetThroughputMetricsResponse {
  repeated ThroughputMetric throughput_metrics = 1;
}

TLI Command: tli monitor throughput [--service <service>]

---

8. StreamAlerts

Stream real-time system alerts and notifications.

Method: MonitoringService.StreamAlerts (Server Streaming)

Request:

message StreamAlertsRequest {
  optional AlertSeverity min_severity = 1; // INFO, WARNING, CRITICAL, EMERGENCY
  repeated string service_names = 2;
  repeated AlertType alert_types = 3;
}

Response Stream:

message AlertEvent {
  Alert alert = 1;
  AlertEventType event_type = 2;        // TRIGGERED, ACKNOWLEDGED, RESOLVED, ESCALATED
  int64 timestamp = 3;
}

TLI Command: tli monitor stream --type alerts [--severity <level>]

---

9. AcknowledgeAlert

Acknowledge an active alert.

Method: MonitoringService.AcknowledgeAlert

Request:

message AcknowledgeAlertRequest {
  string alert_id = 1;
  string acknowledged_by = 2;
  optional string note = 3;
}

Response:

message AcknowledgeAlertResponse {
  bool success = 1;
  string message = 2;
  int64 timestamp = 3;
}

TLI Command: tli monitor alert-ack --id <alert_id> --note <note>

---

10. GetActiveAlerts

Get all currently active alerts.

Method: MonitoringService.GetActiveAlerts

Request:

message GetActiveAlertsRequest {
  optional AlertSeverity min_severity = 1;
  repeated string service_names = 2;
}

Response:

message GetActiveAlertsResponse {
  repeated Alert active_alerts = 1;
  int32 total_count = 2;
}

TLI Command: tli monitor alerts [--severity <level>]

---

Configuration Service

Base Package: foxhunt.config Backend Port: 50052 (co-located with Trading Service) Total Methods: 4

1. GetConfig

Get a single configuration value.

Method: ConfigurationService.GetConfig

Request:

message GetConfigRequest {
  string service_scope = 1;
  string config_key = 2;
}

Response:

message GetConfigResponse {
  string config_value = 1;              // JSON-serialized value
  string data_type = 2;
  string description = 3;
  int64 updated_at = 4;                 // Unix timestamp
  string updated_by = 5;
}

TLI Command: tli config get --scope <service> --key <key>

---

2. UpdateConfig

Update a configuration value.

Method: ConfigurationService.UpdateConfig

Request:

message UpdateConfigRequest {
  string service_scope = 1;
  string config_key = 2;
  string new_value = 3;                 // JSON-serialized value
  string updated_by = 4;
}

Response:

message UpdateConfigResponse {
  bool success = 1;
  string message = 2;
}

TLI Command: tli config update --scope <service> --key <key> --value <value>

Required Permission: ADMIN only

---

3. ListConfigs

List all configurations for a service scope.

Method: ConfigurationService.ListConfigs

Request:

message ListConfigsRequest {
  optional string service_scope = 1;    // If not provided, lists all scopes
}

Response:

message ListConfigsResponse {
  repeated ConfigItem configs = 1;
}

TLI Command: tli config list [--scope <service>]

---

4. ReloadConfig

Trigger configuration reload.

Method: ConfigurationService.ReloadConfig

Request:

message ReloadConfigRequest {
  optional string service_scope = 1;
  optional string config_key = 2;
}

Response:

message ReloadConfigResponse {
  bool success = 1;
  string message = 2;
}

TLI Command: tli config reload [--scope <service>] [--key <key>]

---

TLI Command Reference

Complete mapping of TLI commands to gRPC methods.

Authentication Commands

TLI Command	gRPC Method	Description
tli auth login	N/A (HTTP/REST)	Login with username/password
tli auth verify-mfa	N/A (HTTP/REST)	Verify MFA code
tli auth logout	N/A	Clear stored JWT token
tli auth status	N/A	Check authentication status

Trading Commands

TLI Command	gRPC Method	Service
tli trade submit	TradingService.SubmitOrder	Trading
tli trade cancel	TradingService.CancelOrder	Trading
tli trade status	TradingService.GetOrderStatus	Trading
tli trade positions	TradingService.GetPositions	Trading
tli trade portfolio	TradingService.GetPortfolioSummary	Trading
tli trade history	TradingService.GetExecutionHistory	Trading
tli trade stream	TradingService.StreamOrders/StreamPositions/StreamExecutions	Trading

ML Trading Commands

TLI Command	gRPC Method	Service
tli trade ml submit	TradingService.SubmitMLOrder	Trading
tli trade ml predictions	TradingService.GetMLPredictions	Trading
tli trade ml performance	TradingService.GetMLPerformance	Trading

Trading Agent Commands

TLI Command	gRPC Method	Service
tli agent universe select	TradingAgentService.SelectUniverse	Trading Agent
tli agent universe show	TradingAgentService.GetUniverse	Trading Agent
tli agent universe update	TradingAgentService.UpdateUniverseCriteria	Trading Agent
tli agent assets select	TradingAgentService.SelectAssets	Trading Agent
tli agent assets show	TradingAgentService.GetSelectedAssets	Trading Agent
tli agent allocate	TradingAgentService.AllocatePortfolio	Trading Agent
tli agent allocate show	TradingAgentService.GetAllocation	Trading Agent
tli agent rebalance	TradingAgentService.RebalancePortfolio	Trading Agent
tli agent orders generate	TradingAgentService.GenerateOrders	Trading Agent
tli agent orders submit	TradingAgentService.SubmitAgentOrders	Trading Agent
tli agent strategy register	TradingAgentService.RegisterStrategy	Trading Agent
tli agent strategy list	TradingAgentService.ListStrategies	Trading Agent
tli agent strategy update	TradingAgentService.UpdateStrategyStatus	Trading Agent
tli agent status	TradingAgentService.GetAgentStatus	Trading Agent
tli agent performance	TradingAgentService.GetAgentPerformance	Trading Agent
tli agent stream	TradingAgentService.StreamAgentActivity	Trading Agent
tli agent health	TradingAgentService.HealthCheck	Trading Agent

ML Training Commands

TLI Command	gRPC Method	Service
tli ml train	MLTrainingService.StartTraining	ML Training
tli ml stop	MLTrainingService.StopTraining	ML Training
tli ml jobs	MLTrainingService.ListTrainingJobs	ML Training
tli ml job-details	MLTrainingService.GetTrainingJobDetails	ML Training
tli ml list-models	MLTrainingService.ListAvailableModels	ML Training

Hyperparameter Tuning Commands

TLI Command	gRPC Method	Service
tli tune start	MLTrainingService.StartTuningJob	ML Training
tli tune status	MLTrainingService.GetTuningJobStatus	ML Training
tli tune stop	MLTrainingService.StopTuningJob	ML Training
tli tune batch	MLTrainingService.BatchStartTuningJobs	ML Training
tli tune batch-status	MLTrainingService.GetBatchTuningStatus	ML Training

Backtesting Commands

TLI Command	gRPC Method	Service
tli backtest start	BacktestingService.StartBacktest	Backtesting
tli backtest status	BacktestingService.GetBacktestStatus	Backtesting
tli backtest results	BacktestingService.GetBacktestResults	Backtesting
tli backtest list	BacktestingService.ListBacktests	Backtesting
tli backtest stop	BacktestingService.StopBacktest	Backtesting

Risk Management Commands

TLI Command	gRPC Method	Service
tli risk var	RiskService.GetVaR	Risk
tli risk positions	RiskService.GetPositionRisk	Risk
tli risk validate	RiskService.ValidateOrder	Risk
tli risk metrics	RiskService.GetRiskMetrics	Risk
tli risk emergency-stop	RiskService.EmergencyStop	Risk
tli risk stream	RiskService.StreamVaRUpdates	Risk

Monitoring Commands

TLI Command	gRPC Method	Service
tli monitor status	MonitoringService.GetSystemStatus	Monitoring
tli monitor health	MonitoringService.GetHealthCheck	Monitoring
tli monitor metrics	MonitoringService.GetMetrics	Monitoring
tli monitor latency	MonitoringService.GetLatencyMetrics	Monitoring
tli monitor throughput	MonitoringService.GetThroughputMetrics	Monitoring
tli monitor alerts	MonitoringService.GetActiveAlerts	Monitoring
tli monitor alert-ack	MonitoringService.AcknowledgeAlert	Monitoring
tli monitor stream	MonitoringService.StreamMetrics/StreamAlerts/StreamSystemStatus	Monitoring

Configuration Commands

TLI Command	gRPC Method	Service
tli config get	ConfigurationService.GetConfig	Configuration
tli config update	ConfigurationService.UpdateConfig	Configuration
tli config list	ConfigurationService.ListConfigs	Configuration
tli config reload	ConfigurationService.ReloadConfig	Configuration

Market Data Commands

TLI Command	gRPC Method	Service
tli market stream	TradingService.StreamMarketData	Trading
tli market book	TradingService.GetOrderBook	Trading

---

Common Data Types

Order Enums

enum OrderSide {
  ORDER_SIDE_UNSPECIFIED = 0;
  ORDER_SIDE_BUY = 1;
  ORDER_SIDE_SELL = 2;
}

enum OrderType {
  ORDER_TYPE_UNSPECIFIED = 0;
  ORDER_TYPE_MARKET = 1;
  ORDER_TYPE_LIMIT = 2;
  ORDER_TYPE_STOP = 3;
  ORDER_TYPE_STOP_LIMIT = 4;
}

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;
  ORDER_STATUS_PENDING = 1;
  ORDER_STATUS_SUBMITTED = 2;
  ORDER_STATUS_PARTIALLY_FILLED = 3;
  ORDER_STATUS_FILLED = 4;
  ORDER_STATUS_CANCELLED = 5;
  ORDER_STATUS_REJECTED = 6;
}

Position Data

message Position {
  string symbol = 1;
  double quantity = 2;                  // Positive = long, negative = short
  double average_price = 3;
  double market_value = 4;
  double unrealized_pnl = 5;
  double realized_pnl = 6;
  string account_id = 7;
  int64 updated_at = 8;
}

Order Data

message Order {
  string order_id = 1;
  string symbol = 2;
  OrderSide side = 3;
  double quantity = 4;
  double filled_quantity = 5;
  OrderType order_type = 6;
  optional double price = 7;
  optional double stop_price = 8;
  OrderStatus status = 9;
  int64 created_at = 10;
  optional int64 updated_at = 11;
  string account_id = 12;
  map<string, string> metadata = 13;
}

Risk Data

enum RiskLevel {
  RISK_LEVEL_UNSPECIFIED = 0;
  RISK_LEVEL_LOW = 1;
  RISK_LEVEL_MEDIUM = 2;
  RISK_LEVEL_HIGH = 3;
  RISK_LEVEL_CRITICAL = 4;
}

enum VaRMethod {
  VAR_METHOD_UNSPECIFIED = 0;
  VAR_METHOD_HISTORICAL = 1;
  VAR_METHOD_PARAMETRIC = 2;
  VAR_METHOD_MONTE_CARLO = 3;
}

Training Job Status

enum TrainingStatus {
  UNKNOWN = 0;
  PENDING = 1;
  RUNNING = 2;
  COMPLETED = 3;
  FAILED = 4;
  STOPPED = 5;
  PAUSED = 6;
}

enum TuningJobStatus {
  TUNING_UNKNOWN = 0;
  TUNING_PENDING = 1;
  TUNING_RUNNING = 2;
  TUNING_COMPLETED = 3;
  TUNING_FAILED = 4;
  TUNING_STOPPED = 5;
}

---

Method Count Summary

Service	Methods	Port
Trading Service	15 (12 core + 3 ML)	50052
Trading Agent Service	18	50055
ML Training Service	12	50054
Backtesting Service	6	50053
Risk Management Service	6	50052
Monitoring Service	10	50052
Configuration Service	4	50052
Total	71	-

Note: The CLAUDE.md document mentions 37 methods, which refers to the user-facing methods accessible via API Gateway. The actual proto definitions include 71 total gRPC methods across all services (including internal/admin methods).

API Gateway Exposed Methods: 37 (subset of 71 total, excluding internal/admin methods)

---

Appendix: Performance Benchmarks

Latency Targets

Operation	P99 Latency	Target	Status
Authentication	4.4μs	<10μs	✅ Met
Order Matching	1-6μs	<50μs	✅ Met
Order Submission	15.96ms	<100ms	✅ Met
API Gateway Proxy	21-488μs	<1ms	✅ Met
DBN Data Loading	0.70ms	<10ms	✅ Met (14x faster)
ML Inference (DQN)	~200μs	<1ms	✅ Met
ML Inference (MAMBA-2)	~500μs	<1ms	✅ Met
Universe Selection	<1s	<1s	✅ Met
Asset Selection	<2s	<2s	✅ Met
Portfolio Allocation	<500ms	<500ms	✅ Met

Throughput

Operation	Throughput	Target	Status
PostgreSQL Inserts	2,979/sec	660/sec	✅ Met (4.5x)
API Gateway Requests	100/sec	100/sec	✅ Met
Market Data Streams	10 streams	10 streams	✅ Met

---

References

• Proto Files: /services/{service}/proto/*.proto
• TLI Commands: /tli/src/commands/*.rs
• API Gateway: /services/api_gateway/src/main.rs
• CLAUDE.md: System architecture and current status

Last Updated: 2025-10-16 Maintained By: Foxhunt Development Team