Financial Statements API for AI Agents 面向 AI Agent 的财务报表 API

TL;DR: choose the statement contract before the providerTL;DR：先确定报表契约，再选择供应商

What “financial statements API” searchers actually need搜索“财务报表 API”的人真正需要什么

This query is not asking for a definition of an income statement. The user usually needs to select a source, fetch the three statements, make periods comparable, handle revisions, and produce calculations that can be traced back to a filing. A page that only lists fields or promotes one routing layer leaves the implementation problem unsolved.

这个搜索并不是在询问“什么是利润表”。用户通常需要选择数据源、获取三张报表、对齐期间、处理修订，并让每个计算都能追溯到 Filing。只列字段或只宣传路由层，并没有解决实现问题。

Who this guide is for and what to prepare适用人群与前置条件

This guide is for engineers building equity-research agents, screeners, valuation systems, covenant monitors, portfolio reviews, and source-backed financial copilots. It assumes the workflow needs more than a demo response: it must survive odd fiscal calendars, provider corrections, missing facts, and audit questions.

本指南适合构建股票研究 Agent、选股器、估值系统、契约监控、组合复盘和可追溯金融 Copilot 的工程师。默认目标不是拿到一次 Demo 响应，而是应对特殊财年、供应商修正、字段缺失和审计问题。

• Create a test universe containing a normal issuer, bank, insurer, ADR, non-calendar fiscal year, loss-making company, and recently restated filer.测试集至少包含普通公司、银行、保险公司、ADR、非自然年公司、亏损公司和近期重述公司。
• Define annual, quarterly, YTD, and TTM as separate contracts before fetching data.取数前把年度、季度、YTD 和 TTM 定义为不同契约。
• Store API credentials server-side and record plan entitlements separately from code.API 凭证只放在服务端，并把套餐权限与代码分开记录。
• Decide which source is authoritative when standardized values disagree with a filing.提前确定标准化数值与 Filing 不一致时的权威来源。

Annual, quarterly, TTM, and as-reported are different contracts年度、季度、TTM 与 As-reported 是不同契约

Evaluation criteria for an agent-ready statements APIAgent 可用的财务报表 API 选型标准

• Coverage: issuers, exchanges, active and delisted securities, history depth, banks, insurers, and foreign filers.覆盖：发行人、交易所、在市/退市证券、历史深度、银行、保险和外国发行人。
• Period semantics: fiscal year, fiscal quarter, start/end dates, filing date, accepted date, and discrete versus YTD values.期间语义：财年、财季、起止日、Filing Date、Accepted Date，以及单季/YTD。
• Statement modes: standardized, as-reported, annual, quarterly, TTM, bulk, segments, and restatement history.报表模式：标准化、As-reported、年度、季度、TTM、Bulk、分部与重述历史。
• Evidence: accession number, filing URL, source tag, unit, currency, retrieval time, and revision identity.证据：Accession Number、Filing URL、Source Tag、单位、币种、获取时间与版本身份。
• Operations: rate limits, bulk behavior, correction policy, cache and redistribution rights, status reporting, and support.运维：限额、Bulk 行为、修正策略、缓存和再分发权、状态报告与支持。

Financial statements API providers compared财务报表 API 供应商对比

Choose by workflow, not by feature count按工作流选型，而不是按功能数量选型

A provider-neutral architecture for financial statements供应商中立的财务报表架构

Fetch all three statements and preserve the evidence envelope获取三张报表并保留证据 Envelope

The example uses Financial Datasets because its documented endpoint returns all three statements in one call. The important part is the envelope: use the same pattern for every provider adapter.

下面以 Financial Datasets 为例，因为官方端点可一次返回三张报表。真正重要的是 Evidence Envelope：每个供应商 Adapter 都应使用同样模式。

import hashlib
import json
import os
from datetime import datetime, timezone

import requests

def fetch_statement_bundle(ticker: str, period: str = "annual", limit: int = 8):
    endpoint = "https://api.financialdatasets.ai/financials"
    params = {"ticker": ticker, "period": period, "limit": limit}
    response = requests.get(
        endpoint,
        params=params,
        headers={"X-API-KEY": os.environ["FINANCIAL_DATASETS_API_KEY"]},
        timeout=30,
    )
    response.raise_for_status()
    raw = response.json()
    stable = json.dumps(raw, sort_keys=True, separators=(",", ":"))

    return {
        "provider": "financial_datasets",
        "endpoint": endpoint,
        "request": params,
        "retrievedAt": datetime.now(timezone.utc).isoformat(),
        "rawSha256": hashlib.sha256(stable.encode()).hexdigest(),
        "raw": raw,
        "statements": raw.get("financials", raw),
    }

