白板流程图：SPY 或 QQQ 代码请求转换为标准化 ETF 持仓 JSON，供应用或 Agent 使用

免费 ETF 持仓 API 能提供什么

核心任务

先把 ETF 准确解析到基金与份额类别，再获取特定持仓日期对应的完整组合，而不是只取第一页或前几大持仓。

常见响应

实用 JSON 应包含稳定成分标识、名称、资产类型、权重、数量、市值、币种、国家、行业和组合日期，并保留现金与衍生品。

核对“免费”边界

区分长期免费套餐与限时试用，并检查额度、接口权限、署名、缓存和商业使用许可。

持仓具有时间点

组合日期、来源发布日期、供应商处理时间和抓取时间应分别保存；后续更正必须形成修订版本，不能无声覆盖原快照。

ETF 持仓数据接口的字段与时效

实用的 ETF 持仓 API 应提供完整成分股、持仓权重、股数、市值、行业分布、标识符、分页信息和历史快照。“最新”不一定代表实时数据，因此响应必须明确标注该份持仓对应的日期。

完整性还取决于基金结构。股票代码可能只是组合的一部分，债券标识、期货、掉期、期权、抵押品、应收应付和现金都会影响实际敞口与权重合计。应保留供应商的资产类型标签，并区分基金直接报告的头寸与通过其他基金或衍生品推导出的穿透敞口。

完整成分股与前十大持仓

部分免费接口只返回前十大持仓，即使基金实际包含数百或数千项资产。应核对持仓总数、分页方式、单页上限、现金与衍生品记录，以及权重的计算口径是否符合供应商说明。

历史 ETF 持仓 API 快照

进行回测时，应使用同时包含持仓日期、申报日期或处理日期的时点快照，以减少前视偏差并识别后续修订。历史持仓功能往往需要更高等级的套餐。

权重核对与重合度分析

计算集中度或重合度前，应对齐组合日期，统一百分比与小数单位，用稳定 ID 映射证券，并明确现金、衍生品、空头头寸和基金中基金记录的处理方式。权重合计因合理原因可能不等于 100%，但残差需要解释，不能一律自动缩放。

免费 ETF 持仓数据可以从哪里获取

没有一种来源适合所有 ETF 场景。发行人文件通常最接近基金当前组合，聚合 API 则更便于跨发行人使用统一结构；监管数据适合建立可追溯的历史记录，但遵循披露周期，并非每日持仓源。应先明确产品需要支持什么决策，再选择数据来源。

数据来源	适用场景	使用前核对
发行人持仓文件	查询指定 ETF 的当前持仓、每日监控与单一发行人研究。	是否为完整组合、持仓日期、文件地址稳定性、使用条款，以及现金和衍生品的表示方式。
Alpha Vantage ETF Profile	以统一 API 响应获取受支持 ETF 的概况与持仓。	基金覆盖范围、返回的持仓深度、更新日期、当前免费额度及商业使用权限。
Financial Modeling Prep ETF 持仓	希望在同一供应商接口中结合行情、基本面与 ETF 持仓的开发者。	当前套餐是否开放接口、分页、字段、历史深度、限流与再分发权限。
SEC Form N-PORT 数据集	可审计的美国注册基金研究与历史验证。	报告期与公开日期、系列和份额类别映射、修订申报以及披露滞后。

不要混淆实际持仓、申赎篮子与指数成分

实际持仓表示基金在指定日期持有的资产；申购或赎回篮子表示授权参与商为一个创设单位交付或收取的证券与现金，它可能不是完整组合；指数成分反映基准指数的规则与成员，并不等于基金当日的精确头寸。抽样复制、现金管理、衍生品、费用、公司行动和调仓时点都会造成差异。

实用判断：如果产品要回答“这只 ETF 持有什么”，应使用带明确日期的实际持仓。申赎业务使用篮子数据，指数研究使用基准成分。把三者混用，可能生成看似合理、实际错误的敞口和重合度结果。

实例：避免前十大持仓偏差的 ETF 重合度计算

假设 ETF A 与 ETF B 的前十大持仓中有六只相同证券，这并不能证明整体重合度很高：A 可能持有 500 项资产，B 只有 100 项，而且共同证券的权重可能相差很大。应取得同一持仓日期的完整组合，用稳定标识匹配证券，并对每个共同持仓计算 min(weight_A, weight_B) 后求和。同时列出被排除的现金、无法匹配的衍生品、缺失标识和两边的权重残差。

按使用场景选择方案

展示单只 ETF

优先使用发行人文件，或选择能明确给出持仓日期的供应商，并在持仓旁展示日期与覆盖范围。

ETF 对比工具

必须取得完整列表、稳定标识和一致的资产类型，对齐日期，并公开重合度计算公式。

时点回测

除持仓日期外，还要保存公开时间与修订记录；监管历史数据可用于验证当时可知的信息。

Agent 工作流

除标准化记录外，还应返回来源、完整性、残差和警告，使 Agent 能对答案附加必要条件。

