Install, configure, and connect

Components

Your process does not connect directly to an exchange or to a public IBKR REST endpoint. The path is:

Python process -> TCP socket -> TWS or IB Gateway -> authenticated IBKR session -> IBKR services/exchanges

Install ib_async with the same version used by this reference:

python -m pip install "ib_async==2.1.0"

In TWS/IB Gateway, enable API > Settings > Enable ActiveX and Socket Clients, choose a socket port, add remote source addresses to Trusted IPs, and disable Read-Only API only if this client is allowed to trade.

Default ports depend on the application and can be changed:

Application	Live	Paper
TWS common defaults	7496	7497
IB Gateway common defaults	4001	4002
Example container/proxy remapping	5001	5002

Never infer live versus paper from a port alone. The authenticated username/session determines the environment.

Async connection

from ib_async import IB, Stock

ib = IB()
await ib.connectAsync(
    host="127.0.0.1",
    port=4002,
    clientId=7,
    timeout=10,
    readonly=True,
    account="DU1234567",
    raiseSyncErrors=True,
)

contract = Stock("AAPL", "SMART", "USD")
[contract] = await ib.qualifyContractsAsync(contract)

connectAsync completes only after the socket handshake and the configured startup synchronization. Its parameters are:

Parameter	Meaning and edge cases
host	TWS/IBG address. Bind the gateway to private interfaces only; never expose the socket publicly.
port	Configured socket port, not an environment guarantee.
clientId	Must be unique among simultaneous API connections to that TWS/IBG. 0 has special manual-order binding behavior.
timeout	Connection and startup-request timeout. 0/None means no timeout in 2.1.0. A timeout does not prove the server rejected the request.
readonly	Suppresses order synchronization on startup; it does not change TWS permissions by itself.
account	Account selected for account updates. Empty auto-selects only when exactly one account is available.
raiseSyncErrors	Raise after startup synchronization timeouts instead of merely logging them.
fetchFields	StartupFetch bitmask controlling open/completed orders, account updates, subaccounts, and executions. Positions are requested unconditionally in 2.1.0.

The default StartupFetchALL includes positions, open orders, completed orders, account updates, subaccount updates, and executions. Completed orders require server version 150+. Execution synchronization intentionally runs after order synchronization so fills can be attached to known Trade objects.

Blocking connection

ib = IB()
ib.connect("127.0.0.1", 4002, clientId=7, timeout=10, readonly=True)

Blocking IB methods run the asyncio loop internally. They are appropriate for scripts, but do not call them from an already-running event loop. In notebooks use the environment's supported integration; in services use *Async calls.

Connection readiness

IB.isConnected() means the client considers the socket connected. Client.isReady() additionally means the handshake supplied server version, connection time, accounts, and a valid request/order-ID basis. Wait for connectAsync to finish or connectedEvent before issuing application work.

Official reference: TWS API connectivity.

Disconnect

ib.disconnect()

Disconnecting clears the wrapper's synchronized state. Capture anything needed for diagnostics or persistence before deliberately disconnecting. A disconnect does not cancel working orders at IBKR.