几分钟完成第一次调用

快速开始

安装 Python SDK，然后创建客户端：

pip install polygon-api-client

from polygon import RESTClient

client = RESTClient(
    api_key="mh_live_your_key",
    base="https://marilux.dev"
)

身份认证

推荐使用 Bearer 请求头。也可以使用兼容参数 apiKey。

curl "https://marilux.dev/v2/aggs/ticker/AAPL/prev" \
  -H "Authorization: Bearer mh_live_your_key"

接口范围

下面这些接口 Starter 和 Advanced 套餐都能用，覆盖美股股票与 ETF 的聚合行情、历史K线与参考数据。逐笔成交/报价、财务数据、WebSocket 实时推送是 Advanced 专属，见下面单独两节；期权数据需要单独开通期权套餐，见期权数据一节；指数、外汇与期货暂不提供。

指定时间粒度和区间的历史K线（聚合行情）。

curl "https://marilux.dev/v2/aggs/ticker/AAPL/range/1/day/2024-01-01/2024-01-05?adjusted=true" \
  -H "Authorization: Bearer mh_live_your_key"

{
  "ticker": "AAPL",
  "adjusted": true,
  "queryCount": 4,
  "resultsCount": 4,
  "results": [
    { "t": 1704171600000, "o": 187.15, "h": 188.44, "l": 183.885, "c": 185.64, "v": 82488674, "vw": 185.9374, "n": 1008875 },
    ...
  ],
  "status": "OK",
  "count": 4
}

日K的 t 是该交易日美东时间 0 点的毫秒时间戳。

查看 Massive 官方参数文档 →

上一交易日的收盘K线。

{
  "ticker": "AAPL",
  "adjusted": true,
  "queryCount": 1,
  "resultsCount": 1,
  "results": [
    { "T": "AAPL", "t": 1704171600000, "o": 187.15, "h": 188.44, "l": 183.885, "c": 185.64, "v": 82488674, "vw": 185.9374, "n": 1008875 }
  ],
  "status": "OK",
  "count": 1
}

查看 Massive 官方参数文档 →

某个交易日全市场股票的日线，量化回测/复盘常用。

查看 Massive 官方参数文档 →

指定股票在某个交易日的开高低收。

查看 Massive 官方参数文档 →

股票/ETF 基础信息检索，支持按代码、交易所、状态过滤。

{
  "results": [
    { "ticker": "AAPL", "name": "Apple Inc.", "market": "stocks", "locale": "us", "primary_exchange": "XNAS", "type": "CS", "active": true, "currency_name": "usd" }
  ],
  "status": "OK",
  "count": 1,
  "next_url": "https://marilux.dev/v3/reference/tickers?cursor=..."
}

next_url 已经改写成你自己的域名，直接翻页请求即可，不会带出上游地址或凭证。

查看 Massive 官方参数文档 →

单只股票/ETF 的详细资料：CIK、composite/share class FIGI、市值、行业分类（SIC）、上市日期等。

{
  "results": {
    "ticker": "AAPL", "name": "Apple Inc.", "cik": "0000320193",
    "composite_figi": "BBG000B9XRY4", "share_class_figi": "BBG001S5N8V8",
    "market_cap": 4669699774600, "sic_code": "3571", "sic_description": "ELECTRONIC COMPUTERS",
    "list_date": "1980-12-12", "total_employees": 166000, "homepage_url": "https://www.apple.com",
    "branding": {
      "logo_url": "https://marilux.dev/v1/reference/company-branding/.../logo.svg",
      "icon_url": "https://marilux.dev/v1/reference/company-branding/.../icon.png"
    }
  },
  "status": "OK"
}

注意：品牌图片（branding 里的 logo_url / icon_url）目前暂不提供下载，链接仅供参考，请求会失败；其余字段均可正常使用。

查看 Massive 官方参数文档 →

拆股/合股历史，做复权价计算时和 dividends 是一对，缺一个都会算错。

查看 Massive 官方参数文档 →

分红历史。

查看 Massive 官方参数文档 →

新版拆股/合股接口，比 /v3/reference/splits 多了 adjustment_type（正拆/反拆等）和 historical_adjustment_factor（历史复权因子，可直接乘到历史价格上）。参数 ticker、execution_date（支持 .gte/.lte），按日期倒序加 sort=execution_date.desc。

