Developer docs

指数代理序列

用跟踪指数的 ETF 合成的逐日序列,价格和全收益两种口径,适合做回测基准、行业轮动和市场状态判断。

入门版和高级版都能用。本站不提供指数本身的行情:标普、纳斯达克、罗素等指数的数据要指数公司授权。这里提供的是指数代理序列,用跟踪该指数的 ETF 合成,例如 SPX 用 SPY、NDX 用 QQQ。ETF 有管理费(每年 0.03%~0.95%)和跟踪误差,所以数值跟指数本身不完全相同,但涨跌走势高度一致。量化研究里本来就多用这些 ETF 做基准,因为它们可以交易,有真实的成交量和价差。

  • 更新时间:每个交易日收盘后自动更新,美东时间 21:00 前能取到当天数据(北京时间次日 10:00 前,夏令时 09:00 前)。只提供已收盘的日线,不含盘中实时数据。响应里的 updated_through 是目前已更新到的交易日
  • 历史:从 2003-09-10 开始,ETF 上市更晚的从上市日开始,每个代理的起点见清单接口返回的 start。入门版只能查最近 5 年,更早的返回 403
  • 代码变更:ETF 换过代码的自动拼接成连续序列,例如 QQQ 在 2004–2011 年间叫 QQQQ,SOXX 在 2010 年以前叫 IGW
  • 计费:跟其他接口一样,每次请求计 1 次调用,按返回的字节数计流量

接口

GET/v1/indices

可用的指数代理清单:代码、名称、分类、对应的 ETF、数据起点和口径说明。

curl "https://marilux.dev/v1/indices?apiKey=mh_live_your_key"
{
  "status": "OK", "updated_through": "2026-11-20", "count": 41,
  "categories": [ { "id": "broad", "name": "宽基指数" }, … ],
  "results": [
    { "symbol": "SPX", "name": "标普 500", "category": "broad", "proxy": "SPY", "start": "2003-09-10", "note": null },
    { "symbol": "NDX", "name": "纳斯达克 100", "category": "broad", "proxy": "QQQ", "start": "2003-09-10",
      "note": "2004-12 至 2011-03 期间 ETF 代码是 QQQQ,已自动拼接" },
    …
  ]
}
GET/v1/indices/{代码}/bars

某个指数代理的逐日 K 线。{代码} 用清单里的 symbol,大小写都可以,也可以写成 I:SPX。参数:

  • from、to:日期 YYYY-MM-DD,默认最近一年。to 晚于 updated_through 时按 updated_through 算
  • series:price(默认,价格口径)或 total_return(全收益口径),区别见下一节

一次最多返回整个历史(约 5800 行),不用翻页。返回的 K 线字段跟 历史K线 接口相同,多了一个美东日期 date:t 是美东时间 0 点的毫秒时间戳,o/h/l/c 是开高低收,v 是成交量(按拆股折算成现在的份额),vw 是成交量加权均价,n 是成交笔数。

curl "https://marilux.dev/v1/indices/SPX/bars?from=2024-12-18&to=2024-12-20&apiKey=mh_live_your_key"
{
  "status": "OK", "symbol": "SPX", "name": "标普 500", "proxy": "SPY", "series": "price",
  "from": "2024-12-18", "to": "2024-12-20", "updated_through": "2026-11-20", "count": 3,
  "results": [
    { "date": "2024-12-18", "t": 1734498000000, "o": 603.98, "h": 606.405, "l": 585.89, "c": 586.28, "v": 108248729, "vw": 594.9972, "n": 772894 },
    { "date": "2024-12-19", "t": 1734584400000, "o": 591.36, "h": 593, "l": 585.85, "c": 586.1, "v": 85919452, "vw": 588.217, "n": 702101 },
    { "date": "2024-12-20", "t": 1734670800000, "o": 581.77, "h": 595.75, "l": 580.91, "c": 591.15, "v": 125716674, "vw": 589.0173, "n": 772177 }
  ]
}

价格口径和全收益口径

  • series=price(价格口径):只按拆股调整,不含分红。最新一天等于 ETF 的真实收盘价,跟 K 线接口 adjusted=true 的结果一致,对应指数公司的"价格指数"(标普 500 平时报的点位就是价格指数)。ETF 以后再拆股时,拆股之前的历史价格会整体按比例调整
  • series=total_return(全收益口径):拆股加分红再投资。以数据起点那天为基准(起点当天等于 ETF 收盘价),之后每次除息都把分红按除息前一交易日收盘价再投资进去。历史值永远不变,以后的分红和拆股只影响之后的数值,所以每天只追加最新一行就行,分段拉取也能直接拼接。数值本身不是可成交的价格,只用来算收益率

回测基准请用全收益口径。价格口径不含分红,拿来比较会每年低估基准 1.3%~1.5%(标普 500 的股息率),策略看起来会比实际好。用同一天的两个口径一除,就是累计分红的贡献:2024-12-18 SPX 全收益 867.72、价格 586.28,2003-09 以来分红再投资让收益多了约 48%。

代理清单

下表跟 /v1/indices 接口返回的清单一致。代码用业内常见的指数代码,方便对照;"说明"一列是这个代理需要注意的口径问题。

