market-feed

Unified TypeScript client for financial market data. Wraps Yahoo Finance, Alpha Vantage, Polygon.io, Finnhub, Twelve Data, and Tiingo under one consistent interface — with caching and automatic fallback built in.

The problem

Every free financial API speaks a different language:

// Yahoo Finance
result.chart.result[0].meta.regularMarketPrice

// Alpha Vantage
data["Global Quote"]["05. price"]

// Polygon.io
data.ticker.lastTrade.p

You write adapters, you add caching, you handle fallback — for every project, every time.

The solution

import { MarketFeed } from "market-feed";

const feed = new MarketFeed();
const quote = await feed.quote("AAPL");

console.log(quote.price); // always a number, always the same key

One interface. Six providers. Zero API key required for Yahoo Finance.

Features

• Unified types — Quote, HistoricalBar, CompanyProfile, NewsItem, SearchResult are consistent regardless of which provider answers
• Zero production dependencies — uses native fetch, works everywhere
• Built-in LRU cache — configurable TTL per method, pluggable driver (Redis, Upstash, etc.)
• Automatic fallback — if Yahoo is down, tries Alpha Vantage, then Polygon
• Rate-limit aware — won't silently burn your free Alpha Vantage / Polygon quota
• Strict TypeScript — no any, full autocomplete, compile-time safety
• Multi-runtime — Node 20+, Bun 1+, Deno 2+ (via JSR), Cloudflare Workers
• Escape hatch — pass { raw: true } to get the original provider response
• Exchange calendar — synchronous, offline-capable holiday and session detection for 8 exchanges + crypto (24/7)
• WebSocket streaming — market-feed/ws opens a persistent WS connection to Polygon, Finnhub, Alpaca, or IB TWS; polling fallback for others; getOrderBook() for top-of-book bid/ask
• Observable stream — market-hours-aware HTTP polling that pauses overnight and on weekends; emits earnings_released events when new quarterly reports are detected (includeFundamentals: true)
• Price consensus — query all providers in parallel, get a weighted mean with confidence score
• Technical indicators — SMA, EMA, RSI, MACD, Bollinger Bands, ATR, VWAP, Stochastic — pure functions, zero deps
• Portfolio tracking — live P&L, unrealised gains, day change across all positions
• Backtesting — single-asset pure-function engine + multi-asset portfolioBacktest() with shared cash pool, position sizing, and benchmark comparison
• Price alerts — async generator that fires AlertEvent on price/volume/change conditions, with debounce
• ESG scores — environmental, social, and governance scores on CompanyProfile.esg via Yahoo Finance
• Earnings, dividends, splits — structured historical corporate action data from Yahoo, Polygon, and Finnhub
• Financial statements — income statement, balance sheet, and cash flow statement via market-feed/fundamentals
• Options chains — full options chain with Greeks (delta, gamma, theta, vega) from Polygon.io via market-feed/options
• Macro indicators — 15 FRED economic series including CPI, GDP, unemployment, and yield curve data via market-feed/macro
• Stock screener — filter a universe of symbols by price, volume, market cap, 52-week range, or any custom predicate via market-feed/screener
• React hooks — useQuote, useStream, useAlerts, useWebSocket, useOrderBook for React ≥ 18 and React Native via market-feed/react
• CLI — npx market-feed quote AAPL — no install required
• Crypto & Forex — isCrypto() / isForex() helpers, CRYPTO calendar exchange (always open)
• Browser bundle — market-feed/browser with createFetchWithProxy / installCorsProxy; all providers accept fetchFn for CORS proxy routing; works via CDN without a bundler
• tRPC / HTTP router — market-feed/trpc exports createMarketFeedRouter() and createHttpHandler() for exposing market data as typed tRPC procedures, GraphQL resolvers, or a fetch-compatible REST API

Subpath modules

market-feed ships sixteen optional subpath modules alongside the core client.

market-feed/ws

True WebSocket streaming — tick-by-tick trade data from Polygon and Finnhub, with automatic polling fallback for other providers.

import { connect } from "market-feed/ws";
import { MarketFeed, FinnhubProvider, PolygonProvider } from "market-feed";

// Finnhub — real-time WebSocket
const provider = new FinnhubProvider({ apiKey: process.env.FINNHUB_KEY! });

// Polygon — real-time WebSocket (requires paid plan for true real-time)
// const provider = new PolygonProvider({ apiKey: process.env.POLYGON_KEY! });

const controller = new AbortController();

for await (const event of connect(provider, ["AAPL", "MSFT", "TSLA"], {
  signal: controller.signal,
})) {
  switch (event.type) {
    case "trade":
      console.log(`${event.trade.symbol}: $${event.trade.price} × ${event.trade.size} shares`);
      break;
    case "connected":
      console.log(`Connected to ${event.provider}`);
      break;
    case "disconnected":
      console.log(`Disconnected (attempt ${event.attempt}, reconnecting: ${event.reconnecting})`);
      break;
    case "error":
      if (!event.recoverable) throw event.error;
      break;
  }
}

controller.abort(); // stop the stream

Unlike market-feed/stream (which is HTTP polling), market-feed/ws opens a persistent WebSocket connection and yields individual trade executions in real time.

Provider support

| Provider | WebSocket | Notes | |----------|-----------|-------| | PolygonProvider | Native WS | Auth via JSON handshake, subscribes to T.* trades | | FinnhubProvider | Native WS | Token in URL, per-symbol subscribe | | AlpacaProvider | Native WS | Free IEX or paid SIP feed; key/secret auth | | IbTwsProvider | Native WS | Local TWS / IB Gateway; level I market data | | YahooProvider | Polling fallback | Polls quote() every 5 s | | AlphaVantageProvider | Polling fallback | Same as Yahoo |

