Financial Modeling Prep (fmpsdk)

FMP SDK

这个项目旨在为 Financial Modeling Prep（FMP）提供的 API 端点提供一站式服务。

跟你说句心里话：很抱歉这个包已经过时这么久。FMP 一直在调整其 API，后来我又遇到个人问题，导致进度进一步延误。现在一切都回到正轨了。由于这段空档，这个包中大约一半的旧方法已无法用于 FMP 当前的 API，因此我没有勉强修补，而是基于 FMP 的 stable/ API 从头重建了它。如果你使用的是 20250102.0 或更早版本，那你用的是重写前的旧方法；任何更新的版本都使用下文所述的架构。旧版本已从 PyPI 撤回（普通的 pip install fmpsdk 现在始终会安装重写后的版本），但仍可通过明确指定版本来安装，例如 pip install fmpsdk==20250102.0。不过请注意，这并不能恢复其功能：FMP 已于 2025-08-31 完全停用了这些旧方法所调用的旧版 /api/v3/ API，因此即使成功安装指定的旧版本，其调用也都会失败。保留这些版本是为了让你在迁移期间兼容现有的固定版本依赖文件，而不是让你继续回避重写。

覆盖范围

共 29 个数据组、约 240 个方法，既可通过 client.<method>(...) 调用，也可通过对应的命名空间分组调用，例如 client.statements.income_statement(...)：

• 公司与基本面 — 公司概况、高管、并购、DCF 估值、财务报表／比率／增长（利润表、资产负债表、现金流量表——包括报告值、TTM 和增长版本）
• 市场数据 — 实时与盘后报价、历史价格图表、技术指标
• 参考与筛选 — 按 symbol／CIK／CUSIP／ISIN 搜索、公司筛选器、行业／产业／交易所目录
• 日历与事件 — 财报、股息、拆股、IPO、经济日历
• 所有权与合规 — 内部人交易、13F 表格机构持股、SEC 文件、ESG 披露
• 另类市场 — 加密货币、外汇、大宗商品、指数、ETF 和共同基金
• 情绪与分析 — 分析师评级／目标价、TipRanks 评级、国会交易、市场异动
• 批量下载 — 覆盖整个市场的数据转储，一次调用即可获取，无需按每个 symbol 分别调用

每个方法自己的 docstring 都会说明所需的 FMP 订阅计划级别（Free／Starter／Premium／Ultimate）——详见下文的定价层级。有一个例外：7 个 client.tipranks 方法虽已实现并通过单元测试，但未使用真实响应进行测试——原因请参阅该部分。

使用方法

1. 需要 Python 3.9 或更高版本。安装此包：pip install fmpsdk python-dotenv（python-dotenv 为可选项——下方示例仅用它从 .env 文件加载 API 密钥）。
2. 创建 .env 文件，并在其中填入 API 密钥。在 .env 中写入：FMP_API_KEY='blah'
3. 创建一个 Client，并按数据类别调用方法，例如： client.company.profile(symbol="AAPL")、client.statements.income_statement(symbol="AAPL")。
4. 方法调用的返回值几乎总是一个字典列表。你需要自行解析。

示例代码

#!/usr/bin/env python3

from dotenv import load_dotenv

import fmpsdk

# Actual API key is stored in a .env file. Not good to store API key directly in script.
load_dotenv()
client = fmpsdk.Client()  # reads FMP_API_KEY from the environment

# Company Valuation Methods
symbol = "AAPL"
print(f"Company Profile: {client.company.profile(symbol=symbol)}")

# Every non-2xx FMP response raises a typed exception instead of returning
# None or an error-shaped dict, so a plan-gated or bad-key call is obvious:
try:
    client.statements.income_statement_ttm(symbol=symbol)
except fmpsdk.FMPPlanLimitError:
    print("Your FMP plan doesn't cover this endpoint — check its docstring for which tier does.")
except fmpsdk.FMPAuthenticationError:
    print("Check your FMP_API_KEY.")

有个命名上的小细节值得提前了解：client.quote 是整个报价组的命名空间（client.quote.aftermarket_quote(...)、client.quote.batch_quote(...) 等），因此它会与同名的顶层 quote() 方法重名——调用顶层方法时，请使用 client.quote.quote(symbol="AAPL")。

定价等级

FMP 的套餐构成一个阶梯：Free、Starter、Premium、Ultimate，每个套餐都会在前一个套餐的基础上增加更多端点。套餐未涵盖的调用会引发 fmpsdk.FMPPlanLimitError，而不是返回数据。这里没有需要保持同步的统一套餐表；相反，每个分组模块的文档字符串（例如 fmpsdk/endpoints/search.py）以及每个方法自己的文档字符串，都会在调用代码旁明确说明所需的套餐等级，并且已使用真实密钥，在 Free 到 Ultimate 的每个等级上进行实时验证。请查看这些文档，或者直接尝试调用并捕获 FMPPlanLimitError。

有一个例外，完全不在这个套餐阶梯之内：client.tipranks 的 7 个方法。 即使是 Ultimate 套餐，这些方法仍会返回 402——FMP 自己的错误消息说明了原因：TipRanks 数据需要单独付费的附加服务（“TipRanks data boost”），且需独立于上述四个套餐等级购买。我们尚未购买此附加服务，因此这 7 个方法虽已实现并通过单元测试（使用模拟数据），但从未使用真实响应进行验证——请将其视为尚未验证，而不是已确认可用。如果你拥有该附加服务，并在其中某个方法上遇到错误，欢迎提交包含修复方案的 PR（并说明真实响应的实际内容）。

MCP 服务和 OpenAPI 规范

mcp/ — Model Context Protocol 服务，单独发布为 fmpsdk-mcp（因此 pip install fmpsdk 不会拉取 fastmcp）。它允许 AI 助手（Claude Code、Claude Desktop 等）通过此库查询 FMP：提供 10 个精选工具，满足常见需求（报价、简介、报表、比率、价格历史、新闻），另有发现工具，可在运行时访问全部约 240 个方法。使用 uv：

claude mcp add fmpsdk -s user -e FMP_API_KEY=your-key -- uvx fmpsdk-mcp

请参阅 mcp/README.md，了解 Claude Desktop 配置、完整工具列表和开发环境设置。

openapi.json — 对相同 API 范围的 OpenAPI 3.1 描述。FMP 未发布 OpenAPI/Swagger 文档；此文件是通过检查本库源代码生成的（python tools/gen_openapi.py），并非从 FMP 获取，也未获 FMP 背书。

贡献

请参阅 CONTRIBUTING.md——了解开发环境设置、单元测试／实时测试／Ultimate 测试等级，以及如何验证并为上述未经测试的 tipranks 方法提交修复 PR。

许可证

BSD 3-Clause——请参阅 LICENSE.md。

致谢

特别感谢以下为本项目贡献力量的朋友！开源项目因大家的参与和帮助而得以发展！他们是本项目的明星。谢谢大家。

• Ken Caruso
• iforgotmypass
• Ivelin Ivanov
• Claude Code