chengzuopeng/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 迁移指南（破坏性变更，无兼容别名）。
## 📖 官网文档
> ## 👉 https://stock-sdk.linkdiary.cn
> 完整 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）
## 安装
bash
# 最新版（v2：命名空间 API / CLI / MCP）
npm install stock-sdk
# v1 旧版（已封存，仅维护 critical 修复）
npm install stock-sdk@legacy
## 快速开始
ts
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）：
bash
# 行情（按代码自动识别市场）
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，一条命令启动：