curl "https://marilux.dev/stocks/v1/splits?ticker=AAPL&sort=execution_date.desc&apiKey=mh_live_your_key"

{
  "status": "OK",
  "results": [
    { "ticker": "AAPL", "execution_date": "2020-08-31", "split_from": 1, "split_to": 4,
      "adjustment_type": "forward_split", "historical_adjustment_factor": 0.25 }
  ]
}

新版分红接口，比 /v3/reference/dividends 多了 historical_adjustment_factor（分红复权因子）和 split_adjusted_cash_amount（按拆股调整后的每股分红）。参数 ticker、ex_dividend_date（支持 .gte/.lte），按除息日倒序加 sort=ex_dividend_date.desc。

curl "https://marilux.dev/stocks/v1/dividends?ticker=AAPL&sort=ex_dividend_date.desc&limit=4&apiKey=mh_live_your_key"

{
  "status": "OK",
  "results": [
    { "ticker": "AAPL", "ex_dividend_date": "2026-08-10", "record_date": "2026-08-10", "pay_date": "2026-08-13",
      "declaration_date": "2026-07-30", "cash_amount": 0.27, "currency": "USD", "frequency": 4,
      "distribution_type": "recurring", "historical_adjustment_factor": 0.999138, "split_adjusted_cash_amount": 0.27 }
  ]
}

代码变更历史（改名、换代码），{id} 可以是股票代码、CUSIP 或 composite FIGI。做历史回测时用它把旧代码对应到现在的公司，比如 FB → META。

curl "https://marilux.dev/vX/reference/tickers/META/events?apiKey=mh_live_your_key"

{
  "results": {
    "name": "Meta Platforms, Inc. Class A Common Stock", "composite_figi": "BBG000MM2P62", "cik": "0001326801",
    "events": [
      { "type": "ticker_change", "date": "2022-06-09", "ticker_change": { "ticker": "META" } },
      { "type": "ticker_change", "date": "2012-05-18", "ticker_change": { "ticker": "FB" } }
    ]
  },
  "status": "OK"
}

IPO 日历：即将上市、正在发行和已上市的新股，含发行价区间、最终发行价、发行股数、上市日期和状态。可按 ticker、ipo_status（如 pending、new、history、rumor、withdrawn）、listing_date.gte / listing_date.lte 筛选，sort=listing_date&order=desc 按上市日期倒序。数据每天更新。

curl "https://marilux.dev/vX/reference/ipos?ipo_status=pending&limit=10&apiKey=mh_live_your_key"

{
  "results": [
    { "ticker": "GBC", "issuer_name": "Georgia Banking Co. Inc", "ipo_status": "direct_listing_process",
      "announced_date": "2026-10-02", "primary_exchange": "XNAS", "security_type": "CS",
      "max_shares_offered": 7040514, "lot_size": 100, "currency_code": "USD", "last_updated": "2026-10-15" }
  ],
  "status": "OK",
  "next_url": "https://marilux.dev/vX/reference/ipos?cursor=..."
}

查看 Massive 官方参数文档 →

交易所列表及基础信息。

查看 Massive 官方参数文档 →

当前市场开/收盘状态。

查看 Massive 官方参数文档 →

即将到来的休市安排。

查看 Massive 官方参数文档 →

全市场（或用 tickers= 指定的多只）股票快照，价格仍按上述延迟规则提供。

查看 Massive 官方参数文档 →

单只股票的快照。

查看 Massive 官方参数文档 →

当日涨幅榜。

查看 Massive 官方参数文档 →

当日跌幅榜。

查看 Massive 官方参数文档 →

Advanced 专属接口

下面这些接口只有 Advanced 套餐的 Key 能用，Starter 套餐调用会收到 404。

指定股票在时间范围内的逐笔成交数据（tick-level）。

curl "https://marilux.dev/v3/trades/AAPL?limit=1&apiKey=mh_live_your_key"

{
  "results": [
    { "exchange": 12, "id": "133121", "price": 334.8, "size": 5, "conditions": [12,14,37,41],
      "sip_timestamp": 1789775989256756500, "participant_timestamp": 1789775989256742000,
      "sequence_number": 10448785, "tape": 3 }
  ],
  "status": "OK"
}

查看 Massive 官方参数文档 →

指定股票在时间范围内的逐笔报价（NBBO 最优买卖价）。

