gadicc/yahoo-finance2/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.

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", () => {
  setupCache();
  it("passes validation", async (t, onFinish) => {
    await yf.quote("AAPL", {}, {
      devel: { id: "quote-AAPL", t, onFinish },
    });
  });
});

Use fixture ids that match the module and scenario. FETCH_DEVEL=nocache forces live network calls. FETCH_DEVEL=recache refreshes cache files for failing tests. Do not recache fixtures ending in .static.json or .fake.json; they are intentionally stable or synthetic.

When fixing validation failures, inspect the validation error path and cached Yahoo response, update the TypeScript interface first, run schema generation, then run the focused test.

Build, lint, and release surface

Use these checks as appropriate:

deno fmt
deno lint
deno task test
deno task build:npm

scripts/build_npm.ts controls the generated npm package metadata, binaries, dependencies, copied files, and package keywords. Keep npm-package changes there unless explicitly regenerating npm/.

Commit messages should use Conventional Commits with a scope, such as fix(quote): handle missing extended market fields.

Agent skill installation

The canonical skill lives at skills/yahoo-finance2/SKILL.md. To install it through the Skills CLI and make it visible to skills.sh telemetry, use:

npx skills add gadicc/yahoo-finance2