tektii.comGo to App

Trading API Concepts

The Trading API defines a unified protocol for building trading strategies. Your strategy connects to the self-hosted Trading Gateway, which presents the same REST + WebSocket interface whether you are backtesting, paper trading, or trading live.

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 Gateway mode it connects to:

  • Backtest mode — Simulated trading against historical data
  • Paper trading — Simulated orders against live market data
  • Live trading — Real orders executed on a trading provider

This means you can develop and test your strategy locally, validate it against historical data, and promote it to live markets — without changing a single line of code.

Provider Abstraction

The Trading Gateway normalizes differences between trading providers. Whichever broker you're connecting to through the Gateway, your strategy sees the same:

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

The Gateway handles all provider-specific translations, authentication, and quirks.

Execution Modes

The Trading API supports three execution modes. Your strategy code does not change between modes. For paper and live trading you select a mode by how you start the Gateway — specifically the GATEWAY_PROVIDER and GATEWAY_MODE environment variables. Backtests run on the Tektii platform and are not something you launch yourself.

Backtest Mode

Simulated trading against historical market data. Backtests run on the Tektii platform — you do not start the Gateway yourself. The platform controls time progression, and your strategy acknowledges each batch of events before time advances, which makes runs deterministic and reproducible.

Paper Trading Mode

Real market data with simulated order execution. Run the Gateway with a broker provider (e.g. GATEWAY_PROVIDER=alpaca) and GATEWAY_MODE=paper (the default) to validate your strategy against current market conditions without risking capital.

Live Trading Mode

Real orders on real markets. Run the Gateway with a broker provider and GATEWAY_MODE=live. The protocol behaves identically to paper mode, but executions affect real positions and balances.

See Supported Brokers in the Trading Gateway README for the full provider matrix and required credentials.

Platform Identifiers

TradingPlatform is a string emitted by the Gateway on subscription entries and on some response fields (for example, Bar.provider, Quote.provider, and the broker field on connection events). Your strategy does not set it — it is metadata that tells you which upstream broker/market a given event came from.

Canonical values (from the Trading Gateway OpenAPI spec):

  • alpaca-live, alpaca-paper
  • binance-spot-live, binance-spot-testnet
  • binance-futures-live, binance-futures-testnet
  • binance-margin-live, binance-margin-testnet
  • binance-coin-futures-live, binance-coin-futures-testnet
  • oanda-live, oanda-practice
  • saxo-live, saxo-sim
  • mock — in-memory mock provider used for development

The Gateway's openapi.json is the source of truth; treat the list above as the current set rather than a closed enum.

Connection Model

Your strategy communicates with the 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 ────│  Trading Gateway │
│   (Client)   │        Events        │     (Server)     │
│              │                      │                  │
│              │─────── REST API ────►│                  │
│              │       Orders         │                  │
└──────────────┘                      └──────────────────┘
  1. Strategy connects to the Gateway via WebSocket
  2. Gateway streams market events to the strategy
  3. Strategy acknowledges events (required for backtest mode)
  4. Strategy submits orders via REST API
  5. Gateway executes orders and streams results via WebSocket

Next Steps