## What This Blueprint Helps You Build

This blueprint shows you how to connect Claude to Interactive Brokers so you can inspect your portfolio, analyze positions, receive alerts, and optionally test trade execution from a paper account.

The recommended approach keeps investment decisions under your control while delegating repetitive work to Claude. Start with read only analysis. Add execution only after the analysis workflow is reliable, and test every execution feature with paper trading first.

The complete architecture has three possible levels:

| Level | Capability | Recommended use |
|---|---|---|
| 1 | Claude reads your IBKR account through the official integration | Portfolio analysis, exposure checks, trade reviews, and research |
| 2 | Claude connects to Trader Workstation through its programming interface | Controlled paper trade execution from your computer |
| 3 | A Telegram bridge connects your phone to the computer running Claude | Mobile analysis, scheduled reports, alerts, and optional paper execution |

You do not need to implement every level. For most investors, Level 1 plus mobile alerts provides the majority of the practical value.

## Important Operating Principle

Do not begin by allowing Claude to choose and execute investments autonomously.

A safer division of responsibility is:

* You make discretionary investment decisions.
* Claude retrieves account data and performs analysis.
* Claude monitors predefined conditions.
* Claude prepares or executes simple instructions only when you explicitly authorize them.
* Large or unusual transactions remain manual.

AI systems can misunderstand instructions or produce incorrect output. Keep order confirmation enabled during experimentation and use an IBKR paper trading account before considering live execution.

## Prerequisites

Prepare the following before starting:

* An Interactive Brokers account.
* Access to Claude Code on the computer running the workflow.
* A local project folder for prompts, configuration, and portfolio memory.
* Interactive Brokers Trader Workstation if you plan to test execution.
* Python if you plan to use the Trader Workstation programming interface.
* A Telegram account if you want mobile access.
* A separate computer or hosted machine that can remain running if you want continuous alerts.

The transcript does not identify the specific Python library used in the original implementation. Ask Claude Code to inspect the current IBKR interface and select a compatible, maintained connection method rather than assuming a particular package.

## Step 1: Create the Local Project

Keep the entire assistant in one folder so Claude can reference your portfolio policy, prompts, and configuration consistently.

Suggested structure:

```text
ibkr-portfolio-assistant/
  README.md
  portfolio-policy.md
  prompts.md
  config/
  scripts/
  logs/
```

Do not store brokerage passwords or Telegram tokens inside Markdown files. Enter authentication information only through the broker login flow or the local secret handling method selected during setup.

Use this prompt in Claude Code:

```text
Create a local project for an Interactive Brokers portfolio assistant.

Use this structure:

ibkr-portfolio-assistant/
  README.md
  portfolio-policy.md
  prompts.md
  config/
  scripts/
  logs/

The assistant must begin in analysis only mode. It must not place, modify, or cancel orders unless I later enable a separate paper trading execution workflow.

Keep portfolio policies and reusable prompts in Markdown files. Do not place brokerage credentials, authentication codes, or Telegram tokens in those files.

Create the folders and starter files, then explain what was created.
```

## Step 2: Connect the Official IBKR Integration

Interactive Brokers provides an official connection that allows Claude to inspect account information. This route is suitable for analysis because instructions do not automatically become orders.

Use the broker supplied authorization process. Depending on your setup, you can initiate it through the supported application or provide the official connection address to Claude Code. The broker login should take place through the broker controlled authentication screen.

After authorization, Claude may be able to inspect information such as:

* Positions.
* Cash and available buying power.
* Margin.
* Profit and loss.
* Transaction history.
* Risk exposure.

Run this verification prompt after connecting:

```text
Verify the official Interactive Brokers connection in read only mode.

Before doing any analysis, report:

1. The account number or masked account identifier you are connected to.
2. Whether the connection is read only.
3. The account currency.
4. Current account value.
5. Available cash or buying power.
6. Open positions.

Do not prepare, place, modify, or cancel any order.
```

Confirm that the account shown is the one you intended to connect.

## Step 3: Run the Core Portfolio Analysis Prompts

Save the following prompts in `prompts.md` so they can be reused without rewriting them.

### Account Snapshot

```text
Using my connected Interactive Brokers account, give me a current portfolio snapshot.

Include:

1. Total account value.
2. Cash balance.
3. Available buying power or dry powder.
4. Total unrealized profit and loss.
5. Total realized profit and loss if available.
6. Every open position with its current weight in the portfolio.
7. My five largest exposures.

Clearly state the account identifier and the time associated with the account data. Do not place any orders.
```

### Recent Trade Review

```text
Summarize all trades from the last month using my connected account data.

Calculate or report:

1. Number of trades.
2. Total commissions paid.
3. Win rate where it can be determined from the available records.
4. Average trade size.
5. Largest winning trade.
6. Largest losing trade.
7. Positions with the highest total commission cost.

Separate facts pulled from the account from calculations or interpretations. Do not place any orders.
```

