FinData 金融数据 API / MCP

用同一套只读接口查询美股行情、公司财报、盈利预期、机构评级、SEC 披露和研究快照。可以由程序通过 REST 接入，也可以由 AI 通过 MCP 调用。

样例方案 · 数据尚未补全：本服务用于体验数据查询与系统接入，目前仅提供部分股票、期间及字段的已保存数据，不代表全市场覆盖，也不是实时行情。样例可查询不等于数据质量已全部验收。

首次体验请保留调试页预填的股票代码，不填日期、财期等可选筛选，先取得第一份返回结果，再按实际覆盖调整参数。默认样例只影响文档调试，不会将客户明确请求的股票替换成其他股票。未收录或无匹配的数据如实返回空数组，不自动补零或换股。

数据目录提供 sample_query（可直接使用的样例参数）和 sample_status。调用 GET /v1/datasets 或 MCP discover_datasets() 查看当前开放的接口。客户目录、调试文档及 MCP 工具列表仅展示已有记录的数据集；尚未形成样例的数据能力作为内部后续建设项，不对外列为可用接口。

例如补充财务指标接口当前覆盖 DAL、JPM、KO、META、NVDA、PLD、WMT，默认演示 DAL；BRK.B 在此接口暂无记录，不能据此推断其他接口也没有 BRK.B。机构共识演示 AAPL，首次查询不要额外填写 period_type=annual。覆盖以当前数据目录为准。

在线 API 调试 · 完整数据字典 · OpenAPI 契约 · 本页 Markdown · AI 索引

1. 五分钟完成第一次查询

准备服务地址和独立提供的访问密钥。在 API 调试 顶部确认当前服务地址，粘贴密钥并点击 验证并连接。看到“已连接：密钥验证成功”后，再展开接口，点击 Try it out → Execute。查询自动携带授权，不用手动拼接 Bearer。

密钥只保存在当前标签页的会话中，刷新后自动重新验证；点击 清除授权 可立即移除。浏览器禁止会话存储时，页面会提示刷新后重新输入。本地测试与服务器使用不同密钥，必须与页面显示的服务地址对应。验证成功只证明访问权限有效，不代表数据准确性已验收。

也可直接使用以下命令。示例为 Bash；Windows 请使用 curl.exe 并按终端语法设置环境变量。不要将密钥写进 URL、公开代码或 AI 提示词。

export FINDATA_BASE_URL="https://43.167.212.164"
# FINDATA_API_KEY 设置为服务方单独提供的密钥。

# 第一步：哪些机构数据现在有记录？
curl "$FINDATA_BASE_URL/v1/datasets?domain=analysts&available_only=true" \
  -H "Authorization: Bearer $FINDATA_API_KEY"

# 第二步：它有哪些股票、字段，日期筛选针对哪个日期？
curl "$FINDATA_BASE_URL/v1/datasets/analysts/ratings" \
  -H "Authorization: Bearer $FINDATA_API_KEY"

# 第三步：读取 AAPL 的一条机构评级事件。
curl "$FINDATA_BASE_URL/v1/analysts/ratings?ticker=AAPL&limit=1" \
  -H "Authorization: Bearer $FINDATA_API_KEY"

返回 200 表示查询成功；data: [] 表示当前筛选无匹配，不表示请求失败。

2. 按业务问题选择接口

以下是常用入口，不是全部能力；所有数据集都保留在目录和 字段参考 中。

/v1/companies/ 提供公司概况。预测历史表格保留在 /v1/analysts/tables 和 /v1/analysts/detail-tables，优先使用结构化接口，再用表格补充。

3. 覆盖、日期和一行的含义

GET /v1/datasets 返回简短目录，可按 domain、available_only 筛选。GET /v1/datasets/{dataset_id} 返回单个数据集详情。例如 dataset_id=analysts/ratings。

日期筛选采用 YYYY-MM-DD，包含起止两端。例如评级事件的 start/end 当前筛选 observed_at，事件本身的日期是 data.event_date。财期、交易日、申报日和观测时间不是同一概念。

所有筛选条件都是精确匹配，股票代码大小写不敏感。CIK 保留前导零，股票股类标点按目录填写，例如 BRK.B。仅使用对应接口声明的筛选字段，不支持 SQL、模糊搜索或任意排序。

4. 看懂返回结果

所有业务分类查询都返回 data、meta、pagination。下面是保存快照中的评级记录节选，省略部分字段，仅用于理解结构，不代表当前评级或投资建议。

{
  "data": [{
    "ticker": "AAPL",
    "currency": "USD",
    "observed_at": "2026-09-21T03:17:49.217000+00:00",
    "quality_status": "checked",
    "data": {
      "institution": "Evercore ISI",
      "analyst": "Amit Daryanani",
      "event_date": "2026-09-15",
      "action": "Maintains",
      "rating": "buy",
      "target": 365.0,
      "target_previous": null
    }
  }],
  "meta": {
    "dataset": "analysts/ratings",
    "time_basis": "observed_at",
    "strict_pit_certified": false
  },
  "pagination": {"limit": 1, "offset": 0, "returned": 1, "next_offset": 1}
}

金额和精确小数可能用字符串表示，数字字符串应按字段语义转换为 Decimal，不要把所有字符串转成数字。币种、单位、GAAP / non-GAAP 和股类需一起解读；缺失币种不能默认美元。null、字段缺失及历史文本 None 都不能擅自补成零。