curl "https://marilux.dev/v3/quotes/AAPL?limit=1&apiKey=mh_live_your_key"

查看 Massive 官方参数文档 →

财务比率（估值、盈利能力、偿债能力等）。同一个 /stocks/financials/v1/ 前缀下还有 income-statements（利润表）、balance-sheets（资产负债表）、cash-flow-statements（现金流量表），按需替换路径最后一段。注意参数名不同：ratios 用 ticker，三张报表用 tickers（多一个 s），可再加 fiscal_year、fiscal_quarter、timeframe 筛选。参数名写错不会报错，而是返回未筛选的全市场数据。

curl "https://marilux.dev/stocks/financials/v1/ratios?ticker=AAPL&apiKey=mh_live_your_key"
curl "https://marilux.dev/stocks/financials/v1/income-statements?tickers=AAPL&fiscal_year=2024&apiKey=mh_live_your_key"

{
  "status": "OK",
  "results": [
    { "ticker": "AAPL", "price": 336.13, "market_cap": 4905541723400,
      "earnings_per_share": 8.83, "price_to_earnings": 38.05, "price_to_book": 45.62,
      "dividend_yield": 0.0032, "return_on_equity": 1.1991, "debt_to_equity": 0.78 }
  ]
}

查看 Massive 官方参数文档 →

卖空持仓（每半月结算一次）：卖空股数、日均成交量、回补天数。参数 ticker，按日期倒序可加 sort=settlement_date.desc。

curl "https://marilux.dev/stocks/v1/short-interest?ticker=AAPL&sort=settlement_date.desc&limit=1&apiKey=mh_live_your_key"

{
  "status": "OK",
  "results": [
    { "settlement_date": "2026-09-15", "ticker": "AAPL", "short_interest": 128753092,
      "avg_daily_volume": 45135477, "days_to_cover": 2.85 }
  ]
}

每日卖空成交量，含卖空占比 short_volume_ratio 以及各交易所明细。参数 ticker，按日期倒序可加 sort=date.desc。

curl "https://marilux.dev/stocks/v1/short-volume?ticker=AAPL&sort=date.desc&limit=1&apiKey=mh_live_your_key"

{
  "status": "OK",
  "results": [
    { "ticker": "AAPL", "date": "2026-09-25", "total_volume": 11119362.83,
      "short_volume": 6485654.25, "short_volume_ratio": 58.33, "exempt_volume": 66813 }
  ]
}

流通股数量及流通比例。参数 ticker。

curl "https://marilux.dev/stocks/vX/float?ticker=AAPL&apiKey=mh_live_your_key"

{
  "status": "OK",
  "results": [
    { "ticker": "AAPL", "free_float": 13521179933, "free_float_percent": 92.1,
      "effective_date": "2026-05-14" }
  ]
}

WebSocket 实时推送

Advanced 套餐专属。连接地址 wss://marilux.dev/stocks，协议和 Polygon 官方 WebSocket 完全一致：连上先鉴权，鉴权成功后按需订阅，之后行情会持续推过来，直到你退订或断开。

1. 连接后会先收到：

[{"ev":"status","status":"connected","message":"Connected Successfully"}]

2. 发送鉴权消息：

{"action":"auth","params":"mh_live_your_key"}

成功返回 auth_success；套餐不是 Advanced、Key 已停用/过期、或超出套餐的并发连接数上限都会返回 auth_failed，原因见 message（连接数超限时会带上你的上限）。连接建立后须在 10 秒内鉴权成功，否则服务端会以关闭码 1008 断开连接，鉴权失败的连接同样会被断开，请修正原因后重新连接。

[{"ev":"status","status":"auth_success","message":"authenticated"}]

3. 订阅标的：params 是"事件类型.股票代码"，逗号分隔可以一次订阅多个，事件类型 T=逐笔成交、Q=逐笔报价。

{"action":"subscribe","params":"T.AAPL,Q.AAPL,T.MSFT"}

订阅成功返回：

[{"ev":"status","status":"success","message":"subscribed to: T.AAPL,Q.AAPL"}]

订阅数超出套餐上限时，超出的部分会被拒绝，已订阅的部分不受影响，并额外收到一条错误消息列出未订阅的标的：

[{"ev":"status","status":"error","message":"已达到套餐订阅股票数上限（200 只），未订阅: T.MSFT"}]

4. 行情推送——数组形式，可能一次包含多条：

