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:

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

## Client to Server Messages

### Get Active Strategies

Request information about all active strategies.

```json
{
  "type": "get_active_strategies"
}
```

### Start Strategy

Start a specific strategy.

```json
{
  "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.

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

### Pause Strategy

Pause a running strategy.

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

## Server to Client Messages

### Strategy Status List

Response to `get_active_strategies` request.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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:

```typescript
// 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:

```typescript
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.