English | 中文
A stock market data JavaScript SDK for frontend and Node.js.
No Python. No backend service. Fetch real-time quotes and K-line data for A-shares / Hong Kong stocks / US stocks / mutual funds directly in the browser or Node.js. It also ships a command-line tool and an MCP server — one command to pull quotes or wire up AI tools.
✨ Zero dependencies, Lightweight distribution | 🌐 Browser + Node.js | 📦 ESM + CJS + subpaths | 🧠 Full TypeScript typings | 🖥️ CLI | 🤖 MCP
✨ v2.0.0: v2 is an architectural leap (namespaced API, unified symbol model,
Quotediscriminated union, unified error system, CLI / MCP / subpath exports). Install:npm i stock-sdk. Upgrading from v1? Read the v1 → v2 migration guide first (breaking changes, no compat aliases).
Full API, namespace overview, CLI / MCP guides, the online Playground, and the v1 → v2 migration guide all live here. Start with the docs for the fastest onboarding.
(v1 stable docs are archived)
📦 NPM | 📖 GitHub | 🎮 Live Playground
🧭 Stock Dashboard: A stock market dashboard demo built with stock-sdk. Feel free to try it.
If you're a frontend engineer, you may have encountered these problems:
- Most stock market tools are in the Python ecosystem, making them hard to use directly in frontend
- You want to build a quote dashboard / demo without maintaining an extra backend service
- Financial APIs return messy, complex formats (GBK encoding / concurrency / batching)
stock-sdk's goal is simple:
Let frontend engineers fetch stock market data elegantly, using the JavaScript / TypeScript they already know.
- 📊 Stock quote dashboards (Web / Admin)
- 📈 Data visualization (ECharts / TradingView)
- 🎓 Stock / finance course demos
- 🧪 Quant strategy prototyping (JS / Node)
- 🕒 Scheduled quote scraping in Node.js
- 🖥️ Ad-hoc quotes from the terminal / 🤖 a data source for AI tools
- ✅ Zero dependencies, runs in both the browser and Node.js 18+; ships both ESM and CommonJS
- ✅ Namespaced API:
sdk.quotes.cn()/sdk.kline.cn()/sdk.options.etf.dailyKline(), grouped by domain, great IDE autocomplete - ✅ Unified symbol model:
stringas a first-class input —sh600519/600519/600519.SH/00700/hk00700/AAPL/105.AAPLare all parsed tolerantly; special indices supported (930955/H30533/HSHCI/GDAXI, see the symbols guide) - ✅ A-shares / HK / US / mutual funds: real-time quotes, daily/weekly/monthly K-lines, minute K-lines (1/5/15/30/60), intraday time-series
- ✅ Technical indicators: MA / MACD / BOLL / KDJ / RSI / WR / BIAS / CCI / ATR / OBV / ROC / DMI / SAR / KC
- ✅ Chip distribution (CYQ):
sdk.chips.cn/hk/us— profit ratio / average cost / 90-70 cost ranges & concentration / chip-peak histogram (Eastmoney's algorithm computed locally, no new data source) - ✅ Signals / screener / backtest:
calcSignals(golden/death cross, overbought/oversold, etc.), a chainable screener, local backtesting - ✅ Futures / options / fund flow / dragon-tiger list / northbound / block trades / margin / limit-up pool and more
- ✅ Mutual-fund deep data: NAV history, peer-ranking trends, deep profiles (top holdings / managers / scale), fund/ETF dividends, theme funds
- ✅ Subpath exports:
stock-sdk/{indicators,signals,symbols,screener,cache,errors}— pure-compute imports don't pull in the network layer (tree-shake friendly) - ✅ Unified error system: only
SdkErroris thrown to callers, each with a stablecode, importable fromstock-sdk/errors - ✅ Request governance: per-provider retry / rate-limit / circuit-breaker + injectable
fetchImpl/signal/ lifecyclehooks - ✅ CLI:
stock-sdk quote 600519to pull quotes straight from the terminal - ✅ Built-in MCP server:
stock-sdk mcpwires up Cursor / Claude / Codex and other AI tools in one line (hand-written, zero deps, no@modelcontextprotocol/sdk)
# Latest (v2: namespaced API / CLI / MCP)
npm install stock-sdk
# v1 legacy (frozen, critical fixes only)
npm install stock-sdk@legacyimport { StockSDK } from 'stock-sdk';
const sdk = new StockSDK();
// Namespaced API (v2) — symbol input is tolerant: '600519' / 'sh600519' / '600519.SH' all work
const quotes = await sdk.quotes.cnSimple(['sh000001', 'sz000858', 'sh600519']);
quotes.forEach((q) => {
console.log(`${q.name}: ${q.price} (${q.changePercent}%)`);
});
// History K-line + technical indicators
const kline = await sdk.kline.withIndicators('600519', {
period: 'daily',
indicators: { ma: { periods: [5, 10, 20] }, macd: {} },
});
// Whole-market A-share quotes (5000+ stocks, built-in concurrency control)
const all = await sdk.batch.cn({ concurrency: 5 });
console.log(`${all.length} stocks`);HK
'00700'/'hk00700', US'AAPL'/'105.AAPL'— all normalized bynormalizeSymbol.
After install you get the stock-sdk command (or use npx):
# Quotes (market auto-detected from the code)
npx stock-sdk quote 600519 00700 AAPL
# K-line with output truncation
npx stock-sdk kline 600519 --period weekly --limit 30
# With technical indicators
npx stock-sdk indicators 600519 --ma 5,10,20 --macd
# Search
npx stock-sdk search 茅台
# Direct access to any namespace method
npx stock-sdk quotes cn sh600519 sz000001The CLI defaults to JSON output and accepts --format table|csv, --pretty, and --limit N. Invalid arguments produce exit code 2. Run stock-sdk fundFlow rank --help to see the ranking pagination flags.
v2 ships a built-in, zero-dependency MCP server — start it with one command:
npx stock-sdk mcpWire it into Cursor / Claude Desktop / Codex / Gemini, etc. (mcpServers config):
{
"mcpServers": {
"stock-sdk": {
"command": "npx",
"args": ["-y", "stock-sdk", "mcp"]
}
}
}STOCK_SDK_MCP_TOOLS=core|full|<comma-separated tool names> controls the tool set (default core).
To expose the full MCP tool set when launching through npx, add the env entry:
{
"mcpServers": {
"stock-sdk": {
"command": "npx",
"args": ["-y", "stock-sdk", "mcp"],
"env": { "STOCK_SDK_MCP_TOOLS": "full" }
}
}
}MCP validates array entries and nested indicator settings before calling the SDK. It keeps the newest K-lines and signals when results exceed its limits. Fund NAV and peer-rank tools accept startDate and endDate and report the returned interval in coverage. MCP tool docs
The SDK ships seven scenario AI Skills as MCP Prompts. STOCK_SDK_MCP_PROMPTS selects skills, and the client discovers those that the active tool set can run. Set both the tool and prompt tiers to full to use all seven. AI Skills docs
import { calcSignals } from 'stock-sdk/signals';
import { screen, backtest } from 'stock-sdk/screener';
// Event detection (golden/death cross, overbought/oversold) on indicator-enriched K-lines
const signals = calcSignals(klineWithIndicators, {
ma: { fast: 5, slow: 20 },
rsi: {},
});
// Chainable screening over any quote array — purely local, no network
const picks = screen(allQuotes)
.where((q) => q.pe != null && q.pe < 20)
.where((q) => q.changePercent > 3)
.sortBy((q) => q.amount)
.top(20);
// Local backtest
const report = backtest({
klines,
strategy: (bar, i, all) => 'hold', // return 'buy' | 'sell' | 'hold'
});
console.log(report.totalReturn, report.winRate, report.maxDrawdown);import { StockSDK } from 'stock-sdk';
import { HttpError, getSdkErrorCode } from 'stock-sdk/errors';
const sdk = new StockSDK({
retry: { maxRetries: 2, baseDelay: 500 },
providerPolicies: {
eastmoney: { timeout: 12000, rateLimit: { requestsPerSecond: 3, maxBurst: 3 } },
},
});
try {
await sdk.quotes.cnSimple(['sh600519']);
} catch (error) {
// v2 only throws SdkError, each carrying a stable code
if (error instanceof HttpError) console.log(error.status, error.statusText);
console.log(getSdkErrorCode(error)); // HTTP_ERROR / NETWORK_ERROR / TIMEOUT / ABORTED / PARSE_ERROR ...
}For pure-compute use (indicators / symbols / signals / screener), import from a subpath so the bundle doesn't pull in RequestClient or any provider:
// 14 indicators, 17 pure functions in total (the MA family ships calcSMA /
// calcEMA / calcWMA variants): calcSMA / calcEMA / calcWMA / calcMA /
// calcMACD / calcBOLL / calcKDJ / calcRSI / calcWR / calcBIAS / calcCCI /
// calcATR / calcOBV / calcROC / calcDMI / calcSAR / calcKC
import { calcMACD, calcKDJ } from 'stock-sdk/indicators';
import { normalizeSymbol, toTencentSymbol } from 'stock-sdk/symbols';
import { calcSignals } from 'stock-sdk/signals';
import { screen, backtest } from 'stock-sdk/screener';
import { MemoryCacheStore, cacheThrough } from 'stock-sdk/cache';
import { SdkError, isSdkError, getSdkErrorCode } from 'stock-sdk/errors';Coverage varies by market — this table helps you quickly check whether the SDK fits your scenario.
- ✅ Supported |
⚠️ Partial (see notes) | ❌ Not yet | — Not applicable
| Capability | A-share | HK | US | Mutual fund | Futures | Options |
|---|---|---|---|---|---|---|
| Real-time quotes | ✅ | ✅ | ✅ | ✅ | ✅ global | ✅ ETF / CFFEX / commodity |
| History K-line (D/W/M) | ✅ | ✅ | ✅ | ✅ domestic + global | ✅ | |
| Minute K-line (5/15/30/60) | ✅ | ✅ kline.hkMinute |
✅ kline.usMinute |
❌ | ❌ | |
| Chip distribution (CYQ) | ✅ chips.cn |
✅ chips.hk |
✅ chips.us |
— | — | — |
| Intraday (1-min) | ✅ quotes.timeline |
✅ kline.hkMinute(period='1') |
✅ kline.usMinute(period='1') |
❌ | ✅ ETF options | |
| Dividends | ✅ | ❌ | ❌ | ✅ fund + ETF | — | — |
| Fund flow | ✅ stock/market/rank/sector | ❌ | ❌ | — | — | — |
| Sectors (industry / concept) | ✅ | ❌ | ❌ | ❌ | — | — |
| Dragon-tiger list | ✅ | — | — | — | — | ✅ option LHB |
| Stock Connect / northbound | ✅ northbound | ✅ southbound | — | — | — | — |
| Block trades / margin | ✅ | ❌ | ❌ | — | — | — |
| Limit-up pool / abnormal moves | ✅ | — | — | — | — | — |
| Code list / batch quotes | ✅ 5000+ | ✅ | ✅ | ✅ codes | ❌ | ❌ |
| Inventory data | — | — | — | — | ✅ domestic + COMEX | — |
| Trading calendar | ✅ calendar.* |
— | — | — |
Data latency: real-time quotes come from public endpoints (Tencent Finance / Eastmoney, etc.), not exchange matching feeds — typically delayed by seconds to minutes. Not suitable for high-frequency trading decisions.
K-line fallback: Regular CN historical and 5/15/30/60-minute K-lines use Eastmoney primarily and fall back to Tencent, then Sina OHLCV when
push2hisis disconnected or soft-limited. To request Eastmoney only, turn this off withnew StockSDK({ klineFallback: false }).
💡 Full API in the documentation. In v2, every method lives under a namespace:
| Namespace | Representative methods |
|---|---|
sdk.quotes |
.cn / .cnSimple / .hk / .us / .fund / .fundFlow / .largeOrder / .timeline |
sdk.codes |
.cn / .us / .hk / .fund |
sdk.batch |
.cn / .hk / .us / .byCodes / .raw |
sdk.kline |
.cn / .cnMinute / .hk / .hkMinute / .us / .usMinute / .withIndicators / .signals |
sdk.chips |
.cn / .hk / .us (chip distribution: profit ratio / avg cost / cost ranges / chip peak) |
sdk.board |
.industry.* / .concept.* (list / spot / constituents / kline / minuteKline) |
sdk.options |
.index.* / .etf.* / .commodity.* / .cffex.* / .lhb |
sdk.futures |
.kline / .globalSpot / .globalKline / .inventory / .comexInventory … |
sdk.fundFlow |
.individual / .market / .rank / .sectorRank (both rankings support page / pageSize) / .sectorHistory |
sdk.northbound |
.minute / .summary / .holdingRank / .history / .individual |
sdk.marketEvent |
.ztPool / .stockChanges (multi-type / 'all' / page paging) / .boardChanges / .individualChanges / .individualChangesHistory (per-stock changes) / .unusualFluctuation (regulatory fluctuation alerts) |
sdk.dragonTiger |
.detail / .stockStats / .institution / .branchRank / .seatDetail |
sdk.blockTrade / sdk.margin |
block trades / margin trading |
sdk.fund |
.dividendList / .navHistory / .rankHistory / .profile / .theme.* (getThemeList / getThemeFunds) |
sdk.calendar |
.isTradingDay / .nextTradingDay / .prevTradingDay / .marketStatus |
sdk.reference |
.dividendDetail / .tradingCalendar |
| top-level | sdk.search(keyword) |
sdk.quotes.fundFlow(codes) provides Eastmoney-sourced real-time A-share fund-flow snapshots, including main/small-order inflow, outflow, net amount, and ratios. Use sdk.fundFlow.* for history, rankings, and sector flows.
Indicator math moved from the main package to a subpath:
import { calcMACD } from 'stock-sdk/indicators'. Migrating from the v1 flat API? See the v1 → v2 migration guide (with the fullsdk.getXxx()→sdk.<ns>.<method>()mapping).
pnpm typecheck
pnpm build
pnpm test
pnpm test:integration:smoke # smoke integration (real network)
pnpm test:integration:full # full integration regression🌐 Website | 📦 NPM | 📖 GitHub | 🎮 Live Demo | 🧭 Stock Dashboard | 🐛 Issues
If this project helps you, a Star ⭐ or an Issue is very welcome.