WsOptions

| Option | Type | Default | Description | |--------|------|---------|-------------| | wsImpl | typeof WebSocket | globalThis.WebSocket | Custom WS constructor for Node 18–20 | | maxReconnectAttempts | number | 10 | Reconnects before closing | | reconnectDelayMs | number | 1000 | Base delay (doubles per attempt, max 30 s) | | signal | AbortSignal | — | Stop the stream |

Node 20

Node 21+, Bun, Deno, and Cloudflare Workers expose WebSocket globally. For Node 20, install the ws package and inject it:

import WebSocket from "ws";
connect(provider, ["AAPL"], { wsImpl: WebSocket as unknown as typeof globalThis.WebSocket })

market-feed/calendar

Synchronous exchange calendar — no network, no async, works offline.

import {
  isMarketOpen,
  getSession,
  nextSessionOpen,
  nextSessionClose,
  isHoliday,
  isEarlyClose,
  getHolidayDates,
  getExchangeInfo,
} from "market-feed/calendar";

// Is NYSE open right now?
isMarketOpen("NYSE");  // true | false

// What session is it?
getSession("NYSE");    // "pre" | "regular" | "post" | "closed"

// When does it next open?
nextSessionOpen("NYSE");   // Date (UTC)
nextSessionClose("NYSE");  // Date (UTC)

// Holiday checks
isHoliday("LSE");                          // false
isHoliday("NYSE", new Date("2025-04-18")); // true — Good Friday
isEarlyClose("NYSE");                      // true on day before Thanksgiving

// All holidays for a year
getHolidayDates("NYSE", 2026);  // Date[]

// Exchange metadata
getExchangeInfo("LSE");
// { id: "LSE", name: "London Stock Exchange", mic: "XLON",
//   timezone: "Europe/London", openTime: "08:00", closeTime: "16:30", ... }

