选择适合公募基金与 ETF 的
免费基金持仓 API
免费基金持仓 API 可以支持原型开发，但必须具备合适的覆盖范围、
明确日期、清晰许可和可验证的 JSON 数据。
免费基金持仓 API：快速结论
根据分析任务匹配基金类型、完整或重仓持仓、资产类别明细、历史深度、修订、配额与许可。
核对法律基金与份额 ID、组合与发布日期、分页、资产类型、币种、正负号、权重和完整性。
保存原始与规范化记录、来源申报、首次可知日期、修订 ID、解析版本、抓取日志和提供方条款。
基金持仓 API 必须覆盖什么
评估时应从一只真实基金、一个明确的组合日期和一个具体产品场景开始。选择接口需要检查公募基金与 ETF 覆盖、法律标识符、持仓日期、权重、历史数据、分页、调用限制、JSON 质量和再使用条款。只有当返回范围与产品需要解释的数据一致时，免费额度才真正有价值。
“持仓”可能指披露证券头寸、衍生品敞口、抵押品、现金、应收应付，或从另一只基金推导出的穿透头寸。实用接口应把直接报告记录与衍生敞口分开，明确法律份额类别，并说明响应属于完整组合、监管申报、重仓子集还是供应商重建结果。
比较免费公募基金与 ETF 持仓 API
| 来源类型 | 适合场景 | 使用前检查 |
|---|---|---|
| 公开申报 | 直接出处和自建数据库。 | 覆盖、解析、修订、披露滞后和发行人 ID。 |
| 免费层 REST API | 需要标准 JSON 的原型。 | 配额、完整或重仓持仓、历史范围与再使用。 |
| 基金公司或交易所数据 | 特定基金系列或市场的官方明细。 | 地址稳定性、格式、更新日程和标准化。 |
| 监管申报转换 | 带直接申报出处的时点历史。 | 表单范围、修订、保密或省略记录、分类体系与披露滞后。 |
| 穿透分析 | 跨基金、衍生品或嵌套载体的敞口与重合。 | 方法、重复计算、日期、代理映射与衍生数据许可。 |
可实际评估的数据路线
这些路线解决的问题不同：监管数据更强调出处和历史，标准化 API 更强调接入效率，基金公司文件则适合获取特定基金系列的最新官方明细。不能只按请求额度给它们排名。
| 路线 | 可以获得 | 更适合 | 主要限制 |
|---|---|---|---|
| SEC Form N‑PORT 数据 | 注册投资公司申报的结构化组合信息，带直接申报出处和报告期背景。 | 构建美国基金研究数据库、审计链路或时点一致的历史数据管道。 | 披露与公开存在滞后，还要处理修订、复杂工具、表单分类和较重的标准化工程。 |
| Alpha Vantage ETF Profile | 通过常见 API 请求方式返回 ETF 概况及持仓相关数据。 | 希望快速获得规范 JSON、暂时不想自建申报解析器的 ETF 原型。 | 必须核实持仓深度、组合日期、市场覆盖、端点权限、更新频率以及是否提供历史记录。 |
| Financial Modeling Prep ETF 持仓 | 在更广泛的金融数据 API 体系中提供规范化 ETF 成分或持仓记录。 | 已经使用同一供应商的价格、概况或基本面接口，希望保持统一数据结构的应用。 | 核实当前端点与套餐、完整或部分持仓、日期、标识符、分页和再分发条款。 |
| 基金公司持仓下载 | 特定 ETF 系列的官方 CSV、表格或网页持仓，通常带明确的持仓日期。 | 只覆盖少量基金，并且官方最新明细比广泛覆盖更重要的展示或核对场景。 | 格式和地址可能变化，不同基金公司字段不统一，历史文件、自动化抓取和再分发也可能受限。 |
Form 13F 不能代替基金持仓接口。它披露的是符合条件的机构投资管理人持有的部分头寸，并不是每只公募基金或 ETF 份额类别的完整、最新组合。如果产品声称展示基金自身持仓，应优先使用 N‑PORT、基金公司披露或专门的基金数据服务。
同时评估访问、数据与许可用途
免费层可能限制请求、不提供历史数据、只返回重仓或禁止再分发。应优先检查可靠日期、来源 ID、文档和许可；请求成功并不代表获得再使用权。
优先使用基金公司带日期的官方文件，或能够返回可核验来源与明确持仓日期的规范 API。页面要说明列表是完整组合还是仅重仓，并突出展示组合发布日期，不能把抓取时间误写成“持仓最新日期”。
需要稳定的证券标识、足够完整的组合、同一口径的权重和对齐的日期。计算重合前先统一份额类别与币种，并披露未映射和省略权重，避免一个整洁的百分比掩盖缺失头寸。
使用带申报出处或可识别修订的时点快照，并保存首次可知时间。修订文件不能直接覆盖旧版本，模拟也必须等到数据公开后才能使用。今天重建出来的组合，不能安全地回答六个月前投资者当时知道什么。
结果应包含基金与份额类别身份、持仓范围、组合日期、发布日期、来源、头寸数量、重仓列表、已报告权重合计、残差和许可状态。Agent 必须区分直接披露持仓与穿透估算，并引用摘要背后的带日期来源。
如何接入免费的基金持仓数据 API
1. 明确基金范围与所需字段
明确市场范围、完整或重仓持仓、历史深度、币种、行业和标识符。
2. 检查认证、日期与分页
记录密钥位置、配额响应头、分页、持仓日期、申报日期和时区；抓取时间不能替代组合报告期。
3. 发起小范围请求并检查 JSON
GET /v1/funds/{ticker}/holdings?limit=100 只是 REST 形态示例，并非真实提供方地址。入库前应验证类型、空值、币种、权重、ID 和分页数量。
4. 同时保存原始响应与标准记录
保存原始响应和提供方代码，并标准化 fund_id、security_id、market_value、weight_pct、currency、as_of_date、filing_date 与 source_url。快照键应包含提供方、基金和持仓日期。
5. 核对资产类型与组合合计
分别计算多头、空头、现金、衍生品、负债和未解释残差合计，保留原始正负号与单位，按稳定 ID 和头寸背景去重；债券或衍生品标识含糊时应隔离复核，不能强行归入股票。
6. 建立可识别修订的历史
用基金、份额类别、组合日期、申报或来源发布时间、供应商处理时间和修订号共同确定版本，保留被替代记录与变化原因，使回测只能使用模拟时点已经可得的数据。
分析前验证基金持仓数据
为什么持仓权重不一定恰好等于 100%
重仓接口会省略较小仓位；完整组合也可能受现金、衍生品、负债、舍入、币种或分类影响。权重合计只能作为预警，不能单独证明正确。
组合核对示例：为什么 94% 和 108% 都可能合理
假设某接口把响应称为“持仓”，所有返回记录合计只有 94%。这可能是因为它只列出了主要证券，同时组合中还有 3% 现金、1% 应收项目和 2% 被省略的小额头寸。如果把这 94% 强行缩放到 100%，每只证券的显示权重都会被放大，也会掩盖接口并不完整这一事实。
另一只基金的总敞口可能达到 108%，因为多头证券、期货、互换、空头、现金和负债采用的口径不同。总敞口可以超过净资产，而净敞口仍接近 100%。至少应分别核对四组数据：已报告多头市值、已报告空头市值、现金与其他净资产，以及衍生品名义或 Delta 调整后敞口；只有分母一致的字段才能直接比较。
不要自动“修复”残差。先确认接口属于仅重仓、完整组合、申报转换还是供应商重建，再检查现金、负债、衍生品、空头、省略记录、舍入、汇率转换和权重分母。在原因明确之前，应把残差作为数据质量字段公开保留。
公募基金持仓多久更新一次
更新速度取决于披露和处理流程。应区分持仓、申报与抓取日期；回测需要时点快照和修订历史，以避免前视偏差。
上线前测试边界情况
应测试不同份额类别、缺少代码、衍生品、多币种、修订和空分页，并区分 Schema 变化与网络故障。美国基金结果应与 SEC EDGAR 申报核对。
区分披露持仓与穿透敞口
基金中基金记录属于直接披露持仓，把它展开到底层组合后形成的是衍生敞口。应标注转换过程、对齐两层组合日期、披露未映射权重，并避免父基金与底层头寸同时计入，除非指标明确要求这样做。
QVeris 如何帮助调用基金持仓 API
QVeris 帮助智能体发现并检查能力，但不拥有或认证提供方数据。
- 使用 QVeris 服务商详情发现相关金融数据能力。
- 调用前检查基金与份额身份、完整或重仓范围、资产类型、日期、修订、分页、方法和许可。
- 要求结果包含完整性元数据、各资产类型权重合计、残差、缺失标识，以及披露或衍生标签。
- 保留提供方 URL、原始记录、来源与抓取日期、修订 ID、解析版本、许可和日志。
免费基金持仓 API 常见问题
有免费层或公开申报处理方案，但必须核对覆盖、配额、时效和再使用条款。
部分接口可以；需要确认返回完整组合还是仅前十大持仓，并保留报告期。
基金与证券标识、名称、数量、市值、权重、币种、资产类别、持仓日期、申报日期和来源。
部分提供方支持时点历史，通常不完全包含在免费层中，应检查历史深度和修订处理。
重仓接口只返回最大的若干仓位；完整持仓接口通常覆盖披露组合中的较小仓位，有时还包括现金或衍生品。
这取决于提供方许可和底层来源条款。能够访问 API 并不自动获得再分发或商业展示权。
仅重仓覆盖、现金、衍生品、空头、负债、舍入、币种处理和缺失记录都可能形成残差。重新缩放或判为错误前，应先检查组合口径。
把嵌套基金映射到其对应日期的组合，用父子权重相乘，保留未映射敞口并标记为衍生结果；同时对齐日期，避免载体与展开头寸重复计算。
组合日期、来源申报或发布日期、供应商处理时间、抓取时间和修订时间用途不同。历史研究需要全部重要日期，不能只用一个通用时间戳。