IBKR TWS API setup
Figures on this page are as of 2026-09. Fees, limits and margin tiers change — check the venue's own docs before acting on a number.
The TWS API is not a web API. It is a TCP socket to a running desktop application, which means nothing works unless Trader Workstation or IB Gateway is open and logged in. Everything below follows from that.
Before you start: IBKR has two entirely separate API products. The TWS API (sockets, desktop app) and the Client Portal Web API (REST, local gateway) are different systems, and code for one does not port to the other. This covers the TWS API.
Before you start
You need TWS or IB Gateway installed and logged in, and the account you intend to use. Whether you are targeting a live account or its paper counterpart, the live account must be fully open and funded.
IB Gateway is the lighter option — no charting, less memory — and is the usual choice for anything long-running.
Step 1: enable socket clients
Global Configuration → API → Settings. In TWS Classic: Edit → Global Configuration. In Mosaic: File → Global Configuration, or the cog wheel in the top right. In IB Gateway: Configure → Settings → API → Settings.
Tick “Enable ActiveX and Socket Clients”.
This is off by default in TWS. A fresh TWS install refuses API connections entirely. IB Gateway, by contrast, accepts socket API connections by default — which is a common source of “it works on the Gateway but not in TWS”.
Step 2: untick Read-Only API — deliberately
In the same panel is Read-Only API, available in TWS 950 and above. It “allows viewing of market data and account information, but blocks any type of trading activity.”
It is enabled by default and will block all API orders.
If you are reading data, leave it on. It is a genuinely good boundary and it is free.
If you intend to place orders, untick it — and recognise what you just did. This is the moment your setup goes from unable-to-trade to able-to-trade, and unlike most venues, IBKR made you take that step explicitly.
Debugging note. If API orders are being rejected and everything else works — connection fine, market data fine, account data fine — check this checkbox before you look at your code. It is the most common cause by a wide margin, and the symptom looks nothing like a permissions problem.
Step 3: confirm the port
| Target | Default port |
|---|---|
| TWS live | 7496 |
| TWS paper | 7497 |
| IB Gateway live | 4001 |
| IB Gateway paper | 4002 |
These are defaults and are editable. The port configured in TWS must match the
port in your client’s connect() call.
The live/paper split arrived in TWS v954, specifically so both accounts could run at the same time — production kept 7496 and paper took 7497; Gateway paper moved from 4001 to 4002.
Step 4: connect
app.connect("127.0.0.1", 7497, 0) # host, port, clientIdHost is 127.0.0.1 or localhost when the code runs on the same machine as
TWS.
Client ID 0 is documented as recommended for optimal order-management
behaviour. TWS supports up to 32 simultaneous API connections, each needing
its own client ID.
If connecting from another machine, add its address under Trusted IP addresses in the same settings panel — a connection from a trusted IP is not challenged; others produce a verification prompt, which will block an unattended process.
What goes wrong
Error 502 "Couldn't connect to TWS" — the standard port/settings
mismatch. Working through it: is TWS running and logged in; is “Enable ActiveX
and Socket Clients” ticked; does the port in your code match the port in
settings; are you pointed at 7497 when TWS is running a live session on 7496.
Orders rejected, everything else fine — Read-Only API, step 2.
Works on Gateway, not on TWS — socket clients are on by default in Gateway and off in TWS.
Connection challenged or hanging — a verification prompt is waiting because the connecting address is not in Trusted IP addresses.
Paper and live confusion — the ports are the only thing distinguishing them in your code. It is worth logging which port you connected to at startup.
The constraint you cannot engineer around
The TWS API requires a logged-in desktop application. Any plan involving unattended, long-running automation inherits that: something has to keep TWS or IB Gateway running and authenticated.
The Client Portal Web API does not avoid this — it trades one constraint for another. It is REST rather than sockets, but it requires its own local gateway, presents a self-signed certificate warning at login, is rate limited to 10 requests per second per authenticated username, and IBKR does not support automated authentication: clients must re-authenticate daily.
So on both paths there is a recurring human step. This is not a gap in any library and not something a wrapper can abstract away — it is how IBKR works. Budget for it rather than discovering it in week two.
For context, IBKR is consolidating its web API products (Client Portal Web API, Digital Account Management, Flex Web Service) into a unified Web API using OAuth 2.0, with existing endpoints not deprecated. Whether that changes the daily authentication requirement is not something to assume.
FAQ
Why are my TWS API orders being rejected?
Almost certainly the Read-Only API setting, which is enabled by default from TWS 950 onward and blocks all API trading while leaving market data and account information working. Global Configuration → API → Settings. The symptom is distinctive: everything reads fine and only orders fail.
What port should I use for paper trading?
7497 for TWS paper and 4002 for IB Gateway paper, against 7496 and 4001 for
live. These are configurable defaults, so the real answer is whatever is set in
your Global Configuration → API → Settings panel — and the port in your
connect() call must match it.
Can I run IBKR automation without keeping TWS open?
Not via the TWS API — it is a socket to the running application. The Client Portal Web API replaces that with its own local gateway, but requires daily re-authentication with no automated path, so there is a human step either way.
Why does my connection work from the Gateway but not TWS?
“Enable ActiveX and Socket Clients” is off by default in TWS and on by default in IB Gateway. Tick it in the TWS settings panel.