Trading API Concepts

The Trading API provides a unified interface for building trading strategies that work identically across backtest simulations and live trading environments.

Unified Interface

The core principle of the Trading API is write once, run anywhere. Your strategy code interacts with a single, consistent API regardless of whether it's running in:

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

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

Provider Abstraction

Under the hood, the Trading API normalizes differences between trading providers. Whether you're trading on Alpaca or Binance, your strategy sees the same:

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

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

Execution Modes

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

Backtest Mode

In backtest mode, the 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

Paper trading uses real market data but simulates order execution. This lets you validate your strategy against current market conditions without risking capital.

Live Trading Mode

In live mode, orders are submitted to real exchanges. The API behaves identically to paper mode, but executions affect real positions and balances.

Connection Model

Your strategy communicates with the platform 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 ────│    Proxy     │
│   (Client)   │        Events        │   (Server)   │
│              │                      │              │
│              │─────── REST API ────►│              │
│              │       Orders         │              │
└──────────────┘                      └──────────────┘

1. Strategy connects to proxy via WebSocket
2. Proxy streams market events to strategy
3. Strategy acknowledges events (required for backtest)
4. Strategy submits orders via REST API
5. Proxy executes orders and streams results via WebSocket

Next Steps

• Connection Guide - Connect your strategy to the proxy