Skip to main content
可作为 MCP 工具调用：etf_holdings —— 可在 Claude / Cursor / 任意 MCP 客户端中直接使用。详见 MCP Server 60 秒配置。
已上线   每次 1 credit（不在覆盖范围时 0）

​
它为 Agent 做什么

etf_holdings 返回单只美国上市 ETF 的完整持仓表，可以查最新可用申报，也可以用 as_of 回看某个日期前已经公开的申报。返回行数受 limit 限制；每行都整理成同一套 EtfHolding 字段，包括 ticker / cusip / isin / sedol、weight、market_value、shares，以及 sector / country / asset_type。结果按 weight 从高到低排列。 当 agent 需要逐条持仓时用它：算前十大占比、HHI，比较两只 ETF 的重合持仓，或从某只 ETF 的底层成分里挑主题股票。如果只是想知道这只 ETF 是什么、前几大持仓是什么，优先用免费的 etf_lookup。 当前支持名单里的 ticker 会返回持仓并扣 1 credit；暂不支持的 ticker 会返回 200 OK、coverage_status="unsupported" 和空 holdings，不扣 credit。传 as_of=YYYY-MM-DD 可取 as_of_date <= as_of 的最近申报；比较两只 ETF 的持仓重合仍由 agent 自己计算。

​
返回值

​
data
EtfHoldingsResult
required
​
meta.count
number
本次返回的行数（小 ETF 可能 < limit，unsupported 时为 0）。
​
meta.limit
number
本次实际应用的 limit。
​
meta.creditsUsed
number
full / partial / stale 数据返回时为 1；coverage_status="unsupported" 时为 0。
​
meta.remainingCredits
number
账户剩余 credit。
200 OK · etf_holdings（supported）
{
  "data": {
    "ticker": "SPY",
    "fund_name": "SPDR S&P 500 ETF Trust",
    "issuer": "State Street",
    "holdings": [
      {
        "holding_name": "APPLE INC",
        "ticker": "AAPL",
        "cusip": "037833100",
        "isin": "US0378331005",
        "sedol": null,
        "asset_type": "equity",
        "sector": "Information Technology",
        "country": "US",
        "shares": 168000000,
        "market_value": 30450000000,
        "weight": 0.071,
        "notional_value": null,
        "source": "sec_nport",
        "source_url": "https://www.sec.gov/files/dera/data/form-n-port-data-sets/2019q4_nport.zip#FUND_REPORTED_HOLDING.tsv",
        "as_of_date": "2019-09-30"
      },
      {
        "holding_name": "MICROSOFT CORP",
        "ticker": "MSFT",
        "cusip": "594918104",
        "isin": "US5949181045",
        "sedol": null,
        "asset_type": "equity",
        "sector": "Information Technology",
        "country": "US",
        "shares": 78000000,
        "market_value": 27890000000,
        "weight": 0.065,
        "notional_value": null,
        "source": "sec_nport",
        "source_url": "https://www.sec.gov/files/dera/data/form-n-port-data-sets/2019q4_nport.zip#FUND_REPORTED_HOLDING.tsv",
        "as_of_date": "2019-09-30"
      }
    ],
    "source": "sec_nport",
    "source_url": "https://www.sec.gov/files/dera/data/form-n-port-data-sets/2019q4_nport.zip#FUND_REPORTED_HOLDING.tsv",
    "as_of_date": "2019-09-30",
    "fetched_at": "2026-05-12T03:14:00Z",
    "stale": false,
    "coverage_status": "full",
    "coverage_notice": "Latest available SEC regulatory disclosure snapshot. Not the issuer's daily latest holdings."
  },
  "meta": { "count": 2, "limit": 50, "creditsUsed": 1, "remainingCredits": 99 }
}
200 OK · etf_holdings（不在覆盖范围）
{
  "data": {
    "ticker": "IBIT",
    "fund_name": null,
    "issuer": null,
    "holdings": [],
    "source": "sec_nport",
    "source_url": null,
    "as_of_date": null,
    "fetched_at": null,
    "stale": false,
    "coverage_status": "unsupported",
    "coverage_notice": "IBIT is not in the current covered ETF list. As a spot Bitcoin trust, its SEC disclosure path differs from the conventional ETFs we cover today."
  },
  "meta": { "count": 0, "limit": 50, "creditsUsed": 0, "remainingCredits": 100 }
}

