stock-api: A Zero-Dependency Quote Client That Falls Back Between Tencent, Sina and Eastmoney

The problem is provider churn, not quote parsing

Public Chinese quote endpoints go down, change shape or start rejecting requests, and every team that scrapes them ends up rewriting the same parser and the same retry logic. stock-api takes that job and packages it as one interface. The README describes it as a zero-runtime-dependency quote tool covering A-shares, Hong Kong and US symbols, exposed four ways: a TypeScript API, a browser bundle, a CLI, and an MCP server for AI clients. The audience is narrow and clear. It is for developers who need a current price, a batch of prices, a K-line series or a symbol search inside an existing application, and who do not want to own the transport layer for three different upstreams. It is not a market data vendor, not a historical archive, and not a trading interface. The disclaimer is explicit that accuracy, completeness, real-time behaviour and continued availability are not guaranteed, and that commercial or high-frequency use requires checking each upstream's terms. That sentence should be read as the scope statement it is.

How stocks.auto picks a provider and what happens when one fails

The core mechanism is a provider factory behind a common interface. The README lists four entry points: stocks.auto, stocks.tencent, stocks.sina and stocks.eastmoney. Each exposes the same five capabilities: single quote, batch quotes, K-lines, symbol search and diagnostics. The auto entry point resolves in a fixed order, documented as tencent, then sina, then eastmoney. That ordering is the design decision worth noticing. Tencent is tried first, Sina second, Eastmoney last, and the docs describe this as automatic fallback rather than load balancing or racing. A fallback chain means a request that succeeds against Tencent never touches Sina, so your results are only as consistent as the first provider that answers. If you need to know which upstream produced a given number, the diagnostics capability is the documented way to find out, and docs/architecture.md is where the provider factory, parsing and error model are described. The architecture doc is also where you would look before adding a fourth source, since the README points to docs/development.md for that workflow. Symbol format is prefix-based: SH, SZ, HK and US, as in SH510500 or SZ000651.

Node.js, browser, CLI and MCP all share one code path

The Node.js surface is a named import. After npm install stock-api on Node 18 or later, the README shows stocks.auto.getStock("SH510500"), stocks.auto.getStocks(["SH510500", "SZ000651"]), stocks.auto.getKlines("SH600519", { period: "day" }) and stocks.auto.searchStocks("格力电器"). Note the shape differences: getStock takes one symbol, getStocks takes an array, getKlines takes a symbol plus an options object where period is the documented key, and searchStocks takes a free-text query. The browser build is an IIFE bundle served from jsDelivr, which exposes the same calls under a StockApi global, so the browser example is StockApi.stocks.auto.getStock("SH510500").then(console.log). The CLI is the same logic through npx: get-stock SH510500, get-stocks SH510500 SZ000651, get-klines SH600519 --period day --count 120, and search-stocks 格力电器. The --count flag appears only in the K-line example. docs/cli.md is where command parameters, output format and exit codes are documented, which matters if you plan to script it. The MCP server is installed by pointing an MCP-capable client at npx -y stock-api mcp and exposes get_stock, get_stocks, get_klines, search_stocks and inspect_stock. The README states the supported protocol versions are 2025-11-25 and 2025-06-18, and that the handshake echoes the version the client requested, falling back to the newest one it supports if the requested version is unknown. There is also a lower-effort path: a SKILL.md file that an agent reads to learn the npx commands directly, which the README frames as the same data logic with a simpler integration.

Eastmoney is not a full peer of Tencent and Sina

