How to Set Up IBKR API Paper Trading (2026)

IBKR API paper trading solves this. You get a simulated environment with virtual cash to validate your logic, test order routing, and debug connection issues without risking a single cent.

However, setting up the API for paper trading is not as straightforward as flipping a switch. It requires specific configurations in the Trader Workstation (TWS) or IB Gateway, correct API settings, and a clear understanding of how paper trading differs from live trading.

In this guide, I will walk you through the exact steps to set up IBKR API paper trading from scratch. Whether you are using Python, C#, or another supported language, these steps will get your environment running safely.

About this guide: I'm Lawrence, the writer behind supa.is. Between February and May 2026 I've published 150+ articles on supa.is across crypto and brokerage tooling — including 30+ Interactive Brokers-specific guides (recent examples: IBKR Python API 2026, IBKR Paper Trading Setup, IBKR API Error Handling). The most-repeated reader question across that IBKR archive is exactly how to connect the API to the paper trading environment, which is why I'm publishing this standardized guide instead of answering one-off.

Why You Must Use IBKR API Paper Trading First

Before diving into the setup, here is why the IBKR API paper trading environment is non-negotiable for new algo traders.

1. The API Environment is Different from the Web UI

2. Testing Market Data Subscriptions

3. Simulating Slippage and Partial Fills

Note: Steps below are reconstructed from official docs (linked). Verify each step against the current UI before relying on it.

Prerequisites: What You Need Before Starting

To set up IBKR API paper trading, you need the following:

1. An Interactive Brokers Account: You can open a free account using our referral link to qualify for the $1,000 IBKR stock bonus.
2. TWS or IB Gateway: The Trader Workstation (TWS) is the full-featured platform, while IB Gateway is a lightweight alternative designed specifically for API connections. For paper trading, IB Gateway is often preferred due to lower resource usage.
3. API Client Language: Python is the most popular, but IBKR also supports Java, C++, C#, and more.

Step 1: Enable Paper Trading in TWS or IB Gateway

Switch your TWS or IB Gateway environment to paper trading. You don't need a funded account for this, but you will start with a simulated balance (usually $100,000 USD).

1. Download and Install TWS or IB Gateway: If you haven't already, download the latest version of TWS or IB Gateway from the Interactive Brokers download page.
2. Log In: Enter your username and password.
3. Select Paper Trading:

1. Wait for Initialization: It may take a few minutes for the paper trading environment to load. You will see the account balance update to your simulated funds.

Step 2: Configure API Settings

Once you are in the paper trading environment, you need to enable the API connection. This is where most beginners get stuck.

1. Open Global Configuration:

1. Enable ActiveX and Socket Clients: Ensure the checkbox for "Enable ActiveX and Socket Clients" is checked.
2. Set the Port: The default port is 7497. You can use this, or change it to a different port if you are running multiple instances of TWS/Gateway.
3. Allow Connections from External Clients: If you are running your API script on a different machine than TWS/Gateway, you must check "Allow connections from external clients" and enter the IP address of the machine running your script. If both are on the same machine, leave this unchecked.
4. Apply and Restart: Click "Apply" and "OK". You will be prompted to restart TWS/Gateway for the changes to take effect.

Step 3: Set Up Your API Environment (Python Example)

Now that TWS/Gateway is configured, it's time to set up your local development environment. Python is the easiest language to start with, thanks to the ibapi package provided by Interactive Brokers.

1. Install the ibapi package:

   pip install ibapi
   

1. Verify Installation: Open a Python shell and try importing the library:

   from ibapi.client import EClient
   from ibapi.wrapper import EWrapper
   

1. Create a Basic Connection Script:

   from ibapi.client import EClient
   from ibapi.wrapper import EWrapper
   from ibapi.common import *
   import time

   class TestApp(EWrapper, EClient):
       def __init__(self):
           EWrapper.__init__(self)
           EClient.__init__(self, self)

       def error(self, reqId, errorCode, errorString):
           print(f"Error: {reqId} - {errorCode} - {errorString}")

       def nextValidId(self, orderId):
           print(f"Next valid order ID: {orderId}")

   if __name__ == "__main__":
       app = TestApp()
       app.connect("127.0.0.1", 7497, 0)
       app.run()
   

