Interactive Brokers

Interactive Brokers (IB) is a trading platform providing market access across a wide range of financial instruments, including stocks, options, futures, currencies, bonds, funds, and cryptocurrencies. NautilusTrader offers an adapter to integrate with IB using their Trader Workstation (TWS) API through their Python library, ibapi.

The TWS API serves as an interface to IB's standalone trading applications: TWS and IB Gateway. Both can be downloaded from the IB website. If you haven't installed TWS or IB Gateway yet, refer to the Initial Setup guide. In NautilusTrader, you'll establish a connection to one of these applications via the InteractiveBrokersClient.

Alternatively, you can start with a dockerized version of the IB Gateway, which is particularly useful when deploying trading strategies on a hosted cloud platform. This requires having Docker installed on your machine, along with the docker Python package, which NautilusTrader conveniently includes as an extra package.

备注

The standalone TWS and IB Gateway applications require manually inputting username, password, and trading mode (live or paper) at startup. The dockerized 版本 of the IB Gateway handles these steps programmatically.

安装

To install NautilusTrader with Interactive Brokers (and Docker) 支持:

pip install --upgrade "nautilus_trader[ib,docker]"

To build from source with all extras (including IB and Docker):

uv sync --all-extras

备注

Because IB does not provide wheels for ibapi, NautilusTrader repackages it for release on PyPI.

示例

You can find live example scripts here.

入门指南

Before implementing your trading 策略, please ensure that either TWS (Trader Workstation) or IB Gateway is currently running. You have the option to log in to one of these standalone applications using your personal credentials or alternatively, via DockerizedIBGateway.

Connection Methods

There are two primary ways to connect to Interactive Brokers:

Connect to an existing TWS or IB Gateway instance
Use the dockerized IB Gateway (recommended for automated deployments)

Default Ports

Interactive Brokers uses different default ports depending on the application and trading mode:

Application	Paper Trading	实时交易
TWS	7497	7496
IB Gateway	4002	4001

Establish Connection to an Existing Gateway or TWS

When connecting to a pre-existing Gateway or TWS, specify the ibg_host and ibg_port parameters in both the InteractiveBrokersDataClientConfig and InteractiveBrokersExecClientConfig:

from nautilus_trader.adapters.interactive_brokers.config import InteractiveBrokersDataClientConfig
from nautilus_trader.adapters.interactive_brokers.config import InteractiveBrokersExecClientConfig

# Example for TWS paper trading (default port 7497)
data_config = InteractiveBrokersDataClientConfig(
    ibg_host="127.0.0.1",
    ibg_port=7497,
    ibg_client_id=1,
)

exec_config = InteractiveBrokersExecClientConfig(
    ibg_host="127.0.0.1",
    ibg_port=7497,
    ibg_client_id=1,
    account_id="DU123456",  # Your paper trading account ID
)

Establish Connection to DockerizedIBGateway

For automated deployments, the dockerized gateway is recommended. Supply dockerized_gateway with an instance of DockerizedIBGatewayConfig in both 客户端 configurations. The ibg_host and ibg_port parameters are not needed as they're managed automatically.

from nautilus_trader.adapters.interactive_brokers.config import DockerizedIBGatewayConfig
from nautilus_trader.adapters.interactive_brokers.gateway import DockerizedIBGateway

gateway_config = DockerizedIBGatewayConfig(
    username="your_username",  # Or set TWS_USERNAME env var
    password="your_password",  # Or set TWS_PASSWORD env var
    trading_mode="paper",      # "paper" or "live"
    read_only_api=True,        # Set to False to allow order execution
    timeout=300,               # Startup timeout in seconds
)

# This may take a short while to start up, especially the first time
gateway = DockerizedIBGateway(config=gateway_config)
gateway.start()

# Confirm you are logged in
print(gateway.is_logged_in(gateway.container))

# Inspect the logs
print(gateway.container.logs())

环境 Variables

To supply credentials to the Interactive Brokers Gateway, either pass the username and password to the DockerizedIBGatewayConfig, or set the following 环境 variables:

TWS_USERNAME - Your IB account username
TWS_PASSWORD - Your IB account password
TWS_ACCOUNT - Your IB account ID (used as fallback for account_id)

Connection Management

The adapter includes robust connection management features:

Automatic reconnection: Configurable via IB_MAX_CONNECTION_ATTEMPTS environment variable
Connection timeout: Configurable via connection_timeout parameter (default: 300 seconds)
Connection watchdog: Monitors connection health and triggers reconnection if needed
Graceful error handling: Comprehensive error handling for various connection scenarios

概览

The Interactive Brokers adapter provides a comprehensive integration with IB's TWS API. The adapter includes several major components:

Core Components

InteractiveBrokersClient: The central client that executes TWS API requests using ibapi. Manages connections, handles errors, and coordinates all API interactions.
InteractiveBrokersDataClient: Connects to the Gateway for streaming market data including quotes, trades, and bars.
InteractiveBrokersExecutionClient: Handles account information, order management, and trade execution.
InteractiveBrokersInstrumentProvider: Retrieves and manages instrument definitions, including support for options and futures chains.
HistoricInteractiveBrokersClient: Provides methods for retrieving instruments and historical data, useful for backtesting and research.

Supporting Components

DockerizedIBGateway: Manages dockerized IB Gateway instances for automated deployments.
Configuration Classes: Comprehensive configuration options for all components.
Factory Classes: Create and configure client instances with proper dependencies.

Supported Asset Classes

The adapter supports trading across all major asset classes available through Interactive Brokers:

Equities: Stocks, ETFs, and equity options
Fixed Income: Bonds and bond funds
Derivatives: Futures, options, and warrants
Foreign Exchange: Spot FX and FX forwards
Cryptocurrencies: Bitcoin, Ethereum, and other digital assets
Commodities: Physical commodities and commodity futures
Indices: Index products and index options

The Interactive Brokers 客户端

The InteractiveBrokersClient serves as the central 组件 of the IB adapter, overseeing a range of critical functions. These include establishing and maintaining connections, handling API errors, executing trades, and gathering various types of 数据 such as market 数据, contract/instrument 数据, and account details.

To ensure efficient management of these diverse responsibilities, the InteractiveBrokersClient is divided into several specialized mixin classes. This modular approach enhances manageability and clarity.

客户端架构

The 客户端 uses a mixin-based 架构 where each mixin handles a specific aspect of the IB API:

Connection Management (`InteractiveBrokersClientConnectionMixin`)

Establishes and maintains socket connections to TWS/Gateway.
Handles connection timeouts and reconnection logic.
Manages connection state and health 监控.
Supports configurable reconnection attempts via IB_MAX_CONNECTION_ATTEMPTS 环境 variable.

错误处理 (`InteractiveBrokersClientErrorMixin`)

Processes all API errors and warnings.
Categorizes errors by type (客户端 errors, connectivity issues, request errors).
Handles subscription and request-specific error scenarios.
Provides comprehensive error 日志记录 and 调试 information.

Account Management (`InteractiveBrokersClientAccountMixin`)

Retrieves account information and balances.
Manages position 数据 and 投资组合 updates.
Handles multi-account scenarios.
Processes account-related notifications

Contract/Instrument Management (`InteractiveBrokersClientContractMixin`)

