HiThink Financial-API: Tonghuashun's A-share data service, reviewed for adopters

The gap this fills: one key across four consumption styles

Most A-share data access in practice is a patchwork. A research script scrapes one endpoint, a dashboard calls another, and an agent gets a third through a hand-written tool wrapper. HiThink Financial-API is positioned as the opposite: a single API key issued through the Tonghuashun service portal at fuyao.aicubes.cn, usable from a REST call, a hosted MCP endpoint, an npm-installed CLI, or a Python SDK. The README states explicitly that API, MCP, CLI and remote Python fetches share the same key. That is the actual product claim, and it is a narrower and more useful claim than 'we have financial data'. The audience named in the README is AI agents, quantitative researchers and application developers. If you are a discretionary trader who wants a chart, this is not aimed at you. If you are writing code that needs A-share prices, statements, valuations, index and sector membership, fund data, or the Tonghuashun-specific datasets (limit-up pools, failed limit-up pools, consecutive limit-up ladders, unusual movement, popularity rankings, dragon-tiger lists), the project is claiming to be the official route to all of it.

How the data actually reaches you

There are four transport paths and they are not equivalent. The REST path is plain HTTP against fuyao.aicubes.cn, authenticated with an X-api-key header; the README's example calls /api/a-share/prices/snapshot with a thscodes query parameter. The MCP path is a set of hosted HTTP endpoints, and the README shows them configured as separate servers named hithink-finance-a-share, hithink-finance-a-share-index and hithink-finance-meta, each with the same X-api-key header interpolated from an environment variable. Note the split: MCP capabilities are partitioned across endpoints rather than exposed as one server, so a client that only registers hithink-finance-a-share will not see index tools. The CLI path is an npm package that wraps remote fetching, authentication, structured JSON output and large-result spooling to disk. The fourth path is the interesting one architecturally: marketdb builds and maintains a local DuckDB database, so historical K-line and corporate-action queries run as SQL against a local file rather than over the network. The README's example queries a view called v_daily_qfq, which is the forward-adjusted daily series, implying the adjustment is materialised during sync rather than computed per query. Identifiers throughout are thscode values such as 600519.SH, and the README describes a symbol search command for resolving names or codes to a unique thscode, which tells you the project treats identifier disambiguation as a first-class problem rather than assuming you already have clean codes.

Getting it running: the two commands that matter first

The README's recommended starting point is not the API. It is the Agent Skill, installed with npx skills add HiThink-Tech/Financial-API --skill hithink-finance -g --yes. The Skill bundles the entry-point selection rules, the API contract mirror, the disambiguation rules and the context-control guidance, and the README warns that references/ must be copied alongside SKILL.md if you install by hand. Skill installs from that command silently self-update on the first use of each agent session; HITHINK_FINANCE_NO_SKILL_UPDATE=1 disables that, and the README states the update is skipped when the install directory does not match its tracked hash. For the CLI, npm install -g @hithink-tech/hithink-finance-cli, then hithink-finance auth login followed by hithink-finance capabilities --format json. That second command is worth running before anything else: it prints the machine-readable capability catalogue for the version you installed, which is the only reliable way to know what your build supports. From there the README's examples are hithink-finance symbol search --q 600519 --limit 5 --format json, hithink-finance market snapshot --thscodes 600519.SH --format json, hithink-finance financials income --thscode 600519.SH --limit 4 --format json, and hithink-finance data init --format json for the local database. Credentials go in the user-level environment variable HITHINK_FINANCE_API_KEY; the README is direct that the key should be entered through hidden input or an environment variable, that an agent must not echo it back, and that it must not be written into code, logs, public configuration or a Git repository. The CLI stores its own copy in the system credential store, so it works independently of the Skill once logged in. Non-interactive replacement uses auth login --api-key-stdin --replace.

What is deliberately out of scope

