openfund-arbitrage 3.9.1

跨交易所资金费率套利系统

OpenFund Arbitrage

跨交易所资金费率套利系统 - 生产级实盘交易引擎

功能概述

• 套利机会发现: 实时监控 9 个以上交易所的资金费率差异，识别净年化收益。
• 运行模式隔离: 支持纯监控 (Monitor)、模拟交易 (Paper) 与 真实交易 (Live) 三种模式物理隔离。
• 安全守护引擎 (RealTradeGuard):
  • Audit A (强一致性对账): 开仓前强制对比本地数据库与交易所实盘持仓，防止“脑裂”。
  • 熔断机制: 10分钟内超过 3 次回滚失败自动锁定全局交易。
  • DIRTY 锁定: 发现持仓不一致时立即锁定对应交易对，需人工介入。
• 实盘执行约束:
  • IOC 限价保护: 使用 Immediate-or-Cancel 订单配合 ±0.05% 价格偏移，防止滑点。
  • 逐仓强制模式: 自动切换至 Isolated Margin 模式，物理隔离单仓风险。
  • 头寸硬约束: 默认限制 1.0 USDT 极小头寸与 1x 杠杆，确保初期安全。
  • 多交易所方言适配: 针对 OKX, Gate, HTX 等交易所专门优化结算周期 (Interval) 与非标准接口的兼容性，确保费率对齐 100% 准确。

技术栈

• Python 3.10+
• FastAPI + Pydantic v2
• CCXT (异步模式)
• APScheduler (任务调度)
• python-dotenv (环境管理)

快速开始

1. 安装依赖

cd openfund-arbitrage
poetry install

2. 配置环境

创建 .env 文件并填入 API 密钥：

cp .env.example .env
# 编辑 .env 填入各交易所 API Key, Secret, Password

3. 配置策略参数

编辑 arbitrage_config.yaml：

• arbitrage.is_paper_trading: false (切换为实盘模式)
• arbitrage.auto_trading.enabled: true (开启自动执行)
• arbitrage.live_trading.max_latency_ms: 3000 (设置最大允许延迟)

4. 启动服务

poetry run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

运行模式说明

模式	配置要求	行为描述
监控模式 (Monitor)	auto_trading.enabled: false	仅扫描并通知，不注册持仓监控任务，无状态运行。
模拟模式 (Paper)	is_paper_trading: true	使用虚拟账户执行，记录模拟 PnL，不涉及真实资金。
实盘模式 (Live)	is_paper_trading: false	连接真实 API 执行，强制 1 USDT 限制及 RealTradeGuard 审计。

安全特性说明 (RealTrader)

• 价格保护: 实盘不使用市价单，强制使用 IOC Limit 单，确保成交价优于 LastPrice * (1 ± 0.05%)。
• 延迟审计: 自动复用费率扫描阶段的真实 REST 延迟，若延迟超过 max_latency_ms 则拦截执行。
• 保证金校验: 下单前强制检查可用余额是否覆盖 头寸 + 0.1%手续费缓冲。
• 动态持仓同步: 自动抓取并对齐多交易所资金费流水，支持全生命周期收益追踪。

收益报告系统 (Reporting System)

系统集成了自动化收益统计与可视化报表功能，支持每日定时生成或按需手动触发。

• 全生命周期追踪: 不仅统计当日收益，还能自动回溯至开仓时刻，计算持仓全周期的累计收益。
• 多维度损益分析:
  • 当日贡献: 细化至多空双腿各交易所的当日资金费收入。
  • 累计收益: 实时累计从开仓至今的所有已结算利息。
  • 资金效率: 自动计算 累计收益 / 占用本金，评估头寸质量。
• 可视化报表:
  • Markdown 报表: 生成位于 reports/ 目录，包含每笔持仓的详细流水、时间分布及审计回顾。
  • JSON 镜像: 同步生成位于 data/reports/ 的数据文件，便于二开或程序化分析。
• 决策回顾 (Decision Review): 报表自动关联开仓时的审计快照，对比“预期 APR”与“实际收益 APR”，并展示审计置信度。

决策审计与对账 (Audit & Reconcile)

• Audit B (持仓快照): 开仓时自动保存市场深度、中间价格及 4H TWAP 差值，作为后期收益评估的基准。
• 预期达成率: 自动分析实际收到的利息是否符合开仓时的费率预测，及时识别“费率刺客”。
• 流水级对账: 细化每一笔利息的时间、金额与流水 ID，确保交易所账单与本地数据完全匹配。

项目结构

openfund-arbitrage/
├── app/
│   ├── core/           # 核心逻辑 (Executor, Guard, Manager, Fetcher)
│   ├── scheduler/      # 调度任务 (Scan, Monitor, Sync, Jobs/Report)
│   ├── services/       # 业务服务 (PaperTrading, Opportunity, FundingSync)
│   ├── data/           # 持久化存储 (Sqlite, Positions, Reports JSON)
│   └── main.py         # 应用入口
├── reports/            # 自动化生成的 Markdown 收益报表
├── arbitrage_config.yaml # 核心配置文件
├── .env                # 敏感凭据
└── tests/              # 单元测试与诊断工具

运维与诊断

系统提供了一套完整的“烟雾测试 (Smoke Test)”工具，用于在启动实盘前验证各交易所的 API 连通性、权限及可用保证金。

交易所连通性测试 (V3)

该工具会自动执行：初始化连接 -> 检查余额 -> 自动调量 -> 开仓 -> 等待 -> 平仓（ReduceOnly）。

# 1. 测试所有已启用的交易所 (默认使用 DUSK 以适配小额账户)
python tests/test_exchange_connectivity_v3.py

# 2. 极速测试特定交易所 (仅初始化目标交易所)
python tests/test_exchange_connectivity_v3.py -e okx

# 3. 指定交易所并指定特定币种进行测试
python tests/test_exchange_connectivity_v3.py -e htx -s XRP/USDT:USDT

# 4. 查看帮助文档
python tests/test_exchange_connectivity_v3.py --help

注意：脚本具备“自适应账户余额”能力。如果账户余额紧张，它会自动降级至 1 张合约（物理最小单位）进行测试，确保即便只有 5-10U 的账户也能完成验证。

手动重发收益报表 (Manual Report)

如果需要重新生成特定日期的报表（例如 API 波动导致数据缺失后补救），可以使用以下脚本：

# 修改脚本中的 date_str 为目标日期，例如 "2026-03-10"
python tests/rerun_report_310.py

报表生成后将自动更新 reports/ 下对应的 .md 文件和通知。

注意事项

• API 权限: 实盘模式需要 API 具有 Read (获取持仓/余额) 和 Trade (开仓/平仓) 权限。
• 代理建议: 建议在 arbitrage_config.yaml 中配置稳定代理以保证 max_latency_ms 达标。
• 风险提示: 即便有 RealTradeGuard 保护，量化交易仍存在不可预见的风险，请务必从极小本金开始。