AgentFilings

AgentFilings

面向 AI Agent 的结构化美国 SEC/EDGAR 申报数据——申报索引、从 XBRL 派生的收益数据，以及 Form 4 内部人交易，均以简洁 JSON 格式通过 HTTP 和 MCP 提供。

按调用付费，使用 x402（Base 主网 USDC，无需账户）。项目在 apps/api/src/billing/ 中实现了统一的 Stripe 订阅支付方式——API 密钥签发、订阅门控、结账和 webhook——但尚未在正式部署中启用。

服务地址：api.agentfilings.com · OpenAPI · llms.txt · MCP 地址为 https://api.agentfilings.com/mcp，已在官方 MCP 注册表中登记为 com.agentfilings/mcp，并提供 MCP 服务卡片、 AI 目录 和用于发现的 x402 清单。

# Free. Tells you what data exists before you spend anything.
curl "https://api.agentfilings.com/probe?ticker=AAPL"

这里真正有意思的地方

大部分工作都集中在三件容易被 SEC 数据坑到的事，以及一件容易被 Agent 支付坑到的事上。

重述数据。 companyfacts 会为每份报告了该期间数据的申报各返回一次该期间。当公司重述某项数据时，被取代的值仍会留在 API 中。这里的每个期间都会采用最新申报的值进行校准，而不是使用最先遇到的值。

财年期间的来源。 某项事实中的 fy/fp 字段描述的是申报，而不是期间。10-Q 若将上一年的季度列为比较数据，就会用较新申报的财年来标记这个较早的期间。这里的每个期间都会保留最初报告该期间数据的申报中的标签。benchmark/ 提供了可运行的测量，用于统计这些标签不一致的频率。

实体身份。 SEC 的股票代码映射可能指向一家重组后的空壳公司，该公司持有股票代码，却不申报任何财务数据。实体解析以 CIK 为准，并设有保护机制：如果某实体没有报告 us-gaap 事实，就不会记录其覆盖情况。

支付重放。 每份 x402 支付凭证都绑定到其所支付的特定资源，因此，为某个端点或 MCP 工具签发的凭证不能重放到另一个端点或工具。结算具有幂等性，EIP-712 域会从 USDC 合约按网络读取，而非硬编码。

真实覆盖情况

/probe 免费，并会告诉你不要付费：

{
  "ticker_coverage": {
    "covered": true,
    "endpoints_with_data": ["/filings/latest", "/earnings/summary"],
    "empty_endpoints": ["/insiders"],
    "hint": "Partial coverage. /filings/latest and /earnings/summary will return data. /insiders would return an empty result, so do not pay for those."
  }
}

公司可能有申报数据覆盖，却没有收益数据——例如按 IFRS 申报的外国发行人或尚未产生收入的公司。对一个返回空结果的调用收费，是让自动化买家永久流失最快的方式，因此服务会在收款前说明这一点。

目录结构

apps/api/          TypeScript / Hono — HTTP API + MCP server
  src/payments/    x402 v2: routes config, replay guard, idempotency, discovery
  src/billing/     Stripe rail: key issuance, subscription gate, checkout, webhook
  src/mcp/         MCP over streamable HTTP, paid tools
  src/repo/        Corpus access (Postgres in prod, local JSON in tests)
apps/ingest/       Python 3.12 — SEC ingestion, XBRL + Form 4 parsers
packages/shared/   Pricing table, x402 constants, response types
infra/migrations/  SQL schema
benchmark/         Standalone, runnable SEC XBRL correctness measurement
tests/             Cross-cutting, including the payment-security spec

packages/shared/src/pricing.ts 是 API 接口的唯一事实来源。支付中间件、/probe、MCP 工具列表和 OpenAPI 文档都由它生成。

开发

pnpm install
pnpm test        # vitest — api + shared
pnpm typecheck
pnpm lint
pnpm dev         # http://localhost:8080

curl localhost:8080/health
curl "localhost:8080/probe?ticker=AAPL"

默认情况下，支付功能处于关闭状态，因此开发环境中的付费路由会开放提供。数据摄取需要 SEC_CONTACT_EMAIL——SEC 要求在 User-Agent 中提供联系人，并会拦截缺少该信息的请求。请参阅 .env.example 和 infra/DEPLOY.md。

原则

• 免费服务如实告知。 /health 和 /probe 始终免费，且 /probe 绝不会夸大覆盖情况。
• 不为无法提供的内容收费。 未实现的端点绝不会启用支付门控——否则中间件会先收款，然后返回 404。
• 仅限公有领域数据。 SEC EDGAR。没有授权数据集，也没有抓取的文字稿。
• 仅作为商户。 服务绝不持有、路由或转发第三方资金。

许可证

MIT。数据来自 SEC EDGAR，属于公有领域。