HiThink-Tech/Financial-API: Tonghuashun's Official A-share Data Service, Reviewed

The gap this fills: official A-share data behind one key

Most A-share data in research code arrives through scraping, community wrappers or a vendor SDK with its own authentication model. Each source has a different symbol convention, a different field naming scheme and a different idea of what a trading calendar is. The HiThink project, published by Tonghuashun itself, collapses that into one credential. The README states that a single API key covers API, MCP, CLI and Python remote access, and that the key is created in the API Key management console at fuyao.aicubes.cn/admin/.

The intended audience is narrow and explicit: AI agents, quantitative researchers and application developers. The repository ships an Agent Skill, four hosted MCP endpoints, a Node CLI published to npm, a Python package, and a local DuckDB layer called marketdb. That spread is the interesting part. It is not one library with a thin wrapper around it; it is several access paths that share a credential and, according to the README, a single upstream contract.

The data catalogue is where the project earns its place. Beyond snapshots and historical K-lines, it lists call auction snapshots, corporate actions and adjustment factors, income statements, balance sheets, cash flow statements, five classes of financial indicators, valuation snapshots (PE TTM/MRQ, PB MRQ, PS TTM, PCF TTM), trading calendar, index and sector constituents, and Tonghuashun-specific datasets: limit-up pools, failed limit-up pools, consecutive limit-up ladders, unusual movement, hot lists and the Dragon-Tiger list. Public fund data, including manager, holdings, performance and ETF/LOF on-exchange quotes, is in scope too. If your work touches A-share sentiment or corporate fundamentals, most of what you would otherwise assemble from three sources is here.

How the access paths fit together

The architecture is a hosted service with multiple clients, not a self-contained library. Every path resolves to fuyao.aicubes.cn. The REST API is the base layer: the README shows a plain HTTP request with an X-api-key header, and points to docs/api/README.md as the only in-repo source of the REST contract, with the machine-readable upstream contract at fuyao.aicubes.cn/llms-full.txt. That decision to keep field definitions in one place is a good one; the README explicitly says other documents do not duplicate them.

MCP is a thin configuration layer over the same host. The README gives four hosted endpoints and asks that they be named with the hithink-finance-* prefix, with the key passed through an environment variable reference rather than a literal. The CLI sits on top of both remote fetching and local storage: it handles authentication through the system credential store, emits a stable JSON format with --format json, and can initialize a local DuckDB database that it then queries with SQL. The Python SDK is the research-facing path. The Agent Skill is not a runtime at all; it is a document bundle that tells an agent which of the other four to use, and the README says it includes the full API contract mirror, symbol disambiguation rules and context-control guidance.

Two design choices are worth calling out. First, large results are meant to land on disk rather than in a terminal or an agent's context window; the README frames CLI and market dumps as the route for full-market, long-range pulls. Second, the README states that unsupported requests should be reported as unsupported rather than answered with simulated or static example data. That is a deliberate instruction to agents, and it is the kind of constraint most data wrappers omit.

Installing the CLI and running a first query

The README's default recommendation for both humans and agents is the CLI, installed globally from npm under the package name @hithink-tech/hithink-finance-cli. Node.js 22.12 or later is required according to the package badge in the README.

npm install -g @hithink-tech/hithink-finance-cli

Users in mainland China can point npm at the npmmirror registry instead, which the README gives as a separate command.

npm install -g @hithink-tech/hithink-finance-cli --registry=https://registry.npmmirror.com

Next, log in and check what the installed version supports. The login command records the API key securely, and capabilities returns a machine-readable catalogue of the current build.

hithink-finance auth login
hithink-finance capabilities --format json

With that done, a symbol lookup and a snapshot query are the two commands to try first. The README uses 600519.SH, the Kweichow Moutai code, in its own examples.

hithink-finance symbol search --q 600519 --limit 5 --format json
hithink-finance market snapshot --thscodes 600519.SH --format json

If you want a local store rather than one-off calls, initialize the DuckDB database and query the forward-adjusted daily view. The view name v_daily_qfq appears verbatim in the README example.

hithink-finance data init --format json
hithink-finance db query \
  --sql "SELECT * FROM v_daily_qfq LIMIT 10" \
  --format json

For a no-install check, the REST endpoint returns the same snapshot over plain HTTP. The environment file in the repository names API_KEY and BASE_URL, with BASE_URL set to https://fuyao.aicubes.cn.

curl 'https://fuyao.aicubes.cn/api/a-share/prices/snapshot?thscodes=600519.SH' \
  -H 'X-api-key: <API_KEY>'

If you would rather have an agent pick the path, the README's preferred route is the Skill, installed with npx skills add HiThink-Tech/Financial-API --skill hithink-finance -g --yes. It notes that the installed Skill checks for updates silently once per session, that HITHINK_FINANCE_NO_SKILL_UPDATE=1 disables that, and that the references/ directory must be kept when copying the Skill by hand.

The data boundary is the real limitation

