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 (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 has no observed IP ban; reach for it 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.

Gildata research and OTC funds

When the user has enabled the corresponding feature and configured a Gildata token, use its tool for China macro observations, announcements and broker reports. Inspect the returned api_names; routing is vendor-selected. Rows retain vendor order and explicitly report truncation. Narrow the topic or date window to retrieve omitted records. When declaring a macro observation, reference its actual field, for example call_id::rows[0].value, and preserve the returned unit and date. Indicator codes are identifiers, not measurements.

get_fund_nav reads OTC fund NAV history with an exact vendor-code match. Exchange-listed ETF/LOF prices still use the OHLCV loaders. Unit, accumulated and adjusted NAV are different measures; name the one actually reported. Missing NAV values remain missing. NAV rows never enter the OHLCV backtest loader.