Profile
Back to NewsBack
GitHub Trending 4 min
Reader Mode
chengzuopeng/stock-sdk: 为前端设计的无需 Python、无需后端服务、零依赖的获取股票数据 JavaScript SDK。

chengzuopeng/stock-sdk: 为前端设计的无需 Python、无需后端服务、零依赖的获取股票数据 JavaScript SDK。

Stock SDK

npm version</a> npm downloads</a> license</a> MCP</a> AI Ready</a>

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)

安装

# 最新版(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。参数格式错误会返回退出码 2。用 stock-sdk fundFlow rank --help 查看资金流排名的分页参数。


🤖 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 暴露全量 MCP 工具,在配置中加入 env:

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

MCP 在调用 SDK 前校验数组元素和嵌套指标配置。K 线和信号超限时保留最近记录。基金净值和同类排名工具支持 startDate / endDate,并在 coverage 中标注实际返回的区间。MCP 工具文档

内置 7 个场景化 AI Skills(MCP Prompts)。STOCK_SDK_MCP_PROMPTS 选择技能范围,客户端会发现当前工具集可以执行的技能。将工具和技能范围都设为 full 可使用全部 7 个。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..() 映射表)。

开发校验

pnpm typecheck
pnpm build
pnpm test
pnpm test:integration:smoke   # 冒烟集成(真实网络)
pnpm test:integration:full    # 全量集成回归

许可证

ISC


🌐 官网 | 📦 NPM | 📖 GitHub | 🎮 在线演示 | 🧭 Stock Dashboard | 🐛 Issues


如果这个项目对你有帮助,欢迎 Star ⭐ 或提出 Issue 反馈。

Chat with me