stock-sdk: A Zero-Dependency JavaScript SDK for A-Share, Hong Kong and US Market Data

The Problem stock-sdk Solves for Front-End Engineers

Most stock market tooling lives in Python. If you write JavaScript or TypeScript and want a quote board, your usual options are to run a Python service and proxy it, or to call an undocumented financial endpoint directly and deal with GBK-encoded responses, batch limits and concurrency by hand. The README frames the project around exactly that gap: it says stock market tools are mostly in the Python ecosystem and hard for front-end developers to use directly.

stock-sdk is aimed at front-end engineers who want market data in the language they already write. The README lists the intended uses: quote dashboards for web and admin panels, charting with ECharts or TradingView, course demos, quantitative strategy prototypes in JavaScript or Node, scheduled scraping from Node.js, ad hoc terminal lookups, and feeding data to AI tools. The audience is narrow on purpose. This is not a trading system, an order router, or a data warehouse. It is a client library that returns quotes and candles.

How the Namespace API, Symbol Normalization and Request Governance Work

Version 2 reorganized the surface into namespaces: sdk.quotes.cn(), sdk.kline.cn(), sdk.options.etf.dailyKline(). The README describes this as an architectural shift from v1 with a unified symbol model, a discriminated union for Quote, a unified error system, and CLI, MCP and subpath exports. The migration guide is linked from the README, and the project states the change is breaking with no compatibility aliases.

Symbol handling is the part that saves the most code. The README says normalizeSymbol accepts sh600519, 600519, 600519.SH, 00700, hk00700, AAPL and 105.AAPL, and that special indices such as 930955, H30533, HSHCI and GDAXI are supported. If you have ever written a market-prefix parser, you know how many edge cases that removes.

Requests are governed per provider. The README gives providerPolicies with a timeout and a rateLimit of requestsPerSecond plus maxBurst, and a retry object with maxRetries and baseDelay. A fetchImpl and an AbortSignal can be injected, and lifecycle hooks are exposed. Errors are normalized: the README says v2 only throws SdkError outward, with codes such as HTTP_ERROR, NETWORK_ERROR, TIMEOUT, ABORTED and PARSE_ERROR, importable from stock-sdk/errors.

The subpath exports matter for bundle size. The README states that importing from stock-sdk/{indicators,signals,symbols,screener,cache,errors} avoids pulling RequestClient and the provider layer into the bundle. The indicators subpath exposes 17 pure functions across 14 indicators, including calcSMA, calcEMA, calcWMA, calcMACD, calcKDJ, calcRSI, calcBOLL, calcATR, calcOBV, calcDMI, calcSAR and calcKC. Chips distribution (CYQ) is computed locally with what the README calls the Eastmoney algorithm, and the project notes it adds no new data source. The screener and backtest functions run on arrays you already hold, with no network calls.

Installing stock-sdk and Getting a First Quote

The README gives a single install command for the current version. Node.js 18 or newer is listed as the requirement, and the package ships both ESM and CommonJS builds.

npm install stock-sdk

After installing, construct a StockSDK instance and call a namespace method. The README's example uses cnSimple with a list of symbols and prints name, price and changePercent for each. Because normalizeSymbol handles the prefixes, you can pass sh000001, sz000858 or a bare 600519.

import { StockSDK } from 'stock-sdk';

const sdk = new StockSDK();
const quotes = await sdk.quotes.cnSimple(['sh000001', 'sz000858', 'sh600519']);
quotes.forEach((q) => {
  console.log(`${q.name}: ${q.price} (${q.changePercent}%)`);
});

For a chart, the README shows kline.withIndicators with a period of daily and an indicators object carrying ma periods and macd. For a whole-market pull, sdk.batch.cn takes a concurrency option; the README's example uses 5 and notes the target is more than 5000 A-share symbols. That concurrency setting is the one to watch, because it is the difference between a slow page and a wall of rate-limit errors.

const kline = await sdk.kline.withIndicators('600519', {
  period: 'daily',
  indicators: { ma: { periods: [5, 10, 20] }, macd: {} },
});

const all = await sdk.batch.cn({ concurrency: 5 });

If you would rather not write code first, the package installs a stock-sdk binary, and the README shows npx invocations that work without a local install. Output defaults to JSON, with --format table|csv, --pretty and --limit N available.

npx stock-sdk quote 600519 00700 AAPL
npx stock-sdk kline 600519 --period weekly --limit 30
npx stock-sdk indicators 600519 --ma 5,10,20 --macd

The third command exercises the indicator path from the terminal, which is the fastest way to confirm that the package resolves and that the upstream endpoint answers from your network before you wire anything into an app.

MCP Server and CLI: Wiring Market Data into an AI Tool

The MCP integration is the part of this project that is least like a typical quote library. The README states the MCP server is hand-written with zero dependencies and does not use @modelcontextprotocol/sdk. It starts with npx stock-sdk mcp, and the README gives a JSON configuration block for clients such as Cursor, Claude Desktop, Codex and Gemini under the mcpServers key.

