feat: add OKX options module with dual API, USDT/USDC convert, and docs

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/期权方案.md

@@ -0,0 +1,143 @@
+# OKX 期权模块 — 技术方案
+
+> 适用范围：`crypto_monitor_okx` 实例；与永续子账户并行，不新增 PM2 进程。
+
+## 1. 目标
+
+在现有 OKX 监控实例中增加 **USDⓈ 本位期权（买方）** 能力：
+
+- 永续/关键位：继续走 **子账户 API-A**（现有 `OKX_API_*`）
+- 期权：走 **主账户 API-B**（`OKX_OPTIONS_API_*`）
+- 资金展示对齐 OKX：**资金账户 / 交易账户**，分币种显示 USDT、USDC、USDG
+- 支持 **手动 USDT→USDC 兑换** 与 **USDC 账户划转**
+- **无总资金池上限**；单笔权利金上限可配置（默认 10 USDC）
+
+## 2. 交易规则（硬约束）
+
+| 规则 | 说明 |
+|------|------|
+| 仅买方 | 开仓 `buy`，平仓 `sell`；禁止卖方开仓 |
+| 产品 | `BTC-USD_UM` / `ETH-USD_UM`（线性、USDC/USDG 结算） |
+| 到期 | 仅展示 ≤2 日到期合约（可配置 `OKX_OPTIONS_MAX_DTE_DAYS`） |
+| 虚实 | 仅 **轻度实值**（`OKX_OPTIONS_ITM_ONLY`） |
+| 合约规格 | **1 张 = 0.01 ETH/BTC**（`ctMult=0.01`，以接口为准） |
+| 报价单位 | 盘口 ask/bid = **每 1 ETH/BTC** 的 USD 价 |
+| 权利金 | `总权利金 = 报价 × ETH数量`；`张数 = ETH数量 / 0.01` |
+| 单笔预算 | `≤ OKX_OPTIONS_TRADE_BUDGET_USDC`（默认 10），算张数 × `OKX_OPTIONS_BUDGET_BUFFER`（默认 0.95） |
+| 开仓 | 限价买单，价格 = 卖一 |
+| 平仓 | 限价卖单，价格 = 买一（市价需显式开启且二次确认） |
+| 监控 | 浮盈 / 已付权利金 ≥ 100% → 企业微信推送一次 |
+
+## 3. 架构
+
+```
+crypto_okx（单 PM2）
+├── exchange (swap)     ← OKX_API_* 子账户
+└── exchange_options    ← OKX_OPTIONS_API_* 主账户
+
+lib/options/
+├── okx_options_lib.py      # 封装于 lib/exchange/
+├── options_pricing_lib.py
+├── options_db.py
+├── options_monitor_lib.py
+└── options_register.py     # 路由 + 监控线程
+```
+
+**隔离：** 期权模块只调用 `exchange_options`；永续逻辑只调用 `exchange`。
+
+## 4. 资金与兑换
+
+### 4.1 展示（期权页顶栏）
+
+| 账户 | 币种 |
+|------|------|
+| 资金账户 | USDT、USDC（若有） |
+| 交易账户 | USDT、USDC、USDG（若有） |
+
+不展示「练手池」等抽象记账名称。
+
+### 4.2 推荐操作流程
+
+```
+资金账户 USDT
+    → [手动兑换 USDT→USDC]（OKX Convert API，资金账户内）
+    → [划转到交易账户]（USDC）
+    → 交易账户 USDC
+    → [限价买入期权]
+```
+
+### 4.3 API
+
+| 接口 | OKX |
+|------|-----|
+| 余额 | `fetch_balance`（funding / trading）+ `GET /api/v5/asset/balances` |
+| 询价兑换 | `POST /api/v5/asset/convert/estimate-quote` |
+| 确认兑换 | `POST /api/v5/asset/convert/trade` |
+| 划转 | `exchange.transfer(ccy, amt, from, to)` |
+
+## 5. 配置项（`.env`）
+
+```bash
+OKX_OPTIONS_ENABLED=false
+OKX_OPTIONS_API_KEY=
+OKX_OPTIONS_API_SECRET=
+OKX_OPTIONS_API_PASSPHRASE=
+OKX_OPTIONS_ACCOUNT_LABEL=主账户·期权
+
+OKX_OPTIONS_TRADE_BUDGET_USDC=10
+OKX_OPTIONS_BUDGET_BUFFER=0.95
+OKX_OPTIONS_DEFAULT_UNDERLY=ETH
+OKX_OPTIONS_MAX_DTE_DAYS=2
+OKX_OPTIONS_ITM_MAX_DIST_USD=30
+OKX_OPTIONS_PROFIT_ALERT_RATIO=1.0
+OKX_OPTIONS_POLL_SECONDS=15
+OKX_OPTIONS_TD_MODE=cross
+OKX_OPTIONS_ALLOW_MARKET_CLOSE=false
+```
+
+修改 `.env` 后须 `pm2 restart crypto_okx`。
+
+## 6. 数据库
+
+### `options_trades`
+
+记录本地开仓/平仓、权利金、翻倍提醒状态。
+
+### `options_convert_log` / `options_transfer_log`
+
+可选记录兑换与划转操作。
+
+## 7. HTTP 路由
+
+| 方法 | 路径 |
+|------|------|
+| GET | `/options` |
+| GET | `/api/options/balances` |
+| GET | `/api/options/chain` |
+| GET | `/api/options/quote` |
+| POST | `/api/options/open` |
+| POST | `/api/options/close` |
+| POST | `/api/options/convert/quote` |
+| POST | `/api/options/convert/execute` |
+| POST | `/api/options/transfer` |
+| GET | `/api/options/positions` |
+
+## 8. 分阶段交付
+
+1. **基础设施**：双 API、余额、文档、设置页说明  
+2. **兑换 + 划转**：资金账户 USDT→USDC、划转到交易户  
+3. **交易**：链、报价、开平仓、持仓  
+4. **监控**：翻倍微信提醒  
+
+## 9. 不在一期范围
+
+- 卖方、组合单、RFQ  
+- 自动 USDT↔USDC  
+- `manual-agent-okx` / 中控聚合  
+- 币本位期权  
+
+## 10. 安全
+
+- 期权 API：**交易 + 读**，禁止提币  
+- 日志不输出 Secret  
+- 下单前校验 `client is exchange_options`

