What is returned by the IB Portfolio skill?

A JSON object with connected and positions; each position includes symbol, quantity, avg_cost, market_value, unrealized_pnl.

What if I’m not connected?

Make sure TWS or IB Gateway is running and API is enabled; the output will indicate not connected.

Which port should I use?

Use 7497 for paper trading and 7496 for live trading unless you’ve configured differently.

ib-portfolio

npx machina-cli add skill staskh/trading_skills/ib-portfolio --openclaw

Files (1)

SKILL.md

1.1 KB

IB Portfolio

Fetch current portfolio positions from Interactive Brokers.

Prerequisites

User must have TWS or IB Gateway running locally with API enabled:

Paper trading: port 7497
Live trading: port 7496

Instructions

Note: If uv is not installed or pyproject.toml is not found, replace uv run python with python in all commands below.

uv run python scripts/portfolio.py [--port PORT]

Arguments

--port - IB port (default: 7496 for live trading)
--account - Specific IB account ID (optional, defaults to first account)

Output

Returns JSON with:

connected - Whether connection succeeded
positions - Array of positions with symbol, quantity, avg_cost, market_value, unrealized_pnl

If not connected, explain that TWS/Gateway needs to be running.

Dependencies

ib-async

Source

git clone https://github.com/staskh/trading_skills/blob/main/.claude/skills/ib-portfolio/SKILL.mdView on GitHub

Overview

This skill retrieves your current Interactive Brokers portfolio positions from a locally running TWS or IB Gateway. It shows holdings with symbol, quantity, avg_cost, market_value, and unrealized_pnl in a JSON payload. It relies on the ib-async dependency and connects via the IB API to pull live portfolio data.

How This Skill Works

It runs scripts/portfolio.py (via uv run python or plain python) to connect to IB on port 7496 for live trading or 7497 for paper trading. It accepts an optional --account and returns JSON with a connected flag and a positions array. Each position includes symbol, quantity, avg_cost, market_value, and unrealized_pnl.

When to Use It

When you want to see current holdings before a trade or rebalancing
When a user asks 'What stocks do I own?' or 'What are my IB positions?'
When evaluating risk or P&L by symbol with real-time data
When auditing a client’s portfolio or preparing a report
When diagnosing connectivity or IB API issues (check connected status)

Quick Start

Step 1: Ensure TWS/IB Gateway is running with API enabled
Step 2: Run the command: uv run python scripts/portfolio.py --port 7496 [--account AMEX-12345] (use 7497 for paper trading; if uv is unavailable, replace with python)
Step 3: Review the JSON output for connected and positions

Best Practices

Ensure TWS or IB Gateway is running with API enabled before requesting data
Use the correct port: 7497 for paper trading, 7496 for live trading
Provide an --account if you want a specific IB account; otherwise defaults apply
Verify the output JSON contains connected and a positions array with required fields
Run in a secure environment and refresh data before critical decisions

Example Use Cases

User asks, 'What positions do I hold in IB right now?'
Advisor pulls the client’s holdings to assess diversification
Trader checks symbol-by-symbol unrealized_pnl before price moves
Finance team generates a daily portfolio snapshot for a report
System validates that the IB connection is active and returns positions

Frequently Asked Questions

Add this skill to your agents