文档:新增OKX单笔期权币本位与USDT桥开发方案

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-20 11:46:04 +08:00
parent 339f5e6db0
commit 2028251fc1
1 changed files with 241 additions and 0 deletions
@@ -0,0 +1,241 @@
+# OKX 单笔期权 · 币本位模式（USDT 桥 + 复利）— 开发方案
+
+> 状态:**方案待实现**(按本文落地;改需求先改本文).  
+> 范围:**仅 `crypto_monitor_okx` 单笔期权**;对冲计划(永期/期期)**不接币本位**.  
+> 相关:[期权方案.md](./期权方案.md) · [期权用法.md](./期权用法.md) · [期权开平仓与监控说明.md](./期权开平仓与监控说明.md) · [position-sizing-mode.md](./position-sizing-mode.md)
+
+---
+
+## 1. 背景与动机
+
+当前单笔期权仅支持 **USDⓈ 本位**(权利金 **USDC**):人工 USDT→USDC 兑换/划转后,按 `OKX_OPTIONS_TRADE_BUDGET_USDC` 卖一开 / 买一平.
+
+实盘观察:**部分到期与行权附近,币本位期权流动性往往好于 USDC 期权**,更利于「只锁卖一 / 买一」的成交质量.
+
+币本位权利金用 **ETH/BTC** 支付,操作者仍习惯用 **USDT** 思考本金与复利.因此需要一条自动资金桥,并支持交易账户 USDT 滚仓放大.
+
+---
+
+## 2. 目标(首版)
+
+1. **env 切换**单笔期权模式:`usdc`(现状) ↔ `coin`(币本位 + USDT↔ETH/BTC 桥).  
+2. **币本位开仓**:按交易账户 USDT 预算 **先买满现货** → 再用币 **尽量开满** 期权(不按权利金精算买币数量).  
+3. **币本位平仓**:期权卖出成功后,**自动现货市价**把剩余标的币卖回 USDT.  
+4. **USDT 全仓复利**:每轮预算默认 = 交易账户 USDT × 缓冲(0.95);赚留在交易户则下一轮自动变大;减规模靠 **人工转走**.  
+5. **可选单笔上限**:开关默认 **关闭**;开启后 `min(账户×0.95, N U)`.  
+6. **有未平单笔期权或桥流程半成品时,拒绝切换模式**.  
+7. **对冲计划**继续只走 USDC 路径;币本位模式下对冲开仓保持不可用或明确提示未支持.
+
+---
+
+## 3. 不做(首版外)
+
+- 对冲计划(永期/期期)币本位腿或双模式混开  
+- 盘中按单笔切换本位(必须 env + 重启/无仓校验)  
+- 按权利金精确计算后再买现货(明确不做;见 §5)  
+- 自动把资金账户 USDT 划入交易账户(首版只读 **交易账户** 可用 USDT;不足则提示人工划转)  
+- 市价平期权(继续沿用现有「买一限价、禁市价平」纪律,除非另改总则)  
+- 多笔并行单笔期权仓(维持「一次一仓」)  
+- 中控代下币本位期权
+
+---
+
+## 4. 模式开关与互斥
+
+### 4.1 env(草案)
+
+| 变量 | 含义 | 默认 |
+|------|------|------|
+| `OKX_OPTIONS_MARGIN_MODE` | `usdc` \| `coin` | `usdc` |
+| `OKX_OPTIONS_TRADE_BUDGET_USDC` | USDC 模式单笔权利金预算上限(现有) | `10` |
+| `OKX_OPTIONS_BUDGET_BUFFER` | 预算缓冲(现有,币本位复利亦用) | `0.95` |
+| `OKX_OPTIONS_COIN_COMPOUND` | 币本位是否按交易户 USDT 复利 | `true`(建议默认开) |
+| `OKX_OPTIONS_COIN_BUDGET_USDT` | 复利关闭时的固定 USDT 预算;或作展示参考 | `10` |
+| `OKX_OPTIONS_COIN_MAX_USDT_ENABLED` | 单笔不超过 N U 开关 | `false`(**默认关**) |
+| `OKX_OPTIONS_COIN_MAX_USDT` | 上限 N(仅开关开启时生效) | 如 `50`(可改) |
+
+说明:
+
+- **主路径(复利开 + 上限关)**:`budget_usdt = trading_usdt_available × OKX_OPTIONS_BUDGET_BUFFER`.  
+- **上限开**:`budget_usdt = min(上式, OKX_OPTIONS_COIN_MAX_USDT)`.  
+- **复利关**:`budget_usdt = OKX_OPTIONS_COIN_BUDGET_USDT × buffer`(或直接固定值,实现时二选一写死一种,避免歧义;推荐 `固定值 × buffer` 与现 USDC 习惯一致).
+
+### 4.2 切换门禁
+
+| 条件 | 行为 |
+|------|------|
+| 本地/交易所存在未平 **单笔期权** 持仓 | **拒绝**切换 `usdc`↔`coin` |
+| 存在未完成桥状态(已买币未开期权、已平期权未卖回 USDT 等) | **拒绝**切换 |
+| 对冲计划运行中 | **不阻断**单笔模式切换,但币本位下对冲仍不可开新币本位腿;UI 标明对冲仅 USDC |
+| 无仓且无半成品 | 允许改 env 并重启后生效 |
+
+启动或保存配置时若检测到「模式与当前持仓族不一致」,应拒绝进入交易或强制只读提示,避免按错误货币计价.
+
+---
+
+## 5. 币本位资金桥与开平流水
+
+### 5.1 开仓(先买满,再开满)
+
+```
+1. 读取交易账户 USDT 可用
+2. 计算 budget_usdt(§4.1)
+3. 现货市价:用约 budget_usdt 买入标的币(ETH 或 BTC,与所选期权一致)
+4. 用账户中可用于权利金的标的币,按卖一限价尽量开满币本位期权
+   - 受:最小张数、卖一深度、单笔一仓规则约束
+   - 不要求「币数量精确等于权利金」;允许开满后仍残留部分币
+5. 本地记录本轮:模式=coin、budget_usdt、买入币数量/成本、期权成交、桥状态=holding
+```
+
+### 5.2 平仓(先平期权,再卖回 USDT)
+
+```
+1. 按现有纪律买一限价卖出期权(可分批深度)
+2. 期权仓清零(或本轮目标完成)后:
+   现货市价卖出账户内「本桥残留 + 平仓回收」相关标的币 → USDT
+3. 桥状态=closed;交易账户 USDT 更新 → 下一轮自动按新余额复利
+```
+
+### 5.3 失败回滚(必须)
+
+| 失败点 | 处理 |
+|--------|------|
+| 现货买入失败 | 不开期权;报错 |
+| 现货买入成功、期权开仓失败/无卖一 | **自动市价卖回 USDT**;桥状态回滚;告警 |
+| 期权平仓成功、现货卖回失败 | 持仓显示/告警 **「待卖回 USDT」**;提供仅重试卖币接口;拒绝新开仓直至清理 |
+| 半成品状态下进程重启 | 启动扫描未完成桥,提示或自动尝试卖回 |
+
+---
+
+## 6. 复利与「人工转走」
+
+### 6.1 口径
+
+- **加仓/放大**:利润留在 **交易账户 USDT**,下一轮 `×0.95` 自动变大(例:10U 一轮后约 20U → 下一轮约 19U 预算).  
+- **缩小**:运营者 **人工** 将 USDT 转出交易账户(划转到资金账户/提现/他用);系统不自动「复位到 10U」.  
+- **单笔上限开关**(`OKX_OPTIONS_COIN_MAX_USDT_ENABLED`):  
+  - **默认关闭** → 纯靠人工转走控规模.  
+  - **开启** → `min(账户×0.95, N)`，防止单笔过大.
+
+### 6.2 与永续「全仓」的关系
+
+思想同类(吃可用 × 缓冲),但资产不同:
+
+- 永续全仓:USDT 保证金 × 杠杆 → 合约名义  
+- 币本位单笔:USDT × 缓冲 → 现货币 → 期权权利金  
+
+**不要**复用 `POSITION_SIZING_MODE=full_margin` 直接驱动期权;用 §4.1 独立开关,避免永续模式与期权桥耦合.
+
+### 6.3 一次一仓
+
+复利放大后必须坚持:**同时仅一个单笔期权仓**.新开前检查无持仓、无「待卖回」半成品.
+
+---
+
+## 7. 产品与 UI
+
+### 7.1 模式可见性
+
+- 顶栏或期权设置页展示当前:`单笔期权模式: USDC / 币本位`.  
+- 币本位时展示:交易户 USDT、本轮预估预算(`×0.95` 与是否触达 N 上限)、桥状态.  
+- USDC 模式保持现有 USDC 余额与预算展示.
+
+### 7.2 开仓按钮文案(示例)
+
+- 币本位:`买币并开仓(预算 ≈ xx USDT)`  
+- 确认框写明:将市价买 ETH/BTC → 限价买期权;失败会尝试卖回 USDT.
+
+### 7.3 对冲
+
+- 币本位模式下:对冲计划入口保持「仅 USDC / 未支持币本位」禁用或只读测算.  
+- 不在此模式自动把对冲预算改成 USDT 桥.
+
+### 7.4 复盘字段(建议)
+
+单笔 round-trip 尽量可拆:
+
+- 期权腿盈亏(币或折合 USDT)  
+- 桥兑换盈亏(买币成本 vs 卖币回收)  
+- 合计 USDT 变化(对复利最有意义)
+
+首版若难拆细,至少记录:**开仓前 USDT、平仓卖币后 USDT、差值**.
+
+---
+
+## 8. 技术要点
+
+### 8.1 合约与报价
+
+- USDC 模式:继续 `ETH-USD_UM` / `BTC-USD_UM` 等现有路径.  
+- 币本位模式:走 OKX **币本位期权**合约族(实现时以 OKX/ccxt 实际 `instId`/settle 为准,写入适配层,勿与 UM 混用同一计价假设).  
+- 权利金与张数换算按币本位规则单独实现;复用「卖一开、买一平、深度校验」状态机,不复用 USDC 金额公式硬套.
+
+### 8.2 模块建议
+
+| 块 | 职责 |
+|----|------|
+| 模式读取 + 门禁 | env、有仓拒切、启动一致性 |
+| `options_spot_bridge_lib`(名可调) | USDT↔币 市价买卖、回滚、待卖回重试 |
+| 开平编排 | 买满 → 开满 → 平 → 卖回 状态机 |
+| 定价/张数 | 币本位分支 |
+| UI/API | 预算预览、确认、半成品提示 |
+
+现货下单可与现有账户兑换/划转能力并列,但 **桥必须可自动、可回滚**,与「人工 USDT→USDC」不同.
+
+### 8.3 权限与账户
+
+- API 需具备:交易账户现货市价、期权开平.  
+- 预算只认 **交易账户 USDT**;资金账户有钱但交易户不足 → 明确提示先划转(首版不自动划).
+
+### 8.4 测试
+
+- 预算计算:复利开/关、上限开/关、余额边界.  
+- 状态机:开仓失败回滚卖币;平仓后卖币失败 → 待卖回 → 重试成功.  
+- 门禁:有仓切换拒绝;一次一仓.  
+- 回归: `margin_mode=usdc` 时行为与现网一致;对冲仍仅 USDC.
+
+---
+
+## 9. 验收标准
+
+1. `usdc` 模式:单笔期权行为与现网一致.  
+2. `coin` 模式:一轮开平后交易户 USDT 变化符合「买币→期权→卖币」;无异常残留币(或残留时必有待卖回告警).  
+3. 复利:人为把交易户从约 10U 做到约 20U 后,下一轮预览预算约为 `20×0.95`(上限关闭时).  
+4. 上限开关默认关;开启后预算不超过 N.  
+5. 有持仓或半成品时切换模式被拒绝.  
+6. 币本位下对冲不能误开币本位腿.  
+7. 开仓失败自动卖回 USDT,不留下无主现货.
+
+---
+
+## 10. 实现顺序建议
+
+1. 模式 env + 有仓/半成品门禁 + UI 展示当前模式  
+2. 现货桥(买/卖/回滚/待卖回) + 单测  
+3. 币本位合约适配 + 卖一开/买一平接入编排  
+4. 复利预算预览与开仓确认  
+5. 上限开关  
+6. 文档:`期权用法.md` 增补币本位章节;`更新文档.md` 记一笔  
+
+---
+
+## 11. 决策摘要(已拍板)
+
+| 决策 | 结论 |
+|------|------|
+| 对冲 | 暂不接币本位 |
+| 单笔模式 | env:`usdc` ↔ `coin` |
+| 有持仓切换 | **拒绝** |
+| 买币方式 | **先买满预算 USDT 对应的币,再开满期权**(不按权利金精算) |
+| 复利 | 交易账户 USDT × 0.95;人工转走控规模 |
+| 单笔不超过 N U | **独立开关,默认关闭** |
+| 动机 | 币本位流动性往往优于 USDC,利于成交 |
+
+---
+
+## 12. 风险与说明
+
+- 现货双边手续费与滑点会吃掉部分「名义预算」;小资金下占比更明显.  
+- 持仓期间若账户内残留标的币,平仓卖回时含现货汇率盈亏,需与期权腿区分看待.  
+- 流动性优势随到期、行权、标的变化,不保证每一张合约都厚于 USDC;开仓仍以当场卖一深度为准.  
+- 本方案不改变「符合机会才做、不符合就等」的交易纪律;仅改单笔期权的资金路径与合约族.