# ib-api-reloaded/ib_async architecture

> Architecture diagram of the GitHub repository ib-api-reloaded/ib_async, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ib-api-reloaded/ib_async
- Repository: https://github.com/ib-api-reloaded/ib_async

## Overview

ib_async is a Python sync/async client library for Interactive Brokers TWS and IB Gateway. A user calls the high-level IB interface to connect, request market/account/research data, or submit orders; the client encodes requests over a socket, then decodes replies into synchronized state and events. Contracts and orders model request inputs, while ticker and object types represent results. Additional capabilities include Flex Web Service reports and optional TWS/Gateway lifecycle monitoring. The README documents the broader feature set; some subsystem wiring is represented only at the documented capability level because its source was not sampled.

Main entry points: [`ib_async/ib.py`](https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/ib.py) (IB interface), [`ib_async/wrapper.py`](https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/wrapper.py) (State and events), [`ib_async/client.py`](https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/client.py) (Socket client), [`ib_async/connection.py`](https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/connection.py) (Socket transport)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["User API"]
  node_ib["IB interface<br/>[ib.py]"]
  node_util["Async utilities<br/>[util.py]"]
end

subgraph group_protocol["IB Protocol"]
  node_client["Socket client<br/>[client.py]"]
  node_connection["Socket transport<br/>[connection.py]"]
  node_decoder["Message decoder<br/>[decoder.py]"]
  node_wrapper["State and events<br/>[wrapper.py]"]
end

subgraph group_domain["Trading Data"]
  node_contract["Contracts<br/>[contract.py]"]
  node_order["Orders and trades<br/>[order.py]"]
  node_ticker["Live ticker data<br/>[ticker.py]"]
  node_objects["Result objects<br/>[objects.py]"]
  node_research["Research requests<br/>[ib.py]"]
  node_portfolio["Account and portfolio<br/>[ib.py]"]
  node_market["Market data requests<br/>[ib.py]"]
  node_trading["Order submission<br/>[ib.py]"]
end

subgraph group_integration["Integrations"]
  node_controller["Lifecycle watchdog<br/>[ibcontroller.py]"]
  node_flex["Flex reports<br/>[flexreport.py]"]
end

node_user(("Application"))
node_broker(("TWS / IB Gateway"))
node_flexservice(("Flex Web Service"))

node_user -->|"calls"| node_ib
node_ib -->|"sends requests"| node_client
node_ib -->|"tracks state"| node_wrapper
node_ib -->|"runs async"| node_util
node_client -->|"sends bytes"| node_connection
node_connection -->|"exchanges messages"| node_broker
node_connection -->|"delivers bytes"| node_client
node_client -->|"decodes replies"| node_decoder
node_decoder -->|"dispatches events"| node_wrapper
node_wrapper -->|"updates quotes"| node_ticker
node_wrapper -->|"builds results"| node_objects
node_wrapper -->|"updates trades"| node_order
node_market -->|"uses interface"| node_ib
node_ib -->|"returns data"| node_market
node_market -->|"accepts instruments"| node_contract
node_market -->|"returns live data"| node_ticker
node_market -->|"returns bars"| node_objects
node_research -->|"uses interface"| node_ib
node_ib -->|"returns details"| node_research
node_research -->|"accepts instruments"| node_contract
node_portfolio -->|"uses interface"| node_ib
node_ib -->|"returns account state"| node_portfolio
node_portfolio -->|"returns positions"| node_objects
node_trading -->|"uses interface"| node_ib
node_ib -->|"places orders"| node_trading
node_trading -->|"specifies instrument"| node_contract
node_trading -->|"specifies order"| node_order
node_controller -->|"monitors connection"| node_ib
node_controller -->|"starts or stops"| node_broker
node_flex -.->|"downloads reports"| node_flexservice
node_user -->|"requests report"| node_flex

click node_ib "https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/ib.py"
click node_util "https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/util.py"
click node_contract "https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/contract.py"
click node_order "https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/order.py"
click node_ticker "https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/ticker.py"
click node_objects "https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/objects.py"
click node_client "https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/client.py"
click node_connection "https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/connection.py"
click node_decoder "https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/decoder.py"
click node_wrapper "https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/wrapper.py"
click node_research "https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/ib.py"
click node_portfolio "https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/ib.py"
click node_market "https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/ib.py"
click node_trading "https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/ib.py"
click node_controller "https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/ibcontroller.py"
click node_flex "https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/flexreport.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ib,node_util toneBlue
class node_client,node_connection,node_decoder,node_wrapper toneAmber
class node_contract,node_order,node_ticker,node_objects,node_research,node_portfolio,node_market,node_trading toneMint
class node_controller,node_flex toneRose
class node_user,node_broker,node_flexservice toneIndigo
```

## Components

### User API

- [IB interface](https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/ib.py): `ib_async/ib.py`
- [Async utilities](https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/util.py): `ib_async/util.py`

### IB Protocol

- [Socket client](https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/client.py): `ib_async/client.py`
- [Socket transport](https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/connection.py): `ib_async/connection.py`
- [Message decoder](https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/decoder.py): `ib_async/decoder.py`
- [State and events](https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/wrapper.py): `ib_async/wrapper.py`

### Trading Data

- [Contracts](https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/contract.py): `ib_async/contract.py`
- [Orders and trades](https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/order.py): `ib_async/order.py`
- [Live ticker data](https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/ticker.py): `ib_async/ticker.py`
- [Result objects](https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/objects.py): `ib_async/objects.py`
- [Research requests](https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/ib.py): `ib_async/ib.py`
- [Account and portfolio](https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/ib.py): `ib_async/ib.py`
- [Market data requests](https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/ib.py): `ib_async/ib.py`
- [Order submission](https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/ib.py): `ib_async/ib.py`

### Integrations

- [Lifecycle watchdog](https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/ibcontroller.py): `ib_async/ibcontroller.py`
- [Flex reports](https://github.com/ib-api-reloaded/ib_async/blob/main/ib_async/flexreport.py): `ib_async/flexreport.py`

### Other components

- **Application**
- **TWS / IB Gateway**
- **Flex Web Service**

## Connections

- Application → IB interface: calls
- IB interface → Socket client: sends requests
- IB interface → State and events: tracks state
- IB interface → Async utilities: runs async
- Socket client → Socket transport: sends bytes
- Socket transport → TWS / IB Gateway: exchanges messages
- Socket transport → Socket client: delivers bytes
- Socket client → Message decoder: decodes replies
- Message decoder → State and events: dispatches events
- State and events → Live ticker data: updates quotes
- State and events → Result objects: builds results
- State and events → Orders and trades: updates trades
- Market data requests → IB interface: uses interface
- IB interface → Market data requests: returns data
- Market data requests → Contracts: accepts instruments
- Market data requests → Live ticker data: returns live data
- Market data requests → Result objects: returns bars
- Research requests → IB interface: uses interface
- IB interface → Research requests: returns details
- Research requests → Contracts: accepts instruments
- Account and portfolio → IB interface: uses interface
- IB interface → Account and portfolio: returns account state
- Account and portfolio → Result objects: returns positions
- Order submission → IB interface: uses interface
- IB interface → Order submission: places orders
- Order submission → Contracts: specifies instrument
- Order submission → Orders and trades: specifies order
- Lifecycle watchdog → IB interface: monitors connection
- Lifecycle watchdog → TWS / IB Gateway: starts or stops
- Flex reports → Flex Web Service: downloads reports
- Application → Flex reports: requests report