yfinance

name	yfinance
description	yfinance global market data interface — retrieve OHLCV, financials, insider transactions, and institutional holdings for US stocks, HK stocks, ETFs, and indices via Yahoo Finance. Free, no API key required.
category	data-source

yfinance

Overview

yfinance is an open-source Python wrapper for Yahoo Finance, providing global market data (US stocks, HK stocks, ETFs, indices) including historical and real-time quotes. Completely free, no registration or API key required.

The project has a built-in yfinance DataLoader (backtest/loaders/yfinance_loader.py). When backtesting, set source: "yfinance" or source: "auto" to invoke it automatically.

For OHLCV bars in agent/swarm work, prefer the get_market_data tool when it is available. It routes through the project loader layer, normalizes symbols, removes malformed OHLC rows, and returns strict JSON. Use direct yfinance calls mainly for data outside OHLCV coverage such as company info, financial statements, options, holders, and insider transactions.

Deep Yahoo Interfaces (references/)

Beyond the yfinance package, the project ships a built-in Yahoo public-API client (backtest.loaders.yahoo_client) and two read-only agent tools that sit on top of it. These reach Yahoo's own unauthenticated JSON endpoints directly via requests (no yfinance install needed), share one throttled HTTP gate (Yahoo rate-limits by source IP), and handle the cookie+crumb handshake automatically. Each interface has its own reference doc — read the one you need rather than loading them all:

Doc	Covers
yahoo_client.get_chart	Direct v8 OHLCV bars (range or epoch window)
yahoo_client.get_quote_summary	v10 quoteSummary modules (key stats, financials, ownership)
yahoo_client.get_options	v7 option chain (expirations + calls/puts)
yahoo_client.search	v1 instrument search by ticker/name
get_options_chain tool	Agent tool: US options ladder envelope
get_stock_profile tool	Agent tool: company profile/estimates/ownership envelope

Path convention: read_file resolves paths with skills/ as the root, so every link above is written with the skill-name prefix (yfinance/references/...). Omitting the prefix makes the read fail. Reuse this yfinance/references/... form for any new reference docs.

The Yahoo client uses the project ticker convention (AAPL.US → AAPL, 00700.HK → 0700.HK); see the Ticker Format Conversion table below — the same rules apply across all of the interfaces above.

Quick Start

Preferred OHLCV tool call:

{
  "codes": ["AAPL.US", "700.HK"],
  "start_date": "2025-01-01",
  "end_date": "2026-01-01",
  "source": "yfinance",
  "interval": "1D"
}

If you must write a Python script for OHLCV, use the DataLoader instead of raw yf.download:

from backtest.loaders.registry import get_loader_cls_with_fallback

loader = get_loader_cls_with_fallback("yfinance")()
data = loader.fetch(["AAPL.US", "700.HK"], "2025-01-01", "2026-01-01", interval="1D")

for symbol, df in data.items():
    print(symbol, df.tail())

Ticker Format Conversion

The project uses a unified ticker format. The DataLoader automatically converts to yfinance format:

Project Format	yfinance Format	Market
AAPL.US	AAPL	US stock
MSFT.US	MSFT	US stock
700.HK	0700.HK	HK stock
9988.HK	9988.HK	HK stock
SPY.US	SPY	US ETF

Rules:

• US stocks: strip the .US suffix → use the raw ticker
• HK stocks: keep .HK, pad the number to 4 digits (700 → 0700)

Supported Data Types

1. Historical OHLCV

Prefer get_market_data for OHLCV whenever the tool is available:

{
  "codes": ["AAPL.US", "MSFT.US", "GOOGL.US"],
  "start_date": "2025-01-01",
  "end_date": "2026-01-01",
  "source": "yfinance",
  "interval": "1D",
  "max_rows": 250
}

For script-based OHLCV analysis, use the loader:

from backtest.loaders.registry import get_loader_cls_with_fallback

loader = get_loader_cls_with_fallback("yfinance")()

# Single stock
single = loader.fetch(["AAPL.US"], "2025-01-01", "2026-01-01", interval="1D")

# Specific interval
hourly = loader.fetch(["AAPL.US"], "2026-03-01", "2026-03-30", interval="1H")

