NewsLiquid IBKR Gateway

NewsLiquid IBKR Gateway is a local Chrome Native Messaging bridge for Interactive Brokers Client Portal Gateway. It lets the NewsLiquid browser extension and approved NewsLiquid web pages talk to a local Node.js host, which starts or reuses IBKR Client Portal Gateway and forwards account, market data, order, and alert requests to the local Gateway REST API.

Features

• Chrome Native Messaging Host: exposes com.newsliquid.ibkr_client_portal over Chrome's native messaging protocol.
• NewsLiquid Extension Bridge: includes a Manifest V3 extension with nativeMessaging and cookies permissions.
• Browser Login Flow: opens the local IBKR Gateway login page, then transfers Gateway cookies from the extension to the native host.
• Bundled Gateway Runtime: includes IBKR Client Portal Gateway and platform runtime files for mainstream desktop platforms.
• Gateway Process Management: discovers existing local Gateway instances or starts the bundled Gateway as a reusable detached process.
• Trading and Account Actions: supports account info, positions, market data, orders, live orders, and alerts through the local Gateway API.
• Read-only Mode: blocks write actions such as placing orders and changing alerts when enabled.

Security Notice

IMPORTANT WARNINGS:

• Financial Risk: Trading involves substantial risk of loss. Always test with paper trading first.
• Local Only: This software handles sensitive financial data and browser session cookies. Run it only on trusted local machines.
• Origin Boundaries: The included extension only injects the page bridge on https://newsliquid.com/* and https://*.newsliquid.com/*.
• No Warranty: This unofficial software comes with no warranties. Use at your own risk.
• Not Financial Advice: This tool is for automation and integration only, not financial advice.

Prerequisites

You need:

• Interactive Brokers account, paper or live trading
• Node.js 18+
• Chrome, Chromium, Microsoft Edge, or Brave
• NewsLiquid IBKR browser extension

This package includes:

• Pre-configured IBKR Client Portal Gateway
• Runtime files for macOS, Windows, and Linux builds
• Native Messaging host manifest template
• Native Messaging host installers for macOS/Linux and Windows

Quick Start

Install the package:

npm install -g @nl-trading/ibkr-gateway

The package postinstall script attempts to register the Native Messaging host for the default NewsLiquid extension ID:

com.newsliquid.ibkr_client_portal

If you are developing with an unpacked extension or a different extension ID, build and register the host manually:

npm run build
bash scripts/install-native-host.sh <chrome-extension-id>

On Windows:

npm run build
powershell -ExecutionPolicy Bypass -File scripts/install-native-host-windows.ps1 <chrome-extension-id>

Then load or install the browser extension from extension/ or the packaged extension artifact.

Authentication Flow

1. The extension connects to the native host named com.newsliquid.ibkr_client_portal.
2. The native host starts or reuses a local IBKR Client Portal Gateway.
3. The extension calls authenticate, which opens the local Gateway login page.
4. Complete IBKR login and any required 2FA in the browser.
5. The extension reads the local Gateway cookies and sends them to the native host with set_session_cookies.
6. The native host calls initialize_brokerage_session and maintains the session with periodic tickle requests.

The extension background service worker exposes debug helpers in its console:

await ibkrSmokeTest()
await ibkrAuthenticate()
await ibkrCompleteAuth()
await ibkrAccountInfo()
await ibkrPositions()
await ibkrMarketData("AAPL")
await ibkrSearchMarkets("AAPL", { secType: "STK" })
await ibkrFetchMarkets({ instrument: "STK", location: "STK.US.MAJOR", type: "MOST_ACTIVE_USD", filter: [], size: 50 })

Page Bridge

On approved NewsLiquid origins, the extension injects window.ibkr(action, params).

Example:

