Trading API Concepts

The Trading API defines a unified protocol for building trading strategies. Your strategy code works identically whether running on the Tektii Engine (backtesting) or the Trading Gateway (paper and live trading).

Unified Protocol

The core principle of the Trading API is write once, run anywhere. Your strategy code interacts with a single, consistent protocol regardless of which runtime it connects to:

Backtest mode — Simulated trading against historical data, powered by the Tektii Engine
Paper trading — Simulated orders against live market data, via the Trading Gateway
Live trading — Real orders executed on a trading provider, via the Trading Gateway

This means you can develop and test your strategy locally, validate it against historical data, and deploy it to the Trading Gateway — without changing a single line of code.

Provider Abstraction

The Trading Gateway normalizes differences between trading providers. Whether you're connecting to Alpaca or Binance through the Gateway, your strategy sees the same:

Order types and lifecycle events
Position representations
Account balances and margin calculations
Market data formats

The runtime (Engine or Gateway) handles all provider-specific translations, authentication, and quirks.

Execution Modes

The Trading API supports five execution modes via the TradingPlatform identifier:

Platform	Mode	Runtime	Description
`backtest`	Simulation	Tektii Engine	Run against historical market data with time-controlled simulation
`alpaca-paper`	Paper	Trading Gateway	Simulated orders against live Alpaca market data
`alpaca-live`	Live	Trading Gateway	Real orders on Alpaca
`binance-testnet`	Paper	Trading Gateway	Simulated orders against Binance testnet
`binance-live`	Live	Trading Gateway	Real orders on Binance

Backtest Mode (Tektii Engine)

In backtest mode, the Tektii Engine controls time progression. Your strategy receives historical market events and must acknowledge each batch before time advances. This ensures deterministic, reproducible results.

Paper Trading Mode (Trading Gateway)

Paper trading uses real market data but simulates order execution. Run via the Trading Gateway, this lets you validate your strategy against current market conditions without risking capital.

Live Trading Mode (Trading Gateway)

In live mode, orders are submitted to real exchanges via the Trading Gateway. The protocol behaves identically to paper mode, but executions affect real positions and balances.

Connection Model

Your strategy communicates with the runtime (Engine or Gateway) using two complementary channels:

WebSocket - Event Stream

The WebSocket connection delivers real-time events to your strategy:

Market data - Candles (OHLCV bars), quotes (bid/ask)
Order events - Created, filled, cancelled, rejected
Position events - Opened, modified, closed
Account events - Balance updates, margin warnings
Connection events - Connected, disconnecting, reconnecting

Events flow from server to client. Your strategy responds by acknowledging events and submitting orders.

REST API - Order Management

The REST API handles stateful operations:

Submit new orders
Modify existing orders
Cancel orders
Query positions
Get account information

This separation allows high-frequency event streaming without blocking on order operations.

Communication Flow

┌──────────────┐                      ┌──────────────────┐
│   Strategy   │◄────── WebSocket ────│  Engine/Gateway   │
│   (Client)   │        Events        │     (Server)      │
│              │                      │                   │
│              │─────── REST API ────►│                   │
│              │       Orders         │                   │
└──────────────┘                      └──────────────────┘

Strategy connects to the Engine or Gateway via WebSocket
Server streams market events to strategy
Strategy acknowledges events (required for backtest mode)
Strategy submits orders via REST API
Server executes orders and streams results via WebSocket

Next Steps

Connection Guide - Connect your strategy to the Engine or Gateway
Trading Gateway Overview - Set up the open-source Gateway for paper and live trading
Trading Gateway Setup - Feature-gated builds, verification, and monitoring
Going Live - Deploy your backtested strategy to live markets