Skip to main content

​
WebSocket API

Tracera provides real-time price and volatility updates over a persistent WebSocket connection.
The WebSocket endpoint is part of the upcoming platform features. The API contract below is finalized and the hub architecture is designed. See the Roadmap for implementation timeline.
For details on the real-time delivery architecture, see Data Flow and Real-Time Features.

​
Connection

​
GET /api/v1/ws

Establish a WebSocket connection for live updates. 
const ws = new WebSocket('ws://localhost:8080/api/v1/ws');

ws.onopen = () => {
  console.log('Connected to Tracera');
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Update:', data);
};

​
Origin Validation

WebSocket upgrade requests are validated against the configured BASE_URL origin. In development, loopback origins (localhost, 127.0.0.1) are also accepted.

​
Subscribing to Items

After connecting, send a subscription message to receive updates for specific items: 
{
  "action": "subscribe",
  "item_ids": [1, 42, 100]
}

​
Subscription Limits

  • Item IDs are bounded to a maximum count per client
  • IDs are deduplicated — sending the same ID twice has no effect
  • Only positive integers are accepted — invalid IDs are filtered out

​
Message Types

​
Price Update

Received when a tracked item’s price changes: 
{
  "type": "price",
  "item_id": 42,
  "price": 1450000,
  "volume": 12,
  "source": "steam",
  "timestamp": "2025-01-15T10:05:00Z"
}

​
Volatility Update

Received when volatility metrics are recomputed: 
{
  "type": "volatility",
  "item_id": 42,
  "rolling_stddev": 45.2,
  "percent_change": 8.5,
  "trend_score": 1.2,
  "timestamp": "2025-01-15T10:05:00Z"
}

​
Architecture

                     ┌─────────────┐
                     │  Redis      │
                     │  Pub/Sub    │
                     └──────┬──────┘
                            │
                            ▼
                     ┌─────────────┐
                     │  WebSocket  │
                     │    Hub      │
                     └──────┬──────┘
                            │
              ┌─────────────┼─────────────┐
              ▼             ▼             ▼
         ┌────────┐   ┌────────┐   ┌────────┐
         │Client 1│   │Client 2│   │Client 3│
         └────────┘   └────────┘   └────────┘
The WebSocket hub:
  1. Subscribes to Redis Pub/Sub channels for price and volatility updates
  2. Maintains a registry of connected clients and their subscriptions
  3. Fans out updates to only the clients subscribed to the relevant item IDs
  4. Handles client disconnections and subscription changes
Each client connection runs in its own goroutine with a dedicated read pump and write pump for non-blocking I/O.