Interactive Brokers (REST) Backtesting

LumiBot supports backtesting with Interactive Brokers Client Portal (REST).

The primary data path uses Client Portal (REST) via the LumiBot Data Downloader (it does not require the legacy TWS API for bar history).

For expired futures contract discovery (conids), IBKR Client Portal cannot reliably discover old contracts. In that case, LumiBot relies on an offline conid registry (populated via a one-time TWS backfill in internal deployments).

Status

IBKR REST backtesting is under active development and is not yet a fully-supported public workflow in the open-source distribution.

If you want early access or have a specific use case, please open an issue (or contact the maintainers) so we can prioritize it.

Quick Start

Select IBKR as the backtesting data source:

export BACKTESTING_DATA_SOURCE="ibkr"

Supported Data

  • Futures: US futures across CME/CBOT/COMEX/NYMEX via IBKR historical endpoints (1-minute+ bars).

  • Spot crypto: IBKR crypto bars (availability depends on region and IBKR product support).

Futures Exchange Routing (auto + override)

For futures and continuous futures (asset_type="future" / asset_type="cont_future"), LumiBot supports an optional exchange=... parameter on the Strategy data methods:

  • get_historical_prices(..., exchange=...)

  • get_last_price(..., exchange=...)

  • get_quote(..., exchange=...)

When exchange is omitted, LumiBot attempts to resolve the correct futures exchange automatically via IBKR secdef search (preferring USD + US venues). If results are ambiguous, you must pass exchange=... explicitly.

Expired Futures Contracts (conids)

IBKR futures history requires a contract identifier (conid). IBKR Client Portal cannot reliably discover conid values for expired futures contracts, which makes explicit-contract backtests fail unless the mapping is already known.

LumiBot supports an offline conid registry (cache-backed, optionally S3-mirrored):

  • LUMIBOT_CACHE_FOLDER/ibkr/conids.json

The registry is expected to grow automatically over time for new contracts as backtests run (using IBKR REST endpoints). Very old expired contracts may still require a one-time offline backfill in internal deployments.

Internal runbook (engineering): docs/investigations/2026-01-18_IBKR_EXPIRED_FUTURES_CONID_BACKFILL.md.

Caching

IBKR backtests cache historical bars as Parquet:

  • Local: LUMIBOT_CACHE_FOLDER/ibkr/...

  • Optional S3 mirroring: configured via the standard LUMIBOT_CACHE_* variables (see Environment Variables).

Multi-provider routing (Theta + IBKR)

To use multiple providers in a single backtest (example: ThetaData for options/stocks/indexes and IBKR for futures/crypto), set a JSON mapping in BACKTESTING_DATA_SOURCE:

export BACKTESTING_DATA_SOURCE='{"default":"thetadata","stock":"thetadata","option":"thetadata","index":"thetadata","future":"ibkr","crypto":"ibkr"}'

Routing values are case/whitespace/_/- insensitive. For crypto, you may also route to CCXT by using either "ccxt" (auto-select exchange) or a CCXT exchange id directly (for example: "coinbase" or "kraken").

Market Data Subscriptions (IBKR)

IBKR requires appropriate market data entitlements to access market data via the API. IBKR notes that historical bars are part of Level 1 entitlements and that crypto does not require additional market data subscriptions:

For CME futures (ES/MES/NQ/MNQ), note that the cheap CME S&P Indices subscription is for index data, not futures contracts. Professional subscriber pricing and package availability can differ, so confirm your exact costs in the IBKR Market Data Subscriptions page and pricing table:

Authentication / Session Behavior

The Client Portal Gateway is session-based; if the session becomes unauthenticated, the gateway must be re-authenticated. IBKR documents the expected authentication lifecycle and recommends using /iserver/auth/ssodh/init to re-authenticate in most scenarios:

Configuration Notes

Common environment variables for IBKR REST backtesting:

  • IBKR_HISTORY_SOURCE (default: Trades)

  • IBKR_FUTURES_EXCHANGE (default: CME; fallback when auto-routing fails)

  • IBKR_CRYPTO_VENUE (default: ZEROHASH)

  • LUMIBOT_IBKR_ENABLE_FUTURES_BID_ASK (default: disabled; opt-in quote derivation for futures)

See Environment Variables for details.