ibkr

Original：🇺🇸 English

Translated

1 scriptsChecked / no sensitive code detected

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.

15installs

Sourcestarchild-ai-agent/official-skills

Added on2026-08-30

NPX Install

npx skill4agent add starchild-ai-agent/official-skills ibkr

SKILL.md Content

View Translation Comparison →

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

.

--profile paper

guards against accidentally hitting a live account.

Usage

pip install ib_async

(first run). JSON output. Default profile

paper

(port 7497).

bash

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.