### Volatility Review

```text
Review every current holding in my portfolio.

For each holding, provide the latest available implied volatility and its position relative to the 52 week high and low when that information is available.

Rank the holdings from most volatile to least volatile. Identify which positions contribute the most risk based on both volatility and portfolio weight.

If the connected brokerage data does not contain a required field, say which field is missing rather than estimating it. Do not place any orders.
```

### Currency Stress Test

```text
Analyze the currency exposure of my current portfolio.

Identify my largest foreign currency exposures and estimate the portfolio impact if the US dollar weakens by 10 percent against those exposures.

Show:

1. Exposure by currency.
2. Exposure as a percentage of total portfolio value.
3. The estimated effect of the scenario.
4. Which positions create the largest currency sensitivity.

State any assumptions required for the analysis. Do not place any orders.
```

### Geographic Concentration

```text
Using my live portfolio, estimate my exposure to the United States versus other global markets.

Break the portfolio down by country or region where the available data permits. Identify any significant concentration and compare it with the targets in portfolio-policy.md.

If a security has multinational exposure that cannot be determined from the account data, mark it as uncertain rather than assigning a false level of precision. Do not place any orders.
```

### Opportunity Cost Review

```text
Review my portfolio performance over the last 12 months using the available account history.

Identify positions or allocations that contributed most to performance and those that created the greatest opportunity cost. Explain how alternative allocations would have changed the result only when the necessary historical data is available.

Separate historical facts from hypothetical analysis. Do not place any orders.
```

### Fundamentals Review With Optional Data Connections

```text
Review my current semiconductor positions against the latest earnings information available through my connected data sources.

Identify anything that materially changes the original investment case, including major changes in revenue, margins, guidance, or risk when those fields are available.

For every material claim, identify the connected source used. If current earnings data is not available, say so and do not present older information as current. Do not place any orders.
```

The transcript suggests adding dedicated equity data providers when deeper market or fundamental data is required. Only use a provider you have separately connected. Claude should not imply that live external data is available when it is not.

## Step 4: Create a Portfolio Policy Memory File

A portfolio policy gives Claude a stable reference for comparing your actual holdings with your goals. Build it through a voice or text conversation, then save the result as `portfolio-policy.md`.

Use this interview prompt:

```text
Help me create a portfolio policy that you can use when analyzing my connected brokerage account.

Interview me one topic at a time about:

1. My financial situation and investing time horizon.
2. My risk tolerance.
3. My maximum acceptable drawdown.
4. My preferred geographic exposure.
5. My preferred currency exposure.
6. My maximum position size.
7. My concentration limits by sector or market.
8. The conditions that would invalidate an investment thesis.
9. Which decisions must always remain manual.
10. Whether any paper trading execution is permitted.

Do not recommend trades during the interview. After I answer, produce a concise Markdown policy for portfolio-policy.md. Mark any unanswered item as undefined rather than inventing a target.
```

Use this file structure:

```markdown
## Portfolio Objectives

Investment horizon:
Primary objectives:
Liquidity requirements:

## Risk Limits

Maximum acceptable drawdown:
Maximum position size:
Maximum sector concentration:

## Exposure Targets

United States exposure target:
Foreign market exposure target:
Currency exposure targets:

## Decision Rules

Conditions that invalidate a position:
Decisions that must remain manual:
Permitted paper trading actions:

## Execution Status

Current mode: Analysis only
Approved brokerage account:
Last reviewed:
```

Review this file manually before allowing Claude to use it as an operating reference.

## Step 5: Configure Trader Workstation for Paper Execution

Skip this step if you only want analysis and alerts.

Install Interactive Brokers Trader Workstation and log in to your paper trading account. In its settings, review the following items:

1. Enable connections from external programs.
2. Confirm whether the API is read only. Leave it read only for analysis. Disable read only only when intentionally testing paper execution.
3. Accept connections only from the device running the assistant.
4. Keep order confirmation enabled during experimentation.
5. Configure Trader Workstation to restart daily if you intend to keep the system running continuously.
6. Record the displayed socket port.
7. Verify that the port belongs to the paper account, since paper and live accounts may use different ports.

Use this connection prompt in Claude Code:

```text
I have Interactive Brokers Trader Workstation running and logged in to my paper trading account.

API access is enabled. The socket port shown in Trader Workstation is [PORT].

Check whether Python is installed. If it is not installed, explain what is missing before making any system changes. Create an isolated project environment and use a currently compatible Interactive Brokers connection method.

Connect to Trader Workstation and retrieve only:

1. The connected account number.
2. Whether it is a paper or live account.
3. The account summary.
4. Open positions.
5. Whether the connection permits order submission.

Do not submit, modify, or cancel an order. Before anything else, tell me exactly which account you are connected to.
```

