openfund-arbitrage 3.9.1__tar.gz

openfund_arbitrage-3.9.1/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.3
+Name: openfund-arbitrage
+Version: 3.9.1
+Summary: 跨交易所资金费率套利系统
+Author: OpenFund Team
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: aiohttp (>=3.9.0,<4.0.0)
+Requires-Dist: apscheduler (>=3.10.0,<4.0.0)
+Requires-Dist: ccxt (>=4.5.60,<5.0.0)
+Requires-Dist: fastapi (>=0.109.0,<0.110.0)
+Requires-Dist: filelock (>=3.13.0,<4.0.0)
+Requires-Dist: numpy (>=1.26.0,<2.0.0)
+Requires-Dist: pandas (>=2.2.0,<3.0.0)
+Requires-Dist: pydantic (>=2.5.0,<3.0.0)
+Requires-Dist: pyyaml (>=6.0,<7.0)
+Requires-Dist: uvicorn[standard] (>=0.27.0,<0.28.0)
+Description-Content-Type: text/markdown
+
+# 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. 安装依赖
+
+```bash
+cd openfund-arbitrage
+poetry install
+```
+
+### 2. 配置环境
+
+创建 `.env` 文件并填入 API 密钥：
+
+```bash
+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. 启动服务
+
+```bash
+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）。
+
+```bash
+# 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 波动导致数据缺失后补救），可以使用以下脚本：
+
+```bash
+# 修改脚本中的 date_str 为目标日期，例如 "2026-03-10"
+python tests/rerun_report_310.py
+```
+
+报表生成后将自动更新 `reports/` 下对应的 `.md` 文件和通知。
+
+## 注意事项
+
+- **API 权限**: 实盘模式需要 API 具有 `Read` (获取持仓/余额) 和 `Trade` (开仓/平仓) 权限。
+- **代理建议**: 建议在 `arbitrage_config.yaml` 中配置稳定代理以保证 `max_latency_ms` 达标。
+- **风险提示**: 即便有 RealTradeGuard 保护，量化交易仍存在不可预见的风险，请务必从极小本金开始。
+

openfund_arbitrage-3.9.1/README.md

@@ -0,0 +1,148 @@
+# 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. 安装依赖
+
+```bash
+cd openfund-arbitrage
+poetry install
+```
+
+### 2. 配置环境
+
+创建 `.env` 文件并填入 API 密钥：
+
+```bash
+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. 启动服务
+
+```bash
+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）。
+
+```bash
+# 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 波动导致数据缺失后补救），可以使用以下脚本：
+
+```bash
+# 修改脚本中的 date_str 为目标日期，例如 "2026-03-10"
+python tests/rerun_report_310.py
+```
+
+报表生成后将自动更新 `reports/` 下对应的 `.md` 文件和通知。
+
+## 注意事项
+
+- **API 权限**: 实盘模式需要 API 具有 `Read` (获取持仓/余额) 和 `Trade` (开仓/平仓) 权限。
+- **代理建议**: 建议在 `arbitrage_config.yaml` 中配置稳定代理以保证 `max_latency_ms` 达标。
+- **风险提示**: 即便有 RealTradeGuard 保护，量化交易仍存在不可预见的风险，请务必从极小本金开始。

openfund_arbitrage-3.9.1/app/__init__.py

@@ -0,0 +1,3 @@
+"""OpenFund Arbitrage - 跨交易所资金费率套利系统"""
+
+__version__ = "3.9.1"