Retrieves contract details and specifications
Handles instrument searches and lookups
Manages contract 验证 and verification
Supports complex instrument types (options chains, futures chains)

Market 数据 Management (`InteractiveBrokersClientMarketDataMixin`)

Handles 实时 and historical market 数据 subscriptions
Processes quotes, trades, and bar 数据
Manages market 数据 type settings (实时, delayed, frozen)
Handles tick-by-tick 数据 and market depth

订单管理 (`InteractiveBrokersClientOrderMixin`)

Processes order placement, modification, and cancellation
Handles order status updates and 执行报告
Manages order 验证 and 错误处理
Supports complex order types and conditions

Key Features

Asynchronous Operation: All operations are fully asynchronous using Python's asyncio
Robust Error Handling: Comprehensive error categorization and handling
Connection Resilience: Automatic reconnection with configurable retry logic
Message Processing: Efficient message queue processing for high-throughput scenarios
State Management: Proper state tracking for connections, subscriptions, and requests

提示

To troubleshoot TWS API incoming message issues, consider starting at the InteractiveBrokersClient._process_message method, which acts as the primary gateway for processing all messages received from the API.

Symbology

The InteractiveBrokersInstrumentProvider supports three methods for constructing InstrumentId instances, which can be configured via the symbology_method enum in InteractiveBrokersInstrumentProviderConfig.

Symbology Methods

1. Simplified Symbology (`IB_SIMPLIFIED`) - Default

When symbology_method is set to IB_SIMPLIFIED (the default setting), the system uses intuitive, human-readable symbology rules:

Format Rules by Asset Class:

Forex: {symbol}/{currency}.{exchange}
- Example: EUR/USD.IDEALPRO
Stocks: {localSymbol}.{primaryExchange}
- Spaces in localSymbol are replaced with hyphens
- Example: BF-B.NYSE, SPY.ARCA
Futures: {localSymbol}.{exchange}
- Individual contracts use single digit years
- Example: ESM4.CME, CLZ7.NYMEX
Continuous Futures: {symbol}.{exchange}
- Represents front month, automatically rolling
- Example: ES.CME, CL.NYMEX
Options on Futures (FOP): {localSymbol}.{exchange}
- Format: {symbol}{month}{year} {right}{strike}
- Example: ESM4 C4200.CME
Options: {localSymbol}.{exchange}
- All spaces removed from localSymbol
- Example: AAPL230217P00155000.SMART
Indices: ^{localSymbol}.{exchange}
- Example: ^SPX.CBOE, ^NDX.NASDAQ
Bonds: {localSymbol}.{exchange}
- Example: 912828XE8.SMART
Cryptocurrencies: {symbol}/{currency}.{exchange}
- Example: BTC/USD.PAXOS, ETH/USD.PAXOS

2. Raw Symbology (`IB_RAW`)

Setting symbology_method to IB_RAW enforces stricter parsing rules that align directly with the fields defined in the IB API. This method provides maximum 兼容性 across all regions and instrument types:

Format Rules:

CFDs: {localSymbol}={secType}.IBCFD
Commodities: {localSymbol}={secType}.IBCMDTY
Default for Other Types: {localSymbol}={secType}.{exchange}

示例:

IBUS30=CFD.IBCFD
XAUUSD=CMDTY.IBCMDTY
AAPL=STK.SMART

This 配置 ensures explicit instrument identification and supports 金融工具 from any region, especially those with non-standard symbology where simplified parsing may fail.

MIC Venue Conversion

The adapter supports converting Interactive Brokers exchange codes to Market Identifier Codes (MIC) for standardized venue identification:

`convert_exchange_to_mic_venue`

When set to True, the adapter automatically converts IB exchange codes to their corresponding MIC codes:

instrument_provider_config = InteractiveBrokersInstrumentProviderConfig(
    convert_exchange_to_mic_venue=True,  # Enable MIC conversion
    symbology_method=SymbologyMethod.IB_SIMPLIFIED,
)

示例 of MIC Conversion:

CME → XCME (Chicago Mercantile Exchange)
NASDAQ → XNAS (Nasdaq Stock Market)
NYSE → XNYS (New York Stock Exchange)
LSE → XLON (London Stock Exchange)

`symbol_to_mic_venue`

For custom venue mapping, use the symbol_to_mic_venue dictionary to override default conversions:

instrument_provider_config = InteractiveBrokersInstrumentProviderConfig(
    convert_exchange_to_mic_venue=True,
    symbol_to_mic_venue={
        "ES": "XCME",  # All ES futures/options use CME MIC
        "SPY": "ARCX", # SPY specifically uses ARCA
    },
)

Supported Instrument Formats

The adapter supports various instrument formats based on Interactive Brokers' contract specifications:

Futures Month Codes

F = January, G = February, H = March, J = April
K = May, M = June, N = July, Q = August
U = September, V = October, X = November, Z = December

Supported Exchanges by Asset Class

Futures Exchanges:

CME, CBOT, NYMEX, COMEX, KCBT, MGE, NYBOT, SNFE

Options Exchanges:

