Stock SDK

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, Quote discriminated 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).

📖 Official docs

👉 https://stock-sdk.linkdiary.cn/en/

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.

Why stock-sdk?

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.

---

Use cases

• 📊 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

---

Features

• ✅ 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: string as a first-class input — sh600519 / 600519 / 600519.SH / 00700 / hk00700 / AAPL / 105.AAPL are 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 SdkError is thrown to callers, each with a stable code, importable from stock-sdk/errors
• ✅ Request governance: per-provider retry / rate-limit / circuit-breaker + injectable fetchImpl / signal / lifecycle hooks
• ✅ CLI: stock-sdk quote 600519 to pull quotes straight from the terminal
• ✅ Built-in MCP server: stock-sdk mcp wires up Cursor / Claude / Codex and other AI tools in one line (hand-written, zero deps, no @modelcontextprotocol/sdk)

---

Installation

# Latest (v2: namespaced API / CLI / MCP)
npm install stock-sdk

# v1 legacy (frozen, critical fixes only)
npm install stock-sdk@legacy

Quick start

import { 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 by normalizeSymbol.

---

Command line (CLI)

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 sz000001

JSON output by default; add --format table|csv, --pretty, --limit N.

---

🤖 AI / MCP integration

v2 ships a built-in, zero-dependency MCP server — start it with one command:

npx stock-sdk mcp

Wire 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 all 92 MCP tools when launching through npx, add the env entry:

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

Beyond tools, it ships 7 scenario AI Skills (MCP Prompts — e.g. analyze_stock / screen_stocks / diagnose_stock) that Prompts-aware clients can trigger in one click; STOCK_SDK_MCP_PROMPTS=core|full|<list> controls the skill set (default core). See the AI Skills docs.

👉 Full MCP docs

---

Signals / screener / backtest

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);

---

Request governance & errors

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 ...
}

---

Subpath exports

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';

---

Market coverage matrix

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)	✅	✅	✅	⚠️ listed ETF/LOF	✅ domestic + global	✅
Minute K-line (5/15/30/60)	✅	✅ kline.hkMinute	✅ kline.usMinute	⚠️ listed ETF/LOF	❌	❌
Chip distribution (CYQ)	✅ chips.cn	✅ chips.hk	✅ chips.us	—	—	—
Intraday (1-min)	✅ quotes.timeline	✅ kline.hkMinute(period='1')	✅ kline.usMinute(period='1')	⚠️ listed ETF/LOF	❌	✅ 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.*	⚠️ market status only	⚠️ market status only	—	—	—

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 push2his is disconnected or soft-limited. To request Eastmoney only, turn this off with new StockSDK({ klineFallback: false }).

---

API overview (namespaces)

💡 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 full sdk.getXxx() → sdk.<ns>.<method>() mapping).

---

Dev checks

pnpm typecheck
pnpm build
pnpm test
pnpm test:integration:smoke   # smoke integration (real network)
pnpm test:integration:full    # full integration regression

---

License

ISC

---

🌐 Website | 📦 NPM | 📖 GitHub | 🎮 Live Demo | 🧭 Stock Dashboard | 🐛 Issues

---

If this project helps you, a Star ⭐ or an Issue is very welcome.