Do not proceed unless Claude reports the expected paper account.

## Step 6: Test a Controlled Paper Order

Use explicit instructions. Avoid vague requests such as “reduce my risk” or “rebalance everything.” Keep manual order confirmation enabled for initial tests.

Copy and customize this prompt:

```text
Paper trading test only.

Before taking action, report:

1. The connected account number.
2. Whether the account is paper or live.
3. The ticker and side of the proposed order.
4. The requested quantity or notional value.
5. The order type.

The proposed instruction is:

Buy [QUANTITY OR NOTIONAL VALUE] of [TICKER] in the paper account using [ORDER TYPE].

Do not submit the order until I confirm after reviewing the details. If the connected account is not my approved paper account, stop immediately.
```

After reviewing the proposed order, use a separate confirmation:

```text
I confirm the paper order exactly as displayed. Submit it only to the verified paper account, then return the order identifier and current order status.
```

Inspect the resulting order inside Trader Workstation. Do not assume that a generated response proves an order was accepted or filled.

## Step 7: Add a Telegram Mobile Bridge

Telegram can act as a messaging bridge between your phone and the computer running Claude. The portfolio data and account connection remain on the computer. Telegram is only the messaging interface.

The intended message flow is:

```text
Telegram on phone
        ↓
Local listener script
        ↓
Claude workflow and local memory
        ↓
Trader Workstation or read only broker connection
```

Create a bot through Telegram BotFather and obtain its token. Treat that token like a password. Anyone with access to the bot connection or computer may be able to interact with the workflow.

Use this setup prompt:

```text
Inside this project, create a small local Telegram bridge for my portfolio assistant.

The bridge should:

1. Listen for messages sent to my Telegram bot.
2. pass those messages to the existing Claude portfolio workflow.
3. Return the response through Telegram.
4. Keep portfolio policy and brokerage data on this computer.
5. Use the Telegram bot token as a local secret rather than writing it into a Markdown file or printing it in logs.
6. Begin in analysis only mode.
7. Reject all requests to place, modify, or cancel orders until I explicitly enable the separate paper execution workflow.
8. Explain how to start and stop the listener.

Ask me for the bot token only when the local secret configuration is ready. Do not include the token in generated documentation or output.
```

If you want voice message support, add:

```text
Add voice message transcription to the Telegram bridge using Whisper if it is available on this computer.

Transcribe each voice message to text, show me the transcription, and then send the text into the portfolio workflow. Do not interpret a voice transcription as approval for a trade unless the separate paper execution confirmation process has been completed.
```

You can also use a separate voice transcription application on your phone and send the resulting text through Telegram.

## Step 8: Configure Reports and Alerts

### Morning Portfolio Report

```text
Create a scheduled morning portfolio report based on my connected account.

The report should include:

1. Current account value.
2. Change since the previous report.
3. Overnight changes affecting my holdings when current data is available.
4. Largest position gains and losses.
5. Material changes in portfolio concentration.
6. Any portfolio policy limit that is currently exceeded.

Send the report through the configured Telegram bridge. This is an analysis task only. Do not place or prepare orders.
```

### Daily Movement Alert

```text
Monitor my connected portfolio and message me through Telegram if any position falls more than 3 percent during a single trading day.

For each alert, include:

1. Ticker and position name.
2. Percentage move.
3. Current position size and portfolio weight.
4. Time associated with the observed data.

Do not sell, reduce, or modify the position automatically. Send an alert only.
```

Be precise when defining scheduled conditions. Incorrect wording can cause misleading alerts or unintended behavior.

## Security and Execution Checklist

Before leaving the system running, verify every item:

* The official integration is read only unless execution is intentionally required.
* Trader Workstation is connected to the paper account during testing.
* Claude reports the account identifier before any execution request.
* Order confirmation remains enabled during experimentation.
* Connections are accepted only from the intended device.
* The Telegram token is not stored in prompts, Markdown files, or logs.
* The computer has a strong password.
* Two factor authentication is enabled for Claude and Telegram.
* A separate device is used for the continuous workflow where practical.
* Large or unusual transactions remain manual.
* Scheduled alerts never contain automatic execution unless you have deliberately built and tested that separate behavior.

## Recommended Final Configuration

For a practical first version, use this combination:

1. Official IBKR integration in read only mode.
2. A reviewed `portfolio-policy.md` file.
3. Reusable analysis prompts.
4. Telegram access for mobile queries.
5. A scheduled morning report.
6. Movement alerts without automatic selling.
7. Trader Workstation connected only to a paper account for controlled execution experiments.

This setup removes much of the repetitive work involved in monitoring a portfolio while keeping discretionary decisions and high impact execution under your control.