chstockdata

Free China A-share market data toolkit — direct HTTP/TCP access to public quote vendors, no API keys, no third-party data SDKs (akshare-free by design), battle-tested in production by TradingAgents-astock.

pip install chstockdata          # core (pandas/requests only)
pip install "chstockdata[mootdx]"    # + mootdx TCP K-line source (optional)
pip install "chstockdata[baostock]"  # + historical turnover for CYQ chips (optional)

from chstockdata import get_stock_data, get_realtime_snapshot, resolve_ticker

resolve_ticker("贵州茅台")            # -> "600519" (Chinese name -> 6-digit code)
df = get_stock_data("600519", 365)    # daily OHLCV, vipdoc/mootdx/Sina chain
get_realtime_snapshot("600519")       # realtime quote, Tencent -> mootdx -> Sina

53 public functions: K-lines, realtime quotes, fundamentals / three financial statements, valuation history, margin trading, dragon-tiger board (per-stock seats and whole-market daily), lockup expiry, northbound flow, fund flow, board fund flow, industry comparison, concept blocks, block trades, market breadth, limit-up / failed-board / limit-down / previous-day limit-up pools, CYQ chip distribution, ETF option chains (T-quote + greeks + IV), investor Q&A (互动易), hot rank / popularity rank / concept hits, insider transactions, shareholder pledge / buyback, corporate actions, earnings forecast, research reports, news wires, policy news, macro indicators, trading calendar, delisting / suspension info, and more. See chstockdata/__init__.py for the full export list.

Data sources

All Eastmoney requests go through a module-level serial throttle (EM_MIN_INTERVAL, default 1.0s) with jitter and a shared keep-alive session — do not bypass it, do not fan out concurrent full-market scans. push2 / push2his are deliberately not used (see tests/test_astock_push2_source_scan.py).

Hardening carried over from production

This package is not a scraper starter kit; it is an extraction of a data layer that survived months of live A-share analysis runs:

• Realtime fallback chain Tencent → mootdx → Sina, with zombie-quote detection (zero-amount + price == prev-close) so suspended/legacy tickers cannot silently poison valuations.
• mootdx canary server selection: TCP reachability is not enough — every candidate must serve one real K-line bar before adoption; dead pools get an exponential-backoff negative cache (5min → 6h, immediate 6h outside trading hours).
• Local vipdoc history layer: after the official TDX archive is refreshed (via chstockdata-refresh-vipdoc), historical daily bars are read from disk with zero network and never trigger full server-pool probing.
• Point-in-time filtering for historical analyses (financial records are clipped to the analysis date).
• Known pitfall fixes verified against live data: Tencent total/float market-cap fields swapped, static-PE wrong slot, BJ-exchange 920-prefix routing, Eastmoney lockup column renames, block-trade premium-ratio unit (decimal → percent), northbound SSE holiday result:[null] handling, and more — each guarded by regression tests ported from the incidents.

Configuration

Zero-config works out of the box. Optional overrides, in priority order:

from chstockdata import configure
configure(cache_dir="...", vipdoc_dir="...", vipdoc_enabled=True,
          vipdoc_max_staleness_days=5, northbound_store_path="...")

Environment variables (both prefixes accepted): CHSTOCKDATA_CACHE_DIR, CHSTOCKDATA_VIPDOC_HISTORY_DIR, ... or the legacy TRADINGAGENTS_VIPDOC_HISTORY_* / TRADINGAGENTS_DATA_CACHE_DIR names. Tuning knobs: EM_MIN_INTERVAL (Eastmoney throttle seconds), TDX_MIN_INTERVAL, TDX_TOOL_PROBE_BUDGET_SECONDS, EASY_TDX_PYTHON (path to an isolated venv python with easy-tdx==1.20.6).

MCP server (for AI agents)

pip install "chstockdata[mcp]"
chstockdata-mcp

Then register in any MCP client (Claude Code, etc.):

{ "mcpServers": { "chstockdata": { "command": "chstockdata-mcp" } } }

Risk & usage notes

• All endpoints are public, unofficial interfaces of the respective vendors. Rate-limit thresholds cited anywhere in the docs are community observations, not vendor guarantees; endpoints can break or change at any time without notice.
• Built-in throttling must be kept as-is. For heavy or commercial workloads use official paid feeds (Eastmoney Choice, exchange data services).
• Data is provided for research/educational purposes, as-is, with no warranty of accuracy or fitness for trading decisions.

Relationship to upstream projects

Extracted from TradingAgents-astock (Apache-2.0, itself a fork of TauricResearch/TradingAgents). Starting with 0.2.0, selected upstream-unique endpoints of a-stock-data (Apache-2.0) were reverse-ported: ETF options (contracts / T-quote / greeks + IV), limit-up pools (including the previous-day pool and THS limit-up reasons), CYQ chip distribution, market-wide dragon-tiger board, board fund flow, investor Q&A (互动易), hot rank / popularity rank / concept hits, and the upstream ticker routing fix (market identifier conflicts fail loud; 5x ETFs route to Shanghai).

This package is still not a full superset of a-stock-data. Deliberately not included: intraday anomaly pools (product hard boundary in the source project), Shenwan industry history, minute/tick order flow, and any push2/push2his dependency (board fund flow uses the non-push2 bkzj endpoint with a reduced field set — no four-tier breakdown). See MIGRATION.md and docs/planned-upstream-ports.md.

License

Apache-2.0 — see LICENSE and NOTICE.