@stoqey/ib Overview

@stoqey/ib is an Interactive Brokers TWS (Trader Workstation) and IB Gateway API client library for Node.js, fully implemented in TypeScript.

It is a direct port of Interactive Brokers' official Java Client Version 10.32.01 (released October 2024).

Key Features

• TypeScript Native: Full type safety for Contracts, Orders, Market Data, Account Summaries, Executions, and Callbacks.
• Pure Node.js Socket Connection: Communicates directly over TCP sockets using Node's net module—no native wrapper binaries needed.
• Dual API Paradigms:
  • IBApi: Event-driven architecture mirroring the official TWS C++/Java API via EventEmitter.
  • IBApiNext: Reactive architecture leveraging RxJS 7 Observables and Promises for simplified subscription & data flow management.
• Docker-Ready: Works out of the box with headless IB Gateway running locally or in containerized environments.

High-Level Wrapper Available: @stoqey/ibkr

If you are looking for ready-to-use manager singletons (like automatic account cache, portfolio snapshot management, order trade events, and market data managers), check out @stoqey/ibkr!

@stoqey/ibkr is built directly on top of @stoqey/ib to provide a developer-friendly high-level interface.

Architecture Diagram

graph TD
    Sub[Your Node.js Application] -->|Events / RxJS| SDK["@stoqey/ib API Client"]
    SDK -->|IBApi| EventModel[EventEmitter]
    SDK -->|IBApiNext| RxJSModel[RxJS Observables & Promises]
    EventModel --> TCP[Node.js TCP Socket net Module]
    RxJSModel --> TCP
    TCP <-->|Port 4001/4002/7496/7497| TWS[IB Gateway / TWS Workstation]
    TWS <-->|Secure IBKR Network| IBServer[Interactive Brokers Servers]

Quick Example (IBApi)

import { IBApi, EventName, Contract, SecType } from "@stoqey/ib";

// Create API instance
const ib = new IBApi({ port: 7497 });

// Register event handlers
ib.on(EventName.position, (account, contract, pos, avgCost) => {
  console.log(`Position: ${account} | ${pos} x ${contract.symbol} @ $${avgCost}`);
});

ib.once(EventName.positionEnd, () => {
  console.log("Finished retrieving positions.");
  ib.disconnect();
});

// Connect & request data
ib.connect();
ib.reqPositions();

Next Steps