Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.llmquantdata.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
它为 Agent 做什么

etf_holdings 返回单只美国上市 ETF 的 最近一份监管披露持仓 —— 完整持仓表（受 limit 约束），每行归一化为 EtfHolding 结构：ticker / cusip / isin / sedol 标识符、weight、market_value、shares，以及 sector / country / asset_type。按 weight 降序排序。 适合 agent 拿 真实持仓表 的场景：算集中度（Top-10 权重、HHI）、算两只 ETF 的重叠（调两次按 CUSIP / ISIN diff）、或从某只 ETF 的底层构造主题 basket。如果只要 ETF 基本信息、top-N 摘要和分布概览，优先用更便宜的 etf_lookup（免费）。 接口按 coverage 状态分流：覆盖范围内的 ticker 返回持仓 + 扣 1 credit；不在覆盖范围的 ticker 返回 200 OK、coverage_status="unsupported"、空 holdings 数组，0 credit —— 探覆盖范围永远不花钱。不提供 server-side compare 接口，跨 ETF overlap 在 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 }
}

​
Credit 规则

覆盖结果HTTPcreditsUsed
full / partial / stale（持仓已返回）2001
unsupported（空持仓 + 明确 notice）2000
调用方余额不足 且 ticker 在覆盖范围内402n/a —— 不返回持仓
调用方余额不足 且 ticker 不在覆盖范围2000 —— 即使无 credit，也照常返回 coverage envelope
核心原则：探覆盖永远不花钱；只有真正返回持仓才扣 credit。

​
说明

算两只 ETF 的 overlap：调两次 etf_holdings，在 agent 端 diff。优先按 cusip join，其次 isin，最后 ticker —— 持仓行里债券、现金、衍生品经常没有 ticker，但 CUSIP 等稳定标识符通常都在。
集中度指标（Top-10 权重、HHI）拿到行之后很便宜。返回已经按权重降序，直接切片即可。
在调本接口前先调一次 etf_lookup（免费）确认覆盖范围、读 holdings_count 再决定 limit。VTI 这类宽基 ETF 持仓上千只；默认 limit=50 对大多数 agent workflow 够用。

​
当前限制

不是当日 / 每日持仓。行对应最近一份 SEC 官方监管披露快照（通常按月或季度披露，公开发布有滞后），不是 issuer 内部当日底仓。as_of_date 会明确告诉你具体哪天。
行级 ticker 可为空。持仓行里债券、现金、衍生品、crypto trust 经常没有 ticker。识别和 join 一定要 fallback 到 CUSIP / ISIN。
不提供 server-side etf_compare_holdings。跨 ETF overlap、权重 diff、basket 比较都由 agent 调两次 etf_holdings 本地算。
当前不支持按历史日期查询。本接口始终返回最近一份可用快照。按 as_of_date 查询历史是后续 roadmap。
覆盖范围有限。当前覆盖 SPY、QQQ、VTI、SOXX、ARKK 等精选热门 ETF。IBIT / DRAM 当前不在覆盖范围。
不解析 issuer PDF、不接付费数据源。Issuer 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 }
  }
}

​
完整参数参考

​
ticker
string
required
美国上市 ETF ticker（如 SPY、QQQ、VTI、SOXX、ARKK）。大小写不敏感；服务端会 uppercase 并 trim。不在覆盖范围的 ticker 返回 200 OK，coverage_status="unsupported"，creditsUsed=0。
​
limit
integer
default:50
返回的持仓行数上限，按 weight 降序。默认 50，最大 500。宽基 ETF（如 VTI）底层超过最大值；cursor 分页在 roadmap 中。

​
相关接口

ETF 基本信息

Fund identity、SEC mapping、top holdings 摘要、exposure 分布 —— 免费。

美股历史日线

ETF 价格历史走 equity 日线 contract。

MCP Server 接入

60 秒接入 Claude / Cursor / 任意 agent harness。