Yahoo Finance2

yahoo-finance2

What this skill is for

Use this skill when a task involves yahoo-finance2, including:

• Adding Yahoo Finance market data to a server-side JavaScript/TypeScript app.
• Choosing between quote, chart, historical, quoteSummary, fundamentalsTimeSeries, screener, options, or other modules.
• Using the package CLI or bundled MCP server.
• Modifying this repository's Deno source, tests, generated schemas, docs, or npm output build.

This is an unofficial Yahoo Finance client. Do not describe it as a supported Yahoo API, and do not assume Yahoo data availability, freshness, or shape is guaranteed.

Using the package

Prefer the v3 class API:

import YahooFinance from "yahoo-finance2";

const yahooFinance = new YahooFinance();
const quote = await yahooFinance.quote("AAPL");
console.log(quote?.regularMarketPrice, quote?.currency);

Do not use old v1/v2 singleton patterns such as yahooFinance.setGlobalConfig(). In v3, instantiate with new YahooFinance(options).

This package is for server-side runtimes. Do not put direct Yahoo Finance calls in browser/client bundles; Yahoo's CORS and cookie behavior require a server, serverless, edge, Deno, Bun, or Node context.

Module selection

• Use search(query) first when a symbol is uncertain.
• Use quote(symbolOrSymbols) for current or near real-time quote fields. It accepts one symbol or an array. Use fields to limit payloads; for keyed access, request object or map returns.
• Use quoteCombine(symbol) when many independent code paths need quote data; it debounces many single-symbol calls into fewer quote() requests.
• Use chart(symbol, { period1, period2, interval }) for chart-ready historical data with events such as dividends and splits. return: "array" is easier to iterate; return: "object" mirrors Yahoo's native shape.
• Use historical() for a simpler OHLCV history interface.
• Use quoteSummary(symbol, { modules }) for profile, price, summary detail, filings, ownership, recommendations, and other quote-summary modules. Request only the modules needed.
• Use fundamentalsTimeSeries() for financial statements. Since late 2024, quote-summary financial-statement modules such as incomeStatementHistory, balanceSheetHistory, and cashflowStatementHistory provide little data.
• Use options(symbol) for options chains.
• Use screener() instead of removed/deprecated daily gainers or losers modules. Common predefined screeners include day_gainers, day_losers, and most_actives.
• Use trendingSymbols(region), recommendationsBySymbol(), and insights() for their specialized Yahoo Finance endpoints.

Reliability, validation, and errors

Wrap module calls in try/catch. Network errors, Yahoo API errors, delisted symbols, missing data, and validation failures are expected operating conditions.

By default, returned data is validated and coerced so known dates become Date objects and known result shapes are safe to consume. If validation fails, fixing the typed interface and regenerated schema is usually better than turning validation off.

Only use { validateResult: false } when the caller accepts unknown output and performs its own checks. Use { validateOptions: false } only when experimenting with Yahoo query parameters that the library does not yet model.

The default client queue limits concurrent Yahoo requests. Use constructor or per-call queue options when you need stricter rate behavior:

const yahooFinance = new YahooFinance({
  queue: { concurrency: 2, interval: 250 },
});

CLI and MCP

For quick shell use:

npx yahoo-finance2 search AMZN
npx yahoo-finance2 quote AAPL
npx yahoo-finance2 quoteSummary NVDA '{"modules":["assetProfile","secFilings"]}'

JSON-looking positional arguments are parsed as JSON. Successful piped output is JSON-safe.

For MCP clients, the package includes a read-only Yahoo Finance MCP server:

npx -y -p yahoo-finance2 yahoo-finance-mcp

See docs/mcp.md for stdio, HTTP, embedded handler, and client registration details.