​
扣费规则

覆盖结果HTTPcreditsUsed
full / partial / stale（持仓已返回）2001
unsupported（没有持仓，但明确说明不支持）2000
调用方余额不足 且 ticker 在覆盖范围内402n/a —— 不返回持仓
调用方余额不足 且 ticker 不在覆盖范围2000 —— 即使没有 credit，也会返回“不支持”的说明
简单说：查“支不支持”不扣费；真的返回持仓明细才扣 credit。

​
说明

比较两只 ETF 的持仓重合：分别调两次 etf_holdings，再由 agent 自己比较。优先按 cusip 对齐，其次 isin，最后 ticker —— 债券、现金、衍生品经常没有 ticker，但 CUSIP 等稳定标识通常有。
集中度指标（Top-10 权重、HHI）拿到持仓行后很好算。返回已经按权重从高到低排好，直接取前几行即可。
在调本接口前，可以先用免费的 etf_lookup 确认是否支持，再看 holdings_count 决定 limit。VTI 这类宽基 ETF 可能有上千条持仓；默认 limit=50 对多数问题已经够用。

​
当前限制

不是当日 / 每日持仓。这些行来自最近一份 SEC 公开申报，通常按月或按季度披露，公开发布时间会滞后；不是基金公司内部的当天底仓。as_of_date 会告诉你这份数据对应哪一天。
行级 ticker 可能为空。债券、现金、衍生品、crypto trust 经常没有 ticker。识别和对齐持仓时，一定要回退到 CUSIP / ISIN。
不提供服务端 etf_compare_holdings。跨 ETF 持仓重合、权重差异、篮子比较，都由 agent 调两次 etf_holdings 后自己算。
只支持单点历史查询。as_of 选择某一天或以前的最近申报；不支持区间查询、季度号查询或一次返回多期数据。
覆盖范围有限。当前覆盖 SPY、QQQ、VTI、SOXX、ARKK 等精选热门 ETF。IBIT / DRAM 当前不在覆盖范围。
仅使用监管披露。基金公司的 fact-sheet PDF 和其他非监管披露数据暂不用于这个接口。

​
直接调用

// 默认 —— 按权重前 50
{
  "method": "tools/call",
  "params": {
    "name": "etf_holdings",
    "arguments": { "ticker": "SPY" }
  }
}

// 自定义 limit + 按日期回看
{
  "method": "tools/call",
  "params": {
    "name": "etf_holdings",
    "arguments": { "ticker": "VTI", "limit": 200, "as_of": "2025-10-01" }
  }
}

​
完整参数参考

​
ticker
string
required
美国上市 ETF ticker（如 SPY、QQQ、VTI、SOXX、ARKK）。大小写不敏感；服务端会转成大写并去掉前后空格。暂不支持的 ticker 返回 200 OK、coverage_status="unsupported"，且 creditsUsed=0。
​
limit
integer
default:50
返回的持仓行数上限，按 weight 从高到低排列。默认 50，最大 500。宽基 ETF（如 VTI）底层持仓可能超过最大值；分页以后再加。
​
as_of
string
可选报告日期，格式 YYYY-MM-DD。返回 as_of_date <= as_of 的最近一份持仓申报；不传则返回最新可用申报。

​
相关接口

ETF 基本信息

基金基本信息、SEC 映射、前几大持仓和分布概览 —— 免费。

美股历史日线

ETF 历史价格用股票日线接口查。

MCP Server 接入

60 秒把 Claude / Cursor 等客户端接上。