const status = await window.ibkr("gateway_status");
const account = await window.ibkr("get_account_info");
await window.ibkr("set_current_trading_account", { accountId: "U12345" });
const currentAccount = await window.ibkr("get_current_trading_account");
const currentSummary = await window.ibkr("get_current_trading_account_summary");
const positions = await window.ibkr("get_positions", { pageId: 0 });
const quote = await window.ibkr("get_market_data", { symbol: "AAPL" });
const secdef = await window.ibkr("searchMarkets", { symbol: "AAPL", secType: "STK" });
const activeStocks = await window.ibkr("fetchMarkets", {
  instrument: "STK",
  location: "STK.US.MAJOR",
  type: "MOST_ACTIVE_USD",
  filter: [],
  size: 50,
});

For web pages, the extension currently allows these read-oriented actions:

| Action | Params | | ------ | ------ | | ping | {} | | gateway_status | {} | | auth_status | {} | | get_account_info | {} | | set_current_trading_account | { accountId: string } | | get_current_trading_account | {} | | get_current_trading_account_summary | {} | | get_positions | { accountId?: string, pageId?: string \| number, model?: string, sort?: string, direction?: string, period?: string } | | get_market_data | { symbol: string, exchange?: string } | | searchMarkets | { symbol: string, name?: boolean, secType?: string } | | fetchMarkets | { instrument: string, location: string, type: string, filter?: Array<{ code: string, value?: number \| string \| boolean }>, size?: number } | | get_order_status | { orderId: string \| number } | | cancel_order | { orderId: string \| number, accountId?: string } | | get_live_orders | { accountId?: string } |

Native Host Protocol

The native host uses Chrome's Native Messaging framing: each message is UTF-8 JSON prefixed with a 4-byte little-endian message length.

Request shape:

{
  "id": "request-id",
  "action": "gateway_status",
  "params": {}
}

Response shape:

{
  "id": "request-id",
  "ok": true,
  "result": {}
}

Errors use:

{
  "id": "request-id",
  "ok": false,
  "error": {
    "code": "REQUEST_FAILED",
    "message": "Error message"
  }
}

Native Host Actions

| Action | Description | | ------ | ----------- | | ping | Check host liveness, Gateway port, Gateway readiness, and read-only mode. | | gateway_status | Ensure Gateway is ready and return URL, port, readiness, and auth status. | | authenticate | Ensure Gateway is ready and optionally open the local Gateway login page. | | set_session_cookies | Accept Gateway cookies collected by the browser extension. | | initialize_brokerage_session | Initialize the IBKR brokerage session after login cookies are available. | | auth_status | Return current authentication status and Gateway URL. | | get_account_info | Retrieve account information and balances. | | get_positions | Get positions for an account or the cached current trading account. | | get_market_data | Retrieve market data for a symbol and optional exchange. | | searchMarkets | Search /iserver/secdef/search by symbol or company name. | | fetchMarkets | Run /iserver/scanner/run using an IBKR scanner query. | | place_order | Place market, limit, or stop orders. Disabled in read-only mode. | | confirm_order | Confirm an order reply. Disabled in read-only mode. | | cancel_order | Cancel an open order by order ID and optional account ID. Disabled in read-only mode. | | get_order_status | Check order status by order ID. | | get_live_orders | Get open/live orders for an optional account ID. | | get_alerts | List alerts for an account. | | create_alert | Create an alert. Disabled in read-only mode. | | activate_alert | Activate an alert. Disabled in read-only mode. | | delete_alert | Delete an alert. Disabled in read-only mode. |

Configuration

Configuration can be provided through environment variables or command-line arguments in the native host wrapper.

| Feature | Environment Variable | Command Line Argument | | ------- | -------------------- | --------------------- | | Gateway host | IB_GATEWAY_HOST | --ib-gateway-host | | Gateway port | IB_GATEWAY_PORT | --ib-gateway-port | | Force bundled Gateway | IB_FORCE_STANDALONE_GATEWAY | --ib-force-standalone-gateway | | Read-only mode | IB_READ_ONLY_MODE | --ib-read-only-mode |