{
  "mcpServers": {
    "stock-sdk": {
      "command": "npx",
      "args": ["-y", "stock-sdk", "mcp"]
    }
  }
}

The tool surface is controlled by an environment variable. The README says STOCK_SDK_MCP_TOOLS accepts core, full, or a comma-separated list of tool names, and that core is the default. To expose all 92 tools, the configuration adds an env block setting STOCK_SDK_MCP_TOOLS to full. There is a parallel setting for prompts: STOCK_SDK_MCP_PROMPTS with the same core|full|list shape, defaulting to core, covering 7 scenario skills such as analyze_stock, screen_stocks and diagnose_stock.

This design has a clear trade-off. A default of core keeps the tool list short enough that a model picks correctly, but it also means an agent that needs, say, block-trade or margin data will silently lack the tool until you change the environment variable. If you are debugging an agent that claims a data type is unavailable, check STOCK_SDK_MCP_TOOLS before you check anything else.

Where stock-sdk Breaks Down

The README does not name the upstream data sources. It refers to provider policies with an eastmoney key and mentions a push2 fallback host in the v2.4.2 release notes, and the CYQ feature is described as using the Eastmoney algorithm. That tells you the data is scraped or proxied from public endpoints rather than licensed from an exchange. For a hobby dashboard this is fine. For anything where a wrong price has a cost, it is not.

Because the data comes from third-party endpoints, the failure modes are theirs as much as yours. The v2.4.2 release is titled push2 Fallback Host, which implies the primary host can become unavailable and the library had to add a fallback. The v2.4.1 release is titled fund.estimate Removal, meaning a documented capability was taken out. If your product depends on a specific field, a minor release can remove it. Pin your version and read the release notes before upgrading.

The v1 to v2 migration is the other sharp edge. The README states plainly that v2 is a breaking change with no compatibility aliases, and that the v1 documentation site is archived. If you have existing v1 code, the upgrade is a rewrite of call sites, not a version bump.

Finally, this is the wrong tool when you need historical depth, tick-level data, or corporate-action-adjusted series for serious backtesting. The README's backtest function takes klines you supply and a strategy callback returning buy, sell or hold. It is a local simulation over data you already fetched, not a research platform. Treat the numbers it prints as a sanity check, not as evidence.

How stock-sdk Differs from akshare and Python Data Libraries

The obvious alternative is akshare, the Python financial data library whose name appears in this repository's topic list. The difference is runtime and deployment shape. akshare is a Python package: you need a Python environment, and to serve a browser you need a backend process to call it and an HTTP layer to expose results. stock-sdk runs in the browser or in Node.js directly, so a static page can fetch quotes with no server of your own.

That advantage reverses when the work moves server-side. If you already run Python for data cleaning, scheduling or model training, adding akshare to an existing pipeline is one import, whereas stock-sdk would mean a second runtime or a Node service alongside it. The two are not mutually exclusive: a team can use stock-sdk for the browser-facing dashboard and keep Python for batch research.

The other category is commercial market data APIs. Those come with contracts, entitlement rules and support terms, and the README makes no such claims for stock-sdk. The honest comparison is that stock-sdk trades guarantees for zero setup. You get no account, no key, no Python, and no backend, and in exchange you accept whatever the upstream public endpoint returns on any given day.

Licence, Maintenance and the Cost of Upgrades

The package is published under the ISC licence, a permissive licence that the repository's LICENSE file carries. That covers the code. It does not cover the market data flowing through it, and the README says nothing about the terms under which the upstream endpoints may be used or redistributed. If you plan to ship a commercial product on top of this, the licence question you need answered is not about stock-sdk at all.

On maintenance, the last push to the default branch was on 2026-09-09, and the most recent release, v2.4.3, is dated the same day. The release cadence visible in the notes is roughly one minor release per month across the summer, with v2.4.1 on 2026-08-02 and v2.4.2 on 2026-08-19. The repository is not archived.

The upgrade cost is real but bounded. Because v2 removed compatibility aliases, any future major version will likely follow the same pattern: a namespace reorganization, a migration guide, and no shim. The practical hedge is to keep your calls behind a thin wrapper of your own, so a namespace rename touches one file instead of every component. The repository also ships a docs:check script and a doc-consistency checker, which suggests documentation drift is treated as a build failure rather than an afterthought.

Editorial conclusion

Adopt stock-sdk if you are building a front-end or Node.js dashboard, a course demo, or a prototype that needs A-share, Hong Kong and US quotes without standing up a backend. Do not adopt it if you need an SLA, licensed redistribution rights, or official exchange data, because the README does not name the upstream data sources or their terms. Before committing, verify three things yourself: that the endpoints respond from your deployment region, that the v1 to v2 breaking changes do not affect code you already have, and which upstream provider each namespace you depend on actually calls.

Frequently asked questions

Official sources

1. chengzuopeng/stock-sdk on GitHub
2. License: ISC
3. Project website
4. README
5. Releases