From 2028251fc1477b3057a68dbc6a635ca16705e91d Mon Sep 17 00:00:00 2001 From: dekun Date: Thu, 20 Aug 2026 11:46:04 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3:=E6=96=B0=E5=A2=9EOKX?= =?UTF-8?q?=E5=8D=95=E7=AC=94=E6=9C=9F=E6=9D=83=E5=B8=81=E6=9C=AC=E4=BD=8D?= =?UTF-8?q?=E4=B8=8EUSDT=E6=A1=A5=E5=BC=80=E5=8F=91=E6=96=B9=E6=A1=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Cursor --- docs/OKX单笔期权-币本位与USDT桥-开发方案.md | 241 ++++++++++++++++++++ 1 file changed, 241 insertions(+) create mode 100644 docs/OKX单笔期权-币本位与USDT桥-开发方案.md diff --git a/docs/OKX单笔期权-币本位与USDT桥-开发方案.md b/docs/OKX单笔期权-币本位与USDT桥-开发方案.md new file mode 100644 index 0000000..f6c0074 --- /dev/null +++ b/docs/OKX单笔期权-币本位与USDT桥-开发方案.md @@ -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;开仓仍以当场卖一深度为准. +- 本方案不改变「符合机会才做、不符合就等」的交易纪律;仅改单笔期权的资金路径与合约族.