代码指数ETF说明
宽基指数
SPX标普 500SPY
NDX纳斯达克 100QQQ2004-12 至 2011-03 期间 ETF 代码是 QQQQ,已自动拼接
DJI道琼斯工业平均DIA
RUT罗素 2000IWM
RUI罗素 1000IWB
RUA罗素 3000IWV
MID标普中盘 400MDY
SML标普小盘 600IJR
SPXEW标普 500 等权RSP
COMP纳斯达克综合ONEQONEQ 抽样复制、规模较小,跟踪误差比其他宽基大
CRSPTM1美国全市场(CRSP)VTIVTI 在 2013-06 之前跟踪 MSCI US Broad Market
标普 500 行业
S5INFT信息技术XLK
S5FINL金融XLF2016-09 之前包含房地产
S5HLTH医疗保健XLV
S5COND可选消费XLY2018-09 行业分类调整时部分互联网公司移入通信服务
S5CONS必需消费XLP
S5INDU工业XLI
S5ENRS能源XLE
S5MATR原材料XLB
S5UTIL公用事业XLU
S5RLST房地产XLREETF 2015-10 成立
S5TELS通信服务XLCETF 2018-06 成立
细分行业
SOX费城半导体SOXXSOXX 在 2021-06 改为跟踪 NYSE Semiconductor Index;2010-10 之前代码是 IGW,已自动拼接
NBI纳斯达克生物科技IBB
BKXKBW 银行KBWBETF 2011-11 成立
风格(成长 / 价值)
RLG罗素 1000 成长IWF
RLV罗素 1000 价值IWD
RUO罗素 2000 成长IWO
RUJ罗素 2000 价值IWN
SGX标普 500 成长IVW
SVX标普 500 价值IVE
因子
MSCI-MOMMSCI 美国动量MTUMETF 2013-04 成立
MSCI-MINVOLMSCI 美国最小波动USMVETF 2011-10 成立
MSCI-QUALMSCI 美国质量QUALETF 2013-07 成立
债券、美元与商品
UST1-3Y美国国债 1–3 年SHY债券价格,不是收益率
UST7-10Y美国国债 7–10 年IEF债券价格,不是收益率
UST20Y美国国债 20 年以上TLT债券价格,不是收益率
DXY美元指数UUPUUP 持有美元指数期货,含展期损益,跟现货指数有偏差;2007-02 成立
GOLD黄金GLD跟踪伦敦金价;2004-11 成立
WTIWTI 原油USOUSO 持有原油期货,长期因展期损耗明显偏离现货油价;2006-04 成立
COMMODITY综合商品DBCDBC 跟踪 DBIQ 多元商品指数(期货),不是彭博商品指数;2006-02 成立

Python 示例:基准收益和 beta

import requests, pandas as pd

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

def index_bars(symbol, start, end=None, series="total_return"):
    params = {"from": start, "series": series}
    if end:
        params["to"] = end
    r = requests.get(f"{BASE}/v1/indices/{symbol}/bars", headers=H, params=params, timeout=60)
    r.raise_for_status()
    df = pd.DataFrame(r.json()["results"])
    return df.set_index(pd.to_datetime(df["date"]))["c"]

spx = index_bars("SPX", "2015-01-01")
ndx = index_bars("NDX", "2015-01-01")
ret = pd.concat({"SPX": spx, "NDX": ndx}, axis=1).pct_change().dropna()

years = (ret.index[-1] - ret.index[0]).days / 365.25
cagr = (1 + ret).prod() ** (1 / years) - 1
beta = ret["NDX"].cov(ret["SPX"]) / ret["SPX"].var()
print(cagr.round(4), "NDX 对 SPX 的 beta:", round(beta, 2))

每天增量更新:用全收益口径时,本地存的历史不需要重拉,每天美东 21:00 之后取一次 from = 本地最后一天的数据追加即可。价格口径遇到 ETF 拆股时历史会整体调整,增量更新前先比对本地最后一天的收盘价,对不上就整段重拉。

last = local.index[-1].strftime("%Y-%m-%d")          # local 是你已经存下来的序列
new = index_bars("SPX", last)
local = pd.concat([local, new[new.index > local.index[-1]]])

用在实盘程序里

  • 每天更新的日线适合回测、收盘后计算信号、第二天开盘下单这类策略
  • 盘中要用指数的实时值,直接取 ETF 本身的行情:快照、分钟 K 线,或高级版的 WebSocket(T.SPY)。价格口径跟 ETF 真实价格一致,盘中数据可以直接接在日线后面
  • 下单的标的本来就是 ETF(或者期货、期权),用 ETF 做信号源,信号和成交价是同一个东西,不会有指数和 ETF 之间的基差

不提供的数据

  • VIX 等波动率指数:没有能替代的 ETF。VIXY、UVXY 持有 VIX 期货,有展期损耗,长期走势跟 VIX 差很远。需要隐含波动率可以用期权链快照里的 implied_volatility
  • 指数成分股和权重的历史:可以用全市场日线自己构建股票池
  • 国债收益率(如 10 年期 TNX):清单里的国债代理是国债 ETF 的价格,不是收益率
  • 指数的实时点位:见上一节,用 ETF 的实时行情
  • 分钟级的指数代理:只提供日线。需要 SPY、QQQ 等 ETF 2003 年以来的 1 分钟线,可以在历史数据下载直接下载 CSV,拆股、分红复权和代码变更都已处理好

指数名称和代码是各指数公司(S&P Dow Jones Indices、Nasdaq、FTSE Russell、MSCI 等)的商标,本站跟它们没有关联。代理序列由本站根据 ETF 的成交数据、拆股和分红计算,不是指数公司发布的官方数值。