Stock SDK
English | 中文
为 前端和 Node.js 设计的股票行情 JavaScript SDK。
无需 Python、无需后端服务，直接在 浏览器或 Node.js 中获取 A 股 / 港股 / 美股 / 公募基金 的实时行情与 K 线数据。还自带 命令行工具 与 MCP server，一条命令取行情或接入 AI。
✨ 零依赖、轻量发布包 | 🌐 Browser + Node.js | 📦 ESM + CJS + subpath | 🧠 完整 TypeScript 类型 | 🖥️ CLI | 🤖 MCP
✨ v2.0.0：v2 是一次架构跃迁（命名空间 API、统一符号模型、Quote 可辨识联合、统一错误体系、CLI / MCP / subpath 导出）。
安装：npm i stock-sdk。从 v1 升级请先读 v1 → v2 迁移指南（破坏性变更，无兼容别名）。
📖 官网文档
完整 API、命名空间总览、CLI / MCP 指南、在线 Playground、v1 → v2 迁移文档全部在这里。先看官网再上手最快。
（v1 稳定版文档 已归档）
📦 NPM | 📖 GitHub | 🎮 在线 Playground
🧭 Stock Dashboard：基于 stock-sdk 搭建的股票数据大盘演示站点，欢迎体验。
Why stock-sdk？
如果你是前端工程师，可能遇到过这些问题：
- 股票行情工具大多是 Python 生态，前端难以直接使用
- 想做行情看板 / Demo，不想额外维护后端服务
- 财经接口返回格式混乱、编码复杂（GBK / 并发 / 批量）
stock-sdk 的目标很简单：
让前端工程师，用最熟悉的 JavaScript / TypeScript，优雅地获取股票行情数据。
使用场景
- 📊 股票行情看板（Web / Admin）
- 📈 数据可视化（ECharts / TradingView）
- 🎓 股票 / 金融课程 Demo
- 🧪 量化策略原型验证（JS / Node）
- 🕒 Node.js 定时抓取行情数据
- 🖥️ 命令行临时查行情 / 🤖 给 AI 工具接数据源
特性
- ✅ 零依赖，浏览器 + Node.js 18+ 双端运行；同时提供 ESM 和 CommonJS
- ✅ 命名空间 API：
sdk.quotes.cn() / sdk.kline.cn() / sdk.options.etf.dailyKline()，按领域分组、IDE 自动补全友好
- ✅ 统一符号模型：
string 一等公民，sh600519 / 600519 / 600519.SH / 00700 / hk00700 / AAPL / 105.AAPL 等写法容错解析；支持中证等特殊指数（930955 / H30533 / HSHCI / GDAXI，详见符号指南）
- ✅ A 股 / 港股 / 美股 / 公募基金实时行情、历史 K 线（日/周/月）、分钟 K 线（1/5/15/30/60）、当日分时
- ✅ 技术指标：MA / MACD / BOLL / KDJ / RSI / WR / BIAS / CCI / ATR / OBV / ROC / DMI / SAR / KC
- ✅ 筹码分布（CYQ）：
sdk.chips.cn/hk/us 获利比例 / 平均成本 / 90-70 成本区间与集中度 / 筹码峰直方图（东财算法本地计算，零新增数据源）
- ✅ 信号 / 选股 / 回测：
calcSignals（金叉死叉/超买超卖等事件识别）、链式选股器、本地回测
- ✅ 期货 / 期权 / 资金流 / 龙虎榜 / 北向 / 大宗交易 / 融资融券 / 涨停板 等全套扩展数据
- ✅ 基金深度数据：历史净值、同类排名走势、深度资料（重仓股 / 基金经理 / 规模等）、基金/ETF 分红送配、主题基金
- ✅ subpath 导出：
stock-sdk/{indicators,signals,symbols,screener,cache,errors}，纯计算不拖入网络层，tree-shake 友好
- ✅ 统一错误体系：对外只抛
SdkError，带标准 code，可从 stock-sdk/errors 导入
- ✅ 请求治理：provider 级重试 / 限流 / 熔断 + 可注入
fetchImpl / signal / 生命周期 hooks
- ✅ CLI：
stock-sdk quote 600519 终端直接取行情
- ✅ 内置 MCP server：
stock-sdk mcp 一行接入 Cursor / Claude / Codex 等 AI 工具（零依赖手写，无 @modelcontextprotocol/sdk）
安装
# 最新版（v2：命名空间 API / CLI / MCP）
npm install stock-sdk
# v1 旧版（已封存，仅维护 critical 修复）
npm install stock-sdk@legacy
快速开始
import { StockSDK } from 'stock-sdk';
const sdk = new StockSDK();
// 命名空间 API（v2）— 符号写法容错，'600519' / 'sh600519' / '600519.SH' 都可
const quotes = await sdk.quotes.cnSimple(['sh000001', 'sz000858', 'sh600519']);
quotes.forEach((q) => {
console.log(`${q.name}: ${q.price} (${q.changePercent}%)`);
});
// 历史 K 线 + 技术指标
const kline = await sdk.kline.withIndicators('600519', {
period: 'daily',
indicators: { ma: { periods: [5, 10, 20] }, macd: {} },
});
// 全市场 A 股行情（5000+ 股票，内置并发控制）
const all = await sdk.batch.cn({ concurrency: 5 });
console.log(`共 ${all.length} 只`);
港股 '00700' / 'hk00700'，美股 'AAPL' / '105.AAPL'，由 normalizeSymbol 统一容错解析。
命令行（CLI）
安装后即得 stock-sdk 命令（或用 npx）：
# 行情（按代码自动识别市场）
npx stock-sdk quote 600519 00700 AAPL
# K 线 + 输出截断
npx stock-sdk kline 600519 --period weekly --limit 30
# 带技术指标
npx stock-sdk indicators 600519 --ma 5,10,20 --macd
# 搜索
npx stock-sdk search 茅台
# 任意命名空间方法直达
npx stock-sdk quotes cn sh600519 sz000001
默认 JSON 输出，可加 --format table|csv、--pretty、--limit N。
🤖 AI / MCP 集成
v2 内置零依赖 MCP server，一条命令启动：
npx stock-sdk mcp
接入 Cursor / Claude Desktop / Codex / Gemini 等（配置 mcpServers）：
{
"mcpServers": {
"stock-sdk": {
"command": "npx",
"args": ["-y", "stock-sdk", "mcp"]
}
}
}
环境变量 STOCK_SDK_MCP_TOOLS=core|full|<逗号分隔工具名> 控制工具集范围（默认 core）。
要通过 npx 暴露全部 92 个 MCP 工具，在配置中加入 env：
{
"mcpServers": {
"stock-sdk": {
"command": "npx",
"args": ["-y", "stock-sdk", "mcp"],
"env": { "STOCK_SDK_MCP_TOOLS": "full" }
}
}
}
除工具外还内置 7 个场景化 AI Skills（MCP Prompts，如 analyze_stock / screen_stocks / diagnose_stock），支持的客户端可一键触发；STOCK_SDK_MCP_PROMPTS=core|full|<名单> 控制技能集（默认 core）。详见 AI Skills 文档。
👉 完整 MCP 文档
信号 / 选股 / 回测
import { calcSignals } from 'stock-sdk/signals';
import { screen, backtest } from 'stock-sdk/screener';
// 金叉/死叉/超买超卖等事件识别（基于带指标的 K 线）
const signals = calcSignals(klineWithIndicators, {
ma: { fast: 5, slow: 20 },
rsi: {},
});
// 链式选股（输入任意行情数组，纯本地、无网络）
const picks = screen(allQuotes)
.where((q) => q.pe != null && q.pe < 20)
.where((q) => q.changePercent > 3)
.sortBy((q) => q.amount)
.top(20);
// 本地回测
const report = backtest({
klines,
strategy: (bar, i, all) => 'hold', // 返回 '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 对外只抛 SdkError，带统一 code
if (error instanceof HttpError) console.log(error.status, error.statusText);
console.log(getSdkErrorCode(error)); // HTTP_ERROR / NETWORK_ERROR / TIMEOUT / ABORTED / PARSE_ERROR ...
}
子路径导出（subpath）
只用纯计算（指标 / 符号 / 信号 / 选股）时，从 subpath 导入，bundle 不会拖入 RequestClient 与所有 provider：
// 14 个指标、共 17 个纯函数(MA 族含 calcSMA/calcEMA/calcWMA 三个变体):
// 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';
市场支持矩阵
不同市场的能力覆盖度差异较大，下表帮你快速判断 SDK 是否覆盖你的场景。
- ✅ 已支持 ｜ ⚠️ 部分支持（见备注）｜ ❌ 暂未实现 ｜ — 概念不适用
| 能力 |
A 股 |
港股 |
美股 |
公募基金 |
期货 |
期权 |
| 实时行情 |
✅ |
✅ |
✅ |
✅ |
✅ 全球期货 |
✅ ETF / 中金所 / 商品 |
| 历史 K 线（日/周/月） |
✅ |
✅ |
✅ |
⚠️ 场内 ETF/LOF |
✅ 国内 + 全球 |
✅ |
| 分钟 K 线（5/15/30/60） |
✅ |
✅ kline.hkMinute |
✅ kline.usMinute |
⚠️ 场内 ETF/LOF |
❌ |
❌ |
| 筹码分布（CYQ） |
✅ chips.cn |
✅ chips.hk |
✅ chips.us |
— |
— |
— |
| 当日分时（1 分钟） |
✅ quotes.timeline |
✅ kline.hkMinute(period=‘1’) |
✅ kline.usMinute(period=‘1’) |
⚠️ 场内 ETF/LOF |
❌ |
✅ ETF 期权 |
| 分红派送 |
✅ |
❌ |
❌ |
✅ 基金 + ETF |
— |
— |
| 资金流向 |
✅ 个股/大盘/排名/板块 |
❌ |
❌ |
— |
— |
— |
| 板块（行业 / 概念） |
✅ |
❌ |
❌ |
❌ |
— |
— |
| 龙虎榜 |
✅ |
— |
— |
— |
— |
✅ 期权龙虎榜 |
| 沪深港通 / 北向资金 |
✅ 北向 |
✅ 南向 |
— |
— |
— |
— |
| 大宗交易 / 融资融券 |
✅ |
❌ |
❌ |
— |
— |
— |
| 涨停板 / 盘口异动 |
✅ |
— |
— |
— |
— |
— |
| 全市场代码列表 / 批量行情 |
✅ 5000+ |
✅ |
✅ |
✅ 代码 |
❌ |
❌ |
| 库存数据 |
— |
— |
— |
— |
✅ 国内 + COMEX |
— |
| 交易日历 |
✅ calendar.* |
⚠️ 仅市场状态 |
⚠️ 仅市场状态 |
— |
— |
— |
数据延迟：实时行情来自腾讯财经 / 东方财富等公开接口，非实时撮合，通常有数十秒到数分钟延迟，不适合高频交易决策。
K 线降级：普通 A 股历史 K 线及 5/15/30/60 分钟 K 线以东方财富为主源；遇到 push2his 频控断连或软限流时按腾讯、新浪顺序切换 OHLCV 备用源。不需要切换时用 new StockSDK({ klineFallback: false }) 关闭，只请求东方财富。
API 概览（命名空间）
💡 完整 API 见 官方文档。v2 全部方法挂在命名空间下：
| 命名空间 |
代表方法 |
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（筹码分布：获利比例 / 平均成本 / 成本区间 / 筹码峰） |
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（排名均支持 page / pageSize 分页） / .sectorHistory |
sdk.northbound |
.minute / .summary / .holdingRank / .history / .individual |
sdk.marketEvent |
.ztPool / .stockChanges(支持多类型 / 'all' / page 分页) / .boardChanges / .individualChanges / .individualChangesHistory(个股异动) / .unusualFluctuation(监管异动) |
sdk.dragonTiger |
.detail / .stockStats / .institution / .branchRank / .seatDetail |
sdk.blockTrade / sdk.margin |
大宗交易 / 融资融券 |
sdk.fund |
.dividendList / .navHistory / .rankHistory / .profile / .theme.*（getThemeList / getThemeFunds） |
sdk.calendar |
.isTradingDay / .nextTradingDay / .prevTradingDay / .marketStatus |
sdk.reference |
.dividendDetail / .tradingCalendar |
| 顶层 |
sdk.search(keyword) |
其中 sdk.quotes.fundFlow(codes) 提供东方财富源的 A 股实时资金流快照，按代码返回主力与小单流入、流出、净额及占比；历史、排名和板块资金流使用 sdk.fundFlow.*。
指标计算从主包改为 subpath：import { calcMACD } from 'stock-sdk/indicators'。
从 v1 扁平 API 迁移？见 v1 → v2 迁移指南（含完整 sdk.getXxx() → sdk.<ns>.<method>() 映射表）。
开发校验
pnpm typecheck
pnpm build
pnpm test
pnpm test:integration:smoke # 冒烟集成（真实网络）
pnpm test:integration:full # 全量集成回归
许可证
ISC
🌐 官网 | 📦 NPM | 📖 GitHub | 🎮 在线演示 | 🧭 Stock Dashboard | 🐛 Issues
如果这个项目对你有帮助，欢迎 Star ⭐ 或提出 Issue 反馈。
评论