version: "1.0.0" name: data-routing category: data-source description: The single ROUTER for every data need. Load this skill BEFORE any backtest, data-fetch, or research task to pick the best available source/tool, honour auth (env) requirements, and avoid ban-risk providers.

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) > eastmoney / baostock /

akshare > tushare (TUSHARE_TOKEN).

• US stocks: sina > yahoo > stooq > tushare (TUSHARE_TOKEN) > eastmoney >

yfinance > tiingo / fmp / finnhub / alphavantage (key-gated).

• HK stocks: yahoo > tushare (TUSHARE_TOKEN) > futu > eastmoney >

yfinance > akshare.

• Crypto: okx (single exchange) > ccxt (multi-exchange).
• Futures / macro / forex: tushare > akshare.

Execution rules:

• Never hard-code API keys or tokens in scripts. Read TUSHARE_TOKEN from the environment.
• Prefer config.json + code/signal_engine.py + the built-in backtest tool;

it validates strategy code and performs source fallback.

• For CSI 300 constituent backtests, set "universe": "csi300" and use

"source": "auto" or "tushare". The runner expands constituents with Tushare index_weight.

• When a primary source returns partial data or raises a rate-limit error, the

runner retains successful symbols and retries only missing symbols through the same-market chain.

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.

• With TUSHARE_TOKEN configured, Tushare is the preferred authenticated fallback

before rate-limit-prone A-share, US, and HK aggregators.

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.