stoqey/ib Node.js Client Library

The configuration system compiles a single config object by layering multiple sources in a specific order of precedence. This allows you to define common defaults and override them for specific environments or local development.

Precedence Order (Highest to Lowest):

1. process.env environment variables (only those listed in envsToInclude in configuration.ts)
2. Environment-specific JSON files (e.g., staging.json)
3. local.json (used for local overrides, typically gitignored)
4. default.json (contains common configuration and null keys for schema definition)

The package provides two distinct API interfaces:

1. IBApi: Replicates the official TWS API as closely as possible. It uses a request/event design where you call functions and register event callbacks via an EventEmitter. This is ideal for migrating existing Java/C++ code.

2. IBApiNext (Preview): A newer, usability-focused API built on RxJS 7. It moves away from the request/event model:

   • One-shot functions: Return a Promise (e.g., getCurrentTime, getContractDetails).
   • Endless stream subscriptions: Return an Observable (e.g., getAccountSummary, getMarketData). Note that the complete callback for these Observables will never be invoked; do not attempt to convert them to Promises.

Note: IBApiNext is in preview and its interface may change.

Install the Interactive Brokers Typescript API client library using npm or yarn.

$ npm install @stoqey/ib

or

$ yarn add @stoqey/ib

Non-secret configurations

Use default.json for common settings and environment-specific JSON files for environment-specific non-secret settings.

Secret configurations

Do not store secrets in JSON files. Use environment variables for all secret configurations. The configuration system will automatically include these in the final config object if they are registered in configuration.ts via the envsToInclude array.

Local development overrides

You can use local.json to store local-only configurations (both secret and non-secret). This file is ignored by git. Alternatively, you can use a .env file for local development.

To test locally, use the provided IB Gateway Docker container.

WARNING: Always test on a papertrading account as tests may involve buying or selling financial instruments.

1. Copy sample.env to .env and fill in your account info.
2. Install dependencies: yarn.
3. Compile TypeScript: yarn build.
4. Start the container: docker-compose up (use -d for background mode).
5. If using docker-compose, you may need to change IB_PORT from 4002 to 4004 in your .env.
6. To stop the container: docker-compose down.

To run existing Jest tests:

• All tests: yarn test
• Specific test file: jest src/test/unit/api/api.test.ts

The tif property determines how long an order remains active. Valid values include:

• DAY: Valid for the current trading day only.
• GTC: Good until canceled. Automatically canceled if corporate actions occur, if you don't log in for 90 days, or at the end of the calendar quarter following the current quarter.
• IOC: Immediate or Cancel. Any portion not filled immediately is canceled.
• FOK: Fill-or-Kill. The entire order must execute immediately or the whole order is canceled.
• GTD: Good until Date. Requires specifying goodTillDate.
• OPG: Use for Market-on-Open (MOO) or Limit-on-Open (LOO) orders.
• DTC: Day until Canceled.

In versions 1.2.1 and later, values that are not available no longer return Number.MAX_VALUE (to match the Java API). Instead, they return undefined.

If your code checks for Number.MAX_VALUE, you must update it to check for undefined.

Example Change:

Old (1.1.x):

ib.on(EventName.pnlSingle, (reqId, pos, dailyPnL, unrealizedPnL, realizedPnL, value) => {
  // unrealizedPnL and realizedPnL might be Number.MAX_VALUE
});

New (1.2.x+):

ib.on(EventName.pnlSingle, (reqId, pos, dailyPnL, unrealizedPnL, realizedPnL, value) => {
  // unrealizedPnL and realizedPnL might be undefined
});

To place an order, first obtain a valid order ID using reqIds() and listen for the nextValidId event. Then, construct a Contract and an Order object and pass them to placeOrder().

ib.once(EventName.nextValidId, (orderId: number) => {
  const contract: Contract = {
    symbol: "AMZN",
    exchange: "SMART",
    currency: "USD",
    secType: SecType.STK,
  };

  const order: Order = {
    orderType: OrderType.LMT,
    action: OrderAction.BUY,
    lmtPrice: 1,
    orderId,
    totalQuantity: 1,
    account: "YOUR_ACCOUNT_ID",
  };

  ib.placeOrder(orderId, contract, order);
});

ib.connect();
ib.reqIds();

When connecting to Interactive Brokers, use the following ports based on your account type and platform: