> ## 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.

# ETF 持仓明细

> 查询单只美国上市 ETF 的最新或指定日期前可用持仓明细，字段已整理统一，并按权重从高到低排序。

<Note icon="sparkles">
  **可作为 MCP 工具调用**：`etf_holdings` —— 可在 Claude / Cursor / 任意 MCP 客户端中直接使用。详见 [MCP Server](/zh-CN/integration/mcp-server) 60 秒配置。
</Note>

<Badge color="green" icon="circle-check">已上线</Badge>
 
<Badge color="blue" size="sm">每次 1 credit（不在覆盖范围时 0）</Badge>

## 它为 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`](/zh-CN/api/etf/lookup)。

这个接口对平台「动作执行完成就扣费」的规则有一个登记在案的例外：把暂不支持的 ticker 当作免费的**覆盖检查**，而不是一次持仓取数。支持名单里的 ticker 会返回持仓并扣 1 credit；暂不支持的 ticker 会返回 `200 OK`、`coverage_status="unsupported"` 和空 `holdings`，**不扣 credit**。这是只针对 ETF Holdings 的明确例外，不是平台上「没数据就免费」的通用规则。传 `as_of=YYYY-MM-DD` 可取 `as_of_date <= as_of` 的最近申报；比较两只 ETF 的持仓重合仍由 agent 自己计算。

## 返回值

<ResponseField name="data" type="EtfHoldingsResult" required>
  <Expandable title="EtfHoldingsResult 字段">
    <ResponseField name="ticker" type="string" required>
      ETF ticker，服务端会转成大写。
    </ResponseField>

    <ResponseField name="fund_name" type="string" nullable>
      基金显示名称。`coverage_status="unsupported"` 时为 `null`。
    </ResponseField>

    <ResponseField name="issuer" type="string" nullable>
      基金发行方 / 管理方。
    </ResponseField>

    <ResponseField name="holdings" type="EtfHolding[]" required>
      持仓明细，按 `weight` 从高到低返回。`coverage_status="unsupported"` 时为空数组。

      <Expandable title="EtfHolding 字段">
        <ResponseField name="holding_name" type="string" required>持仓名称（按申报文件原文）。</ResponseField>

        <ResponseField name="ticker" type="string" nullable>
          底层资产 ticker。**债券、现金、衍生品、crypto trust 经常没有 ticker** —— 这时用 `cusip` / `isin` 识别。
        </ResponseField>

        <ResponseField name="cusip" type="string" nullable>CUSIP。比较两只基金的重合持仓时优先用它对齐。</ResponseField>
        <ResponseField name="isin" type="string" nullable>ISIN。CUSIP 缺失时再用它对齐。</ResponseField>
        <ResponseField name="sedol" type="string" nullable>SEDOL（申报文件提供时返回）。</ResponseField>

        <ResponseField name="asset_type" type="string" nullable>
          `equity` / `fixed_income` / `cash` / `derivative` / `crypto` / `other`。
        </ResponseField>

        <ResponseField name="sector" type="string" nullable>行业分类，可能为 `null`。</ResponseField>
        <ResponseField name="country" type="string" nullable>国家 / 地区，可能为 `null`。</ResponseField>
        <ResponseField name="shares" type="number" nullable>持有数量（股 / 份）。</ResponseField>
        <ResponseField name="market_value" type="number" nullable>市值（USD）。</ResponseField>

        <ResponseField name="weight" type="number" nullable>
          组合权重，小数形式（例如 `0.071` 表示 7.1%）。
        </ResponseField>

        <ResponseField name="notional_value" type="number" nullable>
          衍生品和特殊资产的名义本金，可能为 `null`。
        </ResponseField>

        <ResponseField name="source" type="string" required>本行数据所来自的 SEC 披露数据集标识。</ResponseField>
        <ResponseField name="source_url" type="string" nullable>相关 SEC 披露数据集链接，可用于引用。</ResponseField>
        <ResponseField name="as_of_date" type="string" nullable>本行对应的监管披露报告日。</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="source" type="string" required>顶层数据所来自的 SEC 披露数据集标识。</ResponseField>
    <ResponseField name="source_url" type="string" nullable>顶层相关 SEC 披露数据集链接，可用于引用。</ResponseField>
    <ResponseField name="as_of_date" type="string" nullable>这份公开申报对应的日期（`YYYY-MM-DD`）。如果传了 `as_of`，这里是 `<= as_of` 的最近可用日期。</ResponseField>
    <ResponseField name="fetched_at" type="string" nullable>LLMQuant Data 上次更新这份持仓数据的 ISO 时间戳。</ResponseField>
    <ResponseField name="stale" type="boolean" required>如果数据已经偏旧，或者本次刷新降级，这里是 `true`。</ResponseField>

    <ResponseField name="coverage_status" type="string" required>
      `full` / `partial` / `stale` / `unsupported` 之一。
    </ResponseField>

    <ResponseField name="coverage_notice" type="string" required>
      当前支持情况说明，始终返回。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">
  `full` / `partial` / `stale` 数据返回时为 `1`；`coverage_status="unsupported"` 时为 `0`。
</ResponseField>

<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>

```json title="200 OK · etf_holdings（supported）" expandable theme={null}
{
  "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/dera/data/form-n-port-data-sets",
        "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/dera/data/form-n-port-data-sets",
        "as_of_date": "2019-09-30"
      }
    ],
    "source": "sec_nport",
    "source_url": "https://www.sec.gov/dera/data/form-n-port-data-sets",
    "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": { "creditsUsed": 1, "remainingCredits": 99 }
}
```