Supports NYSE, NASDAQ, LSE, TSX, ASX, XETRA, NSE, BSE, and CRYPTO (always open — no sessions, no holidays). Holiday rules are computed from first principles — Easter via the Meeus/Jones/Butcher algorithm, all NYSE-specific rules (MLK Day, Presidents' Day, Juneteenth, Memorial Day, Labor Day, Thanksgiving, Good Friday), UK bank holidays, Canadian, Australian, German, and Indian exchanges. DST is handled via Intl.DateTimeFormat — no manual offset arithmetic.

market-feed/stream

Market-hours-aware async generator. Polls during open hours, pauses when the market is closed.

import { watch } from "market-feed/stream";
import { MarketFeed, YahooProvider, PolygonProvider } from "market-feed";

const feed = new MarketFeed({
  providers: [
    new YahooProvider(),
    new PolygonProvider({ apiKey: process.env.POLYGON_KEY }),
  ],
});

const controller = new AbortController();

for await (const event of watch(feed, ["AAPL", "MSFT"], {
  exchange: "NYSE",
  interval: {
    open:    5_000,   // poll every 5s during regular hours
    prepost: 30_000,  // every 30s pre/post market
    closed:  60_000,  // check every 60s for session open
  },
  divergenceThreshold: 0.5,  // % spread between providers
  signal: controller.signal,
})) {
  switch (event.type) {
    case "quote":
      console.log(`${event.symbol}: $${event.quote.price}`);
      break;
    case "market-open":
      console.log(`${event.exchange} session started: ${event.session}`);
      break;
    case "market-close":
      console.log(`${event.exchange} session ended`);
      break;
    case "divergence":
      console.log(`${event.symbol} providers disagree: ${event.spreadPct.toFixed(2)}%`);
      break;
    case "earnings_released":
      console.log(`${event.symbol} new earnings: EPS ${event.earnings.epsActual}`);
      break;
    case "error":
      if (!event.recoverable) throw event.error;
      break;
  }
}

// Stop the stream
controller.abort();

When marketHoursAware: true (default), the stream pauses completely during closed sessions — no wasted API calls overnight or on weekends. It emits market-open / market-close events at session boundaries. When the feed has multiple providers, it detects price divergence across them and emits divergence events. Set includeFundamentals: true to also receive earnings_released events when a new quarterly report is detected.

WatchOptions

| Option | Type | Default | Description | |--------|------|---------|-------------| | exchange | ExchangeId | "NYSE" | Calendar to use for session detection | | interval.open | number | 5000 | Poll interval (ms) during regular hours | | interval.prepost | number | 30000 | Poll interval (ms) during pre/post market | | interval.closed | number | 60000 | Check interval (ms) when market is closed | | marketHoursAware | boolean | true | Pause during closed sessions | | divergenceThreshold | number | 0.5 | % spread that triggers a divergence event | | maxErrors | number | 5 | Consecutive errors before the generator throws | | includeFundamentals | boolean | false | Emit earnings_released when new quarterly reports are detected | | fundamentalsIntervalMs | number | 900000 | How often to check for new earnings (ms) | | signal | AbortSignal | — | Cancel the stream |

market-feed/consensus

Queries all configured providers simultaneously and returns a statistically-weighted price consensus.

Unlike feed.quote() which stops at the first successful provider, consensus() fires all providers in parallel and combines their results.

import { consensus } from "market-feed/consensus";
import { MarketFeed, YahooProvider, AlphaVantageProvider, PolygonProvider } from "market-feed";

const feed = new MarketFeed({
  providers: [
    new YahooProvider(),
    new AlphaVantageProvider({ apiKey: process.env.AV_KEY }),
    new PolygonProvider({ apiKey: process.env.POLYGON_KEY }),
  ],
});

const result = await consensus(feed.providers, "AAPL");

console.log(result.price);       // 189.82 — weighted mean
console.log(result.confidence);  // 0.97   — 0=no agreement, 1=perfect
console.log(result.spread);      // 0.08   — max - min across providers
console.log(result.spreadPct);   // 0.042  — spread as % of price
console.log(result.flags);       // [] or ["HIGH_DIVERGENCE", "STALE_DATA", ...]
console.log(result.providers);
// {
//   yahoo:          { price: 189.84, weight: 0.33, stale: false, included: true },
//   polygon:        { price: 189.80, weight: 0.33, stale: false, included: true },
//   "alpha-vantage": { price: 189.82, weight: 0.33, stale: false, included: true },
// }

ConsensusOptions

| Option | Type | Default | Description | |--------|------|---------|-------------| | stalenessThreshold | number | 60 | Seconds before a quote is stale. Stale providers get half weight. | | divergenceThreshold | number | 2.0 | % deviation from median that marks a provider as an outlier | | weights | Record<string, number> | equal | Custom weights per provider name (normalized automatically) |

Flags

| Flag | Meaning | |------|---------| | HIGH_DIVERGENCE | spreadPct exceeds divergenceThreshold | | STALE_DATA | At least one provider returned a quote older than stalenessThreshold | | SINGLE_SOURCE | Only one provider responded successfully | | OUTLIER_EXCLUDED | At least one provider was excluded as a price outlier |

market-feed/indicators

Technical indicators as pure functions over HistoricalBar[]. No network, no async, tree-shakeable.

import {
  sma, ema, rsi, macd, bollingerBands, atr, vwap, stochastic,
} from "market-feed/indicators";
import { MarketFeed } from "market-feed";

const feed = new MarketFeed();
const bars = await feed.historical("AAPL", { period1: "2024-01-01", interval: "1d" });

// Simple / Exponential Moving Average
const sma20  = sma(bars, 20);   // IndicatorPoint[] — { date, value }[]
const ema12  = ema(bars, 12);

// Relative Strength Index
const rsi14  = rsi(bars, 14);   // values in [0, 100]

// MACD
const macdResult = macd(bars);  // MACDPoint[] — { date, macd, signal, histogram }[]

// Bollinger Bands
const bb = bollingerBands(bars, 20, 2);  // BollingerPoint[] — { date, upper, middle, lower }[]

// Average True Range
const atr14 = atr(bars, 14);

// VWAP (cumulative from first bar)
const vwapPoints = vwap(bars);

// Stochastic Oscillator
const stoch = stochastic(bars, 14, 3);  // StochasticPoint[] — { date, k, d }[]

All functions return typed arrays starting from the first bar where enough data exists. They never throw for insufficient data — they return an empty array instead.

| Function | Output type | Default params | |----------|------------|----------------| | sma(bars, period) | IndicatorPoint[] | — | | ema(bars, period) | IndicatorPoint[] | — | | rsi(bars, period?) | IndicatorPoint[] | period: 14 | | macd(bars, fast?, slow?, signal?) | MACDPoint[] | 12, 26, 9 | | bollingerBands(bars, period?, stdDevMult?) | BollingerPoint[] | 20, 2 | | atr(bars, period?) | IndicatorPoint[] | period: 14 | | vwap(bars) | IndicatorPoint[] | — | | stochastic(bars, kPeriod?, dPeriod?) | StochasticPoint[] | 14, 3 |

market-feed/portfolio

Track a collection of positions and compute live P&L against current market prices.

import { Portfolio } from "market-feed/portfolio";
import { MarketFeed } from "market-feed";

const feed = new MarketFeed();

const portfolio = new Portfolio([
  { symbol: "AAPL", quantity: 10, avgCost: 150.00 },
  { symbol: "MSFT", quantity:  5, avgCost: 280.00 },
  { symbol: "TSLA", quantity: -3, avgCost: 250.00 }, // short position
]);

// Fetch live quotes and compute P&L in one call
const snap = await portfolio.snapshot(feed);

console.log(`Total value:       $${snap.totalMarketValue.toFixed(2)}`);
console.log(`Unrealised P&L:    $${snap.totalUnrealizedPnl.toFixed(2)}`);
console.log(`Today's change:    $${snap.totalDayChange.toFixed(2)}`);

for (const pos of snap.positions) {
  const pct = (pos.unrealizedPnlPct * 100).toFixed(2);
  console.log(`${pos.symbol}: $${pos.marketValue.toFixed(2)} (${pct}%)`);
}

Position

| Field | Type | Description | |-------|------|-------------| | symbol | string | Ticker symbol | | quantity | number | Units held. Negative = short. | | avgCost | number | Average cost per unit | | currency | string? | Defaults to "USD" | | openedAt | Date? | When the position was opened | | notes | string? | Free-form notes |

Portfolio API

portfolio.add(position)          // add or replace a position (chainable)
portfolio.remove(symbol)         // remove a position (chainable)
portfolio.get(symbol)            // Position | undefined
portfolio.list()                 // readonly Position[]
portfolio.size                   // number
portfolio.snapshot(feed)         // Promise<PortfolioSnapshot>

market-feed/backtest

Pure-function backtesting engine over HistoricalBar[]. No network, no side effects.

import { backtest } from "market-feed/backtest";
import type { EntrySignal, ExitSignal } from "market-feed/backtest";
import { MarketFeed } from "market-feed";

const feed = new MarketFeed();
const bars = await feed.historical("AAPL", { period1: "2020-01-01", interval: "1d" });

// Buy when today's close > yesterday's close (momentum)
const entry: EntrySignal = (bars, i) => i > 0 && bars[i]!.close > bars[i - 1]!.close;

// Sell when today's close < yesterday's close
const exit: ExitSignal = (bars, i, _entryPrice) => i > 0 && bars[i]!.close < bars[i - 1]!.close;

const result = backtest("AAPL", bars, entry, exit, {
  initialCapital: 10_000,
  quantity: 10,
  commission: 1,
});

console.log(`Total return:    ${(result.totalReturn * 100).toFixed(2)}%`);
console.log(`Annualised CAGR: ${(result.annualizedReturn * 100).toFixed(2)}%`);
console.log(`Sharpe ratio:    ${result.sharpeRatio.toFixed(2)}`);
console.log(`Max drawdown:    ${(result.maxDrawdown * 100).toFixed(2)}%`);
console.log(`Win rate:        ${(result.winRate * 100).toFixed(1)}%`);
console.log(`Trades:          ${result.totalTrades}`);

Signals fire at bar[i].close. Any open position is closed at the last bar. At most one position is held at a time.

BacktestOptions

| Option | Type | Default | Description | |--------|------|---------|-------------| | initialCapital | number | 100_000 | Starting capital | | quantity | number | 1 | Shares per trade | | commission | number | 0 | One-way commission per trade |

BacktestResult

| Field | Description | |-------|-------------| | totalReturn | Fraction — e.g. 0.25 = 25% | | annualizedReturn | CAGR as a fraction | | sharpeRatio | Annualised Sharpe (risk-free rate = 0) | | maxDrawdown | Positive fraction — peak-to-trough | | winRate | Fraction of profitable trades | | profitFactor | Gross profit / gross loss (Infinity = no losses) | | totalTrades | Completed round-trip trades | | trades | BacktestTrade[] ledger |

market-feed/alerts

Poll a quote feed and yield AlertEvent whenever a configured condition is met.

import { watchAlerts } from "market-feed/alerts";
import type { AlertConfig } from "market-feed/alerts";
import { MarketFeed } from "market-feed";

const feed = new MarketFeed();
const controller = new AbortController();

const alerts: AlertConfig[] = [
  // Fire once when AAPL crosses $200
  { symbol: "AAPL", condition: { type: "price_above", threshold: 200 }, once: true },
  // Alert on TSLA intraday crash; debounce 5 min to avoid spam
  { symbol: "TSLA", condition: { type: "change_pct_below", threshold: -5 }, debounceMs: 300_000 },
  // Unusual volume spike on MSFT
  { symbol: "MSFT", condition: { type: "volume_above", threshold: 100_000_000 } },
];

for await (const event of watchAlerts(feed, alerts, {
  intervalMs: 5_000,
  signal: controller.signal,
})) {
  console.log(
    `[${event.triggeredAt.toISOString()}] ${event.alert.symbol} triggered: $${event.quote.price}`,
  );
}

Alert conditions

| type | Fires when | |--------|-----------| | price_above | quote.price > threshold | | price_below | quote.price < threshold | | change_pct_above | quote.changePercent > threshold | | change_pct_below | quote.changePercent < threshold | | volume_above | quote.volume > threshold |

AlertConfig

| Field | Type | Description | |-------|------|-------------| | symbol | string | Ticker to watch | | condition | AlertCondition | Trigger condition | | once | boolean? | Remove after first fire. Default: false | | debounceMs | number? | Suppress re-fires within this window. Default: 0 |

When all once alerts have fired, the generator terminates automatically. Permanent alerts (once: false) run until signal.abort() is called. Transient fetch errors are silently retried.

market-feed/fundamentals

Fetch income statements, balance sheets, and cash flow statements for any public company.

import { getFundamentals } from "market-feed/fundamentals";
import { MarketFeed } from "market-feed";

const feed = new MarketFeed();

// Fetch all three statements in parallel — partial failure is OK
const { incomeStatements, balanceSheets, cashFlows } = await getFundamentals(feed, "AAPL");

const latest = incomeStatements[0]!;
console.log(`Revenue:   $${(latest.revenue! / 1e9).toFixed(1)}B`);
console.log(`Net income: $${(latest.netIncome! / 1e9).toFixed(1)}B`);
console.log(`Diluted EPS: $${latest.dilutedEps?.toFixed(2)}`);

// Quarterly statements
const { incomeStatements: quarterly } = await getFundamentals(feed, "AAPL", {
  quarterly: true,
  limit: 4,
});

getFundamentals() fires all three queries with Promise.allSettled — if one statement type fails, the others still return.

IncomeStatement

| Field | Description | |-------|-------------| | revenue | Total revenue | | grossProfit | Revenue − cost of revenue | | operatingIncome | Operating income (EBIT) | | netIncome | Bottom-line net income | | ebitda | EBITDA | | dilutedEps | Diluted EPS |

BalanceSheet

| Field | Description | |-------|-------------| | totalAssets | Total assets | | totalLiabilities | Total liabilities | | totalStockholdersEquity | Book value of equity | | cashAndCashEquivalents | Cash + equivalents | | totalDebt | Short + long-term debt |

CashFlowStatement

| Field | Description | |-------|-------------| | operatingCashFlow | Cash from operations | | capitalExpenditures | CapEx (negative = outflow) | | freeCashFlow | operatingCashFlow + capitalExpenditures | | investingCashFlow | Cash from investing | | financingCashFlow | Cash from financing |

All three types include symbol, date (period end date), periodType ("annual" | "quarterly"), and provider.

MarketFeed methods

feed.incomeStatements(symbol, options?)  // Promise<IncomeStatement[]>
feed.balanceSheets(symbol, options?)     // Promise<BalanceSheet[]>
feed.cashFlows(symbol, options?)         // Promise<CashFlowStatement[]>

| FundamentalsOptions | Default | Description | |-----------------------|---------|-------------| | quarterly | false | Return quarterly instead of annual periods | | limit | unlimited | Max number of periods to return | | raw | false | Include raw provider response on each object |

market-feed/screener

Filter a list of symbols against a set of criteria using live quote data.

import { screen } from "market-feed/screener";
import { MarketFeed } from "market-feed";

const feed = new MarketFeed();

// Find large-caps that gained > 1.5% today on high volume
const results = await screen(feed, ["AAPL", "MSFT", "GOOGL", "TSLA", "NVDA", "META"], {
  criteria: [
    { type: "market_cap_above", value: 100_000_000_000 },
    { type: "change_pct_above", value: 1.5 },
    { type: "volume_above",     value: 10_000_000 },
  ],
  limit: 5,
});

for (const r of results) {
  console.log(`${r.symbol}: $${r.quote.price.toFixed(2)} (+${r.quote.changePercent.toFixed(2)}%)`);
}

All criteria are evaluated with AND logic — a symbol must pass every criterion to be included.

Criterion types

| Type | Passes when | |------|-------------| | price_above / price_below | quote.price > / < value | | change_pct_above / change_pct_below | quote.changePercent > / < value | | volume_above / volume_below | quote.volume > / < value | | market_cap_above / market_cap_below | quote.marketCap > / < value (skips if undefined) | | 52w_high_pct_below | Price is within N% of the 52-week high | | 52w_low_pct_above | Price is at least N% above the 52-week low | | volume_vs_avg_above / volume_vs_avg_below | Volume is > / < N× the average volume (skips if avgVolume undefined) | | custom | { type: "custom", fn: (quote: Quote) => boolean } |

ScreenerOptions

| Option | Default | Description | |--------|---------|-------------| | criteria | required | Array of ScreenerCriterion | | batchSize | all at once | Max symbols per quote() call | | limit | unlimited | Max results to return |

screen() accepts any object with a quote(symbols[]) → Quote[] method — works with MarketFeed, individual providers, or a test mock.

market-feed/options

Fetch a full options chain for any underlying symbol, including per-contract Greeks. Currently powered by Polygon.io.

import { getOptionChain } from "market-feed/options";
import { MarketFeed, PolygonProvider } from "market-feed";

const feed = new MarketFeed({
  providers: [new PolygonProvider({ apiKey: process.env.POLYGON_KEY! })],
});

// Fetch the full chain
const chain = await getOptionChain(feed, "AAPL");
console.log(`${chain.calls.length} calls, ${chain.puts.length} puts`);

for (const contract of chain.calls.slice(0, 3)) {
  console.log(
    `${contract.expiry} $${contract.strike} C  ` +
    `bid/ask ${contract.bid}/${contract.ask}  ` +
    `delta ${contract.delta?.toFixed(3)}  IV ${(contract.impliedVolatility! * 100).toFixed(1)}%`,
  );
}

You can also call feed.optionChain() directly:

// Filter by expiry and option type
const julyPuts = await feed.optionChain("AAPL", {
  expiry: "2024-07-19",
  type: "put",
  strikeLow: 150,
  strikeHigh: 200,
  limit: 20,
});

OptionChainOptions

| Option | Type | Default | Description | |--------|------|---------|-------------| | expiry | string | — | Filter to specific expiry date ("YYYY-MM-DD") | | strike | number | — | Exact strike filter | | strikeLow / strikeHigh | number | — | Strike range filter | | type | "call" \| "put" | both | Filter by contract type | | limit | number | 50 | Max contracts to return |

OptionContract fields

| Field | Description | |-------|-------------| | ticker | OCC ticker (e.g. O:AAPL240719C00150000) | | type | "call" or "put" | | strike | Strike price | | expiry | Expiration date string ("YYYY-MM-DD") | | bid / ask / midpoint | Quote prices | | volume / openInterest | Liquidity metrics | | impliedVolatility | IV as a decimal (e.g. 0.35 = 35%) | | delta / gamma / theta / vega | Option Greeks | | provider | Always "polygon" for now |

market-feed/macro

Fetch macroeconomic time series from the FRED API (Federal Reserve Bank of St. Louis). No API key required.

import { FredProvider, getIndicator, INDICATORS } from "market-feed/macro";

const fred = new FredProvider();

// Fetch CPI (inflation) — last 12 months
const cpi = await getIndicator(fred, INDICATORS.CPI, { limit: 12 });

for (const obs of cpi.observations) {
  console.log(`${obs.date}: ${obs.value}`);
}
console.log(cpi.title);      // "Consumer Price Index for All Urban Consumers"
console.log(cpi.units);      // "Index 1982-1984=100"
console.log(cpi.frequency);  // "Monthly"

Available indicators

| Constant | FRED series | Description | |----------|-------------|-------------| | INDICATORS.CPI | CPIAUCSL | Consumer Price Index (all urban consumers) | | INDICATORS.CORE_CPI | CPILFESL | Core CPI (ex food & energy) | | INDICATORS.PCE | PCEPI | Personal Consumption Expenditures price index | | INDICATORS.GDP | GDP | Gross Domestic Product (quarterly, $B SAAR) | | INDICATORS.REAL_GDP | GDPC1 | Real GDP (chained 2017 dollars) | | INDICATORS.UNEMPLOYMENT | UNRATE | Civilian Unemployment Rate (%) | | INDICATORS.NONFARM_PAYROLLS | PAYEMS | Total Nonfarm Payrolls (thousands) | | INDICATORS.FED_FUNDS | FEDFUNDS | Effective Federal Funds Rate (%) | | INDICATORS.T10Y | DGS10 | 10-Year Treasury Constant Maturity Rate (%) | | INDICATORS.T2Y | DGS2 | 2-Year Treasury Constant Maturity Rate (%) | | INDICATORS.T10Y2Y | T10Y2Y | 10-Year minus 2-Year Treasury spread (yield curve) | | INDICATORS.MORTGAGE30 | MORTGAGE30US | 30-Year Fixed Mortgage Rate (%) | | INDICATORS.INDUSTRIAL_PROD | INDPRO | Industrial Production Index | | INDICATORS.RETAIL_SALES | RSAFS | Advance Retail Sales (monthly) | | INDICATORS.HOUSING_STARTS | HOUST | Housing Starts (thousands, SAAR) |

MacroOptions

| Option | Default | Description | |--------|---------|-------------| | limit | all | Max observations to return (most recent N) | | startDate | — | ISO date string filter | | endDate | — | ISO date string filter |

market-feed/react

React hooks for live market data. Requires React ≥ 18 (peer dependency).

npm install market-feed react

import { useQuote, useStream, useAlerts } from "market-feed/react";
import { MarketFeed } from "market-feed";

const feed = new MarketFeed();

// Poll a quote every 5 seconds
function StockPrice({ symbol }: { symbol: string }) {
  const { data, loading, error } = useQuote(feed, symbol);
  if (loading) return <span>Loading…</span>;
  if (error)   return <span>Error: {error.message}</span>;
  return <span>{symbol}: ${data?.price.toFixed(2)}</span>;
}

// Subscribe to a live watch() stream
function LiveFeed() {
  const { event } = useStream(feed, ["AAPL", "MSFT", "GOOGL"]);
  if (!event || event.type !== "quote") return null;
  return <p>{event.symbol}: ${event.quote.price.toFixed(2)}</p>;
}

// Collect price alerts
function AlertLog() {
  const { events, clearEvents } = useAlerts(feed, [
    { symbol: "AAPL", condition: { type: "price_above", threshold: 200 }, once: false },
  ]);
  return (
    <ul>
      {events.map((e, i) => (
        <li key={i}>{e.alert.symbol} triggered @ ${e.quote.price.toFixed(2)}</li>
      ))}
      <button onClick={clearEvents}>Clear</button>
    </ul>
  );
}

Hook reference

useQuote(source, symbol, options?) — polls a quote at a regular interval.

| Option | Default | Description | |--------|---------|-------------| | intervalMs | 5000 | Poll interval in milliseconds | | enabled | true | Set to false to suspend polling |

Returns { data: Quote \| null, loading: boolean, error: Error \| null, refetch() }.

useStream(feed, symbols, options?) — drives a watch() async generator. Restarts automatically when symbols changes; stops on unmount via an internal AbortSignal.

Returns { event: StreamEvent \| null, error: Error \| null }.

useAlerts(feed, alerts, options?) — drives a watchAlerts() async generator. Accumulates triggered events; restarts when alert definitions change.

Returns { events: AlertEvent[], error: Error \| null, clearEvents() }.

useWebSocket(provider, symbols, options?) — drives a connect() WebSocket stream. Works in React Native (native WebSocket available globally). Yields trade ticks and connection events in real time.

Returns { event: WsEvent \| null, latestTrade: WsTrade \| null, error: Error \| null }.

useOrderBook(provider, symbol, options?) — drives getOrderBook() for live bid/ask updates. Works with Polygon, Alpaca, IB TWS, or polling fallback. Works in React Native.

Returns { orderBook: OrderBookEvent \| null, error: Error \| null }.

market-feed/trpc

Framework-agnostic procedure router. createMarketFeedRouter(feed) returns a typed plain object of async procedures. Works standalone, with tRPC, as GraphQL resolvers, or as a fetch-compatible HTTP handler.

import { createMarketFeedRouter, createHttpHandler } from "market-feed/trpc";
import { MarketFeed } from "market-feed";

const mf = createMarketFeedRouter(new MarketFeed());

// Call directly
const { quotes } = await mf.quote({ symbols: ["AAPL", "MSFT"] });
const company     = await mf.company({ symbol: "TSLA" });
const news        = await mf.news({ symbol: "AAPL", limit: 5 });

tRPC v11

import { initTRPC } from "@trpc/server";
import { z } from "zod";

const t = initTRPC.create();

export const appRouter = t.router({
  quote:   t.procedure.input(z.object({ symbols: z.array(z.string()) })).query(({ input }) => mf.quote(input)),
  company: t.procedure.input(z.object({ symbol: z.string() })).query(({ input }) => mf.company(input)),
  news:    t.procedure.input(z.object({ symbol: z.string(), limit: z.number().optional() })).query(({ input }) => mf.news(input)),
});

HTTP handler (Next.js / Cloudflare Workers)

// app/api/market/[procedure]/route.ts
const handler = createHttpHandler(mf);
export { handler as POST };

// POST /api/market/quote  {"symbols":["AAPL"]}  → {"quotes":[...]}
// POST /api/market/company  {"symbol":"AAPL"}   → {"name":"Apple Inc.",...}

market-feed/browser

Browser-native build with CORS proxy utilities. All providers use the native browser fetch and WebSocket APIs — no Node.js dependencies required.

import { MarketFeed, YahooProvider, createFetchWithProxy } from "market-feed/browser";

// Route requests through a CORS proxy in development
const proxiedFetch = createFetchWithProxy("https://corsproxy.io/?");

const feed = new MarketFeed({
  providers: [new YahooProvider({ fetchFn: proxiedFetch })],
});

const quote = await feed.quote("AAPL");
console.log(quote.price); // $189.84

Every provider accepts a fetchFn option so you can route only specific providers through a proxy, or through your own server-side API route in production.

// Production: proxy through your own backend
const serverFetch = createFetchWithProxy("https://my-app.example.com/api/proxy?url=");

const feed = new MarketFeed({
  providers: [
    new PolygonProvider({ apiKey: "...", fetchFn: serverFetch }),
    new FinnhubProvider({ apiKey: "...", fetchFn: serverFetch }),
  ],
});

installCorsProxy(proxyUrl) patches globalThis.fetch globally and returns a cleanup function — useful for development:

import { installCorsProxy } from "market-feed/browser";

const uninstall = installCorsProxy("https://corsproxy.io/?");
// All fetch() calls in your app now go through the proxy
uninstall(); // restore original fetch

Works via CDN without a bundler:

<script type="module">
  import { MarketFeed, YahooProvider, createFetchWithProxy } from "https://esm.sh/market-feed/browser";

  const feed = new MarketFeed({
    providers: [new YahooProvider({ fetchFn: createFetchWithProxy("https://corsproxy.io/?") })],
  });
  const quote = await feed.quote("AAPL");
  console.log(quote.price);
</script>

market-feed/cache

Three official persistent cache drivers — drop-in replacements for the default LRU cache:

| Driver | Use case | |--------|----------| | createRedisCacheDriver(client) | Redis via ioredis, redis@4, or @upstash/redis | | createUpstashCacheDriver({ url, token }) | Upstash REST API — edge-compatible | | createSqliteCacheDriver(db) | SQLite — local persistence (better-sqlite3, bun:sqlite, node:sqlite) |

See Persistent Cache Drivers for full docs.

CLI (npx market-feed)

A zero-config CLI powered by Yahoo Finance (no API key needed). Add keys to unlock more providers.

# Quotes
npx market-feed quote AAPL MSFT GOOGL

# Historical data
npx market-feed historical AAPL --interval 1wk --period1 2024-01-01

# Symbol search
npx market-feed search "apple inc"

# Company profile
npx market-feed company AAPL

# News (JSON output)
npx market-feed news AAPL --limit 5 --json

# Corporate actions
npx market-feed earnings AAPL
npx market-feed dividends AAPL
npx market-feed splits AAPL

Options

| Flag | Description | |------|-------------| | --av-key <key> | Alpha Vantage API key | | --polygon-key <key> | Polygon.io API key | | --finnhub-key <key> | Finnhub API key | | --td-key <key> | Twelve Data API key | | --tiingo-key <key> | Tiingo API key | | --json | Output raw JSON instead of formatted tables | | --limit <n> | Limit results (default: 10) | | --interval <i> | Historical interval: 1m 5m 15m 30m 1h 1d 1wk 1mo (default: 1d) | | --period1 <date> | Historical start date (ISO 8601) | | --period2 <date> | Historical end date (ISO 8601) | | -h, --help | Show help |

Install

# npm / pnpm / bun
npm install market-feed
pnpm add market-feed
bun add market-feed

# Deno (JSR)
deno add jsr:@piyushgupta344/market-feed

Quick Start

import { MarketFeed } from "market-feed";

// Zero-config — uses Yahoo Finance, no API key needed
const feed = new MarketFeed();

// Single quote
const aapl = await feed.quote("AAPL");
console.log(`${aapl.symbol}: $${aapl.price.toFixed(2)}`);

// Multiple quotes (parallel)
const quotes = await feed.quote(["MSFT", "GOOGL", "AMZN"]);

// Historical data
const history = await feed.historical("AAPL", {
  period1: "2024-01-01",
  period2: "2024-12-31",
  interval: "1d",
});

// Search
const results = await feed.search("Tesla");

// Company profile
const profile = await feed.company("AAPL");
console.log(profile.sector); // "Technology"

Providers

| Provider | API Key | Quote | Historical | Search | Company | News | Fundamentals | WebSocket | |----------|---------|:-----:|:----------:|:------:|:-------:|:----:|:------------:|:---------:| | Yahoo Finance | Not required | ✓ | ✓ | ✓ | ✓ | — | ✓ | polling | | Alpha Vantage | Free (25/day) | ✓ | ✓ | ✓ | ✓ | — | — | polling | | Polygon.io | Free (delayed) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | native | | Finnhub | Free (60/min) | ✓ | ✓ | ✓ | ✓ | ✓ | — | native | | Twelve Data | Free (800/day) | ✓ | ✓ | ✓ | ✓ | — | ✓ | polling | | Tiingo | Free (1000/day) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | polling | | Alpaca | Free (IEX) | ✓ | — | — | — | — | — | native | | IB TWS | Local gateway | — | — | — | — | — | — | native |

Get free keys: Alpha Vantage · Polygon.io · Finnhub · Twelve Data · Tiingo

Using multiple providers

import {
  MarketFeed,
  YahooProvider,
  AlphaVantageProvider,
  PolygonProvider,
  FinnhubProvider,
  TwelveDataProvider,
  TiingoProvider,
} from "market-feed";

const feed = new MarketFeed({
  providers: [
    new YahooProvider(),
    new AlphaVantageProvider({ apiKey: process.env.AV_KEY }),
    new PolygonProvider({ apiKey: process.env.POLYGON_KEY }),
    new FinnhubProvider({ apiKey: process.env.FINNHUB_KEY }),
    new TwelveDataProvider({ apiKey: process.env.TD_KEY }),
    new TiingoProvider({ apiKey: process.env.TIINGO_KEY }),
  ],
  fallback: true, // auto-try next provider on failure
});

Caching

The default LRU cache stores responses in memory with sensible TTLs:

| Method | Default TTL | |--------|-------------| | quote | 60s | | historical | 1 hour | | company | 24 hours | | news | 5 minutes | | search | 10 minutes | | marketStatus | 60s | | earnings | 1 hour | | dividends | 24 hours | | splits | 24 hours | | incomeStatements | 24 hours | | balanceSheets | 24 hours | | cashFlows | 24 hours | | optionChain | 60s |

Override TTLs

const feed = new MarketFeed({
  cache: {
    ttl: 60,        // default fallback TTL
    maxSize: 1000,  // max entries in memory
    ttlOverrides: {
      quote: 15,          // aggressive refresh for real-time feel
      company: 604800,    // company profiles change rarely
    },
  },
});

Disable caching

const feed = new MarketFeed({ cache: false });

Persistent cache drivers

market-feed/cache ships three official persistent drivers:

// Redis (ioredis / redis@4 / @upstash/redis)
import Redis from "ioredis";
import { createRedisCacheDriver } from "market-feed/cache";
const feed = new MarketFeed({ cache: { driver: createRedisCacheDriver(new Redis(process.env.REDIS_URL)) } });

// Upstash REST (edge-compatible — Cloudflare Workers, Vercel Edge, Deno)
import { createUpstashCacheDriver } from "market-feed/cache";
const feed = new MarketFeed({
  cache: { driver: createUpstashCacheDriver({ url: process.env.UPSTASH_URL!, token: process.env.UPSTASH_TOKEN! }) },
});

// SQLite (better-sqlite3 / bun:sqlite / node:sqlite)
import Database from "better-sqlite3";
import { createSqliteCacheDriver } from "market-feed/cache";
const feed = new MarketFeed({ cache: { driver: createSqliteCacheDriver(new Database("./cache.db")) } });

See the Persistent Cache Drivers documentation for full details.

API Reference

new MarketFeed(options?)

| Option | Type | Default | Description | |--------|------|---------|-------------| | providers | MarketProvider[] | [new YahooProvider()] | Provider chain | | cache | CacheConfig \| false | LRU, 60s TTL | Cache configuration | | fallback | boolean | true | Auto-failover on provider error |

Methods

// Quotes
feed.quote(symbol: string, options?: QuoteOptions): Promise<Quote>
feed.quote(symbols: string[], options?: QuoteOptions): Promise<Quote[]>

// Historical bars
feed.historical(symbol: string, options?: HistoricalOptions): Promise<HistoricalBar[]>

// Symbol search
feed.search(query: string, options?: SearchOptions): Promise<SearchResult[]>

// Company profile
feed.company(symbol: string, options?: CompanyOptions): Promise<CompanyProfile>

// News
feed.news(symbol: string, options?: NewsOptions): Promise<NewsItem[]>

// Market status
feed.marketStatus(market?: string): Promise<MarketStatus>

// Earnings history (EPS actuals vs. estimates)
feed.earnings(symbol: string, options?: EarningsOptions): Promise<EarningsEvent[]>

// Cash dividend history
feed.dividends(symbol: string, options?: DividendOptions): Promise<DividendEvent[]>

// Stock split history
feed.splits(symbol: string, options?: SplitOptions): Promise<SplitEvent[]>

// Financial statements
feed.incomeStatements(symbol: string, options?: FundamentalsOptions): Promise<IncomeStatement[]>
feed.balanceSheets(symbol: string, options?: FundamentalsOptions): Promise<BalanceSheet[]>
feed.cashFlows(symbol: string, options?: FundamentalsOptions): Promise<CashFlowStatement[]>

// Options chain (requires PolygonProvider)
feed.optionChain(symbol: string, options?: OptionChainOptions): Promise<OptionChain>

// Cache management
feed.clearCache(): Promise<void>
feed.invalidate(key: string): Promise<void>

HistoricalOptions

interface HistoricalOptions {
  period1?: string | Date;   // start date, default: 1 year ago
  period2?: string | Date;   // end date, default: today
  interval?: "1m" | "2m" | "5m" | "15m" | "30m" | "60m" | "1h"
           | "1d" | "5d" | "1wk" | "1mo" | "3mo";  // default: "1d"
  raw?: boolean;
}

Error Handling

import {
  MarketFeedError,
  ProviderError,
  RateLimitError,
  AllProvidersFailedError,
} from "market-feed";

try {
  const quote = await feed.quote("AAPL");
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log(`Rate limited. Retry after: ${err.retryAfter?.toISOString()}`);
  } else if (err instanceof AllProvidersFailedError) {
    console.log("All providers failed:", err.errors.map(e => e.message));
  } else if (err instanceof ProviderError) {
    console.log(`Provider error (${err.provider}): ${err.message}`);
  }
}