The extension flow is designed around browser-based Gateway login. The popup retrieves all available accounts with get_account_info, lets the user select the active account, and persists the last selected accountId in extension storage. The native host uses set_current_trading_account to keep the selected account as the current trading account for calls that omit accountId. Calling authenticate, changing Gateway cookies, changing Gateway port, changing the selected account, or losing authentication clears account summary cache.

Order actions use the current trading account when accountId is omitted. place_order submits to POST /iserver/account/{accountId}/orders, confirm_order replies to Gateway confirmation prompts through POST /iserver/reply/{replyId}, cancel_order cancels open orders through DELETE /iserver/account/{accountId}/order/{orderId}, get_order_status reads GET /iserver/account/order/status/{orderId}, and get_live_orders reads GET /iserver/account/orders.

Gateway Lifecycle

On startup, the native host first probes reachable local Gateway endpoints on the configured port and common Client Portal Gateway ports. If a healthy existing Gateway is found, the host attaches to it and does not start another bundled Gateway.

When no suitable existing Gateway is reachable, the host starts the bundled Java Gateway as a durable detached process. Runtime coordination files are stored under ib-gateway/.runtime/:

• gateway-session.json records the managed Gateway pid, port, version, and log paths.
• gateway-session.lock prevents two native host processes from starting duplicate managed Gateways at the same time.
• gateway.stdout.log and gateway.stderr.log receive Gateway process output.

Normal native host shutdown detaches from the Gateway and leaves it running so later runs can reuse it. If IB_FORCE_STANDALONE_GATEWAY=true is set, the host skips unrelated external Gateway discovery, but it still reuses or coordinates through managed session metadata and lock files.

To reset the managed Gateway session, stop the Gateway process recorded in ib-gateway/.runtime/gateway-session.json, then remove ib-gateway/.runtime/gateway-session.json and any stale ib-gateway/.runtime/gateway-session.lock. The host automatically removes stale metadata when the recorded pid no longer exists.

Native Host Installation Details

macOS and Linux installer:

bash scripts/install-native-host.sh <chrome-extension-id>

This writes a wrapper script and Native Messaging manifests for Chrome, Chrome Beta, Chrome Canary, Chromium, Brave, and Edge where supported.

Windows installer:

powershell -ExecutionPolicy Bypass -File scripts/install-native-host-windows.ps1 <chrome-extension-id>

The Windows installer writes a .cmd wrapper, a manifest JSON file, and browser registry entries under the current user by default. Use -AllUsers for machine-wide registration.

Manifest template:

{
  "name": "com.newsliquid.ibkr_client_portal",
  "description": "IBKR Client Portal for NewsLiquid",
  "path": "<native-host-path>",
  "type": "stdio",
  "allowed_origins": [
    "chrome-extension://affpkcdpailfifflmmdgedaogbpkaagh/"
  ]
}

Troubleshooting

The extension cannot connect to the native host

• Confirm the extension ID matches the ID in the Native Messaging manifest allowed_origins.
• Re-run the installer with the active extension ID.
• Confirm dist/index.js exists. Run npm run build when installing from a source checkout.
• Check browser native messaging registration paths or Windows registry entries.

Authentication does not complete

• Open the Gateway URL returned by authenticate or gateway_status.
• Complete IBKR login and any required 2FA.
• Run ibkrCompleteAuth() from the extension background service worker console.
• Confirm auth_status returns authenticated: true.

Gateway startup fails

• Inspect ib-gateway/.runtime/gateway.stdout.log, ib-gateway/.runtime/gateway.stderr.log, and ib-gateway/.runtime/gateway-session.json.
• If another Gateway should not be reused, set IB_FORCE_STANDALONE_GATEWAY=true.
• To clear a stale managed startup lock, confirm no native host process is starting Gateway, then remove ib-gateway/.runtime/gateway-session.lock.

Support

Open an issue in this repository.

License

MIT License - see LICENSE file for details.