Market Data & Contract Search

Resolving contracts, fetching historical bars, streaming real-time bars, and tick data with MarketDataManager.

Overview (`MarketDataManager`)

MarketDataManager.Instance provides streamlined methods for resolving IBKR contracts, querying historical price bars, subscribing to real-time candlestick updates, and receiving tick-by-tick market data.

1. Resolving Contracts

Use getContract() to resolve full contract details from simple search parameters:

import ibkr, { MarketDataManager } from "@stoqey/ibkr";

await ibkr();

const mkdManager = MarketDataManager.Instance;

// Resolve Stock Contract
const stockContract = await mkdManager.getContract({
  symbol: "AAPL",
  secType: "STK",
  exchange: "SMART",
  currency: "USD",
});

// Resolve Option Contract
const optionContract = await mkdManager.getContract({
  symbol: "AAPL",
  secType: "OPT",
  right: "C",
  strike: 250,
  multiplier: 100,
  currency: "USD",
  exchange: "SMART",
});

To search for all matching contract descriptions matching a query:

const matches = await mkdManager.searchContracts({
  symbol: "ES",
  secType: "FUT",
});

2. Fetching Historical Bars

getHistoricalData() returns OHLCV candlestick bars asynchronously:

import { BarSizeSetting, WhatToShow } from "@stoqey/ib";

const bars = await mkdManager.getHistoricalData(
  stockContract,
  undefined,                  // endDateTime (undefined = now)
  "1 D",                      // durationStr ("1 D", "1 W", "1 M")
  BarSizeSetting.MINUTES_FIVE, // barSizeSetting
  WhatToShow.TRADES,          // whatToShow
  true                        // useRTH (Regular Trading Hours)
);

console.log(`Fetched ${bars.length} historical bars!`);

3. Real-Time Bar Updates

Subscribe to live streaming candlestick bar updates using getHistoricalDataUpdates() and IBKREvents:

import { IBKREvents, IBKREVENTS } from "@stoqey/ibkr";
import type { MarketData } from "@stoqey/ibkr";
import { BarSizeSetting, WhatToShow } from "@stoqey/ib";

// Listen for live bar updates
IBKREvents.Instance.on(IBKREVENTS.IBKR_BAR, (bar: MarketData) => {
  console.log(`[Bar Update] ${bar.instrument?.symbol} | Close: $${bar.close} | Vol: ${bar.volume}`);
});

// Request historical data updates
await mkdManager.getHistoricalDataUpdates(
  stockContract,
  BarSizeSetting.SECONDS_FIVE,
  WhatToShow.TRADES
);

// Unsubscribe when finished:
// mkdManager.removeHistoricalDataUpdates(stockContract);

4. Tick-by-Tick Market Data Updates

getTickByTickDataUpdates() streams individual tick trades, updates portfolio valuations, aggregates ticks into 1-second bars, and emits them via IBKR_BAR:

await mkdManager.getTickByTickDataUpdates(stockContract);

// Unsubscribe when finished:
// mkdManager.removeTickByTickDataUpdates(stockContract);

Historical Ticks

const historicalTicks = await mkdManager.getHistoricalTicksLast(
  stockContract,
  new Date("2026-01-15T14:30:00Z"),
  new Date("2026-01-15T15:30:00Z"),
  1000, // max count
  false
);

5. Instant Quotes (`getQuote`)

Retrieve the latest cached quote snapshot or a point-in-time quote at a target timestamp:

// Latest quote
const latestQuote = await mkdManager.getQuote(stockContract);

// Point-in-time quote
const pastQuote = await mkdManager.getQuote(stockContract, new Date("2026-01-15T15:30:00Z"));