如何评估免费 ETF 成分股 API

检查项	需要核对	重要原因
覆盖范围	覆盖的市场、存续与退市 ETF，以及代码和标识符查询。	避免出现未提示的数据缺口。
完整性	完整列表、总数、分页、现金、衍生品与权重口径。	仅前十大持仓不足以分析重合度和暴露。
数据时效	持仓日期、申报日期、处理日期、更新频率与修订规则。	避免把过期数据误当作当前持仓。
字段	代码、CUSIP/ISIN、名称、权重、股数、市值、行业、国家。	支持关联与标准化。
免费限制	额度、限流、历史、许可、署名与缓存。	试用未必适合生产环境。
资产类型	股票、债券、现金、衍生品、抵押品与空头头寸。	只返回股票代码会严重低估敞口。
修订模型	发布时间、处理时间、更正标识与版本历史。	使历史快照变化可以审计。
权重质量	单位、正负号、残差、重复项与基金中基金处理。	决定集中度与重合度计算是否可靠。

接入返回 JSON 的 ETF 持仓 REST API

步骤 1：按代码测试 SPY 与 QQQ 持仓

如果接口要求鉴权，先申请免费 API 密钥，再按文档调用接口，并检查 HTTP 状态码、鉴权结果、限流响应头、持仓总数、分页信息和实际持仓日期。

步骤 2：标准化 ETF 成分股字段

将供应商字段映射到稳定的内部数据模型，例如 fund_ticker、as_of_date、holding_ticker、name、weight、shares、market_value 和 identifiers，同时保留原始响应，便于审计和排查问题。

步骤 3：验证完整性与变更处理

遍历全部分页，核对返回条数与元数据，测试无效代码和限流场景，并在接口结构发生变化时触发告警。按持仓日期分别保存快照，不要覆盖上一期数据。

步骤 4：核对权重与资产类型

在保留原始值的前提下统一单位，用稳定 ID 检查重复项，并分别计算多头、空头、现金、衍生品和未解释残差。符号或标识不明确的记录应隔离复核，不要强行计入股票敞口。

步骤 5：建立可识别修订的快照

用基金 ID、份额类别、组合日期、来源发布时间和供应商修订号共同确定快照。收到更正文件时应保留新旧版本并记录差异，使回测只能选择模拟时点当时已经可用的版本。

用 QVeris 查找 ETF 持仓数据能力

QVeris 帮助开发者与 Agent 发现、检查并调用可用的金融数据能力。打开 QVeris 服务商详情，查看 ETF 持仓数据供应商、检查输入输出，并在接入前核对服务条款和接口约定。

明确搜索完整持仓、历史持仓或成分股能力；价格与概况 API 不一定包含它们。
调用前检查基金标识、资产类型、组合与发布日期、分页、修订行为、限制和许可。
要求输出完整性报告，包括返回行数、供应商总数、各资产类型权重、残差与缺失标识。
将供应商特定解析与更正逻辑放在标准化、可识别修订的应用接口之后。

FAQ

免费 ETF API 能返回完整成分股吗？

部分供应商提供免费套餐、试用或免费接口，但要确认免费范围确实包含持仓，而不只是价格或基金概况，并核对额度和许可。

如何获取 SPY 或 QQQ 的完整持仓？

按 ETF 代码调用持仓接口并遍历全部分页，直到返回数量与元数据一致。不要把第一页或前十大持仓当成完整列表。

免费 ETF 持仓 API 包含历史数据吗？

有些接口包含历史数据，但可查询的时间范围通常有限，也可能需要单独付费。应检查快照日期、退市基金覆盖范围、修订记录和时点定义。

ETF 持仓 API 应返回哪些字段？

实用字段包括基金代码、数据日期、成分股代码与名称、权重、股数、市值、标识符、行业、国家和来源元数据。

ETF 持仓 API 的数据多久更新一次？

更新频率取决于基金和来源。发行人文件可能每日更新，监管披露通常更慢，应以响应中的数据日期为准。

QVeris 能保证供应商永久免费吗？

不能。QVeris 可帮助发现和检查能力，但可用性、价格、限制和许可仍由供应商控制，并可能变化。

为什么 ETF 持仓权重合计不等于 100%？

现金、衍生品、空头、应计项目、四舍五入、杠杆或不完整覆盖都可能形成残差。重新缩放或判为错误前，应先检查资产类型和供应商权重口径。

怎样比较两只 ETF 的持仓？

先对齐组合日期，用稳定 ID 映射证券并统一权重，再明确现金、衍生品和穿透规则，然后计算共同权重或其他公开说明的重合指标。

持仓日期与发布日期有什么区别？

持仓日期说明快照代表哪一天的组合，发布日期说明该快照何时对外可得。回测必须同时使用两者，避免提前使用尚不可知的持仓。

权威参考与下一步

SEC Form N-PORT datasets Alpha Vantage documentation Financial Modeling Prep documentation Intrinio ETF Holdings API documentation QVeris documentation