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.PRLT.AAPL、Q.MSFT、AM.NVDA多类别普通股统一使用英文点号 . 分隔(如伯克希尔 A 类股写 BRK.A、B 类股写 BRK.B,勿写斜杠 / 或连字符 -)。 详见 All Tickers(全部标的代码)。
美股期权(Options)O: 前缀 + 21 位 OCC 码O:SPY251219C00600000T.O:SPY251219C00600000查询期权链快照按底层正股传 underlyingAsset(如 SPY);查询单张合约 K 线、逐笔或报价必须带完整 O: 前缀。 详见 All Contracts(全部期权合约)。
期货(Futures)品种码 + 月份码 + 年尾数具体合约 ESZ5、CLF6;品种 product_code=EST.ESZ5、Q.NQZ5、AM.CLF6覆盖 CME、CBOT、NYMEX、COMEX 四大交易所;具体到期合约用于 K 线与逐笔,品种代码用于合约列表筛选。 详见 Contracts(期货合约列表)。
指数(Indices)I: 前缀I:SPX、I:NDX、I:DJI、I:VIXV.I:SPX、AM.I:NDX漏写 I: 前缀会被路由当作普通美股代码查询(例如把 I:VIX 误写为 VIX 会导致查无结果或匹配错误标的)。 详见 Indices Snapshot(指数快照)。
外汇(Currencies)C: 前缀(6 位 ISO 货币对)C:EURUSD、C:USDJPY、C:USDCNHC.EUR/USD、CA.EUR/USDREST K 线与快照使用无分隔符的 C:EURUSD;WebSocket 报价与聚合频道订阅参数使用带斜杠的 EUR/USD。 详见 Custom Bars(外汇自定义 K 线)。
加密货币(Crypto)X: 前缀(基础币+计价币)X:BTCUSD、X:ETHUSD、X:SOLUSDXT.BTC-USD、XQ.ETH-USD、XA.BTC-USDREST 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(国债收益率)。
另类数据 & 合作方正股代码 / 国家码 / 机构 IDticker=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(交易时间表) 核对首末交易日。

月份码对应交割月合约代码示例月份码对应交割月合约代码示例
F1 月(Jan)CLF6(原油 2026年1月)N7 月(Jul)CLN6(原油 2026年7月)
G2 月(Feb)GCG6(黄金 2026年2月)Q8 月(Aug)GCQ6(黄金 2026年8月)
H3 月(Mar)ESH6(标普 2026年3月季月)U9 月(Sep)ESU6(标普 2026年9月季月)
J4 月(Apr)GCJ6(黄金 2026年4月)V10 月(Oct)CLV6(原油 2026年10月)
K5 月(May)ZCK6(玉米 2026年5月)X11 月(Nov)ZSX6(大豆 2026年11月)
M6 月(Jun)ESM6(标普 2026年6月季月)Z12 月(Dec)ESZ5(标普 2025年12月季月)

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 / SPXW1 ~ 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}

3 · 多级时间戳精度(ms / ns)与美东夏令时(DST)切日规范

Massive 在聚合层与逐笔微观层同时使用毫秒(13 位)与纳秒(19 位)两种 Unix UTC 时间戳。混用时间精度会导致日期被解析到 1970 年或溢出报错;而在切分盘前、正盘、盘后窗口时直接加减固定小时数,则会在每年 3 月第二个周日(进入 EDT UTC-4)与 11 月第一个周日(退回 EST UTC-5)产生整整 1 小时的 K 线错位。

