Installation and configuration

This guide covers Stripe Checkout, installation, activation, IB Gateway configuration, the complete config file reference, and credential setup.

New here?

Start with the Quickstart -- short steps with screenshots (diagrams you can swap for real photos).

Open Quickstart →

System requirements

Requirement	Details
Operating system	macOS, Linux, or Windows 10+
Python	3.11 or higher
Broker	Interactive Brokers account with IB Gateway or TWS
AI provider	Anthropic, OpenAI, OpenRouter, or Google AI account
Network	Internet for AI API calls; localhost for IBKR connection

Purchase and activation

BrokerBridge access now starts with embedded Stripe checkout on the pricing page. After checkout, install the app locally and activate it from the desktop using the same email address you used at checkout.

1.Start from the pricing page or homepage form and complete Stripe Checkout for your subscription.
2.Install BrokerBridge locally, then launch it. The activation flow appears before trading features unlock.
3.On the Activate BrokerBridge screen, enter the same email address you used at checkout.
4.Need to update billing or cancel later? Use the in-app Manage subscription button to open the Stripe customer portal.

Activation handoff: BrokerBridge no longer uses manual license keys for website purchases. Stripe Checkout confirms the subscription, and the desktop app activates by email after install.

Installation

After purchase, install BrokerBridge into a virtual environment. BrokerBridge requires Python 3.11+ and pulls in FastAPI, Pydantic, httpx, ib_insync, and cryptography as dependencies.

terminal

python -m venv .venv
source .venv/bin/activate    # macOS/Linux
# .venv\Scripts\activate     # Windows

pip install "git+https://github.com/YoungMoneyInvestments/broker-bridge-retail.git"

For development, clone the repo 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 your broker through IB Gateway (headless) 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 IBKR credentials.
3.
Enable API connections: Configure → Settings → API → Settings
- • Check "Enable ActiveX and Socket Clients"
- • Set Socket port to 4002 (Gateway) or 7497 (TWS)
- • Uncheck "Read-Only API" if you want to place orders
- • Add 127.0.0.1 to trusted IPs
4.Click Apply and OK. IB Gateway is now ready for BrokerBridge to connect.

Warning: For paper trading, use a paper trading account. IB Gateway port 4002 is the default for paper mode. Port 4001 is live trading. Double-check your port setting.

Config file reference

BrokerBridge loads config from these locations in priority order:

BROKERBRIDGE_CONFIG_PATH environment variable
config/config.yaml relative to the project root
~/.brokerbridge/config.yaml in your home directory

ai_provider

Field	Type	Default	Description
name	string	"anthropic"	Provider: anthropic, openai, openrouter, google
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 IBKR account ID
paper_trading	bool	true	Enable paper trading mode
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 proposals wait for approval before expiring
min_conviction_score	float	0.6	Minimum AI conviction to generate a proposal (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 authentication methods for AI providers:

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. Key is encrypted locally.

Credentials are stored using Fernet symmetric encryption with a key derived from your machine fingerprint via PBKDF2. See the Security page for details.

Risk settings guide

Five risk gates evaluate every proposal before it reaches you. Configure them in the risk section.

Gate	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

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"

PyYAML is a dependency of broker-bridge-retail. If you see this error, reinstall: pip install "git+https://github.com/YoungMoneyInvestments/broker-bridge-retail.git".

← Quickstart AI Providers →