The capability table in the README is the most useful page in the repository because it shows the providers are not interchangeable. Tencent, Sina and auto are each listed with the full set: single quote, batch quotes, K-lines, search and diagnostics. Eastmoney is listed as A-share single quote, batch quotes, K-lines, search and diagnostics. Read that again: the Eastmoney row is scoped to A-shares. Since Eastmoney sits last in the fallback chain, the practical consequence is that for a Hong Kong or US symbol, the third fallback is not a fallback at all. If Tencent and Sina are both unavailable and you ask for a US ticker through stocks.auto, the documented behaviour does not promise a third attempt that can serve it. That is a real limitation and it is stated plainly in the table rather than buried. The second limitation is structural: this library reads public third-party endpoints. There is no SLA, no rate-limit contract published in the README, and no caching layer mentioned. A batch call against a flaky upstream is a batch call that can fail as a unit. The repository does ship an api-status branch with status badges for the aggregate, Tencent, Sina and Eastmoney, refreshed every 300 seconds per the badge cache parameter, and docs/monitoring.md describes a scheduled check that updates those badges. That tells you availability is tracked, but it also tells you availability is a live concern rather than a solved one.

Where it fits next to a full market data client

The obvious alternative is a general market data library or a paid vendor feed, and the difference is not quality, it is the contract. A vendor feed gives you a documented schema, a rate limit you can plan around, historical depth and someone to call when a field goes missing. stock-api gives you none of that. What it gives you is a single npm install with no runtime dependencies, a TypeScript surface, and the same call working in Node, in a script tag, on the command line and inside an AI client. The trade is depth for reach. If your requirement is a moving price in a dashboard, a quick K-line series for a chart, or a tool an LLM can call to answer "what is SH600519 doing", the vendor contract is overhead you do not need. If your requirement is reproducible historical analysis, backtesting or anything audited, the fallback chain actively works against you, because the same query can be served by a different upstream on a different day. That is the honest dividing line, and it follows directly from the documented design rather than from any benchmark.

Upgrade and maintenance cost

The release cadence visible in the material is steady but not frantic: v2.7.2 in May 2026, v2.7.3 in June, v2.7.4 in September, with the last push to main in September 2026. Patch-level versioning across those three releases suggests the public API is stable and changes are being absorbed inside the provider layer, which is where you would want upstream churn to land. That is the good news for upgrade cost. The bad news is that the maintenance you are avoiding is not eliminated, only relocated. When Tencent changes a response, you wait for a release or you patch the provider yourself, and docs/development.md is the documented entry point for adding or adjusting a source. The MCP surface adds a second compatibility axis: the README pins supported protocol versions to 2025-11-25 and 2025-06-18, so an MCP client that expects a newer revision will be negotiated down rather than rejected. On licensing, the repository is MIT, which is permissive and imposes no copyleft obligation on your own code. That covers the wrapper. It does not cover the quote data, and the disclaimer directs commercial, high-frequency and production users to verify each third-party source's terms, authorisation scope and compliance requirements themselves. Nothing here is legal advice; the point is that the MIT badge answers a narrower question than people assume.

Who should install it and what to check first

Install it if you want quote access inside a Node 18+ service, a static page or an AI tool, and you are comfortable that the numbers come from public endpoints with no guarantee attached. The four-surface design is the actual selling point: one library, four integration paths, no runtime dependencies to audit. Skip it if you need execution, tick history, guaranteed uptime or a stable upstream identity per query. The first thing to verify is not the install, it is the coverage of your symbol list. Run npx stock-api get-stock against one A-share, one HK and one US ticker and confirm each returns; then read docs/api.md for the diagnostic return structure so you can tell which provider answered. If your workload is Hong Kong or US heavy, treat the Eastmoney row in the capability table as absent and plan for two providers, not three.

Editorial conclusion

Adopt stock-api if you need a small, dependency-free way to pull A-share, Hong Kong or US quotes into a Node.js service, a browser page or an AI client, and you accept that the data comes from third-party public endpoints with no accuracy or uptime guarantee. Do not adopt it for order execution, tick-level history or anything where a silent provider switch would be unacceptable, and do not treat Eastmoney as equivalent to the other two providers: the README limits it to A-share quotes. Before wiring it into anything that matters, read docs/api.md for the diagnostic return shape, confirm which provider answered for your symbol set, and check the api-status badges for current Tencent, Sina and Eastmoney availability. The MIT licence covers the wrapper code only; the upstream quote services have their own terms.

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. zhangxiangliang/stock-api on GitHub