/yahoo-finance2

name: yahoo-finance2
description: Use when building with the yahoo-finance2 TypeScript/Deno/npm library, using its Yahoo Finance data modules, CLI, or MCP server, or contributing to the yahoo-finance2 repository including modules, validation schemas, cached fixtures, and npm/JSR build output.

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.

Contributing in this repository

Read `AGENTS.md` and `CONTRIBUTING.md` first. This repo is Deno-first TypeScript; npm output is generated.

Edit source files under `src/`, not generated files under `npm/`, unless the task explicitly asks for generated output. Preserve local `.ts` import extensions.

Public module files usually follow this pattern:

• Typed query/result interfaces are the source of truth.
• Files with `@yf-schema` import their generated `.schema.json`.
• Module functions call `this._moduleExec()` with query defaults, runtime

params, optional transforms, result transforms, schema keys, and module options.

• Overloads distinguish validated results from `{ validateResult: false }`,

which returns `unknown`.

When changing an exported interface in a file marked `@yf-schema`, run:

deno task schema

If adding a module, wire it through `src/modules/index.ts`, `deno.json` exports, docs/README links, README module lists when relevant, tests, and any CLI/MCP exposure only when the module should be user-facing there.

Tests and fixtures

Run all tests with:

deno task test

Run focused tests with:

deno task test src/modules/quote.test.ts

Use `deno task test:serial src/modules/quote.test.ts` when debugging or limiting live Yahoo request concurrency.

Tests that touch Yahoo HTTP responses should call `setupCache()` from `tests/common.ts`. Prefer the existing pattern:

const YahooFinance = createTestYahooFinance({ modules: { quote } });
const yf = new YahooFinance();

describe("quote", () =>