Installation & Setup

How to install @stoqey/ib and configure socket connections to TWS or IB Gateway.

Package Installation

Install @stoqey/ib using your preferred Node.js package manager:

# npm
npm install @stoqey/ib

# yarn
yarn add @stoqey/ib

# pnpm
pnpm add @stoqey/ib

@stoqey/ib requires an active connection to an instance of Interactive Brokers Trader Workstation (TWS) or IB Gateway.

Before your Node.js application can establish a socket connection, API access must be enabled in TWS or IB Gateway:

Open TWS or IB Gateway.
Navigate to Edit -> Global Configuration -> API -> Settings.
Check Enable ActiveX and Socket Clients.
Set Socket port to match your environment (4001, 4002, 7496, or 7497).
(Recommended) Uncheck Read-Only API if you intend to place or modify orders.
Ensure Trusted IP Addresses includes 127.0.0.1 (or your client server IP if running remotely).

Paper Trading Recommended

Always test your API code on a paper trading account (7497 or 4002) before connecting to a live trading account.

If you prefer running a headless IB Gateway environment without installing TWS locally:

# Clone the repository
git clone https://github.com/stoqey/ib.git
cd ib

# Set environment credentials
cp sample.env .env

Edit your .env file with your IB Gateway credentials:

TWS_USERID=your_ib_username
TWS_PASSWORD=your_ib_password
TRADING_MODE=paper
IB_PORT=4002

Start IB Gateway with Docker Compose:

docker-compose up -d

Your IB Gateway instance is now ready to receive socket connections on port 4002!