ib-async: Interactive Brokers API Wrapper

Common errors

• ModuleNotFoundError: No module named 'ib_async'

  cause Attempting to import the library using its PyPI install name (`ib_async`) instead of its internal package name.
  fix Change your import statements from `from ib_async import ...` to `from ib_insync import ...`.

• ConnectionRefusedError: [Errno 111] Connection refused

  cause The Python client could not establish a connection to the specified host and port. Usually, TWS/Gateway is not running, is running on a different port/host, or firewall is blocking the connection.
  fix 1. Ensure TWS or IB Gateway is running. 2. Verify the host (e.g., '127.0.0.1') and port (e.g., 7497) in your `ib.connect()` call match your TWS/Gateway API settings. 3. Check your firewall settings to allow connections on the specified port.

• RuntimeError: Event loop is already running.

  cause This typically occurs when you try to start an asyncio event loop (e.g., with `asyncio.run()` or `IB.run()`) when one is already active.
  fix Ensure you are calling `IB.run()` or `asyncio.run()` only once to start your main async function. If you are integrating `ib-async` into an existing async application, avoid starting a new loop; instead, schedule `ib-async` coroutines within the existing event loop.

• Historical data request error: Not a valid historical data subscription for contract...

  cause The contract definition or historical data parameters are incorrect or not supported by IB for that specific security/exchange, or you lack the necessary market data subscriptions.
  fix 1. Double-check your `Contract` definition (symbol, secType, exchange, currency). 2. Ensure your IB account has the required market data subscriptions. 3. Verify `whatToShow`, `barSizeSetting`, and `useRTH` parameters are valid for the given contract and time period. Use `ib.reqContractDetails(contract)` to get valid contract information.

Warnings

• gotcha The PyPI package name is `ib-async`, but the actual Python package to import is `ib_insync`.
  Fix: Always use `from ib_insync import ...` in your Python code after `pip install ib-async`.
• gotcha ib-async requires a running Interactive Brokers TWS (Trader Workstation) or IB Gateway instance to connect to. It does not connect directly to IB servers.
  Fix: Ensure TWS or IB Gateway is running and configured to allow API connections on the specified host and port (default TWS: 7497, Gateway: 4002). Check TWS/Gateway API settings for `Enable ActiveX and Socket Clients` and `Read-Only API` permissions.
• breaking Between versions 1.x (original ib_insync) and 2.x (ib-async fork), there were significant internal changes and some API adjustments. For example, `util.startLoop()` is less commonly used, with `IB.run()` or direct `asyncio.run()` preferred for managing the event loop.
  Fix: Review the official ib-async documentation for the latest API usage, especially for event loop management and certain data request methods. Update your code to use `IB.run()` or `asyncio.run()` to start your main async function.
• gotcha Incorrectly mixing `asyncio.run()` with `IB.run()` or calling `IB.run()` multiple times in a single script can lead to `RuntimeError: Event loop is already running.`
  Fix: Use either `IB.run()` (which manages the asyncio loop internally for convenience) OR `asyncio.run()` (for direct asyncio control), but not both to start the main application. If using `IB.run()`, ensure it's called only once per application run.

Install

• pip install ib-async Install ib-async

Imports

• IB
  wrong:

  from ib_async import IB

  correct:

  from ib_insync import IB

  Despite `pip install ib-async`, the actual Python package name is `ib_insync`. Attempting to import `ib_async` will result in a `ModuleNotFoundError`.
• Contract

  from ib_insync import Contract

• util

  from ib_insync import util

  The `util` module provides helper functions, including `util.run()` for running async code synchronously, though `IB.run()` is often preferred.

Quickstart

This quickstart demonstrates how to connect to the Interactive Brokers TWS/Gateway, define a stock contract, and retrieve 1-minute historical trade data for the last 10 minutes using the `IB.run()` method to manage the asyncio event loop. Ensure TWS/Gateway is running and API access is enabled.

from ib_insync import IB, Contract, util
import asyncio

async def main():
    ib = IB()
    try:
        # Connect to TWS/Gateway. Default is localhost:7497 for TWS, 4002 for Gateway.
        # Change host/port if TWS/Gateway is running elsewhere.
        await ib.connect('127.0.0.1', 7497, clientId=1)

        print("Connected to IB TWS/Gateway")

        # Define a contract
        contract = Contract(symbol='SPY', secType='STK', exchange='SMART', currency='USD')

        # Request market data
        # Ensure you have subscribed to market data for SPY in TWS/Gateway
        # Data from reqMktData is real-time, consider historical data for backtesting
        # for data in ib.reqMktData(contract):
        #    print(f"Time: {data.time}, Bid: {data.bid}, Ask: {data.ask}")

        # Request historical data for the last 10 minutes
        bars = await ib.reqHistoricalData(
            contract, 
            endDateTime='', 
            durationStr='10 T', 
            barSizeSetting='1 min', 
            whatToShow='TRADES', 
            useRTH=True
        )

        if bars:
            print(f"Retrieved {len(bars)} historical bars for {contract.symbol}")
            for bar in bars:
                print(f"Time: {bar.date}, Open: {bar.open}, Close: {bar.close}, Volume: {bar.volume}")
        else:
            print(f"No historical data found for {contract.symbol}")

    except ConnectionRefusedError:
        print("Connection refused. Is TWS/Gateway running and configured for API access?")
    except Exception as e:
        print(f"An error occurred: {e}")
    finally:
        if ib.isConnected():
            ib.disconnect()
            print("Disconnected from IB TWS/Gateway")

# ib-async recommends using IB.run() for managing the event loop for simpler cases
# or asyncio.run() for more complex applications.

# To run the async main function:
if __name__ == '__main__':
    # Use IB.run() for simple script execution without manually managing asyncio loop
    IB.run(main())
    # Alternatively, for more control over the asyncio event loop:
    # asyncio.run(main())