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 保护，量化交易仍存在不可预见的风险，请务必从极小本金开始。

