ibkr
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.
How do I install this agent skill?
npx skills add https://github.com/starchild-ai-agent/official-skills --skill ibkrIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a command-line interface for Interactive Brokers via a local gateway. It is safe to use and performs expected financial and account management tasks through a local socket connection without exposing credentials to the cloud.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
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.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/starchild-ai-agent/official-skills/ibkr">View ibkr on skillZs</a>