polymarket_arbitrage/docs/使用手册.md

# Polymarket 套利机器人 — 中文使用手册

> 适用版本：v0.1.0 · Python 3.12+ · Windows / Linux / macOS
>
> 本文从环境准备到日常运维，按真实使用顺序逐步讲解。

---

## 目录

1. [项目简介](#1-项目简介)
2. [系统要求](#2-系统要求)
3. [快速安装](#3-快速安装)
4. [首次配置](#4-首次配置)
5. [首次运行](#5-首次运行)
6. [日常使用（Paper 模式）](#6-日常使用paper-模式)
7. [Web 仪表板](#7-web-仪表板)
8. [切换到 Live 模式](#8-切换到-live-模式)
9. [监控与运维](#9-监控与运维)
10. [故障排查](#10-故障排查)
11. [安全建议](#11-安全建议)
12. [附录：环境变量参考](#附录环境变量参考)

---

## 1. 项目简介

**Polymarket NegRisk 多结果套利机器人**。Polymarket 的某些分类事件（例如"2028 大选谁赢"）每个结果独立挂牌交易。当**所有结果的卖一价加总 < $1** 时，买入一整套结果，结算时一定收回 $1 → **无风险套利**。

本机器人扫描所有活跃 negRisk 事件，实时计算套利空间，提供两种模式：

| 模式 | 资金风险 | 用途 |
|------|---------|------|
| **Paper** | $0 | 模拟成交，验证策略，观察 PnL |
| **Live** | 实盘资金 | 真实下单，需提供钱包私钥 |

---

## 2. 系统要求

| 项目 | 要求 |
|------|------|
| **Python** | 3.12 或更高 |
| **操作系统** | Windows 10+ / Linux / macOS |
| **内存** | ≥ 512 MB |
| **磁盘** | ≥ 1 GB（含 SQLite 与日志） |
| **网络** | **必须**能访问 `polymarket.com`（国内需配置代理） |
| **钱包**（仅 Live） | Polygon 上的专用 EOA，持有 USDC.e |

**国内用户注意**：Polymarket 服务器在国内无法直连，必须配置 HTTP 代理（详见 [§4.2 网络代理](#42-网络代理)）。

---

## 3. 快速安装

### 3.1 克隆项目

```bash
git clone https://github.com/matthewnyc2/arbitrage
cd arbitrage
```

### 3.2 创建虚拟环境

**Windows (PowerShell)**：
```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
```

**Linux / macOS**：
```bash
python3 -m venv .venv
source .venv/bin/activate
```

### 3.3 安装依赖

```bash
pip install -e ".[dev]"
```

> **⚠️ 重要**：默认会装 `websockets>=13.0`，pip 可能会拉到 **15.x** 版本，但该版本与项目不兼容（参见 [§10.3 websockets 版本问题](#103-websockets-版本问题)）。**显式锁版本**：
> ```bash
> pip install "websockets==14.2"
> ```

### 3.4 验证安装

```bash
arb --help
```

应显示：`init / discover / scan / web / resolve` 五个子命令。

---

## 4. 首次配置

### 4.1 复制环境变量模板

```bash
cp .env.example .env
```

`.env` 关键字段（Paper 模式默认值即可运行）：

```ini
ARB_MODE=paper                       # paper = 模拟盘；live = 实盘
ARB_CLOB_HOST=https://clob.polymarket.com
ARB_GAMMA_HOST=https://gamma-api.polymarket.com
ARB_PROXY=                           # 国内用户填代理，见下文
```

### 4.2 网络代理

**国内 / 防火墙环境下必须配置**，否则 `arb discover` 会报 `httpx.ConnectTimeout`。

**PowerShell 临时设置**（仅当前会话）：
```powershell
$env:HTTPS_PROXY="http://127.0.0.1:7890"   # 改成你的代理地址
$env:HTTP_PROXY="http://127.0.0.1:7890"
```

**永久设置**（写入 `.env`）：
```ini
ARB_PROXY=http://127.0.0.1:7890
```

> **常见代理端口**：Clash 默认 7890，V2Ray 默认 10809，SSR 默认 1080。
>
> 配置完成后 httpx（REST）和 websockets（WS）都会通过代理连接。

### 4.3 验证代理可用

```bash
arb discover
```

预期输出：
```
seen=2000 negRisk=928 upserted=894 malformed=34
```

如果仍超时，回到 [§10.1 网络连通性](#101-网络连通性)。

---

## 5. 首次运行

### 5.1 初始化数据库

```bash
arb init
```

创建 SQLite 表结构（含 events / outcomes / opportunities / baskets / fills / live_orders / resolutions / denylist / daily_pnl）。

### 5.2 发现事件

```bash
arb discover
```

从 Polymarket Gamma API 拉取所有活跃 negRisk 事件。需要约 10–20 秒。

**持续发现**（生产部署推荐，每 180 秒刷新）：
```bash
arb discover --loop --interval 180
```

### 5.3 启动扫描

```bash
arb scan
```

开始监听 CLOB WebSocket，实时检测套利机会，写入 paper baskets。

预期日志：
```
scan loop started (885 events hydrated)
ws subscribed to N tokens
```

### 5.4 启动 Web 仪表板（另一终端）

```bash
arb web
```

打开浏览器访问 <http://127.0.0.1:8000>。

---

## 6. 日常使用（Paper 模式）

### 6.1 标准三进程部署

| 终端 | 命令 | 作用 |
|------|------|------|
| 终端 1 | `arb discover --loop --interval 180` | 每 3 分钟刷新事件列表 |
| 终端 2 | `arb scan` | 实时扫描 + 模拟成交 |
| 终端 3 | `arb web` | Web 仪表板 |

**Linux/macOS 后台运行**：
```bash
nohup arb discover --loop --interval 180 > logs/discover.log 2>&1 &
nohup arb scan > logs/scan.log 2>&1 &
```

### 6.2 CLI 命令速查

| 命令 | 功能 |
|------|------|
| `arb init` | 创建 SQLite schema |
| `arb discover` | 单次拉取事件 |
| `arb discover --loop` | 持续拉取 |
| `arb scan` | 启动扫描 |
| `arb web` | 启动仪表板（默认 127.0.0.1:8000） |
| `arb resolve <event_id> --winner <token_id>` | 手动标记事件结算结果 |
| `arb resolve <event_id>` | 标记为 invalid |

### 6.3 停止服务

**正常停止**：在运行终端按 `Ctrl+C`。

**强制清理残留进程**（Windows）：
```powershell
Get-Process python | Where-Object { $_.StartTime -gt (Get-Date).AddHours(-1) } | Stop-Process -Force
```

---

## 7. Web 仪表板

仪表板每 2–3 秒自动刷新（HTMX 轮询），无需手动操作。

### 7.1 主要面板

| 面板 | 显示内容 |
|------|---------|
| **Paper PnL** | 已实现盈亏、各状态组合数、Kill Switch 按钮 |
| **Baskets** | 最近 25 个组合：ID、事件、份数、成本、状态、PnL |
| **Recent Opportunities** | 最近 25 个检测到的机会：Σ asks、净边际、最大组合、预期利润 |

### 7.2 关键指标解读

**Σ asks < $1** → 存在套利空间。典型值：
- `0.98` → 净边际 ~2%（扣费前）
- `0.95` → 净边际 ~5%（扣费前）
- `< 0.90` → 非常罕见的深度套利

**net edge bps**：扣除手续费 + 分摊 gas 后的净边际。低于 50 bps 会被 `ARB_MIN_NET_EDGE_BPS` 过滤。

**status**：
| 状态 | 含义 |
|------|------|
| `pending_resolution` | 等待事件结算 |
| `redeemed` | 已结算，PnL 入账 |
| `failed` | 部分腿未成交（paper 模拟时深度消失） |
| `invalid` | 事件被标记为无效 |

### 7.3 Kill Switch

仪表板右下角红色 **kill** 按钮，点击后立即创建 `./KILL` 文件，执行器会拒绝所有新单。再次点击 **unkill** 删除文件即可恢复。

也可在终端手动：
```bash
# Windows
New-Item -Path .\KILL -ItemType File

# Linux/macOS
touch ./KILL
```

---

## 8. 切换到 Live 模式

### 8.1 准备工作

1. **专用钱包**：在 Polygon 上创建一个新的 EOA，**不要复用个人钱包**
2. **充值**：向钱包转入 USDC.e（建议 ≥ $200，含 gas）
3. **批准授权**：按 `docs/api/order-signing.md` §8 的脚本，对 CTF Exchange + NegRisk Exchange + NegRisk Adapter 三个合约授权

### 8.2 派生 L2 API 凭证

按 `docs/api/order-signing.md` §2 的 `bootstrap_clob_creds.py` 脚本执行一次，生成：
- `CLOB_API_KEY`
- `CLOB_SECRET`
- `CLOB_PASSPHRASE`

**这三个凭证无法恢复，丢失需重新派生。**

### 8.3 修改 `.env`

```ini
ARB_MODE=live
ARB_PRIVATE_KEY=0x...                # 钱包私钥（0x 前缀）
ARB_FUNDER_ADDRESS=0x...             # 资金地址（EOA 模式 = 私钥对应地址）
ARB_SIGNATURE_TYPE=0                 # 0=EOA, 1=Polymarket proxy, 2=Gnosis Safe
ARB_API_KEY=...
ARB_API_SECRET=...
ARB_API_PASSPHRASE=...

# 风险上限（强烈建议保持默认值）
ARB_MAX_BASKET_USD=50
ARB_MAX_OPEN_BASKETS=3
ARB_DAILY_LOSS_STOP_USD=100
```

### 8.4 首次实盘（强烈建议 dry_run 验证）

**第 1 步**：先用 dry_run 验证签名链路：
```python
# 在 Python REPL 中手动测试
from arbitrage.engine.live_executor import LiveExecutor, RiskLimits
from arbitrage.book.l2 import BookRegistry
books = BookRegistry()
ex = LiveExecutor(books=books, dry_run=True)  # 只签名不提交
```

**第 2 步**：把 `cli.py:87` 的 `dry_run=False` 保持不变（默认就是 False），但**先把 `ARB_MAX_BASKET_USD` 设为 `5`**：
```ini
ARB_MAX_BASKET_USD=5
ARB_MAX_OPEN_BASKETS=1
```

**第 3 步**：观察 1–2 天无异常后，再逐步放大到默认值。

---

## 9. 监控与运维

### 9.1 日志

日志写在 `logs/arbitrage.jsonl`（结构化 JSON，每天 0 点轮转，保留 7 天）。

**实时查看**：
```bash
# Linux/macOS
tail -f logs/arbitrage.jsonl | jq .

# Windows PowerShell
Get-Content logs\arbitrage.jsonl -Wait
```

**按事件过滤**：
```bash
grep "new_market" logs/arbitrage.jsonl | tail -20
```

### 9.2 数据库

位置：`./arbitrage.db`（SQLite + WAL 模式）

**直接查询**：
```bash
sqlite3 arbitrage.db "SELECT status, COUNT(*) FROM baskets GROUP BY status;"
sqlite3 arbitrage.db "SELECT * FROM opportunities ORDER BY detected_at DESC LIMIT 10;"
```

**备份**：
```bash
cp arbitrage.db arbitrage.db.bak-$(date +%Y%m%d)
```

**重置**（清空所有 paper 数据）：
```bash
rm arbitrage.db
arb init
arb discover
```

### 9.3 进程监控

**检查运行中的 arb 进程**：
```powershell
# Windows
Get-Process | Where-Object { $_.Name -eq "python" -and $_.Path -like "*Python312*" }

# Linux
ps aux | grep arb
```

**查看资源占用**：
```bash
# 内存占用（正常 100-300 MB）
Get-Process python | Select-Object Id, @{n='Mem(MB)';e={[int]$_.WorkingSet64/1MB}}
```

### 9.4 升级

```bash
cd arbitrage
git pull
pip install -e ".[dev]"
# 重启 arb scan / arb web
```

---

## 10. 故障排查

### 10.1 网络连通性

**症状**：`httpx.ConnectTimeout`，`arb discover` 卡住。

**排查**：
```powershell
Test-NetConnection -ComputerName gamma-api.polymarket.com -Port 443
```

如果失败，确认 `ARB_PROXY` 设置正确，或切换代理节点。

### 10.2 WebSocket 反复重连

**症状**：`ws disconnect (TimeoutError); reconnecting in 1.0s` 大量重复。

**根因**：WebSocket 没有走代理。

**修复**：确认 `.env` 中设置了 `ARB_PROXY=http://...`，代码会自动通过 HTTP CONNECT 隧道建立 WS 连接。

### 10.3 websockets 版本问题

**症状**：`AttributeError: 'ClientConnection' object has no attribute 'recv_messages'`，或 `got an unexpected keyword argument 'proxy'`。

**根因**：`websockets 15.0` 与项目不兼容。

**修复**：
```bash
pip install "websockets==14.2"
```

### 10.4 日志 PermissionError

**症状**：`PermissionError: [WinError 32] 另一个程序正在使用此文件`

**根因**：loguru 在 Windows 上的 50MB 轮转触发 `close() → os.rename()` 竞态。

**修复**（已默认配置）：`rotation="1 day"` + `retention="7 days"`，避免高并发期轮转。

如果仍出现：
```powershell
# 清理残留进程
Get-Process python | Where-Object { $_.Path -like "*Python312*" } | Stop-Process -Force
```

### 10.5 残留进程占用文件

**症状**：杀掉 `arb scan` 后，新进程仍报 PermissionError。

**排查**：
```powershell
Get-Process | Where-Object { $_.Name -eq "python" }
```

**清理**：
```powershell
Get-Process python -ErrorAction SilentlyContinue | Stop-Process -Force
```

### 10.6 仪表板 404 / 端口冲突

**症状**：浏览器访问 `http://127.0.0.1:8000` 返回 404 或连接拒绝。

**排查**：
```powershell
Test-NetConnection -ComputerName 127.0.0.1 -Port 8000
Get-NetTCPConnection -LocalPort 8000 -State Listen
```

**修复**：更换端口启动：
```bash
arb web --port 8888
```

### 10.7 没有任何套利机会

**症状**：仪表板显示 `recent opportunities` 为空或 net edge bps 全部 < 50。

**原因**：
1. 当前 Polymarket 没有负空间（正常 — 套利机会稀少）
2. WS 数据未刷新（检查 `ws subscribed` 日志）
3. `ARB_MIN_NET_EDGE_BPS` 设得太高（默认值 50 合理）

---

## 11. 安全建议

### 11.1 私钥保护

- **永远不要把 `.env` 提交到 Git**（已在 `.gitignore` 中）
- 实盘私钥使用**专用钱包**，与其他资产隔离
- 服务器上 `.env` 文件权限设为 `chmod 600`（Linux）
- 考虑使用硬件钱包或多签

### 11.2 Web 仪表板

- 默认绑定 `127.0.0.1`，**不要**改为 `0.0.0.0` 后暴露到公网
- `kill` / `unkill` 端点**无身份认证**，暴露即等于把钱包控制权交给攻击者
- 如果需要远程访问，使用 SSH 隧道：
  ```bash
  ssh -L 8000:127.0.0.1:8000 user@server
  ```

### 11.3 依赖管理

- 锁定关键依赖版本，避免供应链风险：
  ```bash
  pip install "websockets==14.2" "py-clob-client==0.34.6"
  ```
- 定期升级时检查 changelog

### 11.4 Live 模式额外建议

- 先用 ≥ $10 的小资金跑 1 周
- 每日检查 realized PnL，确认与 paper 结果趋势一致
- 设置价格告警（Discord webhook / Telegram bot 等）
- 监控 `daily_pnl` 表，日亏损接近 `ARB_DAILY_LOSS_STOP_USD` 时手动 kill

---

## 附录：环境变量参考

完整 `.env` 配置项：

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `ARB_MODE` | `paper` | `paper` / `live` |
| `ARB_CLOB_HOST` | `https://clob.polymarket.com` | CLOB API |
| `ARB_GAMMA_HOST` | `https://gamma-api.polymarket.com` | Gamma REST |
| `ARB_DATA_HOST` | `https://data-api.polymarket.com` | Data API |
| `ARB_WS_URL` | `wss://ws-subscriptions-clob.polymarket.com/ws/market` | WS 端点 |
| `ARB_POLYGON_RPC` | `https://polygon-rpc.com` | Polygon RPC |
| `ARB_PROXY` | _空_ | HTTP 代理（REST + WS 共享） |
| `ARB_PRIVATE_KEY` | _空_ | 钱包私钥（Live 必填） |
| `ARB_FUNDER_ADDRESS` | _空_ | 资金地址（Live 必填） |
| `ARB_SIGNATURE_TYPE` | `0` | 0=EOA / 1=proxy / 2=Safe |
| `ARB_API_KEY` | _空_ | CLOB L2 API key |
| `ARB_API_SECRET` | _空_ | CLOB L2 API secret |
| `ARB_API_PASSPHRASE` | _空_ | CLOB L2 API passphrase |
| `ARB_MIN_NET_EDGE_BPS` | `50` | 最低净边际（基点） |
| `ARB_MAX_BASKET_USD` | `50` | 单笔组合上限 USD |
| `ARB_MAX_OPEN_BASKETS` | `3` | 全局未结算组合上限 |
| `ARB_DAILY_LOSS_STOP_USD` | `100` | 日亏损止损 USD |
| `ARB_KILL_SWITCH_FILE` | `./KILL` | Kill switch 文件路径 |
| `ARB_PAPER_LATENCY_MS` | `250` | Paper 模拟延迟（毫秒） |
| `ARB_DB_PATH` | `./arbitrage.db` | SQLite 路径 |
| `ARB_WEB_HOST` | `127.0.0.1` | Web 监听地址 |
| `ARB_WEB_PORT` | `8000` | Web 端口 |
| `ARB_LOG_LEVEL` | `INFO` | 控制台日志级别 |

---

## 联系与反馈

- 项目主页：<https://matthewnyc2.github.io/arbitrage/>
- GitHub Issues：<https://github.com/matthewnyc2/arbitrage/issues>
- API 参考：`docs/api/order-signing.md`、`docs/api/negrisk.md`
- 设计文档：`DESIGN.md`