stock-sdk: an ISC-licensed TypeScript SDK that puts A-share, Hong Kong and US quotes in the browser

The gap stock-sdk fills for JavaScript developers

The README states the problem directly: market data tooling is mostly a Python ecosystem, and front-end engineers who want a quote board or a demo end up maintaining a backend service just to proxy data. The second stated pain is format chaos, with the README calling out GBK encoding, concurrency and batching as the messy parts of financial endpoints. stock-sdk targets the person who already knows JavaScript and TypeScript and does not want to learn a second runtime to render a candlestick chart. The README lists the intended uses: quote dashboards, ECharts or TradingView visualization, finance course demos, quantitative strategy prototypes in JS or Node, scheduled Node.js scraping, and a command line for one-off lookups. That list is honest about the ceiling. This is a tool for people who need data to appear on a screen or in a script, not for people who need a licensed feed with a service level agreement.

Namespaces, symbol normalization and the provider layer

The v2 API is organized by namespace rather than by a flat set of functions. The README shows sdk.quotes.cn(), sdk.kline.cn() and sdk.options.etf.dailyKline(), and describes the grouping as IDE-autocomplete friendly. Symbols are strings and the README treats the string as a first-class citizen: sh600519, 600519, 600519.SH, 00700, hk00700, AAPL and 105.AAPL are all parsed by a normalizeSymbol function, with special handling for indices such as 930955, H30533, HSHCI and GDAXI. Underneath, a provider layer handles the actual HTTP work. The README documents per-provider policies, naming eastmoney in the example config, with timeout, rateLimit.requestsPerSecond and maxBurst settings, plus retry options with maxRetries and baseDelay. There is also an injectable fetchImpl and signal, and lifecycle hooks. The error model is unified: the README states that v2 only throws SdkError outward, with codes such as HTTP_ERROR, NETWORK_ERROR, TIMEOUT, ABORTED and PARSE_ERROR, importable from stock-sdk/errors. That is a more considered architecture than most front-end data wrappers, and the provider policy object is the part worth reading before you ship anything that runs on a schedule.

Getting it running: install, first call, CLI and MCP

Installation is one command, npm install stock-sdk, and the README notes that stock-sdk@legacy is the archived v1 line that receives only critical fixes. The first call in the README constructs a StockSDK instance and awaits sdk.quotes.cnSimple(['sh000001', 'sz000858', 'sh600519']), then logs name, price and changePercent for each result. A K-line call with indicators looks like sdk.kline.withIndicators('600519', { period: 'daily', indicators: { ma: { periods: [5, 10, 20] }, macd: {} } }). For whole-market work the README shows sdk.batch.cn({ concurrency: 5 }) returning an array of A-share quotes. The CLI ships with the package: 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, npx stock-sdk search 茅台, and a generic form, npx stock-sdk quotes cn sh600519 sz000001. Output defaults to JSON and accepts --format table|csv, --pretty and --limit N. For AI tooling, npx stock-sdk mcp starts a bundled MCP server that the README says is hand-written with no @modelcontextprotocol/sdk dependency. Clients are configured through an mcpServers block with command npx and args ['-y', 'stock-sdk', 'mcp']. The environment variable STOCK_SDK_MCP_TOOLS accepts core, full, or a comma-separated tool list, defaulting to core, and the README states that full exposes 92 tools. A parallel STOCK_SDK_MCP_PROMPTS variable controls seven scenario prompts such as analyze_stock and screen_stocks.

The subpath split is the most useful packaging decision

The README is explicit that importing from stock-sdk/indicators, stock-sdk/signals, stock-sdk/symbols, stock-sdk/screener, stock-sdk/cache or stock-sdk/errors avoids pulling RequestClient and every provider into the bundle. That matters for a browser build where you want moving averages computed locally from data you already have. The indicators subpath exports 17 pure functions across 14 indicators, including calcSMA, calcEMA, calcWMA, calcMA, calcMACD, calcBOLL, calcKDJ, calcRSI, calcWR, calcBIAS, calcCCI, calcATR, calcOBV, calcROC, calcDMI, calcSAR and calcKC. The signals subpath exports calcSignals, which the README describes as event recognition over K-lines that already carry indicators, configured with ma fast and slow periods and an rsi option. The screener subpath exports screen and backtest, both described as local and network-free: screen takes any quote array and chains where, sortBy and top, while backtest takes klines and a strategy callback returning 'buy', 'sell' or 'hold', and reports totalReturn, winRate and maxDrawdown. The chips namespace, sdk.chips.cn, sdk.chips.hk and sdk.chips.us, computes cost distribution locally using what the README calls the Eastmoney algorithm, with no additional data source. If your workload is indicator math over data you already fetched, these subpaths are the reason to pick this package over hand-rolled fetch calls.