SMART (IB's smart routing)

Forex Exchanges:

IDEALPRO (IB's forex platform)

Cryptocurrency Exchanges:

PAXOS (IB's crypto platform)

CFD/Commodity Exchanges:

IBCFD, IBCMDTY (IB's internal routing)

Choosing the Right Symbology Method

Use IB_SIMPLIFIED (default) for most use cases - provides clean, readable instrument IDs
Use IB_RAW when dealing with complex international 金融工具 or when simplified parsing fails
Enable convert_exchange_to_mic_venue when you need standardized MIC venue codes for compliance or 数据 consistency

金融工具 & Contracts

In Interactive Brokers, a NautilusTrader Instrument corresponds to an IB Contract. The adapter handles two types of contract representations:

Contract Types

Basic Contract (`IBContract`)

Contains essential contract identification fields
Used for contract searches and basic operations
Cannot be directly converted to a NautilusTrader Instrument

Contract Details (`IBContractDetails`)

Contains comprehensive contract information including:
- Order types supported
- Trading hours and calendar
- Margin 要求
- Price increments and multipliers
- Market 数据 permissions
Can be converted to a NautilusTrader Instrument
Required for trading operations

Contract Discovery

To search for contract information, use the IB Contract Information Center.

Loading 金融工具

There are two primary methods for loading 金融工具:

1. Using `load_ids` (Recommended)

Use symbology_method=SymbologyMethod.IB_SIMPLIFIED (default) with load_ids for clean, intuitive instrument identification:

from nautilus_trader.adapters.interactive_brokers.config import InteractiveBrokersInstrumentProviderConfig
from nautilus_trader.adapters.interactive_brokers.config import SymbologyMethod

instrument_provider_config = InteractiveBrokersInstrumentProviderConfig(
    symbology_method=SymbologyMethod.IB_SIMPLIFIED,
    load_ids=frozenset([
        "EUR/USD.IDEALPRO",    # Forex
        "SPY.ARCA",            # Stock
        "ESM24.CME",           # Future
        "BTC/USD.PAXOS",       # Crypto
        "^SPX.CBOE",           # Index
    ]),
)

2. Using `load_contracts` (For Complex 金融工具)

Use load_contracts with IBContract instances for complex scenarios like options/futures chains:

from nautilus_trader.adapters.interactive_brokers.common import IBContract

# Load options chain for specific expiry
options_chain_expiry = IBContract(
    secType="IND",
    symbol="SPX",
    exchange="CBOE",
    build_options_chain=True,
    lastTradeDateOrContractMonth='20240718',
)

# Load options chain for date range
options_chain_range = IBContract(
    secType="IND",
    symbol="SPX",
    exchange="CBOE",
    build_options_chain=True,
    min_expiry_days=0,
    max_expiry_days=30,
)

# Load futures chain
futures_chain = IBContract(
    secType="CONTFUT",
    exchange="CME",
    symbol="ES",
    build_futures_chain=True,
)

instrument_provider_config = InteractiveBrokersInstrumentProviderConfig(
    load_contracts=frozenset([
        options_chain_expiry,
        options_chain_range,
        futures_chain,
    ]),
)

IBContract 示例 by Asset Class

from nautilus_trader.adapters.interactive_brokers.common import IBContract

# Stocks
IBContract(secType='STK', exchange='SMART', primaryExchange='ARCA', symbol='SPY')
IBContract(secType='STK', exchange='SMART', primaryExchange='NASDAQ', symbol='AAPL')

# Bonds
IBContract(secType='BOND', secIdType='ISIN', secId='US03076KAA60')
IBContract(secType='BOND', secIdType='CUSIP', secId='912828XE8')

# Individual Options
IBContract(secType='OPT', exchange='SMART', symbol='SPY',
           lastTradeDateOrContractMonth='20251219', strike=500, right='C')

# Options Chain (loads all strikes/expirations)
IBContract(secType='STK', exchange='SMART', primaryExchange='ARCA', symbol='SPY',
           build_options_chain=True, min_expiry_days=10, max_expiry_days=60)

# CFDs
IBContract(secType='CFD', symbol='IBUS30')
IBContract(secType='CFD', symbol='DE40EUR', exchange='SMART')

# Individual Futures
IBContract(secType='FUT', exchange='CME', symbol='ES',
           lastTradeDateOrContractMonth='20240315')

# Futures Chain (loads all expirations)
IBContract(secType='CONTFUT', exchange='CME', symbol='ES', build_futures_chain=True)

# Options on Futures (FOP) - Individual
IBContract(secType='FOP', exchange='CME', symbol='ES',
           lastTradeDateOrContractMonth='20240315', strike=4200, right='C')

# Options on Futures Chain (loads all strikes/expirations)
IBContract(secType='CONTFUT', exchange='CME', symbol='ES',
           build_options_chain=True, min_expiry_days=7, max_expiry_days=60)

# Forex
IBContract(secType='CASH', exchange='IDEALPRO', symbol='EUR', currency='USD')
IBContract(secType='CASH', exchange='IDEALPRO', symbol='GBP', currency='JPY')

# Cryptocurrencies
IBContract(secType='CRYPTO', symbol='BTC', exchange='PAXOS', currency='USD')
IBContract(secType='CRYPTO', symbol='ETH', exchange='PAXOS', currency='USD')

# Indices
IBContract(secType='IND', symbol='SPX', exchange='CBOE')
IBContract(secType='IND', symbol='NDX', exchange='NASDAQ')

# Commodities
IBContract(secType='CMDTY', symbol='XAUUSD', exchange='SMART')

Advanced 配置 Options

# Options chain with custom exchange
IBContract(
    secType="STK",
    symbol="AAPL",
    exchange="SMART",
    primaryExchange="NASDAQ",
    build_options_chain=True,
    options_chain_exchange="CBOE",  # Use CBOE for options instead of SMART
    min_expiry_days=7,
    max_expiry_days=45,
)

# Futures chain with specific months
IBContract(
    secType="CONTFUT",
    exchange="NYMEX",
    symbol="CL",  # Crude Oil
    build_futures_chain=True,
    min_expiry_days=30,
    max_expiry_days=180,
)

Continuous Futures

For continuous futures contracts (using secType='CONTFUT'), the adapter creates instrument IDs using just the symbol and venue:

# Continuous futures examples
IBContract(secType='CONTFUT', exchange='CME', symbol='ES')  # → ES.CME
IBContract(secType='CONTFUT', exchange='NYMEX', symbol='CL') # → CL.NYMEX

# With MIC venue conversion enabled
instrument_provider_config = InteractiveBrokersInstrumentProviderConfig(
    convert_exchange_to_mic_venue=True,
)
# Results in:
# ES.XCME (instead of ES.CME)
# CL.XNYM (instead of CL.NYMEX)

Continuous Futures vs Individual Futures:

Continuous: ES.CME - Represents the front month contract, automatically rolls
Individual: ESM4.CME - Specific March 2024 contract

备注

When using build_options_chain=True or build_futures_chain=True, the secType and symbol should be specified for the underlying contract. The adapter will automatically discover and load all related derivative contracts within the specified expiry range.

Option Spreads

Interactive Brokers supports option spreads through BAG contracts, which combine multiple option legs into a single tradeable instrument. NautilusTrader provides comprehensive 支持 for creating, loading, and trading option spreads.

Creating Option Spread Instrument IDs

Option spreads are created using the InstrumentId.new_spread() method, which combines individual option legs with their respective ratios:

from nautilus_trader.model.identifiers import InstrumentId

# Create individual option instrument IDs
call_leg = InstrumentId.from_str("SPY C400.SMART")
put_leg = InstrumentId.from_str("SPY P390.SMART")

# Create a 1:1 call spread (long call, short call)
call_spread_id = InstrumentId.new_spread([
    (call_leg, 1),   # Long 1 contract
    (put_leg, -1),   # Short 1 contract
])

# Create a 1:2 ratio spread
ratio_spread_id = InstrumentId.new_spread([
    (call_leg, 1),   # Long 1 contract
    (put_leg, 2),    # Long 2 contracts
])

Dynamic Spread Loading

Option spreads must be requested before they can be traded or subscribed to for market 数据. Use the request_instrument() method to dynamically load spread 金融工具:

# In your strategy's on_start method
def on_start(self):
    # Request the spread instrument
    self.request_instrument(spread_id)

def on_instrument(self, instrument):
    # Handle the loaded spread instrument
    self.log.info(f"Loaded spread: {instrument.id}")

    # Now you can subscribe to market data
    self.subscribe_quote_ticks(instrument.id)

    # And place orders
    order = self.order_factory.market(
        instrument_id=instrument.id,
        order_side=OrderSide.BUY,
        quantity=instrument.make_qty(1),
        time_in_force=TimeInForce.DAY,
    )
    self.submit_order(order)

Spread Trading 要求

Load Individual Legs First: The individual option legs must be available before creating spreads
Request Spread Instrument: Use request_instrument() to load the spread before trading
Market Data Subscription: Subscribe to quote ticks after the spread is loaded
Order Placement: Any order type can be used

Historical 数据 & 回测

The HistoricInteractiveBrokersClient provides comprehensive methods for retrieving historical 数据 from Interactive Brokers for 回测 and research purposes.

Supported 数据 Types

Bar Data: OHLCV bars with various aggregations (time-based, tick-based, volume-based)
Tick Data: Trade ticks and quote ticks with microsecond precision
Instrument Data: Complete contract specifications and trading rules

Historical 数据客户端

from nautilus_trader.adapters.interactive_brokers.historical.client import HistoricInteractiveBrokersClient
from ibapi.common import MarketDataTypeEnum

# Initialize the client
client = HistoricInteractiveBrokersClient(
    host="127.0.0.1",
    port=7497,
    client_id=1,
    market_data_type=MarketDataTypeEnum.DELAYED_FROZEN,  # Use delayed data if no subscription
    log_level="INFO"
)

# Connect to TWS/Gateway
await client.connect()

Retrieving 金融工具

Basic Instrument Retrieval

from nautilus_trader.adapters.interactive_brokers.common import IBContract

# Define contracts
contracts = [
    IBContract(secType="STK", symbol="AAPL", exchange="SMART", primaryExchange="NASDAQ"),
    IBContract(secType="STK", symbol="MSFT", exchange="SMART", primaryExchange="NASDAQ"),
    IBContract(secType="CASH", symbol="EUR", currency="USD", exchange="IDEALPRO"),
]

# Request instrument definitions
instruments = await client.request_instruments(contracts=contracts)

Option Chain Retrieval with Catalog 存储

You can download entire option chains using request_instruments in your strategy, with the added benefit of saving the 数据 to the catalog using update_catalog=True:

# In your strategy's on_start method
def on_start(self):
    self.request_instruments(
        venue=IB_VENUE,
        update_catalog=True,
        params={
            "update_catalog": True,
            "ib_contracts": (
                # SPY options
                {
                    "secType": "STK",
                    "symbol": "SPY",
                    "exchange": "SMART",
                    "primaryExchange": "ARCA",
                    "build_options_chain": True,
                    "min_expiry_days": 7,
                    "max_expiry_days": 30,
                },
                # QQQ options
                {
                    "secType": "STK",
                    "symbol": "QQQ",
                    "exchange": "SMART",
                    "primaryExchange": "NASDAQ",
                    "build_options_chain": True,
                    "min_expiry_days": 7,
                    "max_expiry_days": 30,
                },
                # ES futures options
                {
                    "secType": "CONTFUT",
                    "exchange": "CME",
                    "symbol": "ES",
                    "build_options_chain": True,
                    "min_expiry_days": 0,
                    "max_expiry_days": 60,
                },
            ),
        },
    )

Retrieving Historical Bars

import datetime

# Request historical bars
bars = await client.request_bars(
    bar_specifications=[
        "1-MINUTE-LAST",    # 1-minute bars using last price
        "5-MINUTE-MID",     # 5-minute bars using midpoint
        "1-HOUR-LAST",      # 1-hour bars using last price
        "1-DAY-LAST",       # Daily bars using last price
    ],
    start_date_time=datetime.datetime(2023, 11, 1, 9, 30),
    end_date_time=datetime.datetime(2023, 11, 6, 16, 30),
    tz_name="America/New_York",
    contracts=contracts,
    use_rth=True,  # Regular Trading Hours only
    timeout=120,   # Request timeout in seconds
)

Retrieving Historical Ticks

# Request historical tick data
ticks = await client.request_ticks(
    tick_types=["TRADES", "BID_ASK"],  # Trade ticks and quote ticks
    start_date_time=datetime.datetime(2023, 11, 6, 9, 30),
    end_date_time=datetime.datetime(2023, 11, 6, 16, 30),
    tz_name="America/New_York",
    contracts=contracts,
    use_rth=True,
    timeout=120,
)

Bar Specifications

The adapter supports various bar specifications:

Time-Based Bars

"1-SECOND-LAST", "5-SECOND-LAST", "10-SECOND-LAST", "15-SECOND-LAST", "30-SECOND-LAST"
"1-MINUTE-LAST", "2-MINUTE-LAST", "3-MINUTE-LAST", "5-MINUTE-LAST", "10-MINUTE-LAST", "15-MINUTE-LAST", "20-MINUTE-LAST", "30-MINUTE-LAST"
"1-HOUR-LAST", "2-HOUR-LAST", "3-HOUR-LAST", "4-HOUR-LAST", "8-HOUR-LAST"
"1-DAY-LAST", "1-WEEK-LAST", "1-MONTH-LAST"

Price Types

LAST - Last traded price
MID - Midpoint of bid/ask
BID - Bid price
ASK - Ask price

Complete Example

import asyncio
import datetime
from nautilus_trader.adapters.interactive_brokers.common import IBContract
from nautilus_trader.adapters.interactive_brokers.historical.client import HistoricInteractiveBrokersClient
from nautilus_trader.persistence.catalog import ParquetDataCatalog


async def download_historical_data():
    # Initialize client
    client = HistoricInteractiveBrokersClient(
        host="127.0.0.1",
        port=7497,
        client_id=5,
    )

    # Connect
    await client.connect()
    await asyncio.sleep(2)  # Allow connection to stabilize

    # Define contracts
    contracts = [
        IBContract(secType="STK", symbol="AAPL", exchange="SMART", primaryExchange="NASDAQ"),
        IBContract(secType="CASH", symbol="EUR", currency="USD", exchange="IDEALPRO"),
    ]

    # Request instruments
    instruments = await client.request_instruments(contracts=contracts)

    # Request historical bars
    bars = await client.request_bars(
        bar_specifications=["1-HOUR-LAST", "1-DAY-LAST"],
        start_date_time=datetime.datetime(2023, 11, 1, 9, 30),
        end_date_time=datetime.datetime(2023, 11, 6, 16, 30),
        tz_name="America/New_York",
        contracts=contracts,
        use_rth=True,
    )

    # Request tick data
    ticks = await client.request_ticks(
        tick_types=["TRADES"],
        start_date_time=datetime.datetime(2023, 11, 6, 14, 0),
        end_date_time=datetime.datetime(2023, 11, 6, 15, 0),
        tz_name="America/New_York",
        contracts=contracts,
    )

    # Save to catalog
    catalog = ParquetDataCatalog("./catalog")
    catalog.write_data(instruments)
    catalog.write_data(bars)
    catalog.write_data(ticks)

    print(f"Downloaded {len(instruments)} instruments")
    print(f"Downloaded {len(bars)} bars")
    print(f"Downloaded {len(ticks)} ticks")

    # Disconnect
    await client.disconnect()

# Run the example
if __name__ == "__main__":
    asyncio.run(download_historical_data())

数据 Limitations

Be aware of Interactive Brokers' historical 数据 limitations:

Rate Limits: IB enforces rate limits on historical data requests
Data Availability: Historical data availability varies by instrument and subscription level
Market Data Permissions: Some data requires specific market data subscriptions
Time Ranges: Maximum lookback periods vary by bar size and instrument type

Best Practices

Use Delayed Data: For backtesting, MarketDataTypeEnum.DELAYED_FROZEN is often sufficient
Batch Requests: Group multiple instruments in single requests when possible
Handle Timeouts: Set appropriate timeout values for large data requests
Respect Rate Limits: Add delays between requests to avoid hitting rate limits
Validate Data: Always check data quality and completeness before backtesting

实时交易

实时交易 with Interactive Brokers requires setting up a TradingNode that incorporates both InteractiveBrokersDataClient and InteractiveBrokersExecutionClient. These clients depend on the InteractiveBrokersInstrumentProvider for instrument management.

架构概览

The 实时交易设置 consists of three main components:

InstrumentProvider: Manages instrument definitions and contract details
DataClient: Handles real-time market data subscriptions
ExecutionClient: Manages orders, positions, and account information

InstrumentProvider 配置

The InteractiveBrokersInstrumentProvider serves as the bridge for accessing financial instrument 数据 from IB. It supports loading individual 金融工具, options chains, and futures chains.

Basic 配置

from nautilus_trader.adapters.interactive_brokers.config import InteractiveBrokersInstrumentProviderConfig
from nautilus_trader.adapters.interactive_brokers.config import SymbologyMethod
from nautilus_trader.adapters.interactive_brokers.common import IBContract

instrument_provider_config = InteractiveBrokersInstrumentProviderConfig(
    symbology_method=SymbologyMethod.IB_SIMPLIFIED,
    build_futures_chain=False,  # Set to True if fetching futures chains
    build_options_chain=False,  # Set to True if fetching options chains
    min_expiry_days=10,         # Minimum days to expiry for derivatives
    max_expiry_days=60,         # Maximum days to expiry for derivatives
    convert_exchange_to_mic_venue=False,  # Use MIC codes for venue mapping
    cache_validity_days=1,      # Cache instrument data for 1 day
    load_ids=frozenset([
        # Individual instruments using simplified symbology
        "EUR/USD.IDEALPRO",     # Forex
        "BTC/USD.PAXOS",        # Cryptocurrency
        "SPY.ARCA",             # Stock ETF
        "V.NYSE",               # Individual stock
        "ESM4.CME",             # Future contract (single digit year)
        "^SPX.CBOE",            # Index
    ]),
    load_contracts=frozenset([
        # Complex instruments using IBContract
        IBContract(secType='STK', symbol='AAPL', exchange='SMART', primaryExchange='NASDAQ'),
        IBContract(secType='CASH', symbol='GBP', currency='USD', exchange='IDEALPRO'),
    ]),
)

Advanced 配置 for Derivatives

# Configuration for options and futures chains
advanced_config = InteractiveBrokersInstrumentProviderConfig(
    symbology_method=SymbologyMethod.IB_SIMPLIFIED,
    build_futures_chain=True,   # Enable futures chain loading
    build_options_chain=True,   # Enable options chain loading
    min_expiry_days=7,          # Load contracts expiring in 7+ days
    max_expiry_days=90,         # Load contracts expiring within 90 days
    load_contracts=frozenset([
        # Load SPY options chain
        IBContract(
            secType='STK',
            symbol='SPY',
            exchange='SMART',
            primaryExchange='ARCA',
            build_options_chain=True,
        ),
        # Load ES futures chain
        IBContract(
            secType='CONTFUT',
            exchange='CME',
            symbol='ES',
            build_futures_chain=True,
        ),
    ]),
)

Integration with External 数据 Providers

The Interactive Brokers adapter can be used alongside other 数据 providers for enhanced market 数据 coverage. When using multiple 数据 sources:

Use consistent symbology methods across providers
Consider using convert_exchange_to_mic_venue=True for standardized venue identification
Ensure instrument 缓存 management is handled properly to avoid conflicts

数据客户端配置

The InteractiveBrokersDataClient interfaces with IB for streaming and retrieving real-time market data. Upon connection, it configures the market data type and loads instruments based on the InteractiveBrokersInstrumentProviderConfig settings.

Supported 数据 Types

Quote Ticks: Real-time bid/ask prices and sizes
Trade Ticks: Real-time trade prices and volumes
Bar Data: Real-time OHLCV bars (1-second to 1-day intervals)
Market Depth: Level 2 order book data (where available)

Market 数据 Types

Interactive Brokers supports several market 数据 types:

REALTIME: Live market data (requires market data subscriptions)
DELAYED: 15-20 minute delayed data (free for most markets)
DELAYED_FROZEN: Delayed data that doesn't update (useful for testing)
FROZEN: Last known real-time data (when market is closed)

Basic 数据客户端配置

from nautilus_trader.adapters.interactive_brokers.config import IBMarketDataTypeEnum
from nautilus_trader.adapters.interactive_brokers.config import InteractiveBrokersDataClientConfig

data_client_config = InteractiveBrokersDataClientConfig(
    ibg_host="127.0.0.1",
    ibg_port=7497,  # TWS paper trading port
    ibg_client_id=1,
    use_regular_trading_hours=True,  # RTH only for stocks
    market_data_type=IBMarketDataTypeEnum.DELAYED_FROZEN,  # Use delayed data
    ignore_quote_tick_size_updates=False,  # Include size-only updates
    instrument_provider=instrument_provider_config,
    connection_timeout=300,  # 5 minutes
    request_timeout=60,      # 1 minute
)

Advanced 数据客户端配置

# Configuration for production with real-time data
production_data_config = InteractiveBrokersDataClientConfig(
    ibg_host="127.0.0.1",
    ibg_port=4001,  # IB Gateway live trading port
    ibg_client_id=1,
    use_regular_trading_hours=False,  # Include extended hours
    market_data_type=IBMarketDataTypeEnum.REALTIME,  # Real-time data
    ignore_quote_tick_size_updates=True,  # Reduce tick volume
    handle_revised_bars=True,  # Handle bar revisions
    instrument_provider=instrument_provider_config,
    dockerized_gateway=dockerized_gateway_config,  # If using Docker
    connection_timeout=300,
    request_timeout=60,
)

配置 Options Explained

use_regular_trading_hours: When True, only requests data during regular trading hours. Primarily affects bar data for stocks.
ignore_quote_tick_size_updates: When True, filters out quote ticks where only the size changed (not price), reducing data volume.
handle_revised_bars: When True, processes bar revisions from IB (bars can be updated after initial publication).
connection_timeout: Maximum time to wait for initial connection establishment.
request_timeout: Maximum time to wait for historical data requests.

执行客户端配置

The InteractiveBrokersExecutionClient handles trade 执行, 订单管理, account information, and position tracking. It provides comprehensive order lifecycle management and 实时 account updates.

Supported Functionality

Order Management: Place, modify, and cancel orders
Order Types: Market, limit, stop, stop-limit, trailing stop, and more
Account Information: Real-time balance and margin updates
Position Tracking: Real-time position updates and P&L
Trade Reporting: Execution reports and fill notifications
Risk Management: Pre-trade risk checks and position limits

Supported Order Types

The adapter supports most Interactive Brokers order types:

Market Orders: OrderType.MARKET
Limit Orders: OrderType.LIMIT
Stop Orders: OrderType.STOP_MARKET
Stop-Limit Orders: OrderType.STOP_LIMIT
Market-If-Touched: OrderType.MARKET_IF_TOUCHED
Limit-If-Touched: OrderType.LIMIT_IF_TOUCHED
Trailing Stop Market: OrderType.TRAILING_STOP_MARKET
Trailing Stop Limit: OrderType.TRAILING_STOP_LIMIT
Market-on-Close: OrderType.MARKET with TimeInForce.AT_THE_CLOSE
Limit-on-Close: OrderType.LIMIT with TimeInForce.AT_THE_CLOSE

Time in force options

Day Orders: TimeInForce.DAY
Good-Till-Canceled: TimeInForce.GTC
Immediate-or-Cancel: TimeInForce.IOC
Fill-or-Kill: TimeInForce.FOK
Good-Till-Date: TimeInForce.GTD
At-the-Open: TimeInForce.AT_THE_OPEN
At-the-Close: TimeInForce.AT_THE_CLOSE

Batch operations

Operation	Supported	Notes
Batch Submit	✓	Submit multiple 订单 in single request.
Batch Modify	✓	Modify multiple 订单 in single request.
Batch Cancel	✓	Cancel multiple 订单 in single request.

Position management

功能	Supported	Notes
Query 头寸	✓	实时 position updates.
Position mode	✓	Net vs separate long/short 头寸.
Leverage control	✓	Account-level margin 要求.
Margin mode	✓	投资组合 vs individual margin.

Order querying

功能	Supported	Notes
Query open 订单	✓	List all active 订单.
Query order history	✓	Historical order 数据.
Order status updates	✓	实时 order state changes.
Trade history	✓	执行 and fill 报告.

Contingent 订单

功能	Supported	Notes
Order lists	✓	Atomic multi-order submission.
OCO 订单	✓	One-Cancels-Other with customizable OCA types (1, 2, 3).
Bracket 订单	✓	Parent-child order relationships with automatic OCO.
Conditional 订单	✓	Advanced order conditions and triggers.

Basic 执行客户端配置

from nautilus_trader.adapters.interactive_brokers.config import InteractiveBrokersExecClientConfig
from nautilus_trader.config import RoutingConfig

exec_client_config = InteractiveBrokersExecClientConfig(
    ibg_host="127.0.0.1",
    ibg_port=7497,  # TWS paper trading port
    ibg_client_id=1,
    account_id="DU123456",  # Your IB account ID (paper or live)
    instrument_provider=instrument_provider_config,
    connection_timeout=300,
    routing=RoutingConfig(default=True),  # Route all orders through this client
)

Advanced 执行客户端配置

# Production configuration with dockerized gateway
production_exec_config = InteractiveBrokersExecClientConfig(
    ibg_host="127.0.0.1",
    ibg_port=4001,  # IB Gateway live trading port
    ibg_client_id=1,
    account_id=None,  # Will use TWS_ACCOUNT environment variable
    instrument_provider=instrument_provider_config,
    dockerized_gateway=dockerized_gateway_config,
    connection_timeout=300,
    routing=RoutingConfig(default=True),
)

Account ID 配置

The account_id parameter is crucial and must match the account logged into TWS/Gateway:

# Option 1: Specify directly in config
exec_config = InteractiveBrokersExecClientConfig(
    account_id="DU123456",  # Paper trading account
    # ... other parameters
)

# Option 2: Use environment variable
import os
os.environ["TWS_ACCOUNT"] = "DU123456"
exec_config = InteractiveBrokersExecClientConfig(
    account_id=None,  # Will use TWS_ACCOUNT env var
    # ... other parameters
)

Order Tags and Advanced Features

The adapter supports IB-specific order parameters through order tags:

from nautilus_trader.adapters.interactive_brokers.common import IBOrderTags

# Create order with IB-specific parameters
order_tags = IBOrderTags(
    allOrNone=True,           # All-or-none order
    ocaGroup="MyGroup1",      # One-cancels-all group
    ocaType=1,                # Cancel with block
    activeStartTime="20240315 09:30:00 EST",  # GTC activation time
    activeStopTime="20240315 16:00:00 EST",   # GTC deactivation time
    goodAfterTime="20240315 09:35:00 EST",    # Good after time
)

# Apply tags to an order
order = order_factory.limit(
    instrument_id=instrument.id,
    order_side=OrderSide.BUY,
    quantity=instrument.make_qty(100),
    price=instrument.make_price(100.0),
    tags=[order_tags.value],
)

OCA (One-Cancels-All) 订单

The adapter provides comprehensive 支持 for OCA 订单 with both automatic detection and custom 配置:

Automatic OCO Detection

Bracket 订单 automatically use OCA functionality with safe defaults:

# Bracket orders automatically create OCA groups
bracket_order = order_factory.bracket(
    instrument_id=instrument.id,
    order_side=OrderSide.BUY,
    quantity=instrument.make_qty(100),
    tp_price=instrument.make_price(110.0),
    sl_trigger_price=instrument.make_price(90.0),
    contingency_type=ContingencyType.OCO,  # Automatic OCA Type 1
)

Custom OCA Types

You can specify custom OCA behavior using IBOrderTags:

from nautilus_trader.adapters.interactive_brokers.common import IBOrderTags

# Create custom OCA configuration
custom_oca_tags = IBOrderTags(
    ocaGroup="MY_CUSTOM_GROUP",
    ocaType=2,  # Use Type 2: Reduce with Block
)

# Apply to individual orders
order = order_factory.limit(
    instrument_id=instrument.id,
    order_side=OrderSide.BUY,
    quantity=instrument.make_qty(100),
    price=instrument.make_price(100.0),
    tags=[custom_oca_tags.value],
)

OCA Types

Interactive Brokers supports three OCA types:

Type	Name	Behavior	Use Case
1	Cancel All with Block	Cancel all remaining 订单 with block protection	Default - Safest option, prevents overfills
2	Reduce with Block	Proportionally reduce remaining 订单 with block protection	Partial fills with overfill protection
3	Reduce without Block	Proportionally reduce remaining 订单 without block protection	Fastest 执行, higher overfill risk

Multiple 订单 in Same OCA Group

# Create multiple orders with the same OCA group
oca_tags = IBOrderTags(
    ocaGroup="MULTI_ORDER_GROUP",
    ocaType=3,  # Use Type 3: Reduce without Block
)

order1 = order_factory.limit(
    instrument_id=instrument.id,
    order_side=OrderSide.BUY,
    quantity=instrument.make_qty(50),
    price=instrument.make_price(99.0),
    tags=[oca_tags.value],
)

order2 = order_factory.limit(
    instrument_id=instrument.id,
    order_side=OrderSide.BUY,
    quantity=instrument.make_qty(50),
    price=instrument.make_price(101.0),
    tags=[oca_tags.value],
)

Priority Order

The adapter applies OCA settings in the following priority:

Custom IBOrderTags (highest priority) - Explicit OCA settings in order tags
Automatic Detection - OCO/OUO contingency types in bracket 订单 (uses Type 1)
No OCA - 订单 without contingency types or OCA tags

Apply tags to order (实现 depends on your strategy code)

### Complete Trading Node Configuration

Setting up a complete trading environment involves configuring a `TradingNodeConfig` with all necessary components. Here are comprehensive examples for different scenarios.

#### Paper Trading Configuration

```python
import os
from nautilus_trader.适配器.interactive_brokers.common import IB
from nautilus_trader.适配器.interactive_brokers.common import IB_VENUE
from nautilus_trader.适配器.interactive_brokers.config import InteractiveBrokersDataClientConfig
from nautilus_trader.适配器.interactive_brokers.config import InteractiveBrokersExecClientConfig
from nautilus_trader.适配器.interactive_brokers.config import InteractiveBrokersInstrumentProviderConfig
from nautilus_trader.适配器.interactive_brokers.config import IBMarketDataTypeEnum
from nautilus_trader.适配器.interactive_brokers.config import SymbologyMethod
from nautilus_trader.适配器.interactive_brokers.factories import InteractiveBrokersLiveDataClientFactory
from nautilus_trader.适配器.interactive_brokers.factories import InteractiveBrokersLiveExecClientFactory
from nautilus_trader.config import LiveDataEngineConfig
from nautilus_trader.config import LoggingConfig
from nautilus_trader.config import RoutingConfig
from nautilus_trader.config import TradingNodeConfig
from nautilus_trader.live.节点 import TradingNode

# Instrument provider 配置
instrument_provider_config = InteractiveBrokersInstrumentProviderConfig(
    symbology_method=SymbologyMethod.IB_SIMPLIFIED,
    load_ids=frozenset([
        "EUR/USD.IDEALPRO",
        "GBP/USD.IDEALPRO",
        "SPY.ARCA",
        "QQQ.NASDAQ",
        "AAPL.NASDAQ",
        "MSFT.NASDAQ",
    ]),
)

# 数据 客户端 配置
data_client_config = InteractiveBrokersDataClientConfig(
    ibg_host="127.0.0.1",
    ibg_port=7497,  # TWS paper trading
    ibg_client_id=1,
    use_regular_trading_hours=True,
    market_data_type=IBMarketDataTypeEnum.DELAYED_FROZEN,
    instrument_provider=instrument_provider_config,
)

# 执行 客户端 配置
exec_client_config = InteractiveBrokersExecClientConfig(
    ibg_host="127.0.0.1",
    ibg_port=7497,  # TWS paper trading
    ibg_client_id=1,
    account_id="DU123456",  # Your paper trading account
    instrument_provider=instrument_provider_config,
    routing=RoutingConfig(default=True),
)

# Trading 节点 配置
config_node = TradingNodeConfig(
    trader_id="PAPER-TRADER-001",
    logging=LoggingConfig(log_level="INFO"),
    data_clients={IB: data_client_config},
    exec_clients={IB: exec_client_config},
    data_engine=LiveDataEngineConfig(
        time_bars_timestamp_on_close=False,  # IB standard: use bar open time
        validate_data_sequence=True,         # Discard out-of-sequence bars
    ),
    timeout_connection=90.0,
    timeout_reconciliation=5.0,
    timeout_portfolio=5.0,
    timeout_disconnection=5.0,
    timeout_post_stop=2.0,
)

# Create and configure the trading 节点
节点 = TradingNode(config=config_node)
节点.add_data_client_factory(IB, InteractiveBrokersLiveDataClientFactory)
节点.add_exec_client_factory(IB, InteractiveBrokersLiveExecClientFactory)
节点.build()
节点.投资组合.set_specific_venue(IB_VENUE)

if __name__ == "__main__":
    try:
        node.run()
    finally:
        node.dispose()

Live Trading with Dockerized Gateway

from nautilus_trader.适配器.interactive_brokers.config import DockerizedIBGatewayConfig

# Dockerized gateway 配置
dockerized_gateway_config = DockerizedIBGatewayConfig(
    username=os.environ.get("TWS_USERNAME"),
    password=os.environ.get("TWS_PASSWORD"),
    trading_mode="live",  # "paper" or "live"
    read_only_api=False,  # Allow order execution
    timeout=300,
)

# 数据 客户端 with dockerized gateway
data_client_config = InteractiveBrokersDataClientConfig(
    ibg_client_id=1,
    use_regular_trading_hours=False,  # Include extended hours
    market_data_type=IBMarketDataTypeEnum.REALTIME,
    instrument_provider=instrument_provider_config,
    dockerized_gateway=dockerized_gateway_config,
)

# 执行 客户端 with dockerized gateway
exec_client_config = InteractiveBrokersExecClientConfig(
    ibg_client_id=1,
    account_id=os.environ.get("TWS_ACCOUNT"),  # Live account ID
    instrument_provider=instrument_provider_config,
    dockerized_gateway=dockerized_gateway_config,
    routing=RoutingConfig(default=True),
)

# 实时交易 节点 配置
config_node = TradingNodeConfig(
    trader_id="LIVE-TRADER-001",
    logging=LoggingConfig(log_level="INFO"),
    data_clients={IB: data_client_config},
    exec_clients={IB: exec_client_config},
    data_engine=LiveDataEngineConfig(
        time_bars_timestamp_on_close=False,
        validate_data_sequence=True,
    ),
)

Multi-Client Configuration

For advanced setups, you can configure multiple clients with different purposes:

# Separate 数据 and 执行 clients with different 客户端 IDs
data_client_config = InteractiveBrokersDataClientConfig(
    ibg_host="127.0.0.1",
    ibg_port=7497,
    ibg_client_id=1,  # Data client uses ID 1
    market_data_type=IBMarketDataTypeEnum.REALTIME,
    instrument_provider=instrument_provider_config,
)

exec_client_config = InteractiveBrokersExecClientConfig(
    ibg_host="127.0.0.1",
    ibg_port=7497,
    ibg_client_id=2,  # Execution client uses ID 2
    account_id="DU123456",
    instrument_provider=instrument_provider_config,
    routing=RoutingConfig(default=True),
)

Running the Trading Node

def run_trading_node():
    """Run the trading node with proper error handling."""
    node = None
    try:
        # Create and build node
        node = TradingNode(config=config_node)
        node.add_data_client_factory(IB, InteractiveBrokersLiveDataClientFactory)
        node.add_exec_client_factory(IB, InteractiveBrokersLiveExecClientFactory)
        node.build()

        # Set venue for portfolio
        node.portfolio.set_specific_venue(IB_VENUE)

        # Add your strategies here
        # node.trader.add_strategy(YourStrategy())

        # Run the node
        node.run()

    except KeyboardInterrupt:
        print("Shutting down...")
    except Exception as e:
        print(f"Error: {e}")
    finally:
        if node:
            node.dispose()

if __name__ == "__main__":
    run_trading_node()

Additional Configuration Options

Environment Variables

Set these environment variables for easier configuration:

export TWS_USERNAME="your_ib_username"
export TWS_PASSWORD="your_ib_password"
export TWS_ACCOUNT="your_account_id"
export IB_MAX_CONNECTION_ATTEMPTS="5"  # Optional: limit reconnection attempts

Logging Configuration

# Enhanced 日志记录 配置
logging_config = LoggingConfig(
    log_level="INFO",
    log_level_file="DEBUG",
    log_file_format="json",  # JSON format for structured logging
    log_component_levels={
        "InteractiveBrokersClient": "DEBUG",
        "InteractiveBrokersDataClient": "INFO",
        "InteractiveBrokersExecutionClient": "INFO",
    },
)

You can find additional examples here: https://github.com/nautechsystems/nautilus_trader/tree/develop/examples/live/interactive_brokers

Troubleshooting

Common Connection Issues

Connection Refused

Cause: TWS/Gateway not running or wrong port
Solution: Verify TWS/Gateway is running and check port configuration
Default Ports: TWS (7497/7496), IB Gateway (4002/4001)

Authentication Errors

Cause: Incorrect credentials or account not logged in
Solution: Verify username/password and ensure account is logged into TWS/Gateway

Client ID Conflicts

Cause: Multiple clients using the same client ID
Solution: Use unique client IDs for each connection

Market Data Permissions

Cause: Insufficient market data subscriptions
Solution: Use IBMarketDataTypeEnum.DELAYED_FROZEN for testing or subscribe to required data feeds

Error Codes

Interactive Brokers uses specific error codes. Common ones include:

200: No security definition found
201: Order rejected - reason follows
202: Order cancelled
300: Can't find EId with ticker ID
354: Requested market data is not subscribed
2104: Market data farm connection is OK
2106: HMDS data farm connection is OK

Performance Optimization

Reduce Data Volume

# Reduce quote tick volume by ignoring size-only updates
data_config = InteractiveBrokersDataClientConfig(
    ignore_quote_tick_size_updates=True,
    # ... other config
)

Connection Management

# Set reasonable timeouts
config = InteractiveBrokersDataClientConfig(
    connection_timeout=300,  # 5 minutes
    request_timeout=60,      # 1 minute
    # ... other config
)

Memory Management

Use appropriate bar sizes for your strategy
Limit the number of simultaneous subscriptions
Consider using historical data for backtesting instead of live data

Best Practices

Security

Never hardcode credentials in source code
Use environment variables for sensitive information
Use paper trading for development and testing
Set read_only_api=True for data-only applications

Development Workflow

Start with Paper Trading: Always test with paper trading first
Use Delayed Data: Use DELAYED_FROZEN market data for development
Implement Proper Error Handling: Handle connection losses and API errors gracefully
Monitor Logs: Enable appropriate logging levels for debugging
Test Reconnection: Test your strategy's behavior during connection interruptions

Production Deployment

Use dockerized gateway for automated deployments
Implement proper monitoring and alerting
Set up log aggregation and analysis
Use real-time data subscriptions only when necessary
Implement circuit breakers and position limits

Order Management

Always validate orders before submission
Implement proper position sizing
Use appropriate order types for your strategy
Monitor order status and handle rejections
Implement timeout handling for order operations

Debugging Tips

Enable Debug Logging

logging_config = LoggingConfig(
    log_level="DEBUG",
    log_component_levels={
        "InteractiveBrokersClient": "DEBUG",
    },
)

Monitor Connection Status

# Check connection status in your strategy
if not self.data_client.is_connected:
    self.log.warning("Data client disconnected")

Validate Instruments

# Ensure 金融工具 are loaded before trading
金融工具 = self.缓存.金融工具()
if not 金融工具:
    self.log.error("No instruments loaded")

Support and Resources

IB API Documentation: TWS API Guide
NautilusTrader Examples: GitHub Examples
IB Contract Search: Contract Information Center
Market Data Subscriptions: IB Market Data

安装​

示例​

入门指南​

Connection Methods​

Default Ports​

Establish Connection to an Existing Gateway or TWS​

Establish Connection to DockerizedIBGateway​

环境 Variables​

Connection Management​

概览​

Core Components​

Supporting Components​

Supported Asset Classes​

The Interactive Brokers 客户端​

客户端 架构​

Connection Management (InteractiveBrokersClientConnectionMixin)​

错误处理 (InteractiveBrokersClientErrorMixin)​

Account Management (InteractiveBrokersClientAccountMixin)​

Contract/Instrument Management (InteractiveBrokersClientContractMixin)​

Market 数据 Management (InteractiveBrokersClientMarketDataMixin)​

订单管理 (InteractiveBrokersClientOrderMixin)​

Key Features​

Symbology​

Symbology Methods​

1. Simplified Symbology (IB_SIMPLIFIED) - Default​

2. Raw Symbology (IB_RAW)​

MIC Venue Conversion​

convert_exchange_to_mic_venue​

symbol_to_mic_venue​

Supported Instrument Formats​

Futures Month Codes​

Supported Exchanges by Asset Class​

Choosing the Right Symbology Method​

金融工具 & Contracts​

Contract Types​

Basic Contract (IBContract)​

Contract Details (IBContractDetails)​

Contract Discovery​

Loading 金融工具​

1. Using load_ids (Recommended)​

2. Using load_contracts (For Complex 金融工具)​

IBContract 示例 by Asset Class​

Advanced 配置 Options​

Continuous Futures​

Option Spreads​

Creating Option Spread Instrument IDs​

Dynamic Spread Loading​

Spread Trading 要求​

Historical 数据 & 回测​

Supported 数据 Types​

Historical 数据 客户端​

Retrieving 金融工具​

Basic Instrument Retrieval​

Option Chain Retrieval with Catalog 存储​

Retrieving Historical Bars​

Retrieving Historical Ticks​

Bar Specifications​

Time-Based Bars​

Price Types​

Complete Example​

数据 Limitations​

Best Practices​

实时交易​

架构 概览​

InstrumentProvider 配置​

Basic 配置​

Advanced 配置 for Derivatives​

Integration with External 数据 Providers​

数据 客户端 配置​

Supported 数据 Types​

Market 数据 Types​

Basic 数据 客户端 配置​

Advanced 数据 客户端 配置​

配置 Options Explained​

执行 客户端 配置​

Supported Functionality​

Supported Order Types​

Time in force options​

Batch operations​

Position management​

安装

示例

入门指南

Connection Methods

Default Ports

Establish Connection to an Existing Gateway or TWS

Establish Connection to DockerizedIBGateway

环境 Variables

Connection Management

概览

Core Components

Supporting Components

Supported Asset Classes

The Interactive Brokers 客户端

客户端架构

Connection Management (`InteractiveBrokersClientConnectionMixin`)

错误处理 (`InteractiveBrokersClientErrorMixin`)

Account Management (`InteractiveBrokersClientAccountMixin`)

Contract/Instrument Management (`InteractiveBrokersClientContractMixin`)

Market 数据 Management (`InteractiveBrokersClientMarketDataMixin`)

订单管理 (`InteractiveBrokersClientOrderMixin`)

Key Features

Symbology

Symbology Methods

1. Simplified Symbology (`IB_SIMPLIFIED`) - Default

2. Raw Symbology (`IB_RAW`)

MIC Venue Conversion

`convert_exchange_to_mic_venue`

`symbol_to_mic_venue`

Supported Instrument Formats

Futures Month Codes

Supported Exchanges by Asset Class

Choosing the Right Symbology Method

金融工具 & Contracts

Contract Types

Basic Contract (`IBContract`)

Contract Details (`IBContractDetails`)

Contract Discovery

Loading 金融工具

1. Using `load_ids` (Recommended)

2. Using `load_contracts` (For Complex 金融工具)

IBContract 示例 by Asset Class

Advanced 配置 Options

Continuous Futures

Option Spreads

Creating Option Spread Instrument IDs

Dynamic Spread Loading

Spread Trading 要求

Historical 数据 & 回测

Supported 数据 Types

Historical 数据客户端

Retrieving 金融工具

Basic Instrument Retrieval

Option Chain Retrieval with Catalog 存储

Retrieving Historical Bars

Retrieving Historical Ticks

Bar Specifications

Time-Based Bars

Price Types

Complete Example

数据 Limitations

Best Practices

实时交易

架构概览

InstrumentProvider 配置

Basic 配置

Advanced 配置 for Derivatives

Integration with External 数据 Providers

数据客户端配置

Supported 数据 Types

Market 数据 Types

Basic 数据客户端配置

Advanced 数据客户端配置

配置 Options Explained

执行客户端配置

Supported Functionality

Supported Order Types

Time in force options

Batch operations

Position management