FinMarketPy / 项目研究站
finmarketpy：外汇、宏观与波动率研究的 Python 回测链路
finmarketpy 是 Cuemacro（Saeed Amen）维护的 Python 市场分析与策略回测库，前身是 PyThalesians。它把「取数 → 建信号 → 回测 → 绩效归因」串成一条对象化管线：BacktestRequest 描述这次回测的全部口径，Backtest / TradingModel 执行，TradeAnalysis 出统计。取数交给 findatapy，出图交给 chartpy；它真正区别于通用股票回测框架的地方，是 curve/ 里的外汇即期/远期/期权曲线与波动率曲面、以及 economics/ 里的事件研究与季节性。它不做实盘下单，也没有 A 股行情源。
项目来源
cuemacro/finmarketpy · Apache-2.0 · 约 3.8k Star / 521 Fork / 22 Tags（2026-09-20 采集，数字会随社区活动变化）
查看源码 ↗
pyproject.toml、uv.lock、INSTALL.md、.rhiza 等顶层文件——这正是本站要讲的「PyPI 发布版与仓库现状已经不一样」。能完成哪些研究任务
官方 README 把能力写成五条短语，但真正决定「要不要用它」的是这些任务在代码里长什么样。下表把任务、真实类和方法、以及官方资料里没有写清的注意点放在一起。
| 研究任务 | 对应类 / 方法（源码实测） | 产出 | 适用场景 | 注意点 |
|---|---|---|---|---|
| 策略回测（模板化） | TradingModel（高层模板）、Backtest（底层引擎） | 累计收益曲线、持仓、交易明细 | 把一条信号规则跑成可比较的净值 | 底层 Backtest.calculate_trading_PnL() 直接吃信号 DataFrame；高层模板负责参数装载 |
| 绩效统计与归因 | TradeAnalysis：run_strategy_returns_stats()、run_excel_trade_report()、run_day_of_month_analysis() | 收益统计表、Excel 报告、按日/按月的分解 | 回测跑完后判断「好在哪、烂在哪」 | 支持切换 engine="finmarketpy"，Excel 输出默认写 model.xlsx |
| 策略对比 | BacktestComparison：plot_pnl()、plot_sharpe() | 两条策略的 PnL / Sharpe 对比图 | 同一信号下比较不同成本或参数 | 只在 chartpy 装好时才能出图 |
| 波动率目标与仓位控制 | BacktestRequest 的 signal_vol_* / portfolio_vol_* 参数组 | 按目标波动率缩放的仓位序列 | 让不同资产的回测风险可比 | 官方示例用 5% 目标、最大杠杆 3、60 日估计窗、BM 月度再平衡 |
| 事件研究 | EventStudy / EventsFactory：get_economic_event_date_time()、get_daily_moves_over_event() | 事件日前后窗口的走势统计 | 非农、CPI、央行决议一类宏观事件 | 事件日期表要自己维护；官方示例用 FRED/ALFRED 经济数据 |
| 季节性与日内规律 | Seasonality.time_of_day_seasonality(data_frame, years=False, seconds=False) | 按月份/星期/时段的收益分布 | 判断某个品种是否有稳定的日历效应 | 输入要求是规整的时间索引，缺失值要先处理 |
| 外汇曲线与波动率曲面 | FXSpotCurve、FXForwardsCurve、FXOptionsCurve、FXVolSurface | 曲线插值、曲面拟合、按 delta/strike 取波动率 | 外汇期权定价与曲面研究 | 曲面拟合默认 CLARK5，定价可切 financepy 引擎；需额外装 FinancePy 才走 financepy 路径 |
| 技术指标信号 | TechIndicator.create_tech_ind() + TechParams | 信号 DataFrame | 不需要外部指标库就能起信号 | 内置 9 种指标（SMA/EMA/ROC/SMA2/GMMA/RSI/BB/ATR/VWAP），与本机 stock-technical-mastery 技能覆盖范围不同 |
一次回测在代码里是怎么走的
下面这条链路来自官方示例 finmarketpy_examples/backtest_example.py，每一步都能在源码里找到对应定义。
用 findatapy 描述并取数
MarketDataRequest(start_date=…, finish_date=…, freq='daily', data_source='alfred', tickers=['EURUSD'], vendor_tickers=['DEXUSEU'], fields=['close'], fred_api_key=…)，再交给Market(market_data_generator=MarketDataGenerator()).fetch_market(md_request)。预期输出：一张以日期为索引、以 tickers 为列的行情表。声明这次回测的口径
br = BacktestRequest()后逐项赋值：br.spot_tc_bp = 2.5（2.5bp 买卖价差）、br.ann_factor = 252、br.signal_vol_adjust = True、br.signal_vol_target = 0.05、br.signal_vol_max_leverage = 3。这一组值决定了结果的量级，也是「可复现」要写清的东西。用内置指标生成信号
tech_params = TechParams(); tech_params.sma_period = 200，然后tech_ind.create_tech_ind(spot_df, 'SMA', tech_params)，再signal_df = tech_ind.get_signal()。预期输出：与行情同索引的 -1/0/1 信号表。跑回测
Backtest().calculate_trading_PnL(br, asset_df, signal_df, contract_value_df=None, run_in_parallel=False)，随后backtest.portfolio_cum()取组合累计曲线、backtest.portfolio_signal()取持仓、backtest.pnl()取逐资产 PnL。出统计与图
TradeAnalysis().run_strategy_returns_stats(trading_model)出统计表；图表走 chartpy：style = Style(); style.title = …; style.source = 'FRED'; Chart().plot(port, style=style)。换chartfactory_default_engine就能把同一张图渲成 matplotlib / plotly / bokeh。
按你的任务直接进入对应页面
六条最常被问到的路径，每条都给出「先回答什么」和「读完下一步做什么」。
1. 我要把它装起来
先弄清一件事：PyPI 上装到的 0.11.19 是扁平布局，而 GitHub master 已经改成 src/finmarketpy + pyproject.toml。两条线命令不同、目录不同，装之前先决定走哪条。
3. 我想跑通一次回测
官方最短路径是 FRED/ALFRED 取 G10 货币对日线 → SMA(200) 信号 → calculate_trading_PnL → 统计表。需要一把免费 FRED API key。
4. 我要确认数据源与凭证
凭证有四条路线（改常量 / keyring / datacred.py / 按次传参），缓存与存储还牵扯 Redis、ArcticDB、HDF5、S3、Parquet。A 股要另接。
6. 我卡在报错上
numpy 必须 <2、Windows 下回测默认只有 1 个线程、缺 Redis 会打印 Couldn't push MarketDataRequest 但不影响取数——按五段顺序定位最快。
它不做什么：四条容易搞混的边界
选型决策里最有用的信息往往是「不覆盖什么」。以下四条都能在官方资料或源码里查到依据。
| 容易被误认为 | 实际情况 | 依据 | 该去找什么 |
|---|---|---|---|
| 「一个库搞定取数+画图+回测」 | 取数必须 findatapy、画图必须 chartpy，两者是独立包，可以单独升级、也会单独出问题 | README 安装段要求先装 chartpy 与 findatapy；pyproject 依赖里两者都是必装 | 问题在取数就查 findatapy，在出图就查 chartpy |
| 「可以做 A 股选股/回测」 | findatapy 的 vendor 模块为 bbg / crypto / databento / fred / web 等，没有 A 股行情源；示例资产是 G10 外汇与 FRED 宏观序列 | findatapy 0.1.42 包内 datavendor*.py 清单；示例 tickers 列表 | A 股研究可走免部署路线的 akshare-finance / tushare-finance 等技能 |
| 「能实盘下单」 | 官方资料没有交易执行能力说明；PLANNED_FEATURES 里提到的 event-driven 回测器与盈透包装仍是「低优先级待办」 | PLANNED_FEATURES.md | 实盘执行请用专门的交易框架，finmarketpy只用于研究 |
| 「有实时行情」 | 它的取数是历史/批量的市场数据请求语义；实时行情取决于 findatapy 侧数据源的授权与接口 | README 与 findatapy README 的数据源描述 | 实时行情要确认数据商授权；免部署路线见对比页 |
两条准备路线：自建三库 vs 免部署入口
两条路线解决的不是同一层问题，前置条件差别也很大。
| 对比项 | 自建 finmarketpy 三库 | 免部署技能路线 |
|---|---|---|
| 准备成本 | 装 Python、按顺序装 chartpy → findatapy → finmarketpy | 装 EasyClaw 客户端即可，无需自建 Python 环境 |
| 数据凭证 | 需自备 FRED key（免费）等；Quandl/Eikon/Plotly 等按需 | 技能各自的前置：akshare 免费、Tushare 需 Token、东财妙想需 API Key |
| 拿到的东西 | 可复现的回测对象与全部口径（成本、杠杆、再平衡、年化因子） | 一次性问答结果（行情表、指标、图），口径由技能决定 |
| 能做的深度 | curve/ 曲线与波动率曲面、EventStudy 事件窗口、Seasonality、参数敏感性、Excel 报告 | 行情/财务查询、技术面、出图、单次回测指标 |
| 不覆盖 | A 股行情源、实盘下单、中文官方文档 | 外汇期权与波动率曲面、事件研究框架、可写死的回测口径 |
| 适合谁 | 要写论文/研报、要复现、要改代码的人 | 先要数据与结论、暂不装环境的人 |
backtest_example.ipynb 与 market_data_example.ipynb），可以在浏览器里直接跑官方 notebook，不用装环境——但要能连到 mybinder.org，且部分数据仍需要一个免费的 Quandl/FRED key。免部署路线实际跑出来是什么样
两张本机 EasyClaw 对话截图（复用集群内已核验截图，含义未变），左边翻页查看。它们只证明「这类任务可以一句话发起」，不是 finmarketpy 的运行结果。
本站的证据边界与免责说明
下面这些不是免责套话，而是会影响你判断的具体限制。
| 项目 | 本站的实际情况 | 对你的影响 |
|---|---|---|
| 是否实机跑过 | 没有。本站未在本机安装或运行 finmarketpy，全部命令、参数与行为均来自官方 README、INSTALL.md、pyproject.toml 与 0.11.19 源码实读 | 命令请以官方文档与你自己的运行结果为准；本站不保证在你的环境可复现 |
| 版本口径 | PyPI 最新为 0.11.19（2025-03-10）；GitHub master 最后一次提交为 2026-04-16，已改为 src/ 布局 | 你从 pip 装到的结构与仓库里看到的结构可能不同 |
| Star / Fork 数字 | 3,809 / 521（2026-09-20 采集，GitHub 公开 API） | 数字会随社区活动变化，截图与数字都只代表采集时刻 |
| 与 EasyClaw 的关系 | 无已证实集成。本机 .easyclaw/skills 下 29 个技能里没有 finmarketpy 相关技能 | 对比页比较的是「两条独立路线」，不是「一个平台里的两个功能」 |
| 收益类信息 | 本站不提供任何收益率、胜率、Sharpe 数字，也不评价第三方文章里的具体数字 | 看到任何具体数字请按体检清单自行复现后再采信 |
| 搜索数据 | 关键词接口在 intent_filter 阶段失败，SERP 与竞品位次缺失；仅测得 finmarketpy 一词的中文区月搜索量约 10 | 本站页面优先级依据官方证据的重要性排序，而非搜索量 |
关于 finmarketpy 的高频问题
答案以官方 README、INSTALL.md 与 0.11.19 源码为依据；本站未实机验证，命令请以官方为准。
finmarketpy 免费吗？可以商用吗？
代码本身是 Apache-2.0（仓库 LICENCE 与 GitHub 许可证字段一致），可自由使用与修改。要注意两件不是「代码许可」的事：一是数据要另外买——Bloomberg、Eikon、Databento 这类数据源需要各自的授权，免费档（FRED/ALFRED 等）也有各自条款；二是作者另提供商业培训与技术支持（README 写明 2 天 Python for finance 企业培训与商业技术支持，联系方式在 README 内），并接受 GitHub Sponsors 赞助。以官方文档与数据提供方条款为准。
它和 findatapy、chartpy 是什么关系？我该装几个？
三个是互相独立的包，由同一作者维护：finmarketpy 负责分析与回测，取数靠 findatapy，出图靠 chartpy。官方 README 明确要求先装 chartpy 与 findatapy，再装 finmarketpy；pyproject 里两者都是必装依赖，所以正常安装会一起装进来。想知道「报错该去哪个库查」，看三库分工。
pip 装到的版本和 GitHub 上看到的不一样，正常吗？
正常，而且这是本站最想提醒的一点。PyPI 最新发布是 0.11.19（2025-03-10），解包后是扁平结构（finmarketpy/… + setup.py）；GitHub master 在 2026-04-16 已完成 src/finmarketpy 迁移，并引入 pyproject.toml（hatchling）、uv.lock、Makefile 等。README 自己也说“better to get the newest version from repo, as opposed to releases”。以官方仓库现状与你实际安装结果为准，细节见安装与环境边界。
能不能用它做 A 股？
可以把它当作回测与统计的计算层，但数据层不覆盖 A 股：findatapy 的 vendor 模块清单里没有 A 股行情源，官方示例资产是 G10 外汇与 FRED 宏观序列。要做 A 股，你需要自己接数据（或用技能路线的 akshare-finance / tushare-finance 取数），再喂给它的回测接口。本站不会把 finmarketpy 描述成 A 股量化平台——以官方文档为准。
它强在哪，和 backtrader / vectorbt 有什么区别？
差别主要在研究场景：finmarketpy 自带外汇即期/远期/期权曲线与波动率曲面（curve/）、宏观事件研究（EventStudy）与季节性（Seasonality），并提供了波动率目标与远期 roll 成本这类外汇口径的参数；通用框架通常不带这些。反过来，通用框架在事件驱动执行、超大规模参数扫描、A 股生态上更成熟。选型对照表在顶部导航的「对比」页。
跑起来要花多少钱、要几个 key？
最短路径只需要一把免费的 FRED API key（官方示例的data_source='alfred'就用它），Quandl/Eikon/Plotly/Bloomberg 等只有你用到才需要。没有 key 时最容易卡在取数环节，凭证的四条配置路线见数据源与凭证。
有没有中文文档？
官方没有中文文档，也没有官方 ReadTheDocs 站点——PLANNED_FEATURES.md 里「用 Sphinx 生成 HTML API 文档」还列在待办中。中文资料目前主要是社区文章。本站是独立的研究笔记，不是官方文档的翻译，遇到冲突以官方仓库为准。
不想装这一整套环境怎么办？
两条替代：一是用 README 提供的 Binder 链接在浏览器里直接跑官方 notebook；二是走免部署的 免部署技能路线（本机已核验 akshare-finance、quant-analyst、chart-image、tushare-finance 等技能）。后者不是 finmarketpy 的安装方式，也不提供 curve/ 曲线曲面与事件研究框架，两者没有已证实集成。入口在顶部导航的「对比」页。