Paper agent setup

1. Prepare paper TWS or Gateway

Install and open the IBKR paper application yourself. Sign in and complete any required verification. Enable API socket clients and keep the socket bound to localhost. The agent supports TWS port 7497 or Gateway port 4002.

2. Install the agent

Choose the Windows ZIP or the Apple Silicon Mac app from your dashboard on the computer that runs paper TWS/Gateway. On Windows, install Python 3.11+, create a virtual environment, install the included requirements, and configure the included .env.example. On Mac, open the app, enter your platform license key, select paper TWS (7497) or Gateway (4002), and optionally enter the paper account ID. Keep the selected account in paper trading.

Windows command-line setup:

py -3.11 -m venv .venv
.venv\\Scripts\\Activate.ps1
pip install -r requirements.txt
python agent.py

3. Create a TradingView alert

Copy the private webhook URL from your dashboard. Use JSON with a unique event_id, action, symbol, and quantity. Stock and forex alerts support market or limit orders. Option alerts need expiry, strike, right, and trading class as applicable.

{
  "event_id": "{{ticker}}-{{time}}-{{strategy.order.id}}",
  "sent_at": "{{timenow}}",
  "ticker": "{{ticker}}",
  "action": "{{strategy.order.action}}",
  "quantity": "{{strategy.order.contracts}}",
  "type": "stock",
  "orderType": "MKT",
  "exchange": "SMART",
  "currency": "USD"
}

Option alert example

For a single-option flow, use type: "singloption"; BUY opens and SELL closes the specified contract. Use an explicit expiry, strike, right, and trading class.

{
  "event_id": "AAPL-option-20261218-250-C-001",
  "ticker": "AAPL",
  "action": "BUY",
  "quantity": 1,
  "type": "singloption",
  "orderType": "LMT",
  "limit_price": 3.25,
  "expiry": "20261218",
  "strike": 250,
  "right": "C",
  "tradingClass": "AAPL",
  "multiplier": "100"
}

Order states

HTTP 202 means the alert was durably queued. Unclaimed BUY/SELL entries expire after two minutes; close-only alerts remain queued. Submitted means TWS/Gateway returned an initial order status; it does not confirm a fill. If a claimed order loses its agent response, it becomes reconcile_required. Inspect the paper account before taking further action.

Apple Silicon Mac first launch

The Mac download is built for Apple Silicon (M1–M4) and contains an app bundle. Unzip it and move IBKR Automate.app to Applications. This release is not signed or notarized yet, so macOS may ask you to confirm the first launch: Control-click the app, choose Open, then confirm Open. The app stores its platform key in your macOS user Library and never asks for your IBKR password.