Connection Guide

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

Connection Endpoints

The gateway exposes both WebSocket and REST over a single HTTP port. Your strategy uses the WebSocket channel for the event stream and the REST API for requests such as placing orders or reading account state.

Every REST endpoint is prefixed with /v1/. The only exceptions are the unversioned health and metrics endpoints (/health, /livez, /readyz, /metrics). In production, these URLs are supplied to your strategy via environment variables or configuration.

Host and Port Configuration

Point your strategy at a remote gateway via the GATEWAY_URL environment variable:

GATEWAY_URL=http://gateway.example.com:8080

Or use the localhost default for local development.

Authentication

When the gateway is started with the GATEWAY_API_KEY environment variable set (minimum 32 characters), every REST and WebSocket request must carry the key in one of two headers. If both are present, Authorization wins precedence.

The same headers are sent on the WebSocket upgrade request — there is no separate WebSocket auth handshake or first-message auth.

When GATEWAY_API_KEY is not set, the gateway runs without authentication and logs a warning at startup. Anyone with network access to the port can place, modify, and cancel orders. Do not deploy this way outside a trusted local environment.

Public endpoints — always unauthenticated: /health, /livez, /readyz, /metrics. Every /v1/* path requires the key when GATEWAY_API_KEY is set.

import websockets

headers = {"Authorization": f"Bearer {api_key}"}
async with websockets.connect("ws://localhost:8080/v1/ws", extra_headers=headers) as ws:
    ...

Note: this is gateway auth. The Tektii CLI, which talks to the Tektii management API at api.tektii.com, uses a separate TEKTII_API_KEY — see CLI Authentication Setup.

Establishing a Connection

WebSocket Handshake

1. Open a WebSocket connection to the gateway
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:8080/v1/ws") 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 server")

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

Connection Events

The server sends connection status events:

Event Subscription

Configuring Subscriptions

Subscriptions are configured on the gateway at startup via the SUBSCRIPTIONS environment variable, not via WebSocket messages. The value is a JSON array; each entry names a broker platform, an instrument, and the events to stream for it.

SUBSCRIPTIONS='[
  {"platform": "alpaca-paper", "instrument": "AAPL", "events": ["quote"]},
  {"platform": "alpaca-paper", "instrument": "MSFT", "events": ["quote", "candle_1m"]}
]'

Each entry has three required fields:

Event Names

The following event names are valid in the events array:

Platform Values

platform identifies the upstream broker + mode. Valid values include alpaca-paper, alpaca-live, binance-spot-testnet, binance-spot-live, binance-futures-testnet, binance-futures-live, binance-margin-testnet, binance-margin-live, binance-coin-futures-testnet, binance-coin-futures-live, oanda-practice, oanda-live, saxo-sim, saxo-live, and mock. See the gateway README's "Supported Brokers" section for the canonical list as providers are added.

instrument strings are passed through to the broker verbatim — use the ticker, contract, or pair the broker itself expects (for example AAPL on Alpaca, BTCUSDT on Binance). There is no Tektii-internal prefix scheme.

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 server 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.

Trading Gateway Mode (Optional)

When using the Trading Gateway (paper or live mode), acknowledgments are informational only. The market continues regardless of whether you acknowledge events. However, sending them helps with debugging and monitoring.

Error Handling

The server 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