[{"ev":"T","sym":"AAPL","x":12,"i":"133121","p":334.8,"s":5,"c":[12,14,37,41],"t":1789775989256756500}]

订阅上限按股票数计算：同一只股票同时订阅成交（T.AAPL）和报价（Q.AAPL）只算 1 只。暂不支持通配符（*）订阅全市场。各档位上限：

• 高级版体验：1 个连接，10 只股票
• 高级版月付/季付：2 个连接，200 只股票
• 高级版半年付：3 个连接，500 只股票
• 高级版年付：5 个连接，500 只股票

断线重连：如果你的程序处理消息太慢、服务端待发送的数据积压超过 2MB，连接会以关闭码 1013 断开，以免拖累其他客户；服务器维护重启时连接也会断开。请务必实现自动重连，重连后重新发送 auth 和 subscribe。

退订用 {"action":"unsubscribe","params":"T.AAPL"}。不再需要某个标的记得退订，不退订不会额外收费，但会一直占着你套餐的订阅数配额。

Node.js 示例：

const ws = new WebSocket("wss://marilux.dev/stocks");
ws.onmessage = (event) => {
  const msgs = JSON.parse(event.data);
  for (const m of msgs) {
    if (m.status === "connected") ws.send(JSON.stringify({ action: "auth", params: "mh_live_your_key" }));
    if (m.status === "auth_success") ws.send(JSON.stringify({ action: "subscribe", params: "T.AAPL" }));
    if (m.ev === "T") console.log("成交:", m.sym, m.p, m.s);
  }
};

Python 示例：（pip install websockets）

import asyncio, json, websockets

async def main():
    async with websockets.connect("wss://marilux.dev/stocks") as ws:
        async for raw in ws:
            for m in json.loads(raw):
                if m.get("status") == "connected":
                    await ws.send(json.dumps({"action": "auth", "params": "mh_live_your_key"}))
                elif m.get("status") == "auth_success":
                    await ws.send(json.dumps({"action": "subscribe", "params": "T.AAPL"}))
                elif m.get("ev") == "T":
                    print("成交:", m["sym"], m["p"], m["s"])

asyncio.run(main())

期权数据

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

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

合约列表，用来查出你要的合约代码。常用参数：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 官方参数文档 →

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

期权链快照：该标的所有合约的最新报价、成交、当日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 官方参数文档 →

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

逐笔成交 / 逐笔报价（买一卖一）。用 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 官方参数文档 →

Flat Files 批量下载

整天的历史日K/分钟K，打包成 gzip 压缩的 CSV 文件，一次拿一整天的全市场数据，比逐个 ticker 调 REST 接口高效得多。跟 REST 接口用同一把 API Key，按套餐单独有"每日下载文件数"额度，不占用 REST 的调用额度。

指定交易日全市场日K。

curl "https://marilux.dev/v1/flatfiles/us_stocks_sip/day_aggs_v1/2024/01/2024-01-02.csv.gz" \
  -H "Authorization: Bearer mh_live_your_key" -o 2024-01-02.csv.gz

指定交易日全市场分钟K，单个文件通常在 20MB 左右。

文件格式：解压后是带表头的 CSV，日K和分钟K列相同：

ticker,volume,open,close,high,low,window_start,transactions
AAPL,77874426,187.15,185.64,188.44,183.885,1704171600000000000,1008813

window_start 是该K线起始时间的纳秒时间戳（注意不是 REST 接口的毫秒），日K为美东时间 0 点。

历史范围：Starter 套餐可下载最近 5 年，Advanced 套餐可下载 20 年以上；超出范围返回 403。

每日下载额度（文件数）：

• Starter：月付/季付 20 个，半年付 50 个，年付 100 个
• Advanced：月付/季付 40 个，半年付 100 个，年付 200 个
• 体验套餐不含 Flat Files，请求返回 403

每成功下载一个文件计 1 次，同一个文件重复下载也会重复计数。响应头 X-Flatfiles-Used / X-Flatfiles-Limit 是当日已下载/总额度文件数，按 UTC 0 点重置；同一天的文件对所有客户都是一份缓存，重复下载不会更慢。目前只开放美股日K与分钟K，逐笔报价/成交、期权及其他资产类别暂不提供；数据发布有约 1 天延迟（当天数据在次日可下载）。

响应头与额度