Supported intervals:

• Minute-level: 1m, 2m, 5m, 15m, 30m, 60m, 90m
• Hourly: 1h
• Daily and above: 1d, 5d, 1wk, 1mo, 3mo

Minute data limits:

• 1m: up to 7 days of history
• 2m/5m/15m/30m/60m/90m: up to 60 days
• 1h: up to 730 days
• 1d and above: unlimited

2. Company Info

ticker = yf.Ticker("AAPL")

info = ticker.info
print(f"Company: {info.get('longName')}")
print(f"Industry: {info.get('industry')}")
print(f"Market cap: {info.get('marketCap')}")
print(f"PE: {info.get('trailingPE')}")
print(f"EPS: {info.get('trailingEps')}")
print(f"Dividend yield: {info.get('dividendYield')}")

3. Financial Statements

ticker = yf.Ticker("AAPL")

# Income statement (annual)
income = ticker.financials
# Income statement (quarterly)
income_q = ticker.quarterly_financials

# Balance sheet
balance = ticker.balance_sheet

# Cash flow statement
cashflow = ticker.cashflow

# Earnings data
earnings = ticker.earnings

4. Dividends and Splits

ticker = yf.Ticker("AAPL")

# Dividend history
dividends = ticker.dividends

# Stock split history
splits = ticker.splits

# All corporate actions
actions = ticker.actions

5. Institutional Holdings

ticker = yf.Ticker("AAPL")

# Institutional holders
holders = ticker.institutional_holders

# Major holders summary
major = ticker.major_holders

# Insider transactions
insider = ticker.insider_transactions

6. Indices and ETFs

# Major indices
sp500 = yf.download("^GSPC", start="2025-01-01", end="2026-01-01", progress=False)  # S&P 500
nasdaq = yf.download("^IXIC", start="2025-01-01", end="2026-01-01", progress=False)  # NASDAQ
hsi = yf.download("^HSI", start="2025-01-01", end="2026-01-01", progress=False)      # Hang Seng Index

# ETFs
spy = yf.download("SPY", start="2025-01-01", end="2026-01-01", progress=False)
qqq = yf.download("QQQ", start="2025-01-01", end="2026-01-01", progress=False)

7. FX Rates

# Currency pairs
usdcny = yf.download("CNY=X", start="2025-01-01", end="2026-01-01", progress=False)
usdhkd = yf.download("HKD=X", start="2025-01-01", end="2026-01-01", progress=False)
eurusd = yf.download("EURUSD=X", start="2025-01-01", end="2026-01-01", progress=False)

Backtest Usage

config.json Example

{
  "source": "yfinance",
  "codes": ["AAPL.US", "MSFT.US"],
  "start_date": "2020-01-01",
  "end_date": "2026-03-30",
  "initial_cash": 1000000,
  "commission": 0.001,
  "extra_fields": null
}

Cross-Market Auto Mode

{
  "source": "auto",
  "codes": ["000001.SZ", "AAPL.US", "700.HK", "BTC-USDT"],
  "start_date": "2024-01-01",
  "end_date": "2026-03-30",
  "initial_cash": 1000000,
  "commission": 0.001,
  "extra_fields": null
}

source: "auto" routes automatically by ticker format: A-shares → tushare, HK/US stocks → yfinance, crypto → OKX.

Notes

• Free, no API key: yfinance scrapes Yahoo Finance public data — no registration needed
• Rate limits: high-frequency requests may trigger temporary Yahoo bans — prefer batch downloads over per-ticker loops
• Minute data range: limited by Yahoo Finance (see table above)
• HK tickers: Yahoo Finance uses 4-digit numbers + .HK; pad with leading zeros where needed
• Adjustment: auto_adjust=True (default) returns forward-adjusted prices; the project loader uses auto_adjust=False
• Timezone: returned data includes timezone info; the DataLoader strips it automatically
• extra_fields not supported: yfinance via the backtest loader returns OHLCV only; PE/PB and other fundamentals require separate yf.Ticker().info calls
• Comparison with Tushare: Tushare covers deep A-share data (financials, fund flows, block trades, etc.); yfinance covers global markets but with less depth