Data Conventions & Symbol SpecificationsMassive(原 Polygon.io)标的前缀、OCC 期权编码、纳秒时间戳与 SIP 条件码速查手册
在使用 Massive(原 Polygon.io)构建跨资产量化回测、实盘行情总线或衍生品定价流水线时,绝大多数「查出空数组」「K 线最高最低价与逐笔极值对不上」「夏令时切日偏移 1 小时」等问题,根源都在于标的代码前缀、OPRA 期权整数编码、纳秒时间戳精度与美股 SIP 成交条件码规则。本手册将散落在 211 篇接口文档中的底层工程规范集中汇编成表,供开发与对账时直接查阅。
1 · 九大资产标的代码前缀与期货月份码规范
Massive 采用统一路径承载多资产查询(例如聚合 K 线均走 /v2/aggs/ticker/{ticker}/range/...),服务端完全依赖 ticker 参数的前缀区分资产账本。漏写前缀(如查询标普 500 漏写 I:、外汇漏写 C:、加密货币漏写 X:)是导致接口返回 HTTP 200 空结果集的第一大原因。
| 资产类别 | 前缀/格式规则 | REST 传参示例 | WebSocket 订阅示例 | 关键细节与关联接口 |
|---|---|---|---|---|
| 美股(Stocks) | 无前缀(大写代码) | AAPL、NVDA、BRK.A、BAC.PRL | T.AAPL、Q.MSFT、AM.NVDA | 多类别普通股统一使用英文点号 . 分隔(如伯克希尔 A 类股写 BRK.A、B 类股写 BRK.B,勿写斜杠 / 或连字符 -)。 详见 All Tickers(全部标的代码)。 |
| 美股期权(Options) | O: 前缀 + 21 位 OCC 码 | O:SPY251219C00600000 | T.O:SPY251219C00600000 | 查询期权链快照按底层正股传 underlyingAsset(如 SPY);查询单张合约 K 线、逐笔或报价必须带完整 O: 前缀。 详见 All Contracts(全部期权合约)。 |
| 期货(Futures) | 品种码 + 月份码 + 年尾数 | 具体合约 ESZ5、CLF6;品种 product_code=ES | T.ESZ5、Q.NQZ5、AM.CLF6 | 覆盖 CME、CBOT、NYMEX、COMEX 四大交易所;具体到期合约用于 K 线与逐笔,品种代码用于合约列表筛选。 详见 Contracts(期货合约列表)。 |
| 指数(Indices) | I: 前缀 | I:SPX、I:NDX、I:DJI、I:VIX | V.I:SPX、AM.I:NDX | 漏写 I: 前缀会被路由当作普通美股代码查询(例如把 I:VIX 误写为 VIX 会导致查无结果或匹配错误标的)。 详见 Indices Snapshot(指数快照)。 |
| 外汇(Currencies) | C: 前缀(6 位 ISO 货币对) | C:EURUSD、C:USDJPY、C:USDCNH | C.EUR/USD、CA.EUR/USD | REST K 线与快照使用无分隔符的 C:EURUSD;WebSocket 报价与聚合频道订阅参数使用带斜杠的 EUR/USD。 详见 Custom Bars(外汇自定义 K 线)。 |
| 加密货币(Crypto) | X: 前缀(基础币+计价币) | X:BTCUSD、X:ETHUSD、X:SOLUSD | XT.BTC-USD、XQ.ETH-USD、XA.BTC-USD | REST K 线与技术指标使用 X:BTCUSD;WebSocket 实时逐笔与盘口订阅参数使用连字符格式 BTC-USD。 详见 Custom Bars(加密自定义 K 线)。 |
| 宏观经济(Economy) | 无标的前缀(按日期过滤) | date.gte=2024-01-01&date.lte=2025-12-31 | —(仅 REST 序列) | 国债收益率曲线、CPI/PCE 通胀及非农就业按发布日期(YYYY-MM-DD)拉取时间序列,无需传 ticker。 详见 Treasury Yields(国债收益率)。 |
| 另类数据 & 合作方 | 正股代码 / 国家码 / 机构 ID | ticker=AAPL、country=DE | —(仅 REST 序列) | Benzinga 评级/财报、ETF Global 成分股及 TMX 公司事件直接传大写美股或 ETF 代码(如 AAPL、SPY)。 详见 Analyst Ratings(分析师评级)。 |
CME 集团期货合约月份字母码对照表(Month Codes)
芝商所(CME / CBOT / NYMEX / COMEX)具体到期合约由「品种根代码 + 1 位月份字母码 + 年份尾数」拼成(例如 ESZ5 表示 E-mini S&P 500 2025 年 12 月到期合约)。在拼接主力连续合约前,建议先调用 Contracts(期货合约列表) 与 Schedules(交易时间表) 核对首末交易日。
| 月份码 | 对应交割月 | 合约代码示例 | 月份码 | 对应交割月 | 合约代码示例 |
|---|---|---|---|---|---|
F | 1 月(Jan) | CLF6(原油 2026年1月) | N | 7 月(Jul) | CLN6(原油 2026年7月) |
G | 2 月(Feb) | GCG6(黄金 2026年2月) | Q | 8 月(Aug) | GCQ6(黄金 2026年8月) |
H | 3 月(Mar) | ESH6(标普 2026年3月季月) | U | 9 月(Sep) | ESU6(标普 2026年9月季月) |
J | 4 月(Apr) | GCJ6(黄金 2026年4月) | V | 10 月(Oct) | CLV6(原油 2026年10月) |
K | 5 月(May) | ZCK6(玉米 2026年5月) | X | 11 月(Nov) | ZSX6(大豆 2026年11月) |
M | 6 月(Jun) | ESM6(标普 2026年6月季月) | Z | 12 月(Dec) | ESZ5(标普 2025年12月季月) |
关联核心接口文档:All Tickers(美股全部标的) ·Custom Bars(指数 K 线) ·Custom Bars(外汇 K 线) ·Custom Bars(加密 K 线) ·Contracts(期货合约列表)
2 · OPRA 21 位期权合约代码(OCC Symbol)结构拆解与换算
美股与指数期权统一遵循美国期权清算公司(OCC)21 位标准编码并在最前方冠以 O: 前缀。以标普 500 ETF 于 2025 年 12 月 19 日到期、行权价 600.00 美元的看涨期权 O:SPY251219C00600000 为例,其五段式结构如下:
| 字段分段 | 示例片段 | 长度/格式 | 编码与精度换算规则 |
|---|---|---|---|
| 资产前缀 | O: | 固定 2 字符 | Massive 期权路由标识符(原生 OCC 字符串在交易所报文中不含 O:,调用 Massive 接口时必须前置 O:)。 |
| 底层标的根代码(Root Symbol) | SPY / AAPL / SPX / SPXW | 1 ~ 6 位大写字母 | 对应正股或指数期权根代码(注意标普周度/末日期权根代码常为 SPXW,月度标准期权为 SPX)。查询时紧贴 O:,不补空格。 |
| 合约到期日(Expiration Date) | 251219 | 固定 6 位数字(YYMMDD) | 2 位年份 + 2 位月份 + 2 位日期,如 251219 表示 2025-12-19 到期。 |
| 期权方向(Call / Put) | C 或 P | 固定 1 位字母 | C 代表认购看涨期权(Call),P 代表认沽看跌期权(Put)。 |
| 行权价整数编码(Strike × 1000) | 00600000 | 固定 8 位数字(左补零) | 前 5 位为行权价整数部分(左补 0),后 3 位为小数部分(精确到 0.001 美元)。例如 $600.00 → 00600000,$12.50 → 00012500。 |
SPY1)或带小数的调整后行权价,生产系统切勿盲目在本地硬拼字符串猜测所有行权价,应先调用 All Contracts(全部期权合约)(回测已到期历史合约时务必传 expired=true)或 Option Chain Snapshot(期权链快照) 获取权威合约列表。Python 期权 OCC 代码双向转换函数
from datetime import date
def build_occ_option_ticker(underlying: str, exp: date, right: str, strike: float) -> str:
"""拼装 Massive 标准期权代码,例如 ('SPY', date(2025,12,19), 'C', 600.0) -> 'O:SPY251219C00600000'"""
root = underlying.strip().upper()
ymd = exp.strftime("%y%m%d")
cp = right.strip().upper()[0] # 'C' 或 'P'
strike_int = round(strike * 1000)
return f"O:{root}{ymd}{cp}{strike_int:08d}"
def parse_occ_option_ticker(occ_ticker: str) -> dict:
"""逆向拆解 O:SPY251219C00600000 为结构化合约字典"""
raw = occ_ticker[2:] if occ_ticker.startswith("O:") else occ_ticker
strike = int(raw[-8:]) / 1000.0
right = "call" if raw[-9] == "C" else "put"
y, m, d = int("20" + raw[-15:-13]), int(raw[-13:-11]), int(raw[-11:-9])
return {"underlying": raw[:-15], "expiration": f"{y:04d}-{m:02d}-{d:02d}", "type": right, "strike": strike}关联核心接口文档:All Contracts(全部期权合约) ·Option Chain Snapshot(期权链快照) ·Custom Bars(期权历史 K 线) ·Trades(期权逐笔成交)
3 · 多级时间戳精度(ms / ns)与美东夏令时(DST)切日规范
Massive 在聚合层与逐笔微观层同时使用毫秒(13 位)与纳秒(19 位)两种 Unix UTC 时间戳。混用时间精度会导致日期被解析到 1970 年或溢出报错;而在切分盘前、正盘、盘后窗口时直接加减固定小时数,则会在每年 3 月第二个周日(进入 EDT UTC-4)与 11 月第一个周日(退回 EST UTC-5)产生整整 1 小时的 K 线错位。
| 字段名称 | 时间单位与位数 | 出现的典型通道与接口 | 业务含义与对账口径 |
|---|---|---|---|
t / s / e | Unix 毫秒(ms,13 位整数) | REST Custom Bars (t)、WebSocket 分钟/秒级聚合 (s 起 / e 止) | 聚合 K 线窗口的起始时刻(UTC)。例如 1743168600000 对应美东正盘开盘 09:30:00.000;分钟线 [09:30:00, 09:31:00) 的标签恒为窗口起点 09:30。 |
participant_timestamp | Unix 纳秒(ns,19 位整数) | REST / Flat Files 逐笔成交(Trades)与报价(Quotes) | 底层撮合交易所(如 Nasdaq、NYSE、Cboe)本地匹配引擎盖下的原始成交/报价纳秒时间戳,最贴近真实市场微观事件发生时点。 |
sip_timestamp | Unix 纳秒(ns,19 位整数) | REST / WebSocket (t) / Flat Files 逐笔成交与 NBBO 报价 | 全美证券信息处理器(CTA/UTP SIP 或 OPRA)汇总各交易所报文并对外广播的纳秒时间戳,通常比 participant_timestamp 晚数十微秒至数毫秒。 |
trf_timestamp | Unix 纳秒(ns,19 位整数) | 美股场外/暗池成交(Trades 含 trf_id 时返回) | FINRA 交易报告设施(TRF,暗池与做市商内部化撮合)接收成交申报的纳秒时间戳。注意法规允许场外大宗延迟回报,需防范乱序打印污染当期极值。 |
window_start | Unix 纳秒(ns,19 位整数) | Flat Files 日线聚合(day-aggregates)与分钟聚合(minute-aggregates)CSV | 与 REST 聚合的毫秒级 t 不同,S3 批量 CSV 文件中的 window_start 统一采用 19 位 UTC 纳秒整数,pandas 解析时须指定 unit="ns"。 |
filing_date / period_of_report_date | ISO 日期(YYYY-MM-DD) | 三大财务报表、10-K/8-K 申报、13-F 持仓与分红拆股接口 | period_of_report_date 为会计报告期末日,filing_date 为向 SEC 实际公开提交日。回测必须按 filing_date 对齐交易日,严禁用期末日以防前视偏差。 |
Python 毫秒/纳秒解析与美东正盘(RTH)切片示例
import pandas as pd
# 1. 解析聚合 K 线毫秒级时间戳 (t) 并转换至美东时区(自动兼容 EST UTC-5 与 EDT UTC-4 夏令时)
df["dt_et"] = pd.to_datetime(df["t"], unit="ms", utc=True).dt.tz_convert("America/New_York")
# 2. 解析逐笔成交/盘口 19 位纳秒级时间戳 (sip_timestamp / participant_timestamp / window_start)
ticks["dt_et"] = pd.to_datetime(ticks["sip_timestamp"], unit="ns", utc=True).dt.tz_convert("America/New_York")
# 3. 严格过滤美股正盘连续竞价时段 [09:30:00, 16:00:00)
rth = df.set_index("dt_et").between_time("09:30", "15:59:59", inclusive="both").reset_index()关联核心接口文档:Custom Bars(美股聚合 K 线) ·Trades(美股逐笔成交) ·Quotes(美股 NBBO 报价) ·Market Holidays(美股休市日历)
4 · 美股 SIP 账带(Tape A/B/C)与成交条件码(Trade Conditions)过滤规则
美股逐笔成交(REST Trades / WS Trades / Flat Files Trades)原样保留了全美证券信息处理器(SIP)下发的 tape(账带)与 conditions(成交条件码整数数组)。直接把全天所有逐笔记录取 max(price) / min(price),算出的最高最低价几乎必然与官方日线/分钟线不一致——因为 SIP 明确规定碎股、衍生定价与盘后交易不更新官方常规 K 线极值。可通过 Condition Codes(成交条件代码) 与 Exchanges(交易所名录) 拉取完整机器可读映射表。
美股三大合并账带(Tape ID)定义
| tape 字段值 | 账带名称 | 监管披露计划 | 覆盖挂牌证券范围与代表标的 |
|---|---|---|---|
1 | Tape A | CTA(Consolidated Tape Association) | 纽约证券交易所(NYSE)主板挂牌证券(如 JPM、KO、BRK.A) |
2 | Tape B | CTA(Consolidated Tape Association) | NYSE Arca、Cboe BZX、NYSE American 等交易所挂牌证券与绝大多数美股 ETF(如 SPY、GLD、IWM) |
3 | Tape C | UTP(Unlisted Trading Privileges) | 纳斯达克(Nasdaq)挂牌证券(如 AAPL、NVDA、MSFT、QQQ) |
核心成交条件码(Trade Conditions)对官方 OHLCV 的影响矩阵
| 成交类型与条件特征 | 更新 Last/Close | 更新 High/Low | 计入 Volume | 量化清洗与聚合建议 |
|---|---|---|---|---|
| Regular Sale(常规集合/连续竞价成交,如空数组或 0 / @) | 更新收盘/最新价(Yes) | 更新最高/最低价(Yes) | 计入总成交量(Yes) | 标准公开市场逐笔成交,同时参与官方 OHLC 四价与 VWAP 计算。 |
| Odd Lot Trade(碎股成交,单笔不足 100 股,条件码常为 37 / I) | 不更新官方最新价(No) | 不更新官方最高/最低价(No) | 计入总成交量与 VWAP(Yes) | 高频散户 1 股~99 股成交最常出现偏离盘口的价格毛刺;SIP 规范不将其纳入 K 线 High/Low/Close,自建 Tick 聚合 Bar 时务必剔除其对四价的影响。 |
| Form T / Extended Hours(盘前盘后延长时段成交,条件码常为 12 / T / U) | 不更新正盘官方收盘价(No) | 计入对应盘前/盘后分钟 Bar,不计入正盘日线四价 | 计入全天累计成交量(Yes) | 切分常规交易时段(09:30–16:00 ET)日线因子时,应按美东时间窗口或过滤 Form T 条件码隔离盘前盘后流动性。 |
| Out of Sequence / Sold Last(延迟乱序回报,条件码常为 Z / L) | 视延迟时长与当时盘口而定(通常 No) | 若早于当前窗口则不更新当期 Bar 极值 | 计入总成交量(Yes) | 常见于暗池(TRF)滞后数秒至数分钟补报的场外大宗成交,实盘信号引擎应同时校验 trf_id 与 participant_timestamp 差值。 |
| Average Price / Contingent / Derivatively Priced(均价/附加条件/衍生定价,如 W / V / 4) | 不更新最新价(No) | 不更新最高/最低价(No) | 计入总成交量(Yes) | 价格由全天 VWAP 或期权行权联动推导,不反映报单时刻二级市场真实买卖盘口,微观结构建模须排除价格列。 |
关联核心接口文档:Condition Codes(成交条件代码) ·Exchanges(交易所名录) ·Trades(美股逐笔成交) ·Trades(WS 实时逐笔成交)
5 · REST 范围过滤算子、13 个 /vX/ 固定路径与复权/分页规范
- 范围比较算子(Query Operators):支持按字段做区间过滤的 REST 接口统一采用点号后缀语法:
field.gt(严格大于)、field.gte(大于等于)、field.lt(严格小于)、field.lte(小于等于)以及field.any_of(逗号分隔多值枚举,如ticker.any_of=AAPL,MSFT,NVDA)。 next_url游标分页续拉:当单次查询命中limit条数上限且仍有后续记录时,JSON 顶层会返回完整的next_url字符串。客户端无需也不应手工计算offset,直接携带原有Authorization: Bearer <API_KEY>请求头访问next_url即可拉取下一页,直至响应不再包含next_url。- 拆股复权与现金股息全收益(Total Return):聚合 K 线(Custom Bars)与四大技术指标中的
adjusted=true(默认值)仅按历史拆并股(Splits)调整价格与成交量,默认不扣除现金分红。若构建中长线高股息策略回测,请拉取 Dividends(现金分红) 的ex_dividend_date与cash_amount在除息日做前复权连乘修正。
全站 13 个含 /vX/ 字面量的真实接口清单(切勿替换为 /v1/ 或 /v3/)
以下 13 个美股参考资料、流通股本与 SEC 申报接口路径中的 /vX/ 属于上游生产路由的固定字面量(Literal Path Segment),并非代表版本号变量的占位符;发起请求时必须原样保留 /vX/,改写为 /v1/ 或 /v3/ 会直接触发 HTTP 404:
| 真实请求方法与路径 | 接口中文名称 | 对应中文文档页 |
|---|---|---|
GET /vX/reference/ipos | 首次公开募股(IPOs) | 查看参数与返回字段 → |
GET /vX/reference/tickers/{id}/events | 标的代码变更事件(Ticker Events) | 查看参数与返回字段 → |
GET /stocks/vX/float | 自由流通股本(Share Float) | 查看参数与返回字段 → |
GET /stocks/filings/vX/index | SEC EDGAR 申报主索引 | 查看参数与返回字段 → |
GET /stocks/filings/10-K/vX/sections | 10-K 年报核心章节文本 | 查看参数与返回字段 → |
GET /stocks/filings/8-K/vX/disclosures | 8-K 重大事项结构化披露 | 查看参数与返回字段 → |
GET /stocks/filings/8-K/vX/text | 8-K 重大事项正文全文 | 查看参数与返回字段 → |
GET /stocks/filings/vX/13-F | 机构 13-F 季度持仓披露 | 查看参数与返回字段 → |
GET /stocks/filings/vX/form-3 | Form 3 内部人初始持股申报 | 查看参数与返回字段 → |
GET /stocks/filings/vX/form-4 | Form 4 内部人持股变动申报 | 查看参数与返回字段 → |
GET /stocks/filings/vX/risk-factors | 财报风险因素(Risk Factors)明细 | 查看参数与返回字段 → |
GET /stocks/taxonomies/vX/disclosures | SEC 披露事项分类标准词表 | 查看参数与返回字段 → |
GET /stocks/taxonomies/vX/risk-factors | 风险因素分类标准词表 | 查看参数与返回字段 → |
关联核心接口文档:Splits(拆并股记录) ·Dividends(现金分红) ·Float(自由流通股本) ·Balance Sheets(资产负债表)
6 · WebSocket 实时频道前缀矩阵与 Flat Files(S3)目录结构
六大资产 WebSocket 连接端点与订阅频道前缀一览
| 资产类别 | WSS 连接端点 | 可用订阅频道前缀(params 格式) | 通道概览 |
|---|---|---|---|
| 美股(Stocks) | wss://socket.massive.com/stocks | T.<ticker>(逐笔)、Q.<ticker>(NBBO报价)、AM.<ticker>(分钟Bar)、A.<ticker>(秒Bar)、LULD.<ticker>(涨跌停带)、NOI.<ticker>(开收盘不平衡)、FMV.<ticker>(公允价) | 进入概览 → |
| 美股期权(Options) | wss://socket.massive.com/options | T.O:<occ>(逐笔)、Q.O:<occ>(OPRA报价)、AM.O:<occ>(分钟Bar)、A.O:<occ>(秒Bar)、FMV.O:<occ>(公允价) | 进入概览 → |
| 期货(Futures) | wss://socket.massive.com/futures | T.<contract>(逐笔)、Q.<contract>(最优报价)、AM.<contract>(分钟Bar)、A.<contract>(秒Bar) | 进入概览 → |
| 指数(Indices) | wss://socket.massive.com/indices | V.I:<index>(实时指数点位)、AM.I:<index>(分钟Bar)、A.I:<index>(秒Bar) | 进入概览 → |
| 外汇(Currencies) | wss://socket.massive.com/forex | C.<FROM>/<TO>(实时报价,如 C.EUR/USD)、CA.<FROM>/<TO>(分钟Bar)、CAS.<FROM>/<TO>(秒Bar)、FMV.<FROM>/<TO>(公允价) | 进入概览 → |
| 加密货币(Crypto) | wss://socket.massive.com/crypto | XT.<BASE>-<QUOTE>(逐笔,如 XT.BTC-USD)、XQ.<BASE>-<QUOTE>(报价)、XA.<BASE>-<QUOTE>(分钟Bar)、XAS.<BASE>-<QUOTE>(秒Bar)、FMV.<BASE>-<QUOTE>(公允价) | 进入概览 → |
Flat Files(S3 兼容对象存储 s3://flatfiles/)顶层目录规范
Flat Files 通过 S3 兼容协议(官方 Endpoint https://files.massive.com,Bucket 名称固定为 flatfiles)提供按交易日切分的 .csv.gz 压缩文件,需使用独立的 S3 Access Key 与 Secret Key(不可使用 REST API Key):
| 资产数据集 | Bucket 顶层前缀 | 包含的数据子目录类型 | 通道概览 |
|---|---|---|---|
| 美股(SIP 全市场) | us_stocks_sip/ | day_aggs_v1 / minute_aggs_v1 / trades_v1 / quotes_v1 | 进入概览 → |
| 美股期权(OPRA 全市场) | us_options_opra/ | day_aggs_v1 / minute_aggs_v1 / trades_v1 / quotes_v1 | 进入概览 → |
| 期货(CME / CBOT / NYMEX / COMEX) | us_futures_cme/ | minute-aggregates / session-aggregates / trades / quotes(按四所子目录切分) | 进入概览 → |
| 指数(Indices) | us_indices/ | day-aggregates / minute-aggregates / values | 进入概览 → |
| 外汇(Global Forex) | global_forex/ | day-aggregates / minute-aggregates / quotes | 进入概览 → |
| 加密货币(Global Crypto) | global_crypto/ | day-aggregates / minute-aggregates / trades | 进入概览 → |
关联核心通道概览:Stocks WebSocket(美股实时推送) ·Options WebSocket(期权实时推送) ·Stocks Flat Files(美股 S3 数据包) ·Futures Flat Files(期货 S3 数据包)
7 · 三大通道生产级 Python 工程模板与 HTTP 状态码排障表
模板一:REST API 自动跟随 next_url 游标翻页 + 指数退避重试
import os, time, requests
import pandas as pd
BASE_URL = os.environ.get("MASSIVE_BASE_URL", "https://api.massive.com")
API_KEY = os.environ["MASSIVE_API_KEY"]
def fetch_all_pages(path: str, params: dict | None = None, max_pages: int = 100) -> pd.DataFrame:
"""自动跟随 next_url 游标拉取完整区间数据,内置 429/5xx 指数退避重试"""
session = requests.Session()
session.headers.update({"Authorization": f"Bearer {API_KEY}"})
url, query, rows = f"{BASE_URL}{path}", dict(params or {}), []
for _ in range(max_pages):
for attempt in range(4):
resp = session.get(url, params=query, timeout=20)
if resp.status_code in (429, 502, 503, 504) and attempt < 3:
time.sleep(2 ** attempt)
continue
resp.raise_for_status()
break
payload = resp.json()
batch = payload.get("results") or []
rows.extend(batch if isinstance(batch, list) else [batch])
next_url = payload.get("next_url")
if not next_url:
break
# next_url 已内含完整游标查询串,后续请求清空 params 字典并保留 Authorization 请求头
url, query = next_url, {}
return pd.DataFrame(rows)
# 示例:拉取 AAPL 2025Q1 全量 1 分钟复权 K 线
df_bars = fetch_all_pages("/v2/aggs/ticker/AAPL/range/1/minute/2025-01-02/2025-03-31", {"adjusted": "true", "limit": 50000})模板二:WebSocket 异步状态机(先鉴权后订阅 + 断线指数退避重连)
import os, json, asyncio
import websockets
WS_URL = os.environ.get("MASSIVE_WS_URL", "wss://socket.massive.com/stocks")
API_KEY = os.environ["MASSIVE_API_KEY"]
async def stream_with_reconnect(channels: str = "T.AAPL,Q.AAPL,AM.NVDA"):
"""生产级 WebSocket 订阅循环:断线指数退避重连 + 先鉴权后订阅状态机"""
backoff = 1
while True:
try:
async with websockets.connect(WS_URL, ping_interval=20, ping_timeout=20, max_queue=4096) as ws:
backoff = 1
async for raw in ws:
for ev in json.loads(raw):
ev_type, status = ev.get("ev"), ev.get("status")
if ev_type == "status" and status == "connected":
await ws.send(json.dumps({"action": "auth", "params": API_KEY}))
elif ev_type == "status" and status == "auth_success":
await ws.send(json.dumps({"action": "subscribe", "params": channels}))
elif ev_type in ("T", "Q", "AM", "A"):
# 业务消费最好异步入队,避免阻塞协程导致服务端慢消费断开
print(ev_type, ev.get("sym"), ev.get("p") or ev.get("c"), ev.get("t") or ev.get("s"))
except Exception as exc:
print(f"[WS] 连接中断 ({exc}),{backoff}s 后重连;重连后请用 REST 补齐断流窗口")
await asyncio.sleep(backoff)
backoff = min(backoff * 2, 30)
asyncio.run(stream_with_reconnect())模板三:Flat Files(S3)boto3 流式分块读取大体积 .csv.gz 转 Parquet
import os, boto3
import pandas as pd
s3 = boto3.client(
"s3",
endpoint_url=os.environ.get("MASSIVE_S3_ENDPOINT", "https://files.massive.com"),
aws_access_key_id=os.environ["MASSIVE_S3_ACCESS_KEY"],
aws_secret_access_key=os.environ["MASSIVE_S3_SECRET_KEY"],
)
# 流式分块读取单日全市场逐笔或分钟压缩包,仅提取目标股票池并落盘 Parquet
resp = s3.get_object(Bucket="flatfiles", Key="us_stocks_sip/minute_aggs_v1/2025/03/2025-03-28.csv.gz")
universe = {"AAPL", "MSFT", "NVDA", "SPY", "QQQ"}
chunks = [
chunk[chunk["ticker"].isin(universe)]
for chunk in pd.read_csv(resp["Body"], compression="gzip", chunksize=500_000)
]
df_day = pd.concat(chunks, ignore_index=True)
df_day.to_parquet("us_stocks_minute_20250328.parquet", index=False)常见 HTTP 状态码与空结果集快速排障表
| 状态码/现象 | 触发含义 | 工程排查与修复动作 |
|---|---|---|
200 OK(results 为空) | 请求语法合法,但过滤条件下无记录 | ① 核对指数 I: / 外汇 C: / 加密 X: / 期权 O: 前缀是否漏写;② 检查查询日是否逢美股法定休市日;③ 查询历史已到期期权时须显式传 expired=true。 |
400 Bad Request | 查询参数类型错误、日期格式非法或必填项缺失 | 检查时间戳是否混用了浮点秒数(应传 YYYY-MM-DD 或整数毫秒/纳秒),以及范围算子是否写成合法的 field.gte=... 形式。 |
401 Unauthorized | API Key 未传入或凭据字符串无效 | 确认请求头 Authorization: Bearer <API_KEY> 拼写无误;注意跟随返回体 next_url 翻页时必须继续携带同一 Authorization 请求头。 |
403 Forbidden | 当前凭据无目标资产或实时等级访问权限,或混用 S3 凭据 | 确认当前账号权限范围;下载 Flat Files(files.massive.com)必须使用独立的 S3 Access Key / Secret Key,不可传 REST API Key。 |
404 Not Found | 接口路径拼写错误,或误改了 /vX/ 固定字面量 | 切勿给路径强行前置 /v1,也不要把 GET /vX/reference/ipos 等 13 个端点中的 /vX/ 替换成 /v2/ 或 /v3/。 |
429 Too Many Requests | 超出每分钟请求速率上限(RPM) | 在客户端实现指数退避重试(Exponential Backoff + Jitter,如 1s → 2s → 4s);大跨度历史回测优先改用 Flat Files 按日整包拉取。 |
关联通道协议指南:REST API 协议与调用指南 ·WebSocket 实时订阅指南 ·Flat Files S3 批量下载指南 ·AI 工具与 llms.txt 指南