Data Routing (Router)

This is the one router. It maps (a) every registered backtest data source to its markets / auth / skill, and (b) every research data need to the concrete tool that serves it, its market, and the env key it requires. Source names below are a strict subset of backtest.loaders.registry.VALID_SOURCES (enforced by tests/test_data_routing_sources_subset.py).

Source Overview

Every name here is a registered OHLCV/backtest source in VALID_SOURCES. "Runner-internal" sources are selected by the backtest runner, not authored as a per-source skill.

Capability → Tool Routing

Pick the tool by the data need. "Market" is the universe the tool covers; "Env key" is required only where listed (no key listed = free / no auth).

Notes:

• get_financial_statements reads US statements from SEC EDGAR companyfacts (ticker -> CIK -> XBRL concepts) and A-share/HK statements from the Eastmoney datacenter report API (per-market F10 report names).
• get_stock_news routes A-share (SH/SZ/BJ) to an Eastmoney news client and US (.US) / HK (.HK) to a Yahoo search client; a failure on one upstream is returned as an error envelope, never raised, so a single bad symbol never aborts a batch.

Decision Tree

Backtest scenario (writing config.json)

Use source: "auto" — the runner routes by symbol pattern and falls back across same-market sources automatically. Only set a concrete source when the user asks.

Analysis / research scenario

1. Identify the data need, then read the Capability table for the tool + env key.
2. If the need is plain OHLCV, call get_market_data and let source fallback run.
3. Set any required env key before calling a key-gated tool; if it is missing, report the missing key rather than failing silently.

Source priority (for OHLCV by market)

• A-shares: tencent / mootdx (never banned) > tushare (TUSHARE_TOKEN) > baostock / akshare > eastmoney (throttled).
• US stocks: stooq / yahoo > tiingo / finnhub / fmp / alphavantage (key-gated) > sina / eastmoney (throttled) > yfinance.
• HK stocks: tencent (never banned, daily) > eastmoney / yahoo > futu (local OpenD) > akshare (Eastmoney-backed, daily only) > yfinance > tushare (TUSHARE_TOKEN) / longbridge (key-gated).
• Canada (TSX/TSXV): yahoo > yfinance > local; use Yahoo's canonical .TO / .V suffixes (for example TD.TO, PNG.V).
• Crypto: okx (single exchange) > ccxt (multi-exchange).
• Futures / macro: tushare > akshare.
• Forex / metals: mt5 (local MetaTrader 5 terminal, Windows) > akshare. TickerAll (source="tickerall") is a hosted, no-terminal alternative to the same broker feed (any OS) — opt-in and explicit-only: it never joins this automatic chain, so a user's broker credential is used only when deliberately requested.

Symbol Format Reference

Ban-Risk & Fallback Notes

• Prefer never-banned sources: tencent and mootdx have no observed IP ban; reach for them first for A-share OHLCV when no token is set.
• Eastmoney rate-limits by IP and must be throttled. Every Eastmoney-backed tool/loader routes through the shared per-host throttle; do not hammer it. On a throttle/timeout, fall back to the same-market source above (tencent/baostock).
• Sina / Yahoo also throttle by IP — same per-host wrapper, same fallback rule.
• Key-gated sources need their env key (FINNHUB_API_KEY, ALPHAVANTAGE_API_KEY, TIINGO_API_KEY, FMP_API_KEY, FRED_API_KEY, VIBE_TRADING_IWENCAI_KEY, TUSHARE_TOKEN). If the key is absent the tool/loader is unavailable — route to a free same-market source instead of erroring out.
• A single failing symbol or transient HTTP error is reported inside the envelope; it never aborts the surrounding batch.

Data Verification Discipline

When a number will drive a conclusion (valuation, screening, report), do not trust a single source. Cross-check it:

• Verify material figures across ≥2 independent sources before citing them. Prioritize original disclosures (company annual/quarterly reports, exchange filings) over third-party aggregators.
• Flag any deviation >1% between sources as a ⚠️ caliber mismatch — usually a definition difference (GAAP vs Non-GAAP, consolidated vs parent-only, currency, TTM vs annual). Do not silently pick one; state both and which you adopt.
• Use the financial_rigor tool's cross_validate command to do this exactly: pass {source: value, ...} and it returns the median consensus + per-source deviation + an all_consistent flag at a configurable tolerance (default 2%).
• Mark unverified numbers as "single-source" or "estimate" — never present an uncorroborated figure as established fact.

This discipline is what separates analysis from aggregation.