Initialize crypto_monitor_user (user edition) from monitor codebase.

Retarget git remote, install path, and deploy docs from crypto_monitor to crypto_monitor_user. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-17 16:18:13 +08:00
commit 53863559f4
608 changed files with 162764 additions and 0 deletions
@@ -0,0 +1,151 @@
+# 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
+OKX_OPTIONS_CLOSE_RECYCLE_MULT=2
+OKX_OPTIONS_CLOSE_HOLD_SECONDS=120
+# 平仓限价挂单超时自动撤(秒),默认 600=10 分钟;联调可临时改 60
+OKX_OPTIONS_PENDING_TTL_SECONDS=600
+```
+
+平仓执行:**只锁买一限价**,说明见 [期权开平仓与监控说明.md](./期权开平仓与监控说明.md);线上 `/options/guide`.
+
+修改 `.env` 后须 `pm2 restart crypto_okx`.
+
+## 6. 数据库
+
+### `options_trades`
+
+记录本地开仓/平仓,权利金,翻倍提醒状态.
+
+### `options_convert_log` / `options_transfer_log`
+
+可选记录兑换与划转操作.
+
+## 7. HTTP 路由
+
+| 方法 | 路径 |
+|------|------|
+| GET | `/options` |
+| GET | `/options/guide` | 开平仓与监控说明(独立页) |
+| 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`