docs/期权用法.md

@@ -0,0 +1,114 @@
+# OKX 期权 — 使用说明
+
+## 1. 前置条件
+
+1. OKX **主账户**已开通期权（USDⓈ 本位），且 App 中可见 `ETHUSD UM` / `BTCUSD UM`。
+2. 在 `crypto_monitor_okx/.env` 配置 **期权专用 API**（与永续子账户分开）：
+
+```bash
+OKX_OPTIONS_ENABLED=true
+OKX_OPTIONS_API_KEY=你的主账户Key
+OKX_OPTIONS_API_SECRET=...
+OKX_OPTIONS_API_PASSPHRASE=...
+```
+
+3. 重启实例：`pm2 restart crypto_okx`
+
+> 永续仍用原有 `OKX_API_*`（子账户）；期权只用 `OKX_OPTIONS_API_*`（主账户）。
+
+## 2. 资金准备
+
+期权权利金使用 **USDC 或 USDG**，不能直接用 USDT 买入。
+
+### 推荐步骤
+
+1. 打开 **期权** 页，查看顶栏：
+   - **资金账户**：USDT 余额
+   - **交易账户**：USDC 余额（买期权从这里扣）
+2. **币种兑换**（资金账户内）  
+   - 从 USDT 兑换为 USDC  
+   - 先点 **询价**，确认预估获得量后点 **确认兑换**
+3. **账户划转**  
+   - 从：资金账户 → 到：交易账户  
+   - 币种：USDC  
+   - 将兑换得到的 USDC 划到交易账户
+4. 确认 **交易账户 USDC** 足够支付本笔权利金
+
+系统 **不会** 自动兑换或划转，避免误动资金。
+
+## 3. 下单流程
+
+1. 顶栏进入 **期权**
+2. 选择 **ETH** 或 **BTC**
+3. 选择 **到期日**（默认仅 1～2 日）
+4. 选择 **看涨 Call** 或 **看跌 Put**
+5. 在行权价列表中选 **轻度实值** 合约
+6. 查看：
+   - **卖一价**（每 1 ETH/BTC 的报价）
+   - **张数 / ETH 数量**
+   - **预估权利金**（USDC）
+7. 选择 **按预算打满**（默认 10U×0.95）或 **指定 ETH 数量**
+8. 点击 **限价买入**（价格 = 卖一）
+
+### 张数说明
+
+- **1 张 = 0.01 ETH**（或 0.01 BTC）— 与 OKX App「合约价值」一致
+- 盘口报价是 **每 1 ETH** 的价格  
+  例：报价 15.6，买 0.5 ETH（50 张）→ 权利金 ≈ 15.6 × 0.5 = **7.8 USDC**
+
+## 4. 持仓与平仓
+
+持仓表字段对齐 OKX：合约、张数、开仓均价、标记价、浮盈、收益率、到期等。
+
+**平仓（锁利/止损）：**
+
+1. 在持仓行点击 **平仓**
+2. 查看 **买一价** 与预估收回
+3. 确认 **限价卖出**（价格 = 买一）
+
+> 默认不使用市价平仓。若 `.env` 开启 `OKX_OPTIONS_ALLOW_MARKET_CLOSE=true`，市价按钮会出现并带风险提示。
+
+## 5. 微信提醒
+
+当某笔持仓 **未实现盈亏 ≥ 已付权利金的 100%**（翻倍）时，会发 **一条** 企业微信提醒（同一笔只提醒一次）。
+
+需已配置 `WECHAT_WEBHOOK`。
+
+## 6. 与永续的关系
+
+| | 永续（子账户） | 期权（主账户） |
+|--|----------------|----------------|
+| API | `OKX_API_*` | `OKX_OPTIONS_API_*` |
+| 页面 | 实盘下单 / 关键位 | 期权 |
+| 资金顶栏 | USDT 资金户+交易户 | 期权页单独显示 USDC 等 |
+
+两套资金 **不合并** 显示。
+
+## 7. 配置说明
+
+| 变量 | 默认 | 含义 |
+|------|------|------|
+| `OKX_OPTIONS_TRADE_BUDGET_USDC` | 10 | 单笔权利金上限 |
+| `OKX_OPTIONS_BUDGET_BUFFER` | 0.95 | 算张数时预留 5% 缓冲 |
+| `OKX_OPTIONS_MAX_DTE_DAYS` | 2 | 最多选几天内到期 |
+| `OKX_OPTIONS_ITM_MAX_DIST_USD` | 30 | 轻度实值：价内不超过多少 USD |
+| `OKX_OPTIONS_PROFIT_ALERT_RATIO` | 1.0 | 浮盈/权利金 ≥ 此值推送 |
+
+## 8. 常见问题
+
+**Q：为什么买不了？**  
+- 交易账户 USDC 不足 → 先兑换再划转  
+- 卖一价过高，10U 预算买不到 1 张 → 选更便宜合约或提高 `OKX_OPTIONS_TRADE_BUDGET_USDC`  
+- 期权 API 未配置或 `OKX_OPTIONS_ENABLED=false`
+
+**Q：报价 15 是每张 15U 吗？**  
+- 不是。15 是 **每 1 ETH** 的报价；每张（0.01 ETH）约 0.15 USDC。
+
+**Q：子账户能开期权吗？**  
+- 本系统期权走主账户 API；子账户永续不受影响。
+
+## 9. 风险说明
+
+- 买方最大亏损为 **权利金**；近期实值仍会时间衰减  
+- 限价单可能因无流动性未成交  
+- 请先在小额下验证兑换、划转、开平仓全流程