Risk Radar Setup Guide

← Back to Risk Radar

Risk Radar Setup Guide

Estimated time: 20-30 minutes

Risk Radar runs as a local agent on your machine, next to your IB Gateway or TWS. Your IBKR credentials never leave your machine. The dashboard and alert history are hosted at risk-radars.com.

Component Runs Where You Need To
Agent Your machine Install + configure
IB Gateway Your machine Running with API enabled
Telegram bot Your Telegram Create via @BotFather
Dashboard risk-radars.com Just open in browser

1 Create a Dedicated IBKR Monitor User

Required. Risk Radar must use a separate IBKR username from your trading login. If you skip this step, IBKR will disconnect one session when the other logs in.
User Purpose Used By
TRADER_USER Your normal trading login TWS, Mobile app
MONITOR_USER Read-only monitoring Risk Radar + IB Gateway

How to create the monitor user

  1. Log in to IBKR Account Management
  2. Go to Settings → Users & Access Rights
  3. Create a new user (e.g., “RiskRadar Monitor”)
  4. Assign minimum permissions: read-only, trading disabled, access to account values/portfolio/positions
  5. Wait for IBKR approval (1-2 business days)

Once approved, launch IB Gateway and log in as your monitor user. Keep it running.

Required IB Gateway / TWS Settings

Open the API settings in your IB Gateway or TWS (Edit → Global Configuration → API → Settings) and configure:

Setting Value Why
Enable ActiveX and Socket Clients Checked ✅ Required — this is how Risk Radar connects
Socket port 4001 (Gateway live) or 4002 (Gateway paper) Must match IBKR_PORT in your .env
Read-Only API Checked ✅ (recommended) Extra safety — prevents any order placement even if code has a bug
Allow connections from localhost only Checked ✅ Security — only local connections accepted
Master API client ID Leave empty Avoids client ID conflicts

Then go to Configure → Lock and Exit:

Setting Value Why
Auto Logoff Timer Set a time (e.g., 11:45 PM) IB Gateway shuts down daily at this time
Auto restart Selected ✅ Gateway restarts automatically after logoff — keeps Risk Radar connected
Important: If you leave Auto logoff selected (the default), IB Gateway will shut down and NOT restart. Risk Radar will lose connection permanently until you manually restart Gateway. Always select Auto restart.
Important: If Enable ActiveX and Socket Clients is not checked, Risk Radar cannot connect. This is the most common setup issue.
Why IB Gateway instead of TWS? Gateway has a smaller footprint and is more stable for always-on monitoring. TWS works too — use the same API settings above.

2 Prerequisites

  • Python 3.10+ — check with python3 --version
  • IB Gateway running and logged in as your monitor user
  • Telegram account
macOS note: If python3 --version shows 3.9.x, install a newer version: brew install python@3.10 and use python3.10 instead.

3 Install the Agent

During onboarding, you will receive two files:

  • risk_radar-0.1.0-py3-none-any.whl — the agent package
  • .env.example — configuration template
# Create a directory for Risk Radar
mkdir risk-radar && cd risk-radar

# Create virtual environment (first time only)
python3 -m venv .venv

# Activate
source .venv/bin/activate   # macOS/Linux

# Install the agent from the .whl file you received
pip install risk_radar-0.1.0-py3-none-any.whl

After install, the risk-radar command is available in your virtual environment.

4 Create Your Telegram Bot

  1. Open Telegram, search for @BotFather
  2. Send /newbot and follow the prompts
  3. Copy the bot token (looks like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)
  4. Send any message to your new bot
  5. Get your chat ID: open https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates and find "chat":{"id":123456789}

5 Configure .env

cp .env.example .env

Edit .env with your values:

# IBKR Connection (your local IB Gateway)
IBKR_HOST=127.0.0.1
IBKR_PORT=4001
IBKR_CLIENT_ID=100

# Telegram (your own bot)
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_CHAT_ID=your_chat_id_here
TELEGRAM_ENABLED=true

# Backend (provided during onboarding)
BACKEND_URL=https://risk-radars.com/api
CF_ACCESS_CLIENT_ID=provided_during_onboarding
CF_ACCESS_CLIENT_SECRET=provided_during_onboarding
Security: .env contains your Telegram token and backend credentials. Never commit it to git. Never share it. The CF_ACCESS values authenticate your agent to our backend — they are not your IBKR credentials.

6 Test Telegram

Before connecting to IBKR, verify Telegram works:

source .venv/bin/activate
risk-radar --test-alert

Success: You receive a test message in Telegram.

Error Fix
404 Not Found Bot token is wrong — re-check with @BotFather
400 Bad Request Chat ID is wrong — re-check via /getUpdates
Unauthorized Token is malformed — copy again, no extra spaces
Timeout Check internet connection

7 Start the Agent

Make sure IB Gateway is running with your monitor user logged in:

source .venv/bin/activate
risk-radar

You should see:

  • Connected to IBKR in the terminal
  • Account poll successful messages
  • Dashboard at risk-radars.com shows your account
  • Telegram sends connection notification

8 Run Persistently

macOS / Linux (tmux)

tmux new-session -d -s risk-radar \
  'cd /path/to/risk-radar && source .venv/bin/activate && risk-radar'

# Reattach anytime:
tmux attach -t risk-radar

Linux (systemd)

[Unit]
Description=Risk Radar Agent
After=network.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/path/to/risk-radar
ExecStart=/path/to/risk-radar/.venv/bin/risk-radar
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

During beta, we’ll help you configure persistent operation during your onboarding call.

Troubleshooting

Problem Fix
Can’t connect to IBKR Check IB Gateway is running, API enabled, port matches .env
No Telegram alerts Run --test-alert first. Check bot token and chat ID
Dashboard shows no data Check BACKEND_URL and CF credentials in .env
Agent exits on start Check Python 3.10+ and all deps installed
IBKR disconnects when trading You’re using the same username for both. Create a dedicated monitor user (Step 1)

What Risk Radar Does NOT Do

  • No trading — read-only, cannot place or cancel orders
  • No IBKR credentials stored server-side — your login stays on your machine
  • No trading signals — no predictions, informational only
  • No kill switch — cannot shut down your trading system

Need Help?

This is early beta. If setup fails at any step, contact the founder directly. We’ll walk you through it.

← Back to Risk Radar