checked 表示记录核对，unverified 表示未核验，quarantined 表示疑问值隔离。质量备注和隔离状态必须保留。strict_pit_certified=false 表示尚未通过严格时点认证，不能直接宣称可做无前视偏差回测。

5. Python 查询与分页

安装 httpx，设置 FINDATA_BASE_URL 和 FINDATA_API_KEY 后运行。下面会按页输出 IBM 的盈利预期。实际覆盖先查目录。

import os
import time
import httpx

with httpx.Client(
    base_url=os.environ["FINDATA_BASE_URL"].rstrip("/"),
    headers={"Authorization": "Bearer " + os.environ["FINDATA_API_KEY"]},
    timeout=60,
) as client:
    offset, release = 0, None
    while True:
        for attempt in range(4):
            response = client.get("/v1/estimates/earnings", params={
                "ticker": "IBM", "limit": 100, "offset": offset})
            if response.status_code != 429 or attempt == 3:
                break
            time.sleep(int(response.headers.get("Retry-After", "60")))
        response.raise_for_status()
        page = response.json()
        if release is not None and release != page["meta"]["built_at"]:
            raise RuntimeError("数据版本已切换，请重新开始分页")
        release = page["meta"]["built_at"]
        for row in page["data"]:
            print(row)
        offset = page["pagination"]["next_offset"]
        if offset is None:
            break

默认每页100条，最大500条；没有10000条总量上限。固定快照内顺序稳定，但不保证按日期排序。只能按 next_offset 继续，不能将返回数组第一条自动当作最新值。returned 是本页条数，服务不提供昂贵的实时筛选总数。

6. 让 AI 通过 MCP 接入

MCP 地址为服务地址下的 /mcp，传输方式是 Streamable HTTP，使用同一个 Bearer 密钥。客户端需支持自定义 Authorization 头；不同 AI 产品的配置格式不同，请将密钥保存在客户端的凭据配置中。

推荐工具调用顺序：

1. discover_datasets(domain="analysts", available_only=true)：先查看简短目录。
2. describe_dataset(dataset_id="analysts/ratings")：读取覆盖、字段和日期口径。
3. query_analysts_ratings(filters={"ticker":"AAPL"}, limit=10)：查询已选资源。
4. 结果不为空时，结合 quality_status 和日期解读；需要下一页时使用 next_offset。

每个 query_... 工具提供具体筛选字段的 inputSchema 和嵌套响应的 outputSchema。工具名与 REST operationId 一致，数据结果相同。未知筛选字段会被拒绝。

可以对 AI 这样表达需求：“先检查数据覆盖，再查询 AAPL 已保存的机构评级事件。说明事件日期、观测日期和质量状态；不要把它描述为当前评级，也不要把共识预测写成某家券商的 EPS 预测。”

import asyncio
import os
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    async with streamablehttp_client(
        os.environ["FINDATA_BASE_URL"].rstrip("/") + "/mcp",
        headers={"Authorization": "Bearer " + os.environ["FINDATA_API_KEY"]},
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            contract = await session.call_tool("describe_dataset", {
                "dataset_id": "analysts/ratings"})
            if contract.isError:
                raise RuntimeError(contract.content)
            result = await session.call_tool("query_analysts_ratings", {
                "filters": {"ticker": "AAPL"}, "limit": 10})
            if result.isError:
                raise RuntimeError(result.content)
            print(result.structuredContent)

asyncio.run(main())

MCP 中工具执行错误表现为 isError=true；参数结构不符合 schema 时可能是协议错误。传输层鉴权与限流仍返回 HTTP 401 / 429，不要只检查 JSON 中有没有 data。

7. 错误、限额和排查

REST 错误体示例：

{"error":{"code":"invalid_parameters","message":"Unknown filters: symbol","request_id":"示意请求标识"}}

当前试用配额：最多2个在途请求、每分钟120次认证请求，MCP 握手也计入。密钥持有者共用额度。大型披露表优先筛选 ticker、CIK、CUSIP 或 accession_number。请求失败时保留 request_id、请求路径和时间；不要把密钥附在反馈中。

8. URL 规范与兼容性

采用 GET /v1/{业务域}/{资源}：小写英文、复数资源名、复合词用短横线；股票、日期和分页放在查询参数。SEC 的 13F、N-PORT 等表格保留监管领域含义。路径描述数据内容，不包含供应商、采集文件名或数据库表名。

/v1/datasets 是数据发现入口；/v1/catalog 继续提供完整目录。已有业务 URL 和 query_... 工具名保持有效，不因文案优化而改名。研究批次接口也继续保留，但不作为初次接入的默认入口。

/v1/{dataset} 下的旧有限快照接口及旧 get_... 工具仅用于兼容，新接入使用本指南的业务分类接口。新字段会以兼容方式增加，客户端应容忍未知响应字段；删除字段、改变字段含义或类型需要新的主版本。API 文档的软件版本与 URL 中的数据契约主版本是两回事。

服务会显示数据截至时间；更新发生在新快照发布后。13F / N-PORT 保留申报版本及修订稿，用 accession_number 关联申报与明细。13F reported_value 需结合 value_scale，value_usd 已换算美元。不同层、不同观测与研究批次可能重复，不可直接相加。