SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsibkr-readonly

ibkr-readonly

Data & analytics

View repository

Updated 10-16 10:18

About this skill

IBKR Read-Only Query Skill

⚠️ Safe Mode: This skill can only query data,cannot execute any trading operations。

Architecture

Via IB Gateway (desktop version) + ib_insync (socket API) direct connection, replacing the previously unstable Client Portal Gateway HTTP solution.

Component Description
IB Gateway IBKR official desktop application, resident in the background, supports Auto Restart
ib_insync Python socket API client, built-in automatic reconnection
keepalive.py Health check script, sends Telegram notifications when disconnected

Features

Feature Description
✅ View positions Display all stock positions, cost, market value, profit and loss
✅ View balance Display cash balance, net assets
✅ Real-time market data Query real-time prices of any stock
✅ In-depth fundamentals Query company market cap, P/E ratio, EPS, dividend yield, and industry classification
✅ Historical candlesticks Obtain price series for the past N days/months/years for trend analysis
✅ Market scan Query market-wide top gainers, top losers, and unusual activity lists
❌ Place order Not supported
❌ Modify order Not supported
❌ Cancel order Not supported

🤖 AI Assistant Agent Execution Protocol

As the user's dedicated quantitative and investment analysis advisor, when you are awakened to execute this skill,you absolutely must not merely return dry numbers or answer without thinking. You must execute the following "Four-Step Deep Investment Research Method"：

  1. Extract Core Data (Data Anchoring)
    • You must obtain, by executing /Users/qibaoba/clawd/skills/ibkr-trader/scripts/ibkr_readonly.py , the latest fundamental indicators (P/E, market cap, 52-week high and low) and the latest news for the query target (such as IBM, LMND, etc.).
  2. Mandatory Web Search
    • RSS news alone is not enough! You must use your search_web tool to search the entire web for the company'slatest macro events, earnings call transcripts, product developments, and industry competitor moves(for example: when answering about IBM, you must search for the impact of the current AI industry such as Anthropic/OpenAI on its moat).
  3. Reasoning and Logic Chain (Chain of Thought & Reasoning)
    • Do not merely list news! You must analyze how these external variables (competitor launches, macro policies) will affect the company's future earnings expectations (EPS) and valuation (P/E). Analyze market sentiment and explain theunderlying deep logic。
  4. Output Executive Summary
    • Reply to the user in a professional, clearly organized format. It must include:1. 📊 盘面与基本面速览，2. 🌪️ 核心事件驱动 (结合 web search 深度信息)，3. 🧠 深度竞品与护城河分析，4. 💡 总结与投资视角。

Prerequisites

  1. IBKR account (live or paper trading)
  2. Install the IBKR Key App on your phone (2FA is required for the first login to IB Gateway)
  3. Mac requires Java 17+ and Python 3.9+
  4. IB Gateway Desktop app (download from the IBKR official website)

Quick Setup

1. Install dependencies

# 安装 Java
brew install openjdk@17

# Python 虚拟环境（已有则跳过）
cd ~/trading
source venv/bin/activate
pip install ib_insync requests

2. Install IB Gateway

Download from the IBKR official website IB Gateway (Stable channel)： https://www.interactivebrokers.com/en/trading/ibgateway-stable.php

After installation, launch it and log in with liusaibot (phone 2FA confirmation required).

3. Configure IB Gateway API Settings

In the IB Gateway interface:

  • ✅ Enable ActiveX and Socket Clients
  • ❌ Read-Only API(Do not check this, as it will block some query APIs. Security is ensured at the account level)
  • Port:4001 (live)
  • Trusted IPs：127.0.0.1
  • ✅ Auto Restart(Settings → Lock and Exit → Auto restart, automatically restarts every Sunday)

4. Configure environment variables

~/trading/.env：

IB_HOST=127.0.0.1
IB_PORT=4001
IB_CLIENT_ID=1

5. Test connection

cd ~/trading && source venv/bin/activate
python ibkr_readonly.py

Usage

View positions and balances

cd ~/trading && source venv/bin/activate
python ibkr_readonly.py

Using in OpenClaw

Ask directly in Telegram:

  • "What are my IBKR positions?"
  • "Help me check my position profit and loss"
  • "Help me look at Apple's (AAPL) recent fundamentals, how are its market cap and P/E ratio?"
  • "Using IBKR historical data, analyze NVDA's trend over the past 3 months"
  • "Which 10 US stocks rose the most today?"

Health Check

Check IB Gateway status every 5 minutes via keepalive.py, and send a Telegram notification when disconnected:

# Crontab
*/5 * * * * cd ~/trading && source venv/bin/activate && python keepalive.py >> ~/trading/keepalive.log 2>&1

IB Gateway has built-in Auto Restart, so manual intervention is usually not needed. Manual operation is only required in the following situations:

  • IB Gateway process is killed
  • After the Mac mini restarts
  • During IBKR maintenance

Troubleshooting

Problem Solution
Connection failed Check whether IB Gateway is started and logged in: see whether there is an IB Gateway window on the desktop
Port unreachable Check whether the port in API Settings is 4001 and whether Socket Clients is checked
Authentication expired IB Gateway Auto Restart will handle it automatically; if it fails, manually restart IB Gateway and log in
Process not running After the Mac restarts, IB Gateway needs to be started manually

Security Notes

This skill is designed to becompletely read-only：

  • The source code contains no order placement API calls
  • IBKRReadOnlyClient When connecting, use the readonly=True parameter
  • The liusaibot sub-account itself also has no trading permissions
  • Even if someone requests an order, the skill cannot execute it