```json title="200 OK · etf_holdings（不在覆盖范围）" expandable theme={null}
{
  "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": { "creditsUsed": 0, "remainingCredits": 100 }
}
```

## 扣费规则

| 覆盖结果                                | HTTP  |          `creditsUsed`          |
| ----------------------------------- | ----- | :-----------------------------: |
| `full` / `partial` / `stale`（持仓已返回） | `200` |               `1`               |
| `unsupported`（没有持仓，但明确说明不支持）        | `200` |               `0`               |
| 调用方余额不足 **且** ticker 在覆盖范围内         | `402` |           n/a —— 不返回持仓          |
| 调用方余额不足 **且** ticker 不在覆盖范围         | `200` | `0` —— 即使没有 credit，也会返回“不支持”的说明 |

简单说：查“支不支持”这个动作不扣费，真的返回持仓明细才扣 1 credit。这个「不支持就免费」的行为是只针对 ETF Holdings 的、登记在案的明确例外 —— 其它接口都是动作一执行就扣费，哪怕结果为空。

## 说明

<Tip>
  **比较两只 ETF 的持仓重合**：分别调两次 `etf_holdings`，再由 agent 自己比较。**优先按 `cusip` 对齐**，其次 `isin`，最后 `ticker` —— 债券、现金、衍生品经常没有 ticker，但 CUSIP 等稳定标识通常有。
</Tip>

<Tip>
  **集中度指标**（Top-10 权重、HHI）拿到持仓行后很好算。返回已经按权重从高到低排好，直接取前几行即可。
</Tip>

<Tip>
  在调本接口前，可以先用免费的 [`etf_lookup`](/zh-CN/api/etf/lookup) 确认是否支持，再看 `holdings_count` 决定 `limit`。`VTI` 这类宽基 ETF 可能有上千条持仓；默认 `limit=50` 对多数问题已经够用。
</Tip>

### 当前限制

<Warning>
  **不是当日 / 每日持仓**。这些行来自最近一份 SEC 公开申报，通常按月或按季度披露，公开发布时间会滞后；不是基金公司内部的当天底仓。`as_of_date` 会告诉你这份数据对应哪一天。
</Warning>

<Warning>
  **行级 `ticker` 可能为空**。债券、现金、衍生品、crypto trust 经常没有 ticker。识别和对齐持仓时，一定要回退到 CUSIP / ISIN。
</Warning>

<Warning>
  **不提供服务端 `etf_compare_holdings`**。跨 ETF 持仓重合、权重差异、篮子比较，都由 agent 调两次 `etf_holdings` 后自己算。
</Warning>

<Warning>
  **只支持单点历史查询**。`as_of` 选择某一天或以前的最近申报；不支持区间查询、季度号查询或一次返回多期数据。
</Warning>

<Warning>
  **覆盖范围有限**。当前覆盖 `SPY`、`QQQ`、`VTI`、`SOXX`、`ARKK` 等精选热门 ETF。`IBIT` / `DRAM` 当前不在覆盖范围。
</Warning>

<Warning>
  **仅使用监管披露**。基金公司的 fact-sheet PDF 和其他非监管披露数据暂不用于这个接口。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // 默认 —— 按权重前 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" }
      }
    }
    ```

    ```python Python (HTTP) theme={null}
    import os, requests

    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    resp = requests.get(
        "https://api.llmquantdata.com/api/etf/holdings",
        headers=headers,
        params={"ticker": "VTI", "limit": 50, "as_of": "2025-10-01"},
    ).json()
    d = resp["data"]
    if d["coverage_status"] == "unsupported":
        print(f"暂不支持: {d['coverage_notice']}")
    else:
        top10_weight = sum(h["weight"] or 0 for h in d["holdings"][:10])
        print(f"{d['ticker']} 申报日 {d['as_of_date']}  前十大权重: {top10_weight:.1%}")
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/etf/holdings?ticker=VTI&limit=50&as_of=2025-10-01" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<Accordion title="etf_holdings —— 请求参数" icon="sliders">
  <ParamField query="ticker" type="string" required>
    美国上市 ETF ticker（如 `SPY`、`QQQ`、`VTI`、`SOXX`、`ARKK`）。大小写不敏感；服务端会转成大写并去掉前后空格。暂不支持的 ticker 返回 `200 OK`、`coverage_status="unsupported"`，且 `creditsUsed=0`。
  </ParamField>

  <ParamField query="limit" type="integer" default={50}>
    返回的持仓行数上限，按 `weight` 从高到低排列。默认 `50`，最大 `500`。宽基 ETF（如 `VTI`）底层持仓可能超过最大值；分页以后再加。
  </ParamField>

  <ParamField query="as_of" type="string">
    可选报告日期，格式 `YYYY-MM-DD`。返回 `as_of_date <= as_of` 的最近一份持仓申报；不传则返回最新可用申报。
  </ParamField>
</Accordion>

## 相关接口

<Columns cols={3}>
  <Card title="ETF 基本信息" icon="magnifying-glass" href="/zh-CN/api/etf/lookup">
    基金基本信息、SEC 映射、前几大持仓和分布概览 —— 免费。
  </Card>

  <Card title="美股历史日线" icon="chart-line" href="/zh-CN/api/prices/equity-historical">
    ETF 历史价格用股票日线接口查。
  </Card>

  <Card title="MCP Server 接入" icon="plug" href="/zh-CN/integration/mcp-server">
    60 秒把 Claude / Cursor 等客户端接上。
  </Card>
</Columns>