X-Cache 显示 HIT/MISS（期权逐笔不缓存，显示 BYPASS）；X-Plan、X-Plan-Tier、X-Plan-Expires 显示当前套餐 ID、档位（starter/advanced）与到期时间（ISO 8601，体验套餐按小时计，到期精确到分钟）。

X-Quota-Used / X-Quota-Limit 是每日调用额度：

• 每次 HTTP 请求计 1 次，缓存命中（X-Cache: HIT）也计入，与返回了多少条记录无关。
• 按 UTC 0 点重置（北京时间每天 08:00），重置时间见 X-Quota-Reset。
• 超出当日额度后，当天剩余请求全部返回 429，不会降速放行，需等重置或升级套餐。

速率上限（QPS）：每秒请求数按套餐限制——Starter 体验 5、月付/季付 10、半年付 15、年付 20；Advanced 体验 10、月付/季付 20、半年付 30、年付 40；期权月付/季付 20、半年付 30、年付 40（期权和股票的 QPS、并发分开计算，互不占用）。只有未命中缓存的请求受此限制，超出返回 429，按响应头 Retry-After（秒）等待后重试。未命中缓存的响应带 X-RateLimit-Limit / X-RateLimit-Remaining，以及处理耗时 X-Response-Time。

并发上限：同一个 Key 同时向数据源发起的请求数有上限（Starter 3 个，Advanced 5 个），缓存命中的请求不受限。超出的请求会自动排队，前面的完成后依次处理，不需要改代码；排队过长（超过上限的 4 倍）或等待超过 15 秒会返回 429（带 Retry-After 和 X-Concurrency-Limit），稍后重试即可。批量下载时把并发控制在上限以内，整体速度反而最快。

流量额度：REST 接口另有每月流量上限（Starter 每月 60GB，Advanced 每月 120GB），每天用多少不限，可以集中下载。用量见 X-Traffic-Used-Month / X-Traffic-Limit-Month（单位字节）：

• 按返回的数据量（解压后）计算，缓存命中也计入。
• 按 UTC 自然月重置（每月 1 日北京时间 08:00）。
• 超出后当月剩余请求返回 429，重置时间见 X-Traffic-Reset。
• 加量包：月额度不够用时可购买加量包（入门版 60GB、高级版 120GB），在兑换页面输入兑换码即可到账。套餐月额度用完后才开始使用加量包，可叠加多个，先到期的先用；每个加量包激活后 90 天内有效，用完为止，跨月也可继续使用。剩余量见响应头 X-Traffic-Pack-Remaining（单位字节）。Flat Files 和 WebSocket 有各自的额度，不计入这里的流量。
• 需要批量拉取大量历史数据时，日K/分钟K 建议使用 Flat Files，一个文件就是一整天的全市场数据，比逐个 ticker 调 REST 省得多。

WebSocket 走的是独立的并发连接数 / 订阅标的数配额，跟上面这套 REST 的每日调用额度是两回事，不共用也不互相影响，具体数字见 WebSocket 实时推送。

错误处理

失败响应一般是 { "status": "ERROR", "error": "..." } 结构：

{ "status": "ERROR", "error": "今日调用量已达上限 50000 次，次日 UTC 00:00 重置，或升级套餐" }

例外：REST 接口查询超出套餐历史范围的数据（如 Starter 查 5 年以前的K线）时，返回 403 且 status 为 NOT_AUTHORIZED：

{ "status": "NOT_AUTHORIZED", "error": "当前套餐不包含该数据：Starter 可查询最近 5 年历史，更早的数据需要 Advanced 套餐" }

判断是否失败请以 HTTP 状态码为准。401 密钥缺失或无效；403 密钥停用或已到期（股票和期权分别判断）、未开通对应产品（如没买期权套餐的 Key 请求 O: 期权代码）、超出套餐历史范围、或套餐不含该功能（如体验套餐下载 Flat Files）；404 接口不在当前套餐范围内（比如用 Starter 套餐的 Key 调 Advanced 专属接口）；429 速率、并发、日调用额度、流量额度或 Flat Files 每日下载额度超限；502/503 数据源暂时不可用（历史数据仍可能命中缓存返回）；504 数据源响应超时，稍后重试，批量下载时请降低并发。WebSocket 的错误不走 HTTP 状态码，是 {"ev":"status","status":"auth_failed"|"error","message":"..."} 这种消息，具体原因看 message。