Where the design shows its limits

The most concrete limitation is stated by the project itself: v2 is a breaking change from v1 with no compatibility aliases, and the README points to a migration guide before upgrading. Any team that shipped against v1 has a rewrite, not a version bump. The second limitation follows from the architecture. Every data point comes from a third-party endpoint, and the release history shows what that costs. v2.4.2 is titled push2 Fallback Host, which indicates the upstream host changed or failed and the SDK needed a fallback. v2.4.1 is titled fund.estimate Removal, meaning a documented capability was deleted in a patch release. v2.4.3 addresses fund flow and board changes. That cadence is normal for a wrapper around public endpoints, but it means your build can break for reasons outside your control, and the providerPolicies config exists precisely because those endpoints rate-limit and time out. The third limitation is scope. The README's data covers A-shares, Hong Kong, US equities and public funds, plus futures, options, fund flow, dragon-tiger lists, northbound flow, block trades, margin trading and limit-up boards. If you need intraday tick history, order book depth, or any non-Chinese market beyond US symbols, the material does not claim coverage. For a production trading system, this is the wrong tool.

How it compares to akshare and to writing your own client

The README's own framing puts stock-sdk against the Python ecosystem, and akshare is named in the repository topics. The difference is runtime and distribution, not data. akshare is a Python library, so using it in a browser means a server process in between, and that process becomes something you deploy, monitor and pay for. stock-sdk runs the same class of public market endpoints from JavaScript in the browser or in Node.js 18 or later, which removes the middle tier for read-only display workloads. The cost of that choice is that your API keys, if any were needed, and your rate-limit budget live in the client, and the SDK's own provider policies are the only throttle between your users and the upstream host. Against writing your own fetch wrapper, the SDK's advantage is the accumulated handling: symbol normalization across seven or more formats, GBK and parsing quirks, concurrency control in sdk.batch.cn, retry and circuit breaking, and a typed Quote union. The disadvantage is that you inherit someone else's release schedule, as the fund.estimate removal shows. Both comparisons point the same way. If you want the data pipeline to be someone else's operational problem, use a hosted API with a contract. If you want no backend at all and can tolerate upstream churn, stock-sdk is the shorter path.

Licence, maintenance and what to check before you pin a version

The package is ISC licensed, a permissive licence that imposes few obligations on redistribution. That covers the code. It does not cover the data, and the README does not discuss the terms of the upstream endpoints the SDK calls, so the compliance question for a commercial deployment is one you have to answer outside this repository. The maintenance signal is the release cadence: three releases between August 2 and September 9, 2026, each tied to a specific upstream change, with the repository not archived and the last push matching the newest release. That is active maintenance of a moving target rather than a stable interface. The practical consequence is version pinning. Pin an exact version, read the release title before bumping, and check the migration guide before crossing any major boundary, because the v1 to v2 experience shows the project will make breaking changes when the architecture warrants it. The documentation lives at stock-sdk.linkdiary.cn, with an archived v1 site, a playground, and separate pages for symbols, MCP and AI skills. If the symbol formats or the MCP tool list matter to your integration, those pages are where the README stops and the detail begins.

Editorial conclusion

Adopt stock-sdk if you are building a browser dashboard, a teaching demo, or a Node.js script that needs A-share, Hong Kong or US quotes and you would rather not stand up a Python service. Do not adopt it if you need a contractual data feed, exchange-grade tick data, or a stable API surface across major versions, because the README states that the v1 to v2 migration is a breaking change with no compatibility aliases. Before committing, verify three things against your own environment: that the upstream endpoints the SDK calls are reachable from your network and your users' networks, that the ISC licence and the data source's own terms are acceptable for your distribution model, and that the specific namespace methods you need exist in the version you pin, since v2.4.1 removed fund.estimate.

Official sources

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