bundle = fetch_statement_bundle("AAPL", period="annual")
print(bundle["rawSha256"], bundle["statements"].keys())

Use a long-form fact schema before rebuilding statements先使用长表 Fact Schema，再重建报表

A wide provider response is convenient for display but brittle for multi-provider normalization. Convert each value into a fact record first; pivot into a statement only after identity and period validation.

供应商的宽表响应便于展示，但不适合多供应商标准化。应先把每个数值转换成 Fact Record，完成身份和期间验证后再 Pivot 成报表。

Align identity and periods before joining the three statements连接三张报表前，先对齐身份与期间

Do not join on ticker and year. Use issuer identity plus period type, period end, fiscal year, fiscal quarter, currency, and filing version. Income and cash flow statements are duration facts; many balance-sheet values are instant facts. A calendar-quarter label is not enough to prove they belong together.

不要只用 Ticker 与年份连接。应使用发行人身份、期间类型、Period End、财年、财季、币种和 Filing Version。利润表与现金流量表多为 Duration Fact，资产负债表很多项目是 Instant Fact；仅有自然季度标签不足以证明它们属于同一数据包。

Turn accounting relationships into validation tests把会计关系转化为验证测试

def close_enough(left, right, abs_tol=1_000, rel_tol=0.002):
    scale = max(abs(left), abs(right), 1)
    return abs(left - right) <= max(abs_tol, rel_tol * scale)

def validate_period(bundle):
    errors, warnings = [], []
    bs, cf = bundle["balance"], bundle["cashFlow"]

    if not close_enough(
        bs["totalAssets"],
        bs["totalLiabilities"] + bs["totalEquity"],
    ):
        errors.append("balance_sheet_equation_failed")

    if all(cf.get(k) is not None for k in
           ["beginningCash", "changeInCash", "endingCash"]):
        if not close_enough(
            cf["beginningCash"] + cf["changeInCash"],
            cf["endingCash"],
        ):
            warnings.append("cash_rollforward_failed")

    if len({bundle[x]["currency"] for x in
            ["income", "balance", "cashFlow"]}) != 1:
        errors.append("currency_mismatch")

    if len({bundle[x]["periodEnd"] for x in
            ["income", "balance", "cashFlow"]}) != 1:
        errors.append("period_end_mismatch")

    return {"valid": not errors, "errors": errors, "warnings": warnings}

• Use absolute and relative tolerances; rounding and provider presentation can create small differences.同时使用绝对与相对容差；四舍五入和供应商展示方式会产生小差异。
• Check sign conventions before reconciling capex, debt issuance, buybacks, and dividends.核对 Capex、发债、回购和分红前先确认正负号规则。
• Recompute subtotals only when component definitions and scopes match.只有组件定义和范围一致时才重新计算小计。
• Track check status per period; one failed quarter should not silently contaminate a multi-year trend.按期间记录校验状态，单个失败季度不能静默污染多年趋势。

Restatements and provider corrections need versioned history重述与供应商修正需要版本化历史

The same report period can appear in an original filing, an amendment, and later comparative columns. A provider can also improve its taxonomy mapping after your first retrieval. Overwriting the old row destroys point-in-time reproducibility. Use an append-only key such as issuer + period + statement mode + filing/accession + provider revision + retrieval snapshot.

同一 Report Period 可能出现在原始 Filing、修订文件和后续报表的比较列中；供应商也可能在首次取数后改进 Taxonomy 映射。覆盖旧行会破坏 Point-in-time 可复现性。建议使用“发行人 + 期间 + 报表模式 + Filing/Accession + 供应商版本 + 获取快照”的只追加键。

Security, cost, latency, and licensing controls安全、成本、延迟与许可控制

Common financial statement failure modes常见财务报表失败模式

QVeris pattern: Discover → Inspect → CallQVeris 模式：Discover → Inspect → Call

QVeris belongs above provider endpoints as a capability-discovery and routing layer. It does not become the financial source. The agent discovers a capability such as “annual standardized statements with filing URLs,” inspects schema, coverage, limits, and permissions, then calls the selected tool with bounded inputs. The normalized response must retain the underlying provider and filing evidence.

QVeris 位于供应商端点之上，承担能力发现与路由，而不会变成金融数据来源。Agent 先发现“带 Filing URL 的年度标准化报表”等能力，检查 Schema、覆盖、限制和权限，再用受控输入调用选定工具；标准化响应仍必须保留底层供应商与 Filing 证据。

Financial statements API questions财务报表 API 常见问题

Official sources and related implementation guides官方资料与相关实现指南

Coverage, schemas, quotas, and commercial rights change. Verify current documentation and run a representative issuer test set before committing to a provider.

覆盖、Schema、配额和商业权限会变化。确定供应商前，请核对当前官方文档，并运行代表性发行人测试集。