Interactive Brokers API Trading with LumiBot¶
Interactive Brokers is a brokerage firm that operates in most countries around the world. It’s a great choice for investing and trading, especially if you don’t have access to other supported platforms.
What BotSpot MCP adds
Use Claude, ChatGPT, Codex, Cursor, VS Code or another MCP-compatible assistant? Connect the free BotSpot MCP for:
Skills: build LumiBot strategies.
Free data: news, economics and SEC filings.
Backtests: run tests and read charts.
Cloud hosting: low-cost scheduled bots.
Community: share bots and discuss trades.
Marketplace: discover and publish strategies.
Broker linking: connect accounts through BotSpot.
Note: If you have access to other supported brokers, compare their fee structures to see which one offers the best deal for you.
Note
Easy Setup with .env File
LumiBot automatically loads your API credentials from a .env file! Simply create a .env file in the same folder as your trading strategy and add your Interactive Brokers credentials. LumiBot will automatically detect and use these credentials - no additional configuration required.
Example .env file:
# Interactive Brokers Configuration
IB_USERNAME=your_ib_username
IB_PASSWORD=your_ib_password
IB_ACCOUNT_ID=your_account_id
That’s it! LumiBot handles the rest automatically.
Market Data Subscriptions¶
To access real-time market data, you need to subscribe to the appropriate market data packages. Interactive Brokers offers various subscriptions depending on the exchanges and types of data you need. Here are some common options:
US Securities Snapshot and Futures Value Bundle
US Equity and Options Add-On Streaming Bundle
NASDAQ (Network C/UTP) TotalView
NYSE (Network A/CTA) OpenBook Ultra
OPRA (US Options Exchanges)
Note
Different strategies may require different market data subscriptions. For top options-related strategies, the OPRA (US Options Exchanges) subscription should suffice.
To subscribe to market data:
Important
Market data subscriptions are login-specific. Ensure you’re logged in with the same credentials you plan to use with Lumibot before proceeding.
Log in to the IBKR Client Portal.
Navigate to the Settings menu.
Under Account Settings, find the Market Data Subscriptions section.
Click Configure and select the desired market data packages.
Find your desired subscription.
Follow the prompts to complete the subscription process.
Note: Market data subscriptions may incur additional fees. Review the costs associated with each package before subscribing.
Two-Factor Authentication (2FA)¶
Interactive Brokers requires two-factor authentication for Client Portal Gateway users. Individual users must authenticate in a browser on the same machine as the gateway and reauthenticate at least daily. LumiBot does not provide a supported way to bypass this requirement.
See IBKR Client Portal Gateway requirements.
Warning
LumiBot can start IBeam as a local convenience for controlled individual or internal paper testing. IBeam is a third-party wrapper, and IBKR does not support automated Client Portal Gateway authentication or third-party wrappers. Do not use this path to collect customer credentials. Commercial third-party products should complete IBKR onboarding and use approved OAuth.
Using a Secondary Username¶
IBKR allows one active brokerage session per username. Logging into Client Portal, TWS, IB Gateway, or another trading-enabled session with the same username can displace the API session.
An additional username can isolate API activity from normal Client Portal use. It does not remove IBKR’s 2FA or session-authentication requirements. Market-data subscriptions are username-specific and may incur separate fees.
Using a Paper Trading Account¶
When using a paper trading account, log in with your paper trading username and password. This allows you to practice trading without risking real money.
Steps to get your paper trading username and password:
Log in to the IBKR Client Portal using your primary (live) account credentials.
Navigate to the Settings menu in the upper right corner.
Under Account Settings, find the Paper Trading Account section.
Click on Configure or Request Paper Trading Account.
Follow the prompts to set up your paper trading account.
Once the setup is complete, you’ll receive a separate username and password for your paper trading account.
Use these credentials when logging into the paper trading environment and configuring your API connection.
Note: The paper trading account is separate from your live account. Ensure you’re using the correct credentials for each environment to avoid any login conflicts.
Strategy Setup¶
Add these variables to a .env file in the same directory as your strategy:
Secret |
Description |
Example |
|---|---|---|
IB_USERNAME |
Your Interactive Brokers username. |
<your-paper-username> |
IB_PASSWORD |
Your Interactive Brokers password. |
<your-paper-password> |
IB_ACCOUNT_ID |
(Optional) An Interactive Brokers subaccount to trade on. |
<your-account-id> |
IB_API_URL |
(Optional) URL of an externally managed Client Portal or approved REST transport. |
https://localhost:4234 |
IB_USE_PAPER_ACCOUNT |
Local IBeam paper-account toggle. Defaults to |
true |
IB_GATEWAY_PORT |
(Optional) Host port for local IBeam or a localhost sidecar. |
4234 |
IB_AUTH_TIMEOUT |
(Optional) Maximum authentication wait in seconds. |
300 |
Example Strategy¶
from lumibot.traders import Trader
from lumibot.strategies.examples import Strangle
trader = Trader()
strategy = Strangle()
trader.add_strategy(strategy)
trader.run_all()
Frequently asked questions¶
Does LumiBot work with Interactive Brokers?¶
Yes. This page covers the Client Portal REST connection, which LumiBot selects when IB_USERNAME is set. The older Trader Workstation (TWS) socket method is on Interactive Brokers Legacy and is deprecated.
What environment variables does LumiBot use for Interactive Brokers?¶
Set IB_USERNAME and IB_PASSWORD. IB_ACCOUNT_ID is optional and picks a subaccount. IB_USE_PAPER_ACCOUNT defaults to true.
If keys for other brokers are also set, add TRADING_BROKER=ibrest to force this connection.
How do I paper trade with Interactive Brokers in LumiBot?¶
Request a paper trading account in the IBKR Client Portal under Settings. IBKR gives you a separate paper username and password.
Put those paper credentials in IB_USERNAME and IB_PASSWORD. Keep IB_USE_PAPER_ACCOUNT=true when LumiBot starts the local IBeam gateway.
What can I trade on Interactive Brokers with LumiBot?¶
Stocks, options, futures and forex, plus multi-leg option orders. LumiBot can also read index data.
Order types include market, limit, stop, stop-limit and trailing stop.
Do I need to pay for IBKR market data to use the API?¶
For real-time data, you need IBKR market data subscriptions, and they may cost extra. Check the price of each package in the Client Portal before you subscribe.
Subscriptions belong to one username. Subscribe while logged in with the same username you give LumiBot.
Which IBKR market data subscription do I need for options?¶
For most options strategies, the OPRA (US Options Exchanges) subscription is enough. Other strategies may need other packages, such as the US Securities Snapshot and Futures Value Bundle.
Why does my IBKR API session keep getting logged out?¶
IBKR allows one active brokerage session per username. Logging in to Client Portal, TWS, IB Gateway or another trading session with the same username can push the API session out.
A second username for API use avoids this. It still needs 2FA, and its market data subscriptions are separate.
Do I have to log in to IBKR every day?¶
Yes. IBKR requires two-factor authentication for Client Portal Gateway users, and individual users must log in again at least daily. LumiBot does not bypass this.
What is IBeam?¶
IBeam is a third-party tool that runs the IBKR Client Portal Gateway. LumiBot can start it locally for your own testing, for example with a paper account.
IBKR does not support third-party wrappers like IBeam. Do not use it to collect other people’s credentials.