# Yahoo Finance

> Fetch live financial data from Yahoo Finance. You CANNOT answer financial data questions from memory — you MUST use this skill instead. Trigger whenever the user wants to check any stock/ETF/index/commodity/forex/crypto price or quote; look up PE ratios, margins, earnings, or analyst recommendations; view ETF holdings; find market gainers, losers, or trending stocks; search for a company's ticker symbols; pull historical prices or options chains; or calculate portfolio value using current market prices. Covers all global exchanges (US, Hong Kong, China, etc.) and works in any language. Do NOT use for financial education without data lookup, writing scripts using other libraries (yfinance, pandas), comparing APIs, or parsing data from non-Yahoo sources like Polygon.io.

- Skill: `dvcrn/yahoo-finance-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dvcrn/yahoo-finance-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/yahoo-finance-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: dvcrn (https://skillmd.com/u/dvcrn)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/dvcrn/yahoo-finance-2

---


# Yahoo Finance CLI

A powerful, fully-featured CLI for fetching comprehensive stock data from Yahoo Finance.

This skill uses the community-supported `yahoo-finance2` package. It outputs pure **JSON**, making it extremely easy for Agents to parse, filter, and analyze the data.

## Installation Status

The package is globally installed as `yahoo-finance`.
(Installed via `npm install -g yahoo-finance2`)

## Critical: One Symbol Per Call

The CLI syntax is:
```
yahoo-finance <module> <symbol> [options_json]
```

The CLI accepts **exactly one symbol** per invocation. The second positional argument is always parsed as a JSON options object, not a second symbol. Passing multiple symbols (e.g. `yahoo-finance quote AAPL MSFT`) causes a validation error (`"Expected an object"`).

To query multiple symbols, make **separate calls in parallel**:
```bash
# WRONG — "MSFT" is parsed as options JSON, throws error
yahoo-finance quote AAPL MSFT

# CORRECT — one symbol per call, run in parallel
yahoo-finance quote AAPL 2>/dev/null | jq '{symbol, regularMarketPrice}'
yahoo-finance quote MSFT 2>/dev/null | jq '{symbol, regularMarketPrice}'
```

## Usage / Commands

### 1. Basic Quote (Price & High-level Info)
Returns current price, volume, 52-week highs/lows, market cap, etc. Returns a **single JSON object**.
```bash
yahoo-finance quote AAPL 2>/dev/null | jq '{symbol, regularMarketPrice, regularMarketChangePercent, marketCap}'
```

### 2. Quote Summary (The Data Powerhouse)
Provides deep-dive data. Pass a JSON string to request specific sub-modules. **You can request multiple modules in one call.**

**Basic Fundamentals & Profile:**
```bash
yahoo-finance quoteSummary NVDA '{"modules":["defaultKeyStatistics", "financialData"]}' 2>/dev/null
yahoo-finance quoteSummary NVDA '{"modules":["assetProfile"]}' 2>/dev/null
```

**Advanced Analysis (Smart Money & Ratings):**
```bash
yahoo-finance quoteSummary AAPL '{"modules":["recommendationTrend", "upgradeDowngradeHistory"]}' 2>/dev/null
yahoo-finance quoteSummary TSLA '{"modules":["insiderTransactions", "institutionOwnership"]}' 2>/dev/null
```

**Financial Statements:**
```bash
yahoo-finance quoteSummary MSFT '{"modules":["incomeStatementHistory", "cashflowStatementHistory", "balanceSheetHistory"]}' 2>/dev/null
```

**ETF Specific Data (works for both US and HK ETFs):**
```bash
yahoo-finance quoteSummary SPY '{"modules":["topHoldings"]}' 2>/dev/null
yahoo-finance quoteSummary 3416.HK '{"modules":["topHoldings"]}' 2>/dev/null
```

### 3. Historical Data (Chart)
Get daily, weekly, or monthly OHLCV data. Returns `{meta, quotes[]}`.
```bash
# Daily (default)
yahoo-finance chart AAPL '{"period1": "2024-01-01", "period2": "2024-01-31"}' 2>/dev/null

# Weekly
yahoo-finance chart AAPL '{"period1": "2024-01-01", "period2": "2024-06-01", "interval": "1wk"}' 2>/dev/null

