What this is — read this first
🖥️ Local-gateway broker. IBKR has no key-based public API. You run Trader Workstation (TWS) or the lighter IB Gateway on a machine, log in, enable the API socket, and this CLI connects over a local socket. Your IBKR credentials live in TWS — they never reach this skill.
⚠️ This will NOT work from the Starchild container by default, because TWS runs on your computer and the container's 127.0.0.1 is the container itself. Two ways to use it:
- Run locally — run TWS/Gateway + this script on your own computer. (simplest)
- Bridge the network — run IB Gateway on a host the container can reach, add the container's IP to TWS's "Trusted IPs", and set
IBKR_HOST/IBKR_PORT. You handle network/security; never expose the API socket to the open internet.
If status says the socket isn't listening, this is why.
Set up TWS / IB Gateway (one time)
- Download TWS or IB Gateway from interactivebrokers.com → Trading → Platforms. IB Gateway is lighter and headless-friendly; TWS is the full GUI.
- Log in. Paper trading: IBKR gives every account a free paper login (account id starts with
DU); log into the paper session for testing.
- Enable the API: TWS → File → Global Configuration → API → Settings → check "Enable ActiveX and Socket Clients". For trading, leave "Read-Only API" unchecked (read-only blocks order placement). Note the Socket port.
- Default ports: 7497 = TWS paper, 7496 = TWS live, 4002 = IB Gateway paper, 4001 = IB Gateway live.
- Market data requires the relevant data subscriptions on the account, or quotes/bars return empty.
Configure (.env)
No secret keys — only the gateway location. Request via secure input if non-default.
| Variable |
Required |
Notes |
IBKR_HOST |
no |
default 127.0.0.1 |
IBKR_PORT |
no |
overrides the profile default (7497 paper / 7496 live) |
IBKR_CLIENT_ID |
no |
API client id, default 1 (use distinct ids for concurrent connections) |
IBKR_ACCOUNT |
no |
pin a specific account code (e.g. DU1234567); blank = first managed account |
Paper accounts start with DU, live with U. --profile paper guards against accidentally hitting a live account.
Usage
pip install ib_async (first run). JSON output. Default profile paper (port 7497).
python skills/ibkr/scripts/ibkr_cli.py status # checks socket + lists managed accounts
python skills/ibkr/scripts/ibkr_cli.py account
python skills/ibkr/scripts/ibkr_cli.py positions
python skills/ibkr/scripts/ibkr_cli.py orders [--executions]
python skills/ibkr/scripts/ibkr_cli.py quote --symbol AAPL
python skills/ibkr/scripts/ibkr_cli.py history --symbol AAPL --duration "30 D" --bar-size "1 day"
# place (paper): qty in units; market or limit; contract defaults STK/SMART/USD
python skills/ibkr/scripts/ibkr_cli.py place --symbol AAPL --side buy --qty 10 --type limit --limit-price 180 --tif day
python skills/ibkr/scripts/ibkr_cli.py cancel --order-id <numeric-id>
# live (real money): TWS on live port + --confirm-live
python skills/ibkr/scripts/ibkr_cli.py --profile live --confirm-live place --symbol AAPL --side buy --qty 1
Non-US / non-stock instruments: pass --exchange, --currency, --sec-type (e.g. --sec-type CASH --symbol EUR --currency USD --exchange IDEALPRO for forex). history uses IB's --duration ("30 D", "1 Y") and --bar-size ("1 day", "1 hour", "5 mins").
Gotchas
- "socket not listening" / connection refused = TWS not running, not logged in, on another machine, wrong port, or API socket disabled. Re-read setup step 3.
- For order placement, "Read-Only API" must be OFF in TWS settings — otherwise placement is silently blocked even with
--confirm-live.
cancel needs the numeric IBKR order id and only cancels orders currently open in this session/account.- Quotes/history return empty without the right market-data subscription on the account.
- Use a unique
IBKR_CLIENT_ID if TWS complains about a client id already in use.
1---2name: ibkr3description: Interactive Brokers — global stocks/forex/futures via a LOCAL TWS/IB Gateway, not cloud. Covers stocks, ETFs, forex, futures; account, positions, orders, quotes, history, order placement. Use when the user wants to check or trade an Interactive Brokers account (e.g. "IBKR positions", "buy 10 AAPL on IBKR paper", "my IB account net liq"). Requires a running TWS / IB Gateway — NOT a cloud key.4---5
6## What this is — read this first
7
8🖥️ **Local-gateway broker.** IBKR has **no key-based public API**. You run **Trader Workstation (TWS)** or the lighter **IB Gateway** on a machine, log in, enable the API socket, and this CLI connects over a local socket. Your IBKR credentials live in TWS — they never reach this skill.
9
10**⚠️ This will NOT work from the Starchild container by default**, because TWS runs on *your* computer and the container's `127.0.0.1` is the container itself. Two ways to use it:
11
121. **Run locally** — run TWS/Gateway + this script on your own computer. (simplest)
132. **Bridge the network** — run IB Gateway on a host the container can reach, add the container's IP to TWS's "Trusted IPs", and set `IBKR_HOST`/`IBKR_PORT`. You handle network/security; never expose the API socket to the open internet.
14
15If `status` says the socket isn't listening, this is why.
16
17## Set up TWS / IB Gateway (one time)
18
191. Download **TWS** or **IB Gateway** from [interactivebrokers.com](https://www.interactivebrokers.com) → Trading → Platforms. IB Gateway is lighter and headless-friendly; TWS is the full GUI.
202. Log in. **Paper trading:** IBKR gives every account a free paper login (account id starts with `DU`); log into the paper session for testing.
213. Enable the API: **TWS → File → Global Configuration → API → Settings** → check **"Enable ActiveX and Socket Clients"**. For trading, leave **"Read-Only API" unchecked** (read-only blocks order placement). Note the **Socket port**.
224. Default ports: **7497** = TWS paper, **7496** = TWS live, **4002** = IB Gateway paper, **4001** = IB Gateway live.
235. Market data requires the relevant **data subscriptions** on the account, or quotes/bars return empty.
24
25## Configure (.env)
26
27No secret keys — only the gateway location. Request via secure input if non-default.
28
29| Variable | Required | Notes |
30|---|---|---|
31| `IBKR_HOST` | no | default `127.0.0.1` |
32| `IBKR_PORT` | no | overrides the profile default (7497 paper / 7496 live) |
33| `IBKR_CLIENT_ID` | no | API client id, default `1` (use distinct ids for concurrent connections) |
34| `IBKR_ACCOUNT` | no | pin a specific account code (e.g. `DU1234567`); blank = first managed account |
35
36Paper accounts start with `DU`, live with `U`. `--profile paper` guards against accidentally hitting a live account.
37
38## Usage
39
40`pip install ib_async` (first run). JSON output. Default profile `paper` (port 7497).
41
42```bash
43python skills/ibkr/scripts/ibkr_cli.py status # checks socket + lists managed accounts
44python skills/ibkr/scripts/ibkr_cli.py account
45python skills/ibkr/scripts/ibkr_cli.py positions
46python skills/ibkr/scripts/ibkr_cli.py orders [--executions]
47python skills/ibkr/scripts/ibkr_cli.py quote --symbol AAPL
48python skills/ibkr/scripts/ibkr_cli.py history --symbol AAPL --duration "30 D" --bar-size "1 day"
49# place (paper): qty in units; market or limit; contract defaults STK/SMART/USD
50python skills/ibkr/scripts/ibkr_cli.py place --symbol AAPL --side buy --qty 10 --type limit --limit-price 180 --tif day
51python skills/ibkr/scripts/ibkr_cli.py cancel --order-id <numeric-id>
52# live (real money): TWS on live port + --confirm-live
53python skills/ibkr/scripts/ibkr_cli.py --profile live --confirm-live place --symbol AAPL --side buy --qty 1
54```
55
56Non-US / non-stock instruments: pass `--exchange`, `--currency`, `--sec-type` (e.g. `--sec-type CASH --symbol EUR --currency USD --exchange IDEALPRO` for forex). `history` uses IB's `--duration` ("30 D", "1 Y") and `--bar-size` ("1 day", "1 hour", "5 mins").
57
58## Gotchas
59
60- "socket not listening" / connection refused = TWS not running, not logged in, on another machine, wrong port, or API socket disabled. Re-read setup step 3.
61- For order placement, **"Read-Only API" must be OFF** in TWS settings — otherwise placement is silently blocked even with `--confirm-live`.
62- `cancel` needs the **numeric IBKR order id** and only cancels orders currently open in this session/account.
63- Quotes/history return empty without the right **market-data subscription** on the account.
64- Use a unique `IBKR_CLIENT_ID` if TWS complains about a client id already in use.
starchild-ai-agent