Run this script. If you see "Next valid order ID: 1" (or a higher number), your API connection to the paper trading environment is successful.

Step 4: Request Market Data

Your API script must subscribe to market data before placing orders. This is mandatory in the IBKR API.

1. Define the Contract: You need to specify the instrument you want to trade. For example, Apple stock (AAPL):

   from ibapi.contract import Contract

   contract = Contract()
   contract.symbol = "AAPL"
   contract.secType = "STK"
   contract.exchange = "SMART"
   contract.currency = "USD"
   

1. Request Market Data: Use the reqMktData method to subscribe to real-time prices:

   reqId = 1
   app.reqMktData(reqId, contract, "", False, False, [])
   

1. Handle Market Data Updates: You will need to implement the tickPrice method in your EWrapper class to receive the data:

   def tickPrice(self, reqId, tickType, price, attrib):
       print(f"Tick Price: {reqId} - {tickType} - {price}")
   

Run your script again. You should start seeing a stream of price ticks for AAPL. If you don't, double-check that you have the necessary market data subscriptions enabled in your TWS account (even for paper trading, some data feeds require a subscription).

Step 5: Place a Test Order

With a connection and market data, you're ready to place a simulated order.

1. Define the Order: Create an order object. For a simple market buy:

   from ibapi.order import Order

   order = Order()
   order.action = "BUY"
   order.orderType = "MKT"
   order.totalQuantity = 1
   

1. Place the Order: Use the placeOrder method:

   orderId = app.nextValidOrderId
   app.placeOrder(orderId, contract, order)
   

1. Monitor Order Status: Implement the orderStatus method to track the order:

   def orderStatus(self, orderId, status, filled, remaining, avgFillPrice, permId, parentId, lastFillPrice, clientId, whyHeld, mktCapPrice):
       print(f"Order Status: {orderId} - {status} - Filled: {filled}")
   

If everything is set up correctly, you should see the order status change to "Filled" almost instantly. Check your paper trading account balance in TWS to confirm the trade was executed.

Common Pitfalls and How to Avoid Them

The setup is straightforward, but a few common issues can trip you up.

1. "Market Data Not Subscribed" Error

2. Port Conflicts

3. TWS/Gateway Not Fully Loaded

4. Using the Wrong Exchange

Paper Trading vs. Live Trading: Key Differences

Paper trading has limitations. Don't let it give you a false sense of security.

Advanced Tip: Using IB Gateway for Headless API Trading

If you are running your API script on a server or a machine without a monitor, IB Gateway is the way to go. It is designed to be lightweight and can run in the background.

1. Download IB Gateway: Available from the same Interactive Brokers download page.
2. Run in Headless Mode: IB Gateway can be configured to run without a GUI. You can pass command-line arguments to start it automatically with your paper trading credentials.
3. Set Up Auto-Login: For security, you can use IBKR's two-factor authentication (2FA) via the IBKR Mobile app, but for API automation, you may want to set up a static IP address and use the "Allow connections from external clients" feature to avoid manual login every time.

Conclusion

Paper trading is the only safe way to test your code, debug connection issues, and validate your strategy. Once you've got your environment running, remember that it's not a perfect simulation. Always backtest your strategies against historical data and account for real-world costs before going live.

If you are ready to start trading with Interactive Brokers, you can open a free account using our referral link and qualify for the $1,000 IBKR stock bonus.

FAQ

Can I use IBKR API paper trading without a funded account?

Is the data in paper trading real-time?

Can I run multiple API scripts connected to the same paper trading account?

Why am I getting a "Market Data Not Subscribed" error?

How do I switch from paper trading to live trading?

Risk Warning

Risk Warning: Crypto trading involves substantial risk of loss. Never invest more than you can afford to lose. This is not financial advice.