研究、合规与风险
面向 AI Agent 的 SEC 申报 API
解析 CIK、获取申报与 XBRL 事实、验证来源，并返回有原始证据的 Agent 答案。
精选 Provider 与官方来源
生产使用前，请核对接口覆盖、字段、时效、权限与许可。
SEC EDGAR
Decision brief
TL;DR
用 Submissions 确认 Filing 身份
先把公司解析为补足 10 位的 CIK，再用 Submissions API 获取 Form、Accession、Filing Date、Report Date、Primary Document 和历史记录。
用 Archives 获取原始文档
Filing HTML、Exhibit 与完整 Submission 文件包含叙述性披露，也是 Agent 应引用的主要证据。
用 XBRL API 获取标准化数值
Company Facts、Company Concept 与 Frames 便于查询数值，但必须保留单位、期间、Form 与 Taxonomy 上下文。
事实与推断分离
随抽取证据返回 Accession、Form、日期、Source URL 和 Document Hash；摘要、比较和风险判断必须标为模型推断。
适用对象与前置准备
适用于构建 Filing 研究、风险因素比较、事件监控、财报准备、财务抽取或合规助手的团队。默认你拥有可信后端、持久化存储、HTML/XBRL Parser 以及检索或引用层。
身份：User-Agent 所需的应用名称与联系邮箱
存储：原始响应、标准化记录、内容 Hash
解析：HTML、Inline XBRL、表格和 Exhibit
Agent 契约：引用、不确定性、禁止无依据结论
SEC EDGAR 数据源：选择正确接口
| 数据源 | 适合用途 | 关键字段 | 主要限制 |
|---|---|---|---|
| company_tickers.json | Ticker/公司名到 CIK | cik_str, ticker, title | 仍需验证实体匹配 |
| Submissions API | Filing 历史与元数据 | form, accession, filed, reportDate, primaryDocument | 近期记录为列式结构，旧记录可能在附加文件 |
| Archives | 原始文档、Exhibit、完整 Submission | HTML, text, XML, XBRL artifacts | 解析方式因 Filing 与年代而异 |
| Company Facts | 一次获取公司标准化 Concepts | taxonomy, tag, label, units, facts | 不能替代叙述性披露 |
| Company Concept | 跨 Filing 查询单一 Concept | units, val, accn, fy, fp, form, filed, frame | 自定义 Concept 可能不可比 |
| Frames | 按日历 Frame 跨公司比较 | taxonomy, tag, unit, period, entity facts | 财年日历不一定完全对齐 |
不要混淆：data.sec.gov 的公开数据读取接口，与用于提交 Filing 和管理 Filer Account 的 EDGAR Next API 并不是一回事。
证据优先的 Filing Agent 架构
采集、标准化、检索和生成应分层。URL、Accession、日期与单位必须由确定性服务产生，而不是让模型猜测。
RESOLVE CIK
FETCH METADATA
GET DOCUMENT
PARSE + CHUNK
VALIDATE
ANSWER + CITE
- 采集层：礼貌 HTTP Client、缓存、重试、条件请求，并在适合时使用 Bulk Download。
- 原始证据库：原始字节、响应 Header、检索时间、Source URL 与 SHA-256 Hash。
- 标准化 Filing 记录：CIK、Accession、Form、Filing Date、Report Date、Primary Document 和 Amendment 关系。
- 文档层：清洗后的 Section、表格、Exhibit、Inline XBRL，以及返回源文档的字符位置。
- Agent 层：检索过滤、受控 Context、引用、推断标签，并在证据不足时拒绝作答。
步骤一：解析 Ticker、公司名称与 CIK
EDGAR 以 CIK 而不是 Ticker 组织。先标准化 Ticker，与 SEC 映射匹配，核对 Legal Entity 与 Exchange，并保存补足 10 位的 CIK。不要永久复用映射，因为 Ticker 和公司身份可能变化。
Python · ticker to CIK
import requests
HEADERS = {"User-Agent": "FilingAgent/1.0 research@example.com"}
rows = requests.get(
"https://www.sec.gov/files/company_tickers.json",
headers=HEADERS,
timeout=20,
).json().values()
def resolve_ticker(symbol: str):
symbol = symbol.upper().strip()
row = next(x for x in rows if x["ticker"].upper() == symbol)
return {
"ticker": row["ticker"],
"company": row["title"],
"cik": str(row["cik_str"]).zfill(10),
}步骤二：查询 Submissions 并选择 Filing
近期 Filing 数组是列式结构：相同 Index 的值属于同一条 Filing。只 Zip 已知列，按 Form 与 Filing Date 过滤，同时保留 Filing Date 和 Report Date。Amendment 应显式处理，不要简单丢弃所有 /A。
Python · normalize recent filings
def recent_filings(cik: str):
url = f"https://data.sec.gov/submissions/CIK{cik}.json"
payload = requests.get(url, headers=HEADERS, timeout=20).json()
recent = payload["filings"]["recent"]
keys = ["accessionNumber", "filingDate", "reportDate",
"form", "primaryDocument", "primaryDocDescription"]
return [dict(zip(keys, values)) for values in zip(*(recent[k] for k in keys))]
filing = next(
f for f in recent_filings("0000320193")
if f["form"] in {"10-K", "10-Q", "8-K"}
)步骤三：重建并保存 Filing Document URL
Accession Number 唯一标识一条已接受 Submission。只在 Archives 目录路径中移除横线，引用时保留原始 Accession，再与整数 CIK 和 Primary Document 文件名组合。解析前先保存 URL，确保每段抽取内容都能回到精确文档。
Python · SEC Archives URL
def filing_url(cik: str, filing: dict) -> str:
cik_integer = str(int(cik))
accession_path = filing["accessionNumber"].replace("-", "")
document = filing["primaryDocument"]
return (
"https://www.sec.gov/Archives/edgar/data/"
f"{cik_integer}/{accession_path}/{document}"
)
source_url = filing_url("0000320193", filing)步骤四：使用 XBRL Facts，但不丢失上下文
单独一个数值没有意义。必须保留 Taxonomy、Concept、Unit、Start/End 或 Instant Date、Fiscal Year、Fiscal Period、Form、Filed Date、Accession、Frame，以及该 Fact 是否后来被重复披露或修订。优先使用可比的标准 Taxonomy Fact；遇到自定义 Extension 与叙述上下文时回到 Filing 文档。
Python · inspect Company Facts
facts_url = "https://data.sec.gov/api/xbrl/companyfacts/CIK0000320193.json"
company_facts = requests.get(facts_url, headers=HEADERS, timeout=20).json()
revenue = company_facts["facts"]["us-gaap"]["RevenueFromContractWithCustomerExcludingAssessedTax"]
usd_facts = revenue["units"]["USD"]
annual = [x for x in usd_facts if x.get("form") == "10-K" and x.get("fp") == "FY"]
for fact in annual[-3:]:
print(fact["val"], fact["fy"], fact["filed"], fact["accn"], fact.get("frame"))端到端实施模式
在证据包完成前，生产链路应保持确定性。模型可以判断研究意图或需要的 Section，但实体解析、Filing 选择、URL 构造、解析、Hash 与验证必须由代码完成。
| 阶段 | 确定性服务 | 模型角色 | 保存证据 |
|---|---|---|---|
| Resolve | Ticker/名称到 CIK | 澄清歧义实体 | CIK, company, mapping timestamp |
| Select | Form/日期/Accession 过滤 | 把用户意图转为过滤条件 | form, filed, report date, accession |
| Acquire | HTTP 获取、缓存、Hash | 无 | URL, bytes, headers, retrievedAt, hash |
| Parse | DOM/XBRL/Table Parser | 可选 Section 分类 | section, offsets, tables, concepts |
| Answer | 引用生成与策略检查 | 总结、比较、解释不确定性 | claims, evidence IDs, prompt/model version |
统一 Filing Evidence Contract
JSON · evidence bundle
{
"entity": {"cik":"0000320193","ticker":"AAPL","name":"Apple Inc."},
"filing": {
"form":"10-K","accession":"0000320193-25-000079",
"filed":"2025-10-31","report_date":"2025-09-27",
"primary_document":"aapl-20250927.htm","source_url":"https://www.sec.gov/..."
},
"evidence": [{
"section":"Risk Factors","text":"bounded extracted passage",
"source_url":"https://www.sec.gov/...","document_sha256":"...",
"retrieved_at":"2026-07-31T09:00:00Z"
}],
"answer_policy": {"cite_every_claim":true,"label_inference":true}
}即使应用使用标准化字段名，也应在 Source Payload 或 Provenance Record 中保留 SEC 原始字段。这样才能审计和升级 Parser，而不必重新下载全部数据。
Agent 回答前的验证清单
实体：确认 CIK、Legal Name 与 Ticker 映射
身份：Accession 和 Primary Document 与 Submissions 一致
日期：不混淆 Filing Date 与 Report Period
Form：显式处理 Amendment、Exhibit 与 Form Family
Facts：保留 Taxonomy、Unit、Duration/Instant 与 Frame
文档：Source URL 可访问并保存 Content Hash
结论：每个重要陈述都映射到证据
推断：分析有明确标签并显示不确定性
Fair Access、缓存、成本与延迟控制
SEC 当前指南把自动访问限制在总计不超过每秒 10 个请求，并要求应用声明身份。10 是上限，不是目标。使用可识别的 User-Agent；缓存不可变 Filing 文档；大规模回填优先使用 Bulk ZIP；限制并发；对 403、429 与临时 5xx 使用指数退避。
- 短期缓存 Ticker Mapping 和 Submissions；按 Content Hash 长期缓存 Accession 文档。
- 轮询 Filing Metadata，不要反复下载相同完整文档。
- 完整历史回填使用每日 Bulk Archive，避免数百万次单独请求。
- 设置连接/读取超时、重试预算、熔断和 Dead-Letter Queue。
- 限制发送给模型的 Chunk、表格、Exhibit 与 XBRL Fact，控制 Token 成本和 Prompt Injection 暴露。
常见失败模式与排错
| 现象 | 常见原因 | 修复 |
|---|---|---|
| 403 或访问被阻止 | 缺少 User-Agent、请求过多或突发 | 声明应用、全局限流、缓存并退避 |
| 匹配到错误公司 | Ticker 复用、Symbol 标准化、名称歧义 | 检索前确认 CIK 与 Legal Entity |
| 缺少较旧 Filing | 只读取了 Recent 列式数据 | 继续读取附加文件或导入 submissions.zip |
| Revenue 数值不一致 | Unit、Period、Form、Concept 或 Amendment 不同 | 比较完整 XBRL 上下文与 Accession |
| Risk Section 抽取为空 | Heading 变化、Inline XBRL Markup、文档年代 | 使用 DOM-aware 解析、Form 模板与文本回退 |
| Agent 引用了错误期间 | Filing Date、Report Date 或 Fiscal Frame 混淆 | 在检索和回答模板中保留所有日期 |
如何评估 Filing-Aware AI Agent
检索与证据要和写作质量分开评估。即使语言流畅，只要 Accession 或期间错误，仍然是失败答案。
实体准确：CIK 与 Filer 正确
Filing 准确：Form、Accession、Amendment、日期正确
检索召回：找到相关 Section、Exhibit 与 Fact
引用精度：引用段落确实支持结论
数值完整：Value、Unit、Period、Concept 保持一致
推断纪律：区分事实、计算与观点
QVeris Filing Research 实现模式
基于 QVeris 的 Agent 可以按意图 Discover Filing 或金融能力，Inspect 参数与运维统计，在执行前 Probe 候选输入与报价，再 Call 选定能力。应用记录中仍应保存 SEC Accession、Source URL、Filing Date 与抽取证据；SEC 文档始终是 SEC Filing 结论的权威来源。
推荐循环：Discover → Inspect → Probe → Call → 验证 Accession/Source → 带引用回答 → 核对 Usage History。
继续阅读 QVeris MCP 文档、QVeris REST API 参考、SEC Filing Analysis Agent 指南与 SEC Filing API 对比。
FAQ
SEC EDGAR API 需要 Key 吗？
公开的 data.sec.gov Submissions 与 XBRL API 不需要 Key，但自动访问仍需声明应用身份并遵守 SEC Fair Access。
Submissions 与 Company Facts 有何区别？
Submissions 提供 Filing 身份与历史；Company Facts 提供跨 Filing 的标准化 XBRL Concept 与 Unit。
如何构造 Filing URL？
先把 Ticker 解析到 CIK，从 Submissions 选择 Accession 与 Primary Document，在 Archives 路径中移除 Accession 横线，同时保留原始 Accession 用于引用。
请求速率应该是多少？
SEC 当前指南把总请求上限设为每秒 10 次。实际应低于上限运行、积极缓存并在错误时退避。
可以只依赖 Company Facts 吗？
不可以。数值 Fact 不能替代叙述性披露、Exhibit、自定义 Taxonomy 上下文和原始 Filing。
Amendment 怎么处理？
保留 Form、Accession、日期、Amendment 状态和原始来源，不能静默覆盖原 Filing。
如何降低幻觉？
强制使用 Accession 关联证据、校验日期和单位、引用受控段落，并标记所有模型推断。
QVeris 位于哪里？
QVeris 帮助发现、检查、Probe 和调用相关能力；SEC 文档仍是 Filing 结论的权威来源。