# Extract just dates and closes
yahoo-finance chart 3416.HK '{"period1": "2026-02-01", "period2": "2026-03-04"}' 2>/dev/null | jq '[.quotes[] | {date, close}]'
```

### 4. Options Chain (US stocks only)
Get calls and puts with strike, bid/ask, volume, IV. **Returns empty data for HK stocks.**
```bash
yahoo-finance options SPY 2>/dev/null | jq '{expiration_count: (.expirationDates | length)}'
```

### 5. Insights
Returns `recommendation` and `instrumentInfo` for US stocks. `technicalEvents` is always null.
**Returns all null for non-US stocks** — use `quoteSummary` instead.
```bash
yahoo-finance insights AAPL 2>/dev/null | jq '{recommendation, instrumentInfo}'
```

### 6. Fundamentals Time Series
Historical financial statement data over multiple periods.
```bash
yahoo-finance fundamentalsTimeSeries AAPL '{"period1": "2020-01-01", "period2": "2024-01-01", "module": "financials"}' 2>/dev/null
```

### 7. Market Insights & Movers

**Screener** — returns a flat object with `.quotes[]`:
```bash
yahoo-finance screener '{"scrIds": "day_gainers"}' 2>/dev/null | jq '{title, total, first: .quotes[0].symbol}'
yahoo-finance screener '{"scrIds": "day_losers"}' 2>/dev/null | jq '{title, total}'
```

**Trending** — returns `{count, quotes[]}`:
```bash
yahoo-finance trendingSymbols US 2>/dev/null | jq '{count, symbols: [.quotes[] | .symbol]}'
```

**Recommendations** — returns a flat object (NOT an array):
```bash
yahoo-finance recommendationsBySymbol AAPL 2>/dev/null | jq '{symbol, reco: [.recommendedSymbols[:5][] | .symbol]}'
```

### 8. Search
Search for companies, ETFs, or crypto. Due to a schema validation quirk, results are nested inside `.data`:
```bash
# Extract search results correctly
yahoo-finance search "PetroChina" 2>/dev/null | jq '[.[:5][] | {symbol: .data.symbol, name: .data.shortname, exchange: .data.exchDisp}]'
```

## Symbol Formats

- **US stocks:** `AAPL`, `MSFT`, `GOOGL`, `TSLA`
- **Crypto:** `BTC-USD`, `ETH-USD`
- **Forex:** `EURUSD=X`, `GBPUSD=X`
- **ETFs:** `SPY`, `QQQ`, `VOO`
- **China A-shares (Shanghai):** `600519.SS` (贵州茅台), `688981.SS` (中芯国际)
- **China A-shares (Shenzhen):** `000001.SZ` (平安银行), `300750.SZ` (宁德时代)
- **China indices:** `000001.SS` (上证指数), `399001.SZ` (深证成指)
- **International:** `RELIANCE.NS` (India), `0700.HK` (Tencent Hong Kong)

### Hong Kong Stock Symbol Rules (IMPORTANT)

HK stock codes must **strip leading zeros** to a maximum of 4 digits:

| Official HK Code | Yahoo Finance Symbol | Rule |
|-------------------|---------------------|------|
| 03416.HK | `3416.HK` | Drop leading `0` → 4 digits |
| 02802.HK | `2802.HK` | Drop leading `0` → 4 digits |
| 02840.HK | `2840.HK` | Drop leading `0` → 4 digits |
| 09988.HK | `9988.HK` | Drop leading `0` → 4 digits |
| 00857.HK | `0857.HK` | Drop leading `00` → 4 digits |
| 00700.HK | `0700.HK` | Drop leading `00` → 4 digits |

**Failure modes with wrong codes (two distinct behaviors):**
- Codes like `03416.HK`, `09988.HK` → returns `undefined` (not valid JSON, easy to detect)
- Codes like `00857.HK`, `00700.HK`, `02840.HK` → returns a **stale ghost record** (`market: "us_market"`, all price fields `null`, timestamps from 2019). No error is raised, but the data is completely wrong. Always verify `market` is `"hk_market"` and `regularMarketPrice` is not null.

**Quick conversion rule:** strip all leading zeros, then if the result is less than 4 digits, it's already correct. For official 5-digit HK codes, just remove the first character.

### Index & Futures Symbols

Symbols containing special characters (`^`, `=`) must be **single-quoted** in bash:

```bash
yahoo-finance quote '^HSCE'      # Hang Seng China Enterprises Index
yahoo-finance quote '^HSI'       # Hang Seng Index
yahoo-finance quote '^GSPC'      # S&P 500
yahoo-finance quote '^VIX'       # VIX
yahoo-finance quote '^DJI'       # Dow Jones
yahoo-finance quote '^IXIC'      # NASDAQ Composite
yahoo-finance quote '^TNX'       # US 10-Year Treasury Yield
yahoo-finance quote 'GC=F'       # Gold Futures
yahoo-finance quote 'CL=F'       # WTI Crude Oil
yahoo-finance quote 'BZ=F'       # Brent Crude Oil
yahoo-finance quote 'DX-Y.NYB'   # US Dollar Index
yahoo-finance quote 'EURUSD=X'   # EUR/USD Forex
```

## Known Issues & Best Practices

### 1. Always use `2>/dev/null`

The CLI prints `Storing cookies in ...` and other debug messages to stderr. Always redirect to keep output clean for `jq`:
```bash
yahoo-finance quote 3416.HK 2>/dev/null | jq '...'
```

### 2. Non-existent symbols return `undefined`

Invalid tickers return the literal string `undefined` (not JSON). This will crash `jq`. Handle with:
```bash
result=$(yahoo-finance quote ZZZZZZ 2>/dev/null)
if [ "$result" = "undefined" ]; then echo "Symbol not found"; fi
```

### 3. `insights` is limited

- `technicalEvents` is **always null** (even for US stocks like AAPL)
- `recommendation` and `instrumentInfo` work for US stocks only
- Returns **all null** for non-US stocks
- For technical analysis, use `quoteSummary` with `["recommendationTrend"]` instead

### 4. `options` is US-only

HK stocks return empty options data (0 expirations, 0 strikes). Only use `options` for US-listed equities.

### 5. `search` has a schema quirk

Results come wrapped in validation error objects. Access actual data via the `.data` field:
```bash
# Result fields are under .data, not at top level
yahoo-finance search "Apple" 2>/dev/null | jq '.[0].data | {symbol, shortname, exchDisp}'
```

## Note for Agents

All responses are standard JSON (except `undefined` for missing symbols). Always use `jq` to extract the fields you need. When querying multiple symbols, launch separate parallel Bash calls — never pass multiple symbols to a single invocation.