IBeam Documentation

IBeam requires IBKR credentials to automate login, which introduces security risks because credentials must be stored (e.g., as environment variables).

Mitigation Strategies:

• Docker Swarm: Use Docker Secrets to inject credentials into the container's in-memory /run filesystem. This protects credentials at rest, though they remain accessible in plaintext within the running container.
• GCP Secret Manager: If running on Google Cloud Platform (Compute Engine, Kubernetes, Cloud Run, or Cloud Functions), IBeam can use the Service Account's identity to securely retrieve secrets from GCP Secret Manager via the metadata server.

IBeam automates the maintenance and authentication of the Interactive Brokers Client Portal Web API Gateway through the following lifecycle:

1. Input Sync: Copies files from the Inputs Directory to the Gateway's root folder.
2. Gateway Check: Verifies if the Gateway is running via a tickle endpoint; if not, it attempts to start it.
3. Authentication: If no active authenticated session is found, IBeam:
   • Starts a virtual display using pyvirtualdisplay.
   • Uses selenium with a Chrome Driver instance to access the Gateway's authentication page.
   • Automatically injects the IBEAM_ACCOUNT and IBEAM_PASSWORD into the login form.
   • Waits for login confirmation and then quits the browser.
4. Maintenance Loop: Continuously monitors the session and repeats the login process if the session becomes unauthenticated or inactive.

The WebSocket communication follows two patterns:

1. Solicited (↑↓): You must explicitly send a request to receive data. The format is TOPIC+{ARGUMENTS}.
   • The first letter of the topic determines the action: s for subscribe or u for unsubscribe.
   • + is the separator between the topic and arguments.
   • Use an empty argument {} if no arguments are required.
   • Responses will relay back the topic of the request.
2. Unsolicited (↓↓): The server sends data to you without an incoming request (e.g., system status, notifications).

You can install IBeam using either the recommended Docker image or as a standalone Python package.

Docker (Recommended): Pull the official image from Docker Hub.

Standalone: Install via pip.

Note: IBeam is designed for the Interactive Brokers Client Portal Web API Gateway. It is not intended for automating TWS or IB Gateway (use IBC instead).

# Docker
docker pull voyz/ibeam

# Standalone
pip install ibeam

After starting the gateway, you must authenticate via a web browser to enable API access.

1. Open your browser and navigate to https://localhost:5000/.
2. Log in using your standard credentials on the login page.
3. Once authenticated, the gateway will display a confirmation message indicating the client is authenticated and it is safe to close the browser.

Once this process is complete, the API endpoints will be available for querying via curl or other HTTP clients.

For a more structured deployment, use Docker Compose. This requires an env.list file for credentials and a compose.yaml file.

Important: network_mode: bridge is required due to the clientportal.gw IP whitelist requirements.

# compose.yaml
services:
  ibeam:
    image: voyz/ibeam
    container_name: ibeam
    env_file:
      - env.list
    ports:
      - 5000:5000
      - 5001:5001
    network_mode: bridge # Required due to clientportal.gw IP whitelist
    restart: 'no' # Prevents IBEAM_MAX_FAILED_AUTH from being exceeded

# env.list
IBEAM_ACCOUNT=your_account123
IBEAM_PASSWORD=your_password123

docker compose up -d

To prevent the WebSocket connection from timing out, you should send a heartbeat using the ech+hb topic. It is recommended to send a heartbeat at least once per minute.

Request Format: ech+hb

// Send a heartbeat to maintain connection
ws.send('ech+hb');

Download the Client Portal gateway zip file and extract it to a directory accessible by your user.

Recommended installation paths:

• Windows: C:\gateway\
• Linux: ~user\gateway

Prerequisites:

• Java: Requires Java 1.8 update 192 or higher. OpenJDK 11 is a tested and recommended version.

Directory Structure:

• bin/: Contains run scripts for Linux (.sh) and Windows (.bat).
• build/: Contains required 3rd party libraries.
• dist/: Contains the gateway .jar file.
• doc/: Contains documentation.
• root/: Contains runtime configuration files and webapps.

Download URL: http://download2.interactivebrokers.com/portal/clientportal.gw.zip

To start the gateway, open a command prompt (Windows) or bash (Linux) and navigate to the directory where you extracted the files. Run the appropriate script from the bin directory, passing the path to your configuration file (e.g., root/conf.yaml) as an argument.

Verification: Once started, look for the following message in the console to confirm it is running: Server listening on port 5000

Default Settings:

• Mode: SSL
• Port: 5000

# Linux
bin/run.sh root/conf.yaml

# Windows
bin\run.bat root\conf.yaml

If installed via pip, you can start IBeam by running the starter script.

python ibeam_starter.py

To use WebSocket streaming for market data, orders, and PnL updates, you must first authenticate your gateway session using the standard login instructions. Once you receive the message "Client login succeeds", you can establish a connection to the following endpoint:

wss://localhost:5000/v1/api/ws

To run IBeam in a container, provide your IBKR credentials via environment variables. Map port 5000 to access the Gateway.

docker run --env IBEAM_ACCOUNT=your_account123 --env IBEAM_PASSWORD=your_password123 -p 5000:5000 voyz/ibeam