stock-bot/docs/websocket-api.md

WebSocket API Documentation - Strategy Orchestrator

Overview

This document outlines the WebSocket API provided by the Strategy Orchestrator service for real-time communication between the backend and frontend.

Connection Endpoints

• Strategy Orchestrator WebSocket: ws://localhost:8082
• Market Data Gateway WebSocket: ws://localhost:3001/ws
• Risk Guardian WebSocket: ws://localhost:3002/ws

Message Format

All WebSocket messages follow this standard format:

{
  "type": "message_type",
  "timestamp": "ISO-8601 timestamp",
  "data": {
    // Message-specific data
  }
}

Client to Server Messages

Get Active Strategies

Request information about all active strategies.

{
  "type": "get_active_strategies"
}

Start Strategy

Start a specific strategy.

{
  "type": "start_strategy",
  "id": "strategy-id",
  "config": {
    "symbols": ["AAPL", "MSFT"],
    "dataResolution": "1m",
    "realTrading": false,
    "maxPositionValue": 10000,
    "maxOrdersPerMinute": 5,
    "stopLossPercentage": 0.02
  }
}

Stop Strategy

Stop a running strategy.

{
  "type": "stop_strategy",
  "id": "strategy-id"
}

Pause Strategy

Pause a running strategy.

{
  "type": "pause_strategy",
  "id": "strategy-id"
}

Server to Client Messages

Strategy Status List

Response to get_active_strategies request.

{
  "type": "strategy_status_list",
  "timestamp": "2023-07-10T12:34:56Z",
  "data": [
    {
      "id": "strategy-123",
      "name": "Moving Average Crossover",
      "status": "ACTIVE",
      "symbols": ["AAPL", "MSFT"],
      "positions": [
        {
          "symbol": "AAPL",
          "quantity": 10,
          "entryPrice": 150.25,
          "currentValue": 1550.50
        }
      ]
    }
  ]
}

Strategy Started

Notification that a strategy has been started.

{
  "type": "strategy_started",
  "timestamp": "2023-07-10T12:34:56Z",
  "data": {
    "strategyId": "strategy-123",
    "name": "Moving Average Crossover",
    "symbols": ["AAPL", "MSFT"]
  }
}

Strategy Stopped

Notification that a strategy has been stopped.

{
  "type": "strategy_stopped",
  "timestamp": "2023-07-10T12:34:56Z",
  "data": {
    "strategyId": "strategy-123",
    "name": "Moving Average Crossover"
  }
}

Strategy Paused

Notification that a strategy has been paused.

{
  "type": "strategy_paused",
  "timestamp": "2023-07-10T12:34:56Z",
  "data": {
    "strategyId": "strategy-123",
    "name": "Moving Average Crossover"
  }
}

Strategy Signal

Trading signal generated by a strategy.

{
  "type": "strategy_signal",
  "timestamp": "2023-07-10T12:34:56Z",
  "data": {
    "id": "sig_123456789",
    "strategyId": "strategy-123",
    "name": "Moving Average Crossover",
    "symbol": "AAPL",
    "price": 152.75,
    "action": "BUY",
    "quantity": 10,
    "metadata": { "orderType": "MARKET" },
    "timestamp": "2023-07-10T12:34:56Z",
    "confidence": 0.9
  }
}

Strategy Trade

Notification of a trade executed by a strategy.

{
  "type": "strategy_trade",
  "timestamp": "2023-07-10T12:34:56Z",
  "data": {
    "id": "trade_123456789",
    "strategyId": "strategy-123",
    "orderId": "order-123",
    "symbol": "AAPL",
    "side": "BUY",
    "quantity": 10,
    "entryPrice": 152.75,
    "entryTime": "2023-07-10T12:34:56Z",
    "status": "FILLED",
    "timestamp": "2023-07-10T12:34:56Z"
  }
}

Execution Service Status

Notification about the overall execution service status.

{
  "type": "execution_service_status",
  "timestamp": "2023-07-10T12:34:56Z",
  "data": {
    "status": "RUNNING" // or "STOPPED"
  }
}

Frontend Integration

The frontend can use the WebSocketService to interact with the WebSocket API:

// Subscribe to strategy signals
webSocketService.getStrategySignals(strategyId)
  .subscribe(signal => {
    // Handle the signal
  });

// Subscribe to strategy trades
webSocketService.getStrategyTrades(strategyId)
  .subscribe(trade => {
    // Handle the trade
  });

// Subscribe to strategy status updates
webSocketService.getStrategyUpdates()
  .subscribe(update => {
    // Handle the update
  });

Error Handling

WebSocket connections will automatically attempt to reconnect if disconnected. The frontend can monitor connection status using:

webSocketService.isConnected() // Returns a boolean signal indicating connection status

If a WebSocket message fails to process, the error will be logged, but the connection will be maintained.