Optra

Options trading and analytics, in C++23.

One event-driven engine for backtesting and live trading on Interactive Brokers, research tools on the same data, and one API an AI agent can drive.

Live demo · Architecture · Documentation · 中文

Optra architecture: the control plane, the cut at gRPC, the engine and its ports, the adapters and the numerics

What is in it


Engine	Strategies take events (timer, snapshot, order, fill) and emit orders; the same code runs a deterministic backtest over Parquet days and trades live through IB, in one process with a single writer thread. Multi-leg combos, implied vol and Greeks on each expiry's parity forward, settlement at expiry, per-strategy delta hedging, a pre-trade risk check, P&L attribution by Greeks.
Research tools	Pricing (Black-Scholes, Monte Carlo, trees, PDE, Heston), calibration, stress packs, hedging studies and an options screener, on the engine's own numerics and its backtest and recorded days.
Research loop	A combo picked in the screener is backtested as a rule over every day, broken down by Greek, compared hedged and unhedged, and added to the paper account with the setting it was tested with.
Agent tools	Every capability is a declared tool with a described input schema and one result envelope, over HTTP and from Python; every run is kept for comparison. No tool places an order.

The screener ranking option strategies by edge against a model volatility

Quick start

Linux, GCC 14 or newer (Ubuntu 26.04 is the reference):

sudo apt install g++ cmake make libarrow-dev libparquet-dev libprotobuf-dev protobuf-compiler libgrpc++-dev \
  protobuf-compiler-grpc libabsl-dev nlohmann-json3-dev libsqlite3-dev libgtest-dev 7zip

./build.sh r                     # engine/build: entry_backtest, entry_live, entry_simulate, libanalytics_c.so

# synthetic days from a model whose answers are known (no data ships with the repository)
uv run --project app/server python scripts/data/synthetic_to_parquet.py \
  --start 2025-03-03 --end 2025-03-07 --out data --symbol SPY

# a straddle each day, with its P&L split by delta, gamma, theta, vega
./engine/build/entry_backtest --files data/SPY/SPY-2025-03/*.parquet ComboStrategy \
  leg1_ratio=1 leg2_ratio=1 leg2_right=1

./scripts/dev.sh                 # the server and the page at http://localhost:5173

entry_backtest --list-strategies lists the strategies and their parameters. A backtest needs no network and no database.

How it works

In the diagram at the top: above the cut at gRPC, the control plane (the page and the server) only asks; below it, the engine owns the trading state and reaches the outside through adapters plugged into its ports (market data, venue, storage); the numerics are one library for the engine and the server's research tools. Booking is deterministic: a fill is one contract's, order updates are merged and an order's end waits for its fills, so the holding never depends on the order the broker reports in. A restart rebooks every saved fill and checks the holdings against the broker before any strategy starts. The full design: architecture, and the interactive diagram (click a box for what it does).

Live trading

Optra runs every trading day on an IBKR paper account: contracts synced before the open, a health check every five minutes, and a report after the close that replays the recorded day in a backtest and lines the paper fills up against it. The engine trades one named account and refuses a live one unless root allows it. The live demo runs the same engine on a simulated account (entry_simulate: synthetic days replayed as the market, no broker). What IB sends for each order and how it is booked: IB orders and fills.

For AI agents

Every tool, the engine's included (backtest_combo, hedge_study, backtest_report, holdings_stress), is plain HTTP on the server: its own route, and POST /api/tools/<name> (GET /api/tools lists them with their schemas). Inputs are validated against described schemas, and every run can be listed, rerun and compared: agent toolkit.

Documentation

How Optra fits together: the three programs, why they are split, a quote's path through the engine, from an idea to the paper account
The engine: events and booking, the live process and its threads, restarts and expiry, backtests, what IB sends back, speed, building and testing
The server and the page: what the server does, the page's views, running it day to day
Research: the research views, the methods, market data, tools for agents
Backtest data: the format, converting Databento downloads, replaying paper days, synthetic days
For coding agents: AGENTS.md

Project status

About 13,000 lines of core C++, 154 GoogleTest cases (concurrency, shutdown and IB paper-account integration among them), ASan and TSan runs, and a P&L regression of the example strategies on every change. Paper trading only; the next steps are multi-day backtests, stocks and lower latency. python-mvp keeps the original hand-written Python implementation the C++ system grew out of.

License

For learning and portfolio use (LICENSE). No commercial use, redistribution or production integration without written permission. Trading carries substantial risk; connecting a live account is at your own risk.

optra