美股期权 API 文档 · 合约、期权链快照、希腊值与逐笔数据

期权套餐专属。可以单独购买，也可以叠加在入门版或高级版股票套餐上，跟股票共用同一个 API Key，股票和期权各自到期、各自续费。同时开通两者时，每日调用额度和每月流量额度两边相加；QPS 和并发两边分开计算。期权历史数据可回溯 5 年以上。

期权代码格式：O: + 标的代码 + 到期日（YYMMDD）+ C/P（看涨/看跌）+ 行权价×1000（补足 8 位）。例如 O:QQQ261016C00600000 是 QQQ 在 2026-10-16 到期、行权价 600 的看涨期权。代码里的冒号直接写或编码成 %3A 都可以。

GET/v3/reference/options/contracts

合约列表，用来查出你要的合约代码。常用参数：underlying_ticker（标的）、expiration_date（到期日，可用 .gte/.lte 查区间）、contract_type（call/put）、strike_price.gte/strike_price.lte（行权价区间）、limit（最大 1000）。查历史合约必须加 expired=true，否则只返回还没到期的合约；也可以用 as_of=YYYY-MM-DD 查某一天当时挂牌的合约。

curl "https://marilux.dev/v3/reference/options/contracts?underlying_ticker=QQQ&expiration_date=2025-06-20&expired=true&contract_type=call&strike_price.gte=520&strike_price.lte=530&apiKey=mh_live_your_key"

查看 Massive 官方参数文档 →

GET/v3/reference/options/contracts/{期权代码}

单个合约的详情：标的、到期日、行权价、行权方式、合约乘数。

GET/v3/snapshot/options/{标的}

期权链快照：该标的所有合约的最新报价、成交、当日K线、greeks（delta/gamma/theta/vega）、implied_volatility（隐含波动率）、open_interest（未平仓量）。可用 contract_type、expiration_date、strike_price（均支持 .gte/.lte）筛选，limit 最大 250，用 next_url 翻页。单个合约用 /v3/snapshot/options/{标的}/{期权代码}。

curl "https://marilux.dev/v3/snapshot/options/QQQ?contract_type=put&expiration_date.gte=2026-10-20&limit=50&apiKey=mh_live_your_key"

查看 Massive 官方参数文档 →

GET/v2/aggs/ticker/{期权代码}/range/{multiplier}/{timespan}/{from}/{to}

期权K线，用法跟股票K线完全一样；/v2/aggs/ticker/{期权代码}/prev（上一交易日）和 /v1/open-close/{期权代码}/{date}（某日开高低收）也可以用。

GET/v3/trades/{期权代码}

GET/v3/quotes/{期权代码}

逐笔成交 / 逐笔报价（买一卖一）。用 timestamp=YYYY-MM-DD 取某一天，或用 timestamp.gte/timestamp.lt 取一段时间；limit 最大 50000，数据多时用 next_url 翻页直到没有为止。

批量拉取须知：

期权逐笔不经过缓存（X-Cache: BYPASS），每次都实时取数据，按返回的数据量计流量。
一页 5 万条报价约 11MB，需要十几秒；超过 60 秒没返回会得到 504，把 limit 调小（如 10000）重试即可。
并发不要超过套餐上限（5 个），超出的请求会排队。

Python 示例：查出某天到期的一组合约，再逐个合约翻页拉取当天的全部逐笔报价。

import requests

BASE = "https://marilux.dev"
H = {"Authorization": "Bearer mh_live_your_key"}

# 1. 查合约（历史合约要加 expired=true）
r = requests.get(f"{BASE}/v3/reference/options/contracts", headers=H, params={
    "underlying_ticker": "QQQ", "expiration_date": "2025-06-20", "expired": "true",
    "strike_price.gte": 520, "strike_price.lte": 530, "limit": 1000,
})
contracts = [c["ticker"] for c in r.json()["results"]]

# 2. 逐个合约拉当天的逐笔报价，next_url 翻页直到取完
for ticker in contracts:
    url, params = f"{BASE}/v3/quotes/{ticker}", {"timestamp": "2025-06-20", "limit": 50000}
    while url:
        page = requests.get(url, headers=H, params=params, timeout=90).json()
        rows = page.get("results", [])
        print(ticker, len(rows))     # 在这里保存 rows
        url, params = page.get("next_url"), None

查看 Massive 官方参数文档 →

美股期权数据接口