Building a Custom Provider

Implement the MarketProvider interface to add any data source:

import type { MarketProvider, Quote } from "market-feed";

class MyProvider implements MarketProvider {
  readonly name = "my-provider";

  async quote(symbols: string[]): Promise<Quote[]> {
    // fetch from your API, return normalised Quote objects
  }

  async historical(symbol: string, options) {
    // ...
  }

  async search(query: string) {
    // ...
  }
}

const feed = new MarketFeed({ providers: [new MyProvider()] });

Runtime Compatibility

| Runtime | Version | Notes | |---------|---------|-------| | Node.js | 20+ | fetch and WebSocket global built-in. Node 18 reached EOL April 2025. | | Bun | 1+ | Fully supported | | Deno | 2+ | Install via JSR: deno add jsr:@piyushgupta344/market-feed | | Cloudflare Workers | Latest | Fully supported | | Browser | — | Use market-feed/browser with a CORS proxy — most providers block direct browser requests. |

Contributing

See CONTRIBUTING.md. All contributions welcome.

git clone https://github.com/piyushgupta344/market-feed
cd market-feed
pnpm install
pnpm test

Disclaimer

This library is not affiliated with or endorsed by Yahoo Finance, Alpha Vantage, Polygon.io, Finnhub, Twelve Data, or Tiingo. Data is provided for informational purposes only and should not be used as the sole basis for investment decisions.

License

MIT