> ## 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 的名称、发行方、SEC 注册信息、最新或指定日期前可用的持仓申报，以及前几大持仓和分布概览。

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

<Badge color="green" icon="circle-check">已上线</Badge>
 
<Badge color="gray" size="sm">免费 · 0 credit</Badge>

## 它为 Agent 做什么

`etf_lookup` 用来先回答“一只 ETF 到底是什么”。它会返回基金名称、发行方、资产类型、SEC 注册信息，以及最新或某个日期前已经公开的持仓申报。它还会给出前几大持仓和行业 / 国家 / 资产类型分布，方便 agent 判断要不要继续拉完整持仓表。

它**不查价格**。ETF 历史价格请用 [`equity_historical_prices`](/zh-CN/api/prices/equity-historical)，因为 ETF 价格走和股票一样的日线接口。如果要回看某个日期以前已经公开的持仓，传 `as_of=YYYY-MM-DD`；返回的是那天以前最近一份公开申报，**不是基金公司当天内部持仓**。

不在当前支持名单里的 ticker（例如 `IBIT` / `DRAM`）也会返回 `200 OK`，并通过 `coverage_status="unsupported"` 和 `coverage_notice` 明确告诉你暂不支持，**不会**用空结果假装查到了数据。

## 返回值

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

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

    <ResponseField name="issuer" type="string" nullable>
      基金发行方 / 管理方（如 `State Street`、`Vanguard`、`Invesco`、`BlackRock`）。
    </ResponseField>

    <ResponseField name="asset_class" type="string" nullable>
      `equity` / `fixed_income` / `commodity` / `crypto` / `multi_asset` / `other`。
    </ResponseField>

    <ResponseField name="category" type="string" nullable>
      基金分类标签（如 `Large Blend`、`Semiconductors`）。
    </ResponseField>

    <ResponseField name="cik" type="string" nullable>SEC 注册人 CIK。</ResponseField>
    <ResponseField name="series_id" type="string" nullable>SEC Investment Company Series ID。</ResponseField>
    <ResponseField name="class_id" type="string" nullable>SEC Class ID。</ResponseField>

    <ResponseField name="expense_ratio" type="number" nullable>
      费用率。来自 SEC 公开申报；可能为 `null`。
    </ResponseField>

    <ResponseField name="aum" type="number" nullable>AUM（USD），可能为 `null`。</ResponseField>
    <ResponseField name="nav" type="number" nullable>最新 NAV，可能为 `null`。</ResponseField>
    <ResponseField name="market_price" type="number" nullable>最新市价，可能为 `null`。</ResponseField>
    <ResponseField name="premium_discount_pct" type="number" nullable>相对 NAV 的溢价 / 折价，可能为 `null`。</ResponseField>
    <ResponseField name="inception_date" type="string" nullable>基金成立日（`YYYY-MM-DD`）。</ResponseField>

    <ResponseField name="holdings_count" type="number" nullable>
      这份申报里的持仓条数。可用它判断要不要再调用 `etf_holdings`。
    </ResponseField>

    <ResponseField name="top_holdings" type="array" nullable>
      前几大持仓摘要（通常按权重取前 10）。要完整持仓表请调 [`etf_holdings`](/zh-CN/api/etf/holdings)。
    </ResponseField>

    <ResponseField name="sector_exposure" type="array" nullable>
      行业分布，可能为 `null`。
    </ResponseField>

    <ResponseField name="country_exposure" type="array" nullable>
      国家分布，可能为 `null`。
    </ResponseField>

    <ResponseField name="asset_type_exposure" type="array" nullable>
      资产类型分布（equity / fixed\_income / cash / derivative / ...），可能为 `null`。
    </ResponseField>

    <ResponseField name="source" type="string" required>
      数据所来自的 SEC 监管披露数据集标识。暂不支持的 ticker 也会返回。
    </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 上次更新这只 ETF 基本资料和持仓摘要的 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>
      面向用户和 agent 的说明：当前支持到什么程度，或者为什么暂不支持。始终返回。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">固定 `0` —— lookup 免费。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>

```json title="200 OK · etf_lookup（supported）" expandable theme={null}
{
  "data": {
    "ticker": "SPY",
    "fund_name": "SPDR S&P 500 ETF Trust",
    "issuer": "State Street",
    "asset_class": "equity",
    "category": "Large Blend",
    "cik": "0000884394",
    "series_id": "S000004310",
    "class_id": "C000012075",
    "expense_ratio": 0.0945,
    "aum": null,
    "nav": null,
    "market_price": null,
    "premium_discount_pct": null,
    "inception_date": "1993-01-22",
    "holdings_count": 503,
    "top_holdings": [
      { "ticker": "AAPL", "holding_name": "APPLE INC", "weight": 0.071 },
      { "ticker": "MSFT", "holding_name": "MICROSOFT CORP", "weight": 0.065 }
    ],
    "sector_exposure": [
      { "sector": "Information Technology", "weight": 0.297 },
      { "sector": "Financials", "weight": 0.135 }
    ],
    "country_exposure": [{ "country": "US", "weight": 0.99 }],
    "asset_type_exposure": [{ "asset_type": "equity", "weight": 0.995 }],
    "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": 0, "remainingCredits": 100 }
}
```