The README carries an explicit exclusion list, and it is the most useful paragraph in the document. Minute bars, tick data, overseas market data, macroeconomic series, original news and announcement text, and research reports are stated as not currently in the public capability range. The README goes further and instructs that when unsupported data is requested, the response should say so plainly rather than substitute simulated or static sample data. That instruction is aimed at agents, and it is the right instinct: an agent that fabricates a tick series to satisfy a prompt is worse than one that refuses. The practical consequence is that this service covers A-share end-of-day and snapshot data plus Tonghuashun's proprietary sentiment datasets, and it does not cover anything intraday below the daily bar. If your backtest needs execution modelling at minute resolution, this is the wrong tool and no amount of entry-point choice fixes it. The second boundary is geographic: the scope is A-share and domestic public funds, including ETF and LOF on-exchange quotes. A portfolio that spans US or Hong Kong listings needs a second vendor, and the README does not claim otherwise.

The marketdb trade-off: local speed against sync discipline

Building a local DuckDB database is the design choice with the most consequences. It converts repeated historical queries into local SQL, which removes per-query network latency and keeps large result sets out of an agent's context window, and the README lists data init, sync, validation, repair, SQL query and export as the CLI's database surface. The cost is that you now own a synchronisation process. The README mentions a trading calendar as a queryable dataset, which is presumably how a sync job knows whether there is new data to pull, but it does not state a scheduler, a cron recipe or an automatic background sync. So the freshness of v_daily_qfq is a function of when you last ran the sync, and any analysis that silently assumes today's data is present will be wrong on the days you forget. That is a normal cost for local warehouses and not a defect, but it is the difference between marketdb and a live REST call, and it should drive the choice: use marketdb for repeated historical scans, use REST or MCP for point-in-time lookups where staleness is unacceptable. The README also notes that large results are written to disk rather than streamed into the terminal or the agent context, which is the same trade-off applied to output rather than storage.

Where a plain REST client or a general scraping library differs

The obvious alternative for an A-share developer is not another vendor but a different shape of solution: a generic HTTP client pointed at whatever endpoint you can find, or a Python scraping library with its own parsers. The difference is not data volume, it is where the contract lives. With a scraping approach, the field definitions and the identifier formats are your problem, and a page layout change breaks your pipeline silently. Here, the README designates docs/api/README.md as the single in-repository source of truth for the REST contract and points to https://fuyao.aicubes.cn/llms-full.txt as the upstream machine-readable contract, with an explicit statement that other documents do not duplicate field definitions. For an agent workflow that matters more than for a human one: an agent reading a contract file can generate a correct call, whereas an agent guessing at a scraped HTML structure cannot. The second difference is the MCP and Skill layer, which has no equivalent in a scraping stack. The counter-argument is real: a scraping setup has no API key, no quota, no account and no dependency on a hosted service staying up. If your access pattern is a few hundred rows a day and you already have working parsers, the migration cost may exceed the benefit. The case for switching is scale, contract stability, and the Tonghuashun-specific datasets that are not readily reconstructible from public pages.

Versioning, maintenance and what the MIT licence does not cover

The repository is TypeScript, MIT-licensed, unarchived, with releases v0.1.5, v0.1.7 and v0.1.8 landing between mid-August and early September 2026, roughly a three-week cadence on a 0.x line. Two implications follow. First, 0.x means the API surface can still move; the README's instruction to run hithink-finance capabilities --format json is the mitigation, because it lets you diff what your installed version actually supports instead of trusting a changelog. Second, the Skill's silent self-update means the agent-facing behaviour can change between sessions without you doing anything; HITHINK_FINANCE_NO_SKILL_UPDATE=1 is the pin, and the README notes new versions take effect from the next agent session, not the current one. On licensing, the MIT grant covers the code in this repository: the CLI, the Python toolkit, the Skill definitions and the docs. It does not, on the face of the material supplied, address the hosted service at fuyao.aicubes.cn, the data returned by it, or the terms attached to an API key. Those terms live on the service portal, not in the LICENSE file, and anyone planning to redistribute fetched data or embed it in a product needs to read them there. Nothing here is legal advice; the point is simply that an MIT badge on a client library is not a statement about the data behind it.

Editorial conclusion

Adopt it if you are building A-share tooling in Python, TypeScript or an MCP-capable agent and want one API key across all four entry points; skip it if you need minute bars, tick data, overseas markets or macro series, which the README places outside the public scope. Before committing, verify three things against your own account: the rate and quota terms on the API key page, whether the CLI's data init and db query path reproduces your expected adjustment factors, and whether the MIT licence on this repository actually governs the hosted endpoints you will call.

Official sources

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