global-stock-data

> 📦 项目主页：https://github.com/simonlin1212/global-stock-data — 更新、反馈、支持作者 > > 作者：Simon 林 · X [@linsizhen](https://x.com/linsizhen) · 邮箱：simonlin0423@gmail.com # 美股港股全栈数据工具包 V2.0 — 官方源优先 十三层数据架构，30+ 个端点，11 个数据源，全部零鉴权，实测可用（2026-07-24 全量回归验证）。 **V2.0 设计原则：官方源优先。** 新增层的主力数据取自美国政府（SEC EDGAR / Treasury / CFTC）、 自律组织（FINRA）与交易所（CBOE / Nasdaq）的公开端点。**每个数据源都标注了合规级别与条款原文** （见下方「数据源合规分级」）——"官方"不等于"可自由使用"，各源差异极大。 **本工具只分发代码，不分发、不转售任何市场数据**；数据由使用者自行按各源条款获取。 **使用方式：** 将本文件放入 `~/.claude/skills/global-stock-data/SKILL.md`，Claude Code 会自动识别并在美股/港股相关对话中激活。 ``` 行情层（实时/延时） ├── 新浪财经 → 美股 gb_XXXX 36字段 / 港股 rt_hkXXXXX 25字段 ├── 腾讯财经 → 美股 usXXXX 71字段 / 港股 r_hkXXXXX 78字段 └── 东财 push2 → 美股/港股 secid 实时行情，含中文名/涨跌幅/换手率 K线层（日/周/月/分钟） ├── 新浪 → 美股日K (回溯至1984年) └── Yahoo chart → 美股+港股 (v8 API, 零crumb) 技术指标层（纯计算，零额外依赖） └── MA/EMA + MACD + RSI + KDJ + 布林带 基于K线OHLCV，纯Python计算 基本面层 ├── 东财 datacenter → 美股/港股三表(资产负债+利润+现金流) + GMAININDICATOR(关键指标) ├── Yahoo crumb → 23个模块(财务数据+关键指标+分析师+机构持仓) └── SEC EDGAR XBRL → 美股503个GAAP指标 (仅美股) 资金面层 └── 东财 push2his → 日级资金流(主力/大单/中单/小单) 美股+港股 期权层（仅美股） └── Yahoo crumb → 期权链(calls+puts, 所有到期日) 仅美股(港股期权不在Yahoo覆盖范围) SEC Filing层（仅美股） ├── EDGAR submissions → 10-K/10-Q/8-K 完整Filing列表 └── EDGAR XBRL → 结构化财务指标(营收/净利/EPS等) 工具层 ├── 东财 search → 股票搜索(中英文, 含市场代码映射) ├── 东财 push2 → 全市场股票列表(涨跌幅/成交量排名, 美股5925只+港股18000+只) ├── Yahoo search → 新闻资讯(按股票代码) └── SEC CIK mapping → ticker↔CIK 映射 (仅美股) ━━━ 以下为 V2.0 新增（官方源优先）━━━ 期权层·CBOE 官方（仅美股）⭐ └── CBOE cdn → 全链 + IV + delta/gamma/vega/theta/rho + 0DTE + 异动flow [C级·需授权] 做空层（仅美股）⭐ └── FINRA Reg SHO → 全市场每日空头成交量(实测12,112只) + 个股时序 + 排行 [B级] 申报事件流（仅美股）⭐ ├── EDGAR 每日索引 → Form4内部人/8-K/13F机构持仓/144，当日全量 [S级] └── EDGAR 全文检索 → 2001至今所有申报正文，按关键词+表单+日期 [S级] 全市场横截面（仅美股）⭐ └── EDGAR frames → 任意XBRL标签一次拿全市场(实测1,842~5,309家)=免费screener [S级] 宏观 / 日历 ⭐ ├── Treasury → 美债收益率曲线(1M~30Y, 每日) [S级] ├── CFTC → COT 持仓报告 [S级] └── Nasdaq → 财报日历(含盘前盘后+EPS预期) [C级·未核实] ``` --- ## 端点路由速查（按需定位，不必通读全文） | 我想要… | 去哪层 | 主力源 | 合规级 | |---|---|---|---| | 实时/延时报价 | Layer 1 | 新浪 / 腾讯 / 东财 | C | | K 线（日/周/月） | Layer 2 | 新浪 / Yahoo | C | | 技术指标 MA/MACD/RSI/KDJ/布林 | Layer 3 | 本地计算 | — | | 财报三表 / 关键指标 / 分析师 / 机构持仓 | Layer 4 | 东财 / Yahoo / EDGAR | C·S | | 日级资金流 | Layer 5 | 东财 | C | | **期权链 + 希腊字母 + IV + 0DTE + 异动flow** | **Layer 6.1** | **CBOE 官方** ⭐ | C | | 期权链（无希腊字母，后备） | Layer 6.2 | Yahoo | C | | 10-K/10-Q/8-K 列表、XBRL 财务 | Layer 7 | SEC EDGAR | **S** | | 搜索 / 新闻 / CIK 映射 / 全市场列表 | Layer 8 | 东财 / Yahoo / SEC | C·S | | **全市场每日空头成交量、个股空头占比** | **Layer 9** | **FINRA Reg SHO** ⭐ | B | | **当日申报流：Form 4 内部人 / 8-K / 13F** | **Layer 10.1** | **EDGAR 每日索引** ⭐ | **S** | | **申报全文检索（2001 至今正文）** | **Layer 10.2** | **EDGAR FTS** ⭐ | **S** | | **全市场基本面横截面（免费 screener）** | **Layer 11** | **EDGAR frames** ⭐ | **S** | | 美债收益率曲线 / CFTC COT / 财报日历 | Layer 12 | Treasury / CFTC / Nasdaq | S·C | ⭐ = V2.0 新增，且为 yfinance 与多数开源方案不具备的能力。 --- ## 数据源合规分级（取用前必读 — 各级均引条款原文） > 下表结论来自 **2026-07-24 逐家实读各源条款原文**，不是推断。引号内为原文。 > **各源差异极大，"官方"不等于"可自由使用"。** ### S 级 — 可自由使用（含商用与再分发） | 源 | 依据（原文） | |---|---| | **SEC EDGAR** | 官网明示：*"Anyone can access and download this information **for free**"*、*"We **allow scripted access** to sec.gov content"*。**硬性要求**：`Current max request rate: 10 requests/second`，且必须声明 User-Agent（格式 `Company Name AdminContact@domain.com`），否则触发 *"Undeclared Automated Tool"* / Access Denied | | **US Treasury / CFTC** | 美国联邦政府作品不受版权保护（17 U.S.C. §105）。⚠️ 本次**未逐条核验**两站条款正文，按政府数据惯例归此级 | ### B 级 — 数据文件系主动公开，但站点条款含限制 | 源 | 依据（原文） | |---|---| | **FINRA** | Reg SHO 每日文件是 FINRA 主动发布供下载的监管披露文件；但其 Terms of Use 同时禁止 *"use any process to monitor or copy the FINRA Website **in bulk**, or use any **data mining, scraping or harvesting tools (including robots)**"*，且站点声明 *"FINRA Data provides **non-commercial use** of data"*。→ **下载已发布的数据文件属常规用法；批量爬站点页面不属于。商用前请自行向 FINRA 确认。** | ### C 级 — 使用需事先授权，或条款未核实 | 源 | 依据（原文） | |---|---| | **CBOE** | Use of Content 政策：使用任何 Cboe Content 须 *"receive **approval in advance** from Cboe"*，并须 *"**execution of a license agreement**"*；政策**不区分**商用/非商用、不区分实时/延时。→ **本工具的 CBOE 期权层仅供个人研究；商业用途或再分发前，须先向 Cboe 申请授权。** | | **Nasdaq** | 本次抓取条款页超时，**未核实**。按未核实处理 | | Yahoo / 东财 / 新浪 / 腾讯 | Yahoo 官方文档写明 **personal use only**；其余为站点前端接口。仅供个人研究，勿用于商业产品或再分发 | ### ⛔ 已排除的源 | 源 | 原因 | |---|---| | **HKEX（CCASS 港股席位持股）** | 其 Terms of Use 明文禁止 *"any '**robot**', '**bot**', '**spider**', '**scraper**' or other automated device... to access, obtain, copy, monitor or republish any portion of the Website"*，禁止 *"text or data mining or web scraping"*，且适用于 *"**whether or not for gain**"*（不论是否营利）。→ **本工具不提供 CCASS 抓取代码。** 需要港股席位持股/南向资金数据者，请通过 HKEX 授权渠道或其网页人工查询 | ### 给使用者的三条硬规则 1. **商业用途**：只依赖 **S 级**（SEC EDGAR / Treasury / CFTC）。B 级需自行确认，C 级须先取得授权。 2. **再分发**：本工具**只分发代码，不分发任何市场数据**。你也不应把 B/C 级源取得的数据对外分发。 3. **限速**：所有新增层的请求已内置节流（见「统一 HTTP 层」）。**不要绕过它**——SEC 的 10 req/s 是官方硬上限。 --- ## When to Activate - 用户要查**美股/港股**行情（价格/涨跌幅/成交量） - 用户要拉 K 线（日线/周线/月线/分钟线） - 用户要看**财报**（资产负债表/利润表/现金流量表） - 用户要看**关键财务指标**（PE/PB/ROE/利润率/目标价） - 用户要看**分析师预期**（EPS预测/评级/目标价区间） - 用户要看**机构持仓**（前十大机构/持股比例） - 用户要看**资金流向**（主力/大单/中单/小单净流入） - 用户要查**期权链**（calls/puts/到期日/Greeks） - 用户要查 **SEC Filing**（10-K/10-Q/8-K/年报/季报） - 用户要做**美股财报量化分析**（从 XBRL 拉多年营收/净利/EPS 趋势） - 用户要**搜索股票**（中英文均可） - 用户要看**美股/港股新闻** - 用户要看**全市场涨跌幅排名**（当日涨幅/跌幅最大的股票） - 用户要做**全市场筛选**（遍历美股/港股列表做初筛） - 用户要看**关键财务指标概览**（营收/净利/EPS/ROE/ROA/资产负债率 中文版） - 用户要看**技术指标**（MACD/RSI/KDJ/布林带/均线） - 用户要判断**金叉死叉/超买超卖/变盘信号** - 关键词：美股、港股、AAPL、苹果、腾讯、00700、TSLA、特斯拉、BABA、阿里巴巴、行情、K线、财报、PE、PB、ROE、分析师、目标价、期权、call、put、SEC、10-K、年报、季报、资金流、主力、机构持仓、新闻、涨幅排名、全市场、筛选、关键指标、MACD、RSI、KDJ、布林带、均线、金叉、死叉、超买、超卖、技术分析 --- ## Prerequisites ```bash pip install requests ``` | 依赖 | 版本要求 | 用途 | |------|---------|------| | requests | any | 所有 HTTP API 直连 | > **极简依赖：** 仅需 requests，所有数据源均为直连 HTTP API，零第三方数据封装。 --- ## 市场代码规则 ### 东财 secid 前缀（push2/push2his 用） | 前缀 | 市场 | 示例 | |------|------|------| | 105 | 美股 NASDAQ | `105.AAPL`, `105.TSLA` | | 106 | 美股 NYSE | `106.BABA`, `106.JD` | | 107 | 美股 ETF/其他 | `107.CRSH` | | 116 | 港股 | `116.00700`, `116.09988` | > **如何判断 105/106/107？** 调 `stock_search()` 获取 `MktNum` 字段自动映射。 ### Yahoo Finance 代码格式 | 市场 | 格式 | 示例 | |------|------|------| | 美股 | 直接 ticker | `AAPL`, `TSLA`, `BABA` | | 港股 | 四/五位数字 + `.HK` | `0700.HK`, `9988.HK` | ### 东财 datacenter SECUCODE 格式 | 市场 | 格式 | 示例 | |------|------|------| | 美股 NASDAQ | `TICKER.O` | `AAPL.O`, `TSLA.O` | | 美股 NYSE | `TICKER.N` | `BABA.N`, `JD.N` | | 港股 | `CODE.HK` | `00700.HK`, `09988.HK` | --- ## 共用 Helper 函数 ### Yahoo Finance crumb 管理器 Yahoo quoteSummary/options 等 v7/v10 接口需要 cookie+crumb。以下 helper 自动获取并缓存： ```python import requests _yahoo_session = None def get_yahoo_session() -> requests.Session: """获取带 crumb 的 Yahoo Finance session（自动缓存）""" global _yahoo_session if _yahoo_session and hasattr(_yahoo_session, '_crumb'): return _yahoo_session s = requests.Session() s.headers['User-Agent'] = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36' # Step 1: 获取 cookie s.get('https://fc.yahoo.com', timeout=10) # Step 2: 获取 crumb r = s.get('https://query2.finance.yahoo.com/v1/test/getcrumb', timeout=10) r.raise_for_status() s._crumb = r.text _yahoo_session = s return s def yahoo_quote_summary(symbol: str, modules: list[str]) -> dict: """Yahoo quoteSummary 统一查询""" s = get_yahoo_session() r = s.get(f'https://query2.finance.yahoo.com/v10/finance/quoteSummary/{symbol}', params={ 'modules': ','.join(modules), 'crumb': s._crumb, }, timeout=15) r.raise_for_status() results = r.json().get('quoteSummary', {}).get('result', [{}]) return results[0] if results else {} ``` ### 东财数据中心统一查询 ```python UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" DATACENTER_URL = "https://datacenter-web.eastmoney.com/api/data/v1/get" def eastmoney_datacenter(report_name: str, columns: str = "ALL", filter_str: str = "", page_size: int = 50, sort_columns: str = "", sort_types: str = "-1") -> list[dict]: """东财数据中心统一查询""" params = { "reportName": report_name, "columns": columns, "filter": filter_str, "pageNumber": "1", "pageSize": str(page_size), "sortColumns": sort_columns, "sortTypes": sort_types, "source": "WEB", "client": "WEB", } r = requests.get(DATACENTER_URL, params=params, headers={"User-Agent": UA}, timeout=15) d = r.json() if d.get("result") and d["result"].get("data"): return d["result"]["data"] return [] ``` --- ### 官方源统一出口（限流 + UA 声明）— V2.0 新增 V2.0 新增的 Layer 9–12 全部走这个出口。它负责三件事：**按源限速**、**SEC User-Agent 声明**、 **友好错误提示**。 > ⚠️ **使用前必改**：把 `SEC_CONTACT` 换成你自己的真实姓名与邮箱。 > SEC 官方要求声明 User-Agent，未声明会被判定为 *Undeclared Automated Tool* 并拒绝服务。 ```python import requests, time, threading # ⚠️⚠️ 必改：SEC 要求 UA 含真实联系方式，格式 "Company Name AdminContact@domain.com" SEC_CONTACT = "your-name your-email@example.com" class DataNotAvailable(RuntimeError): """该日/该标的确实没有数据（如非交易日、文件尚未发布）——可安全回退到下一个候选日。 与配置错误、网络错误区分开：后者必须立刻抛给调用方， 否则「SEC_CONTACT 没配」会被日期回退循环吞掉，最后伪装成「没找到数据」。 """ class _RateLimiter: """线程安全的最小间隔节流器（用锁，避免并发下被击穿）""" def __init__(self, max_per_sec: float): self._interval = 1.0 / float(max_per_sec) self._last = 0.0 self._lock = threading.Lock() def wait(self) -> None: with self._lock: gap = self._interval - (time.monotonic() - self._last) if gap > 0: time.sleep(gap) self._last = time.monotonic() # 各源限速：SEC 官方硬上限 10/s，此处取 8/s 留余量；其余为自律保护值 _LIMITS = { "sec.gov": _RateLimiter(8), "finra.org": _RateLimiter(4), "cboe.com": _RateLimiter(4),