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. cancelneeds 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_IDif TWS complains about a client id already in use.