字段名称时间单位与位数出现的典型通道与接口业务含义与对账口径
t / s / eUnix 毫秒(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_timestampUnix 纳秒(ns,19 位整数)REST / Flat Files 逐笔成交(Trades)与报价(Quotes)底层撮合交易所(如 Nasdaq、NYSE、Cboe)本地匹配引擎盖下的原始成交/报价纳秒时间戳,最贴近真实市场微观事件发生时点。
sip_timestampUnix 纳秒(ns,19 位整数)REST / WebSocket (t) / Flat Files 逐笔成交与 NBBO 报价全美证券信息处理器(CTA/UTP SIP 或 OPRA)汇总各交易所报文并对外广播的纳秒时间戳,通常比 participant_timestamp 晚数十微秒至数毫秒。
trf_timestampUnix 纳秒(ns,19 位整数)美股场外/暗池成交(Trades 含 trf_id 时返回)FINRA 交易报告设施(TRF,暗池与做市商内部化撮合)接收成交申报的纳秒时间戳。注意法规允许场外大宗延迟回报,需防范乱序打印污染当期极值。
window_startUnix 纳秒(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_dateISO 日期(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()

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 字段值账带名称监管披露计划覆盖挂牌证券范围与代表标的
1Tape ACTA(Consolidated Tape Association)纽约证券交易所(NYSE)主板挂牌证券(如 JPM、KO、BRK.A)
2Tape BCTA(Consolidated Tape Association)NYSE Arca、Cboe BZX、NYSE American 等交易所挂牌证券与绝大多数美股 ETF(如 SPY、GLD、IWM)
3Tape CUTP(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 或期权行权联动推导,不反映报单时刻二级市场真实买卖盘口,微观结构建模须排除价格列。

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/indexSEC EDGAR 申报主索引查看参数与返回字段 →
GET /stocks/filings/10-K/vX/sections10-K 年报核心章节文本查看参数与返回字段 →
GET /stocks/filings/8-K/vX/disclosures8-K 重大事项结构化披露查看参数与返回字段 →
GET /stocks/filings/8-K/vX/text8-K 重大事项正文全文查看参数与返回字段 →
GET /stocks/filings/vX/13-F机构 13-F 季度持仓披露查看参数与返回字段 →
GET /stocks/filings/vX/form-3Form 3 内部人初始持股申报查看参数与返回字段 →
GET /stocks/filings/vX/form-4Form 4 内部人持股变动申报查看参数与返回字段 →
GET /stocks/filings/vX/risk-factors财报风险因素(Risk Factors)明细查看参数与返回字段 →
GET /stocks/taxonomies/vX/disclosuresSEC 披露事项分类标准词表查看参数与返回字段 →
GET /stocks/taxonomies/vX/risk-factors风险因素分类标准词表查看参数与返回字段 →

6 · WebSocket 实时频道前缀矩阵与 Flat Files(S3)目录结构

六大资产 WebSocket 连接端点与订阅频道前缀一览

资产类别WSS 连接端点可用订阅频道前缀(params 格式)通道概览
美股(Stocks)wss://socket.massive.com/stocksT.<ticker>(逐笔)、Q.<ticker>(NBBO报价)、AM.<ticker>(分钟Bar)、A.<ticker>(秒Bar)、LULD.<ticker>(涨跌停带)、NOI.<ticker>(开收盘不平衡)、FMV.<ticker>(公允价)进入概览 →
美股期权(Options)wss://socket.massive.com/optionsT.O:<occ>(逐笔)、Q.O:<occ>(OPRA报价)、AM.O:<occ>(分钟Bar)、A.O:<occ>(秒Bar)、FMV.O:<occ>(公允价)进入概览 →
期货(Futures)wss://socket.massive.com/futuresT.<contract>(逐笔)、Q.<contract>(最优报价)、AM.<contract>(分钟Bar)、A.<contract>(秒Bar)进入概览 →
指数(Indices)wss://socket.massive.com/indicesV.I:<index>(实时指数点位)、AM.I:<index>(分钟Bar)、A.I:<index>(秒Bar)进入概览 →
外汇(Currencies)wss://socket.massive.com/forexC.<FROM>/<TO>(实时报价,如 C.EUR/USD)、CA.<FROM>/<TO>(分钟Bar)、CAS.<FROM>/<TO>(秒Bar)、FMV.<FROM>/<TO>(公允价)进入概览 →
加密货币(Crypto)wss://socket.massive.com/cryptoXT.<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进入概览 →

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 UnauthorizedAPI 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 按日整包拉取。