Connection Guide

This guide explains how to establish a connection between your strategy and the Trading API proxy, configure market data subscriptions, and handle the event stream.

Proxy Endpoints

Your strategy connects to two endpoints on the proxy:

In production, these endpoints are provided via environment variables or configuration.

Host and Port Configuration

Configure your strategy using environment variables:

PROXY_WS_URL=ws://proxy.example.com:8082
PROXY_REST_URL=http://proxy.example.com:8080

Or use default localhost ports for local development.

Authentication

Authentication is handled at the proxy level, not in your strategy. The proxy authenticates with the trading provider using credentials configured at startup.

Your strategy connects to the proxy without additional auth headers. In production deployments, network-level security (VPC, service mesh) protects the proxy endpoints.

Establishing a Connection

WebSocket Handshake

1. Open a WebSocket connection to the proxy
2. Wait for the CONNECTED connection event
3. Begin receiving market data events

import websockets
import json

async def connect():
    async with websockets.connect("ws://localhost:8082") as ws:
        # Wait for connection confirmation
        msg = await ws.recv()
        event = json.loads(msg)

        if event["type"] == "connection" and event["event"] == "CONNECTED":
            print("Connected to proxy")

        # Start receiving events
        async for message in ws:
            handle_event(json.loads(message))

Connection Events

The proxy sends connection status events:

Event Subscription

Configuring Subscriptions

Event subscriptions are configured via environment variables when starting your strategy container, not via WebSocket messages.

# Subscribe to specific symbols and data types
SUBSCRIPTIONS=S:AAPL:candle,S:AAPL:quote,C:BTCUSD:candle

Subscription format: {symbol}:{event_type}

Symbol Format

Symbols include an asset class prefix:

• S:AAPL - Stock (Apple)
• C:BTCUSD - Crypto (Bitcoin/USD)

Example Subscriptions

# Single instrument
SUBSCRIPTIONS=S:AAPL:candle

# Multiple instruments
SUBSCRIPTIONS=S:AAPL:candle,S:MSFT:candle,S:GOOGL:candle

# Multiple event types per instrument
SUBSCRIPTIONS=S:AAPL:candle,S:AAPL:quote

Handling Events

Message Format

All WebSocket messages use JSON with a "type" field for routing:

{"type": "candle", "bar": {...}, "timestamp": "2025-01-01T00:00:00Z"}
{"type": "quote", "quote": {...}, "timestamp": "2025-01-01T00:00:00Z"}
{"type": "order", "event": "ORDER_FILLED", "order": {...}}
{"type": "ping", "timestamp": "2025-01-01T00:00:00Z"}

Event Types

Ping/Pong Heartbeat

The proxy sends periodic ping messages. Respond with pong to maintain the connection:

// Server sends
{"type": "ping", "timestamp": "2025-01-01T00:00:00Z"}

// Client responds
{"type": "pong"}

Event Acknowledgment

Backtest Mode (Required)

In backtest mode, time simulation is controlled by your strategy. After processing a batch of events, send an acknowledgment to advance time:

{
  "type": "event_ack",
  "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
  "events_processed": ["evt_123", "evt_124"],
  "timestamp": 1700000000000
}

Without acknowledgments, the backtest engine will not advance time.

Live Mode (Optional)

In live trading, acknowledgments are informational only. The market continues regardless of whether you acknowledge events. However, sending them helps with debugging and monitoring.

Error Handling

The proxy sends error events when problems occur:

{
  "type": "error",
  "code": "INVALID_ORDER",
  "message": "Insufficient buying power",
  "timestamp": "2025-01-01T00:00:00Z"
}

Handle errors gracefully and implement reconnection logic for connection failures.

Next Steps

• Review the Concepts documentation for an overview of the unified interface