The README is unusually direct about what is not available, and this is the first thing to read before adopting anything. Minute K-lines, tick data, overseas market quotes, macroeconomic data, original news and announcement text, and research reports are all listed as outside the current public capability set. If your strategy depends on intraday microstructure, this project is the wrong tool regardless of how good the daily coverage is. The same applies to anyone who needs non-A-share listings: the service is A-share and public-fund oriented.

There is a second boundary that is less obvious. The hosted endpoints mean your queries leave your infrastructure. The .env.example file warns not to commit .env, and the README instructs agents not to echo the key and to write it only to user-level credential sources, never into code, logs, public configuration or a Git repository. Those are sensible rules, but they exist because the key is a bearer credential against a remote service. Teams with data-residency constraints should treat that as a blocker, not a configuration detail.

Then there is the maturity question. The release history shows v0.1.5 on 2026-08-17, v0.1.7 on 2026-08-27 and v0.1.8 on 2026-09-08. The last push to the repository was on 2026-09-08. That is a fast cadence for a young 0.1.x line, and it also means the CLI's capability surface can shift between versions. The README's own advice to run hithink-finance capabilities --format json after install is effectively an admission that the command set is version-dependent. Pin your CLI version in CI rather than tracking latest.

Finally, the README does not document rollback for the local database, and it does not describe what happens to a partially applied incremental sync. The .env.example exposes MARKETDB_MAX_LAG_TRADING_DAYS=7 as a guardrail for the daily update path, which suggests staleness is detected rather than silently tolerated, but the recovery procedure is not spelled out in the documentation available. Test that path on a throwaway database before you trust it with months of history.

How it compares with yfinance and vendor APIs

The obvious comparison is yfinance, which appears in the related searches and is the default starting point for many Python users. The difference in approach is fundamental. yfinance is an unofficial client that reads from a public web endpoint; it has no credential, no service-level commitment and no coverage of Tonghuashun-specific datasets such as limit-up pools, failed limit-up pools or the Dragon-Tiger list. The HiThink project is the data vendor's own service, authenticated with a key you create at fuyao.aicubes.cn/admin/, and its catalogue is built around the Chinese market rather than global equities. If you need US or European tickers, yfinance covers ground this project does not.

Against commercial financial data APIs, the distinction is scope rather than quality. Many of those services are global and multi-asset, with macro series and news feeds alongside prices. This project is deliberately the opposite: deep on A-share microstructure and fundamentals, silent on macro, news text and overseas listings. The practical consequence is that a portfolio-level workflow spanning Chinese and US equities will need two sources, and you should decide now which one owns the symbol master, because the thscode convention used here (600519.SH) will not match the tickers the other source expects.

Within the project itself, the CLI and the Python SDK are not interchangeable. The README positions the CLI as the route for bulk downloads, local DuckDB construction, SQL querying and structured output, and the Python toolkit as the route for research scripts, notebooks and custom fetch strategies. Choosing the Python SDK for a full-market backfill would push large results through your process memory; choosing the CLI for a single interactive lookup adds a subprocess for no benefit.

Licence, maintenance and what an upgrade costs

The repository is MIT licensed. That covers the code in the repository: the CLI, the Python package, the Skill documents and the local marketdb tooling. It does not, by itself, grant you anything about the hosted data service, which is governed by the terms attached to the API key you create at fuyao.aicubes.cn. Treat the two separately and read the service terms rather than assuming the MIT file settles data usage. Nothing here is legal advice; if you are redistributing data, get your own answer.

On maintenance, the facts are concrete: the repository is not archived, and the last push was on 2026-09-08, nine days before this review. Three releases landed in the preceding month. That is an actively moving 0.1.x line, and the cost of that is churn. The README states that a Skill installed through npx skills add updates itself silently at the start of an agent session, that the new version takes effect from the next session, and that HITHINK_FINANCE_NO_SKILL_UPDATE=1 turns this off. For a production agent, that auto-update is a behaviour change you did not schedule. Disable it and upgrade deliberately.

For the CLI and Python package, budget for reading the changelog on each bump. The repository ships a CHANGELOG.md at the top level, and the CLI's capabilities command is the authoritative statement of what a given build can do. The local database adds its own upgrade surface: schema changes in marketdb would affect any SQL you have written against views such as v_daily_qfq. Keep those queries in version control alongside the pinned tool version so a schema change shows up as a diff rather than a runtime failure.

Editorial conclusion

Adopt it if you need official Tonghuashun A-share daily data inside an AI agent, a research notebook or a Python service, and you are willing to create an API key at fuyao.aicubes.cn. Do not adopt it for minute bars, tick data, overseas listings, macro series or news text, because the README states those are outside the public scope. Before committing, verify two things yourself: that your key can reach the endpoints you need, and that the Python SDK's 3.11+ and Node 22.12+ floors match your runtime. Then run hithink-finance capabilities --format json to see what your installed version actually exposes.

Frequently asked questions

Official sources

1. HiThink-Tech/Financial-API on GitHub
2. License: MIT
3. Project website
4. README
5. Releases