面向 AI Agent 的最佳 SEC 申报 API

要点速览：按工作流选，不要按品牌选

这份指南适合谁

本文适合构建研究 Copilot、事件监控 Agent、财报工作流、合规审阅或检索系统的工程师，尤其是输出必须附带第一方证据的场景。你需要具备 HTTPS 请求、标准化 JSON 存储以及定时任务或队列的基础能力。

AI Agent 真正需要 Filing API 提供什么

“能返回 10-K”并不是完整需求。生产级 Agent 必须确认发行人身份，区分提交日期与报告期，保留修订版本，获取主文件和附件，并证明每条结论来自哪份原始材料。

• 身份：以 CIK 作为稳定 SEC 主键，Ticker 和法定名称作为别名。
• 发现：按表单、发行人、提交日期、报告期和修订状态过滤。
• 文档：主 HTML/TXT、Filing Index、附件、Inline XBRL 及其他提交材料。
• 证据：Accession Number、规范来源 URL、抓取时间、内容哈希和引用章节。
• 运维：明确的限额、重试、缓存、历史回补和可预测的错误行为。

SEC 文件 API 对比

不要只看功能表。应把相同的 25–50 份文件交给每个候选供应商测试：近期与历史 10-K、10-Q、带附件的 8-K、修订文件、公司更名、Ticker 变更，以及至少一份含自定义 Taxonomy Fact 的文件。

供应商详解：各自真正擅长什么

带来源证据的 Filing Agent 参考架构

分步实现：从 EDGAR 获取最新 10-K

SEC Submissions API 是很好的基线，因为它迫使工作流保留第一方标识。请使用包含组织与联系方式的可识别 User-Agent，缓存响应，并低于 SEC 公布的公平访问上限。

curl --compressed \
  -H "User-Agent: ResearchAgent/1.0 contact@example.com" \
  -H "Accept-Encoding: gzip, deflate" \
  "https://data.sec.gov/submissions/CIK0000320193.json"

import hashlib
import requests
from datetime import datetime, timezone

CIK = "0000320193"
HEADERS = {
    "User-Agent": "ResearchAgent/1.0 contact@example.com",
    "Accept-Encoding": "gzip, deflate",
}

submissions_url = f"https://data.sec.gov/submissions/CIK{CIK}.json"
data = requests.get(submissions_url, headers=HEADERS, timeout=30)
data.raise_for_status()
payload = data.json()
recent = payload["filings"]["recent"]

rows = [dict(zip(recent, values)) for values in zip(*recent.values())]
filing = next(row for row in rows if row["form"] == "10-K")

accession = filing["accessionNumber"]
accession_path = accession.replace("-", "")
cik_path = str(int(CIK))
primary = filing["primaryDocument"]
source_url = (
    f"https://www.sec.gov/Archives/edgar/data/"
    f"{cik_path}/{accession_path}/{primary}"
)

document = requests.get(source_url, headers=HEADERS, timeout=30)
document.raise_for_status()

evidence = {
    "cik": CIK,
    "accessionNumber": accession,
    "form": filing["form"],
    "filingDate": filing["filingDate"],
    "reportDate": filing["reportDate"],
    "primaryDocument": primary,
    "sourceUrl": source_url,
    "retrievedAt": datetime.now(timezone.utc).isoformat(),
    "sha256": hashlib.sha256(document.content).hexdigest(),
}

示例刻意只选择精确的 10-K。如果工作流需要包含修订文件，应将 10-K/A 建模为独立版本，并定义它如何影响此前结论。

在调用模型前先定义证据契约

先明确不同 Filing 回答什么问题

Agent 回答前的验证清单

• CIK 对应目标法定实体，而不只是匹配了 Ticker 字符串。
• Accession Number 格式正确，并能解析到 Filing Index 或主文档。
• Form 策略明确包含或排除修订文件。
• 提交日期、报告期、接收时间和财政期间没有混为一谈。
• 所需附件已经获取，并关联到父 Filing。
• XBRL Facts 的 Taxonomy、单位、时长或时点、维度和期间一致。
• 每条生成结论都有来源 URL 和精确证据位置。
• 存储的哈希和抓取时间能让输入被复现。

安全、成本与延迟控制

SEC 当前要求自动化用户总计不超过每秒 10 次请求，并可能阻止过量或无法识别的 Bot。应把这个数字当作上限而非目标。使用共享限流器、可识别 User-Agent、缓存、指数退避、抖动，并在大规模历史回补时使用 Bulk Archive。

常见失败模式与修复方式

新闻、电话会与行情是辅助层，不是 Filing API

新闻 API 用于解释市场反应，财报电话会文本补充管理层表达，价格与成交量用于衡量响应。但它们都不能替代已提交文件、Accession Number、修订历史或 SEC 来源 URL。应先获取 Filing，再按发行人身份和事件时间连接这些数据集。

QVeris 实现模式：Discover → Inspect → Call

在 Agent 系统中，QVeris 可以位于各供应商端点之上，承担发现与路由。Agent 先发现候选 SEC 工具，再检查输入 Schema 与供应商元数据，最后用受控参数调用所选工具。返回的证据对象仍应注明底层供应商，并保留原始 SEC 来源。

常见问题

官方资料与下一步

供应商功能与访问规则可能变化。生产使用前，请核对最新文档、权限和条款。