ibkr

Imported from starchild-ai-agent/official-skills (ibkr/SKILL.md). Install upstream with npx skills add starchild-ai-agent/official-skills --skill ibkr. Copyright stays with the author.

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:

1. Run locally — run TWS/Gateway + this script on your own computer. (simplest)
2. 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)

1. Download TWS or IB Gateway from interactivebrokers.com → Trading → Platforms. IB Gateway is lighter and headless-friendly; TWS is the full GUI.
2. Log in. Paper trading: IBKR gives every account a free paper login (account id starts with DU); log into the paper session for testing.
3. 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.
4. Default ports: 7497 = TWS paper, 7496 = TWS live, 4002 = IB Gateway paper, 4001 = IB Gateway live.
5. 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.

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.