Getting it connected
There are two things to set up. First, BrokerBridge itself. Second, when you are ready, your Interactive Brokers account: the broker BrokerBridge sends orders to. You keep your own account there. BrokerBridge is not affiliated with, endorsed by, or sponsored by Interactive Brokers. You can try BrokerBridge with practice money before either of those is required. This page covers both, in order.
New here?
Start with the Quickstart for the short path: install, try it with practice money, then connect a real account when you want to.
Open Quickstart →On this page
System requirements
| Requirement | Details |
|---|---|
| Operating system | macOS for the supported packaged launch. Other operating systems are contributor-only until a current package passes release verification. |
| Python | 3.11 or higher |
| Broker | No broker needed for practice money or the AI Arena. Interactive Brokers with IB Gateway or TWS for a connected desk. |
| AI provider | Supported provider account or API key, local Ollama, or pay-as-you-go BrokerBridge credits |
| Local models | Ollama on the same computer; available memory, disk, and GPU support must fit the model you choose |
| Network | Internet for hosted AI calls; localhost for local Ollama and Interactive Brokers connections |
For local-model setup and hardware guidance, see Run a local model with Ollama.
Practice money or a connected account
The fastest way to try BrokerBridge needs no account at all: enter your email to download the macOS app, pick a direct AI provider or Ollama, set your rules, and explore with practice money. A full BrokerBridge account is required when you move into activation, buying credits, or a connected Interactive Brokers desk. No Young Money Investments membership is required.
- 1.Enter your email on the download page, then explore with practice money. No BrokerBridge account, card, access code, or broker connection needed.
- 2.For a connected desk, create and verify your BrokerBridge account, then choose how you will pay for AI: a direct provider, local Ollama, or pay-as-you-go credits.
- 3.Activate the macOS app, connect an Interactive Brokers practice account, and confirm the broker mode before turning on order permissions.
- 4.Set your rules, then choose how you approve trades per strategy: Supervised (you approve each trade), I confirm from the alert (you tap to confirm within a time window), or I approve the strategy up front (a strategy trades on its own once you give it your standing approval in writing, and the strategy has passed review). The AI Arena competition has a separate practice-money-only track and never touches your broker connection.
Credits: pay-as-you-go AI credits are a metered account you top up separately from installing the app, purchased from the dashboard whenever you need them.
Installation
Download and open the current macOS installer. The packaged app is the supported customer path; the source workflow below is for contributors and is not a substitute for a verified customer release.
For development, clone the repository and install editable with dev extras:
git clone https://github.com/YoungMoneyInvestments/broker-bridge-retail.git cd broker-bridge-retail uv venv .venv && source .venv/bin/activate uv pip install -e ".[dev]"
IB Gateway setup
BrokerBridge connects to Interactive Brokers through IB Gateway (one of two apps Interactive Brokers ships that let other software talk to your account; either one works, and it has to be running) or Trader Workstation (TWS). IB Gateway is recommended for always-on trading.
- 1.Download IB Gateway from the Interactive Brokers website.
- 2.Launch IB Gateway and log in with your Interactive Brokers credentials.
- 3.Enable API connections: Configure → Settings → API → Settings
- • Check "Enable ActiveX and Socket Clients"
- • Set Socket port to
4002(Gateway) or7497(TWS) - • Uncheck "Read-Only API" if you want to place orders
- • Add
127.0.0.1to trusted IPs
- 4.Click Apply and OK. IB Gateway is now ready for BrokerBridge to connect.
Warning: For practice-account trading, use a practice (paper) trading account. IB Gateway port 4002 is the default for the practice account. Port 4001 is real, live trading. Double-check your port setting.
Config file reference
BrokerBridge loads config from these locations in priority order:
BROKERBRIDGE_CONFIG_PATHenvironment variableconfig/config.yamlrelative to the project root~/.brokerbridge/config.yamlin your home directory
ai_provider
| Field | Type | Default | Description |
|---|---|---|---|
| name | string | "anthropic" | Provider: anthropic, openai, google, xai, openrouter (DeepSeek and other open-source models) |
| model | string | "claude-sonnet-4-20250514" | Model identifier for the chosen provider |
| max_tokens | int | 4096 | Maximum tokens in AI response |
| temperature | float | 0.3 | Sampling temperature (lower = more deterministic) |
| timeout_seconds | int | 30 | API request timeout |
broker
| Field | Type | Default | Description |
|---|---|---|---|
| host | string | "127.0.0.1" | IB Gateway/TWS host address |
| port | int | 4002 | Socket port (4002=Gateway paper, 4001=Gateway live, 7497=TWS) |
| client_id | int | 1 | Unique client ID (use different IDs for multiple connections) |
| account | string | "" | Your Interactive Brokers account ID |
| paper_trading | bool | true | Use the practice (paper) account |
| readonly | bool | false | Connect in read-only mode (no order placement) |
trading
| Field | Type | Default | Description |
|---|---|---|---|
| symbols | list[str] | [] | Ticker symbols to scan |
| scan_interval_seconds | int | 300 | How often to scan for opportunities |
| approval_timeout_seconds | int | 300 | How long a trade plan waits for approval before it expires |
| min_conviction_score | float | 0.6 | Minimum AI confidence (how sure it is) needed to generate a trade plan (0.0-1.0) |
| session_start | string | "09:30" | Trading session start time (ET) |
| session_end | string | "16:00" | Trading session end time (ET) |
Credential setup
BrokerBridge supports two ways to sign in an AI provider:
OAuth (your existing subscription)
Sign in with your existing AI provider subscription (e.g., Claude Pro, ChatGPT Plus). BrokerBridge does not include AI provider access; you use your own account.
API Key (bring your own)
Use your own API key from the provider. You pay the provider directly for usage. The key is encrypted on your computer.
Credentials are stored using Fernet symmetric encryption with a key derived from your machine fingerprint via PBKDF2. See the Security page for details.
Setting your rules
Your rules check every trade plan before it reaches the broker, and they keep applying to strategies set to I approve the strategy up front or I confirm from the alert. Configure them in the risk section.
| Rule | Config Key | Default | What it does |
|---|---|---|---|
| Position size | max_position_pct | 2% | Blocks trades exceeding this % of account value |
| Open trades | max_positions | 5 | Blocks new trades when you have this many open |
| Daily P&L cap | max_daily_loss_pct | 3% | Halts all trading when daily loss exceeds this |
| Sector concentration | sector_concentration_pct | 40% | Blocks trades that would over-concentrate one sector |
| Portfolio exposure | portfolio_max_exposure_pct | 80% | Blocks trades if total exposure exceeds this % of account |
How you approve is a separate choice from your rules: BrokerBridge supports Supervised approval and I approve the strategy up front, selectable per strategy. Standing approval is granted per strategy, turn on as many as you want, and each one stays inside its own money limit, your rules, allowed instruments, schedule, and broker mode, on top of the kill switch, expiry, pause, and recovery safeguards. The AI Arena competition is practice-money only, and you can turn any strategy off any time.
Common setup issues
"Config file not found"
BrokerBridge uses default values if no config is found. Create config/config.yaml from the example, or set BROKERBRIDGE_CONFIG_PATH.
"Cannot connect to IB Gateway"
Verify IB Gateway is running and the API port matches your config. Check that "Enable ActiveX and Socket Clients" is enabled and 127.0.0.1 is in the trusted IP list.
"PyYAML not installed"
This is a contributor-environment error, not a normal packaged-app step. Reinstall the repository's declared development dependencies in its isolated environment; packaged users should use the installer repair flow or contact support.