IB@stoqey/ib
@stoqey/ibkr (High-Level Wrapper)Advanced Features

Contract Allowlist Filtering

Restricting orders, positions, and market data to specified symbol allowlists with IBKR_CONTRACTS.

Overview

When multiple trading bots or microservices share a single TWS / IB Gateway session, contract filtering prevents applications from processing or placing orders on instruments outside their assigned universe.

@stoqey/ibkr supports global and scoped contract allowlist filtering via environment variables.

Global Contract Allowlist (IBKR_CONTRACTS)

Set IBKR_CONTRACTS in your .env file as a comma-separated list:

IBKR_CONTRACTS=NQ-FUT,AAPL-STK,GC-FUT

Filters are case-insensitive and match on:

  • Symbol: AAPL
  • Symbol & SecType: NQ-FUT
  • Symbol, SecType & Expiry: NQ-FUT-202606
  • Symbol, SecType & Exchange: AAPL-STK-SMART

Scoped Contract Filters

If different modules in your application require distinct allowlists, configure scoped overrides:

# Allow orders only on Nasdaq futures
IBKR_CONTRACTS_ORDERS=NQ-FUT

# Allow position tracking on NQ futures and Gold futures
IBKR_CONTRACTS_POSITIONS=NQ-FUT,GC-FUT

# Disable market data filtering (allow all symbols)
IBKR_CONTRACTS_MARKETDATA=*

Accepted Environment Aliases

  • Orders: IBKR_CONTRACTS_ORDERS or IBKR_CONTRACTS_ORDER
  • Positions: IBKR_CONTRACTS_POSITIONS or IBKR_CONTRACTS_POSITION
  • Market Data: IBKR_CONTRACTS_MARKETDATA or IBKR_CONTRACTS_MD

Wildcard Support

Using * as the filter value disables allowlist checking for that scope.

Market Data Only Mode

Using IBKR_MD_ONLY=true for lightweight market data feeders, scanners, and symbol lookup clients.

On this page

OverviewGlobal Contract Allowlist (IBKR_CONTRACTS)Scoped Contract FiltersAccepted Environment Aliases