```json title="200 OK · etf_lookup（不在覆盖范围）" expandable theme={null}
{
  "data": {
    "ticker": "IBIT",
    "fund_name": null,
    "issuer": null,
    "asset_class": null,
    "category": null,
    "cik": null,
    "series_id": null,
    "class_id": null,
    "expense_ratio": null,
    "aum": null,
    "nav": null,
    "market_price": null,
    "premium_discount_pct": null,
    "inception_date": null,
    "holdings_count": null,
    "top_holdings": null,
    "sector_exposure": null,
    "country_exposure": null,
    "asset_type_exposure": null,
    "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; we may add a dedicated path later."
  },
  "meta": { "creditsUsed": 0, "remainingCredits": 100 }
}
```

## 覆盖说明

| `coverage_status` | 表示什么                                      | `stale`          |
| ----------------- | ----------------------------------------- | ---------------- |
| `full`            | 当前支持这只 ticker；基本资料和持仓申报都能返回。              | `false`（通常）      |
| `partial`         | 当前支持这只 ticker，但有些字段拿不到；缺失字段返回 `null`。     | `false` / `true` |
| `stale`           | 曾经有数据，但最近刷新失败或数据已经偏旧，所以返回较旧可用数据。          | `true`           |
| `unsupported`     | 当前**不支持**这只 ticker。仍返回 `200 OK`，但会明确说明原因。 | `false`          |

先看 `coverage_status` 再读其他字段：如果是 `unsupported`，不要把空字段理解成“这只 ETF 真的没有持仓”。

## 说明

<Tip>
  **配合 [`etf_holdings`](/zh-CN/api/etf/holdings) 使用**：如果只看概览，`etf_lookup` 返回的前几大持仓通常够用；只有需要完整持仓、具体权重，或比较两只 ETF 的重合持仓时，再调 `etf_holdings`。
</Tip>

<Tip>
  查 ETF 的**历史价格**不要用这个接口。请用 [`equity_historical_prices`](/zh-CN/api/prices/equity-historical) 配合 ETF ticker；ETF 价格和股票一样走日线价格接口。
</Tip>

<Tip>
  `lookup` 不扣 credit，但仍会记一条使用记录。可以先用它确认这只 ETF 是否支持，再决定要不要调用会扣费的 `etf_holdings`。
</Tip>

### 当前限制

<Warning>
  **覆盖范围有限**。目前只支持一批热门 ETF（如 `SPY`、`QQQ`、`VTI`、`SOXX`、`ARKK`）。不支持的 ticker 会返回 `coverage_status="unsupported"`，不会静默返回空结果。我们**还不**覆盖整个美国 ETF 市场。
</Warning>

<Warning>
  **这是公开申报数据，不是每日持仓**。持仓和分布来自 SEC 公开数据集，通常会比真实持仓晚几十天到约 60 天。`as_of_date` 是申报报告日，**不是“今天的持仓”**。
</Warning>

<Warning>
  **`IBIT` / `DRAM` 当前暂不支持**。`IBIT` 是现货 BTC trust，披露路径和当前支持的传统 ETF 不一样；`DRAM` 当前不在覆盖范围。两者都会返回 `coverage_status="unsupported"`。
</Warning>

<Warning>
  **仅使用监管披露**。基金公司的 fact-sheet PDF 暂不用于这个接口，所以 `expense_ratio` / `aum` / `nav` / `market_price` / `premium_discount_pct` 可能为 `null`。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // 按日期回看 —— 取 2025-10-01 当天或以前最近一份申报
    {
      "method": "tools/call",
      "params": {
        "name": "etf_lookup",
        "arguments": { "ticker": "VTI", "as_of": "2025-10-01" }
      }
    }

    // 不支持的 ticker —— 200 OK，coverage_status="unsupported"
    {
      "method": "tools/call",
      "params": {
        "name": "etf_lookup",
        "arguments": { "ticker": "IBIT" }
      }
    }
    ```

    ```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/lookup",
        headers=headers,
        params={"ticker": "VTI", "as_of": "2025-10-01"},
    ).json()
    d = resp["data"]
    if d["coverage_status"] == "unsupported":
        print(f"暂不支持: {d['coverage_notice']}")
    else:
        print(f"{d['ticker']} · {d['fund_name']} · {d['holdings_count']} 条持仓 · "
              f"申报日 {d['as_of_date']} (stale={d['stale']})")
    ```

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

## 完整参数参考

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

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

## 相关接口

<Columns cols={3}>
  <Card title="ETF 持仓明细" icon="layer-group" href="/zh-CN/api/etf/holdings">
    单只 ETF 的完整持仓表，按权重从高到低返回。
  </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>