crypto_monitor/docs/OKX单笔期权-币本位与USDT桥-开发方案.md

OKX 单笔期权 · 币本位模式（USDT 桥 + 复利）— 开发方案

状态:已实现首版(按本文落地;改需求先改本文).
范围:crypto_monitor_okx 单笔期权开平 + 中控对 OKX 期权只读字段(能识别币本位);对冲计划(永期/期期)不接币本位.
硬约束:本次不改 Gate(不改 crypto_monitor_gate/、不改 Gate 专用模板/静态/测试;共享 lib 若动刀不得改变 Gate 启动与交易行为).
相关:期权方案.md · 期权用法.md · 期权开平仓与监控说明.md · position-sizing-mode.md · 更新文档.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 路径;币本位模式下对冲开仓保持不可用或明确提示未支持.
8. 中控不代下期权单,但监控/快照/持仓卡片等 只读字段须能识别币本位(见 §7.5).
9. 不涉及 Gate 任何业务改动.

---

3. 不做(首版外)

• 对冲计划(永期/期期)币本位腿或双模式混开
• 盘中按单笔切换本位(必须 env + 重启/无仓校验)
• 按权利金精确计算后再买现货(明确不做;见 §5)
• 自动把资金账户 USDT 划入交易账户(首版只读 交易账户 可用 USDT;不足则提示人工划转)
• 市价平期权(继续沿用现有「买一限价、禁市价平」纪律,除非另改总则)
• 多笔并行单笔期权仓(维持「一次一仓」)
• 中控代下 / 中控内嵌开平仓按钮触发币本位或 USDC 期权下单(开平仍只在 OKX 实例页)
• 任何 Gate 相关改动(含为「顺便统一」去动 Gate 模板或共享路径上的 Gate 分支)

---

4. 模式开关与互斥

4.1 env(草案)

变量	含义	默认
OKX_OPTIONS_MARGIN_MODE	usdc | coin	coin
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、差值.

7.5 中控只读(要做)与不下单(不做)

中控保持现有分工:监控只读 + 点「期权」进 OKX 实例操作;本方案不在中控增加开平仓/买币桥按钮.

只读侧须能区分并展示币本位,避免仍按「一律 USDC 权利金」误读.实例上报快照/期权字段建议至少包含:

字段(名可调)	含义
options_margin_mode	usdc | coin
持仓行可辨本位	合约族/结算币/标签,卡片上能看出「币本位」或「USDC」
币本位时预算口径	可选:交易户 USDT、本轮 ×0.95 预估预算、是否触达 N 上限
桥状态(若有半成品)	如 holding / pending_sell_spot(待卖回 USDT),中控只展示与告警,不代执行

展示落点(与现网对齐即可,不新开中控交易页):

• OKX 账户监控里的期权区块 / 期权持仓卡片
• 推给教练等用的监控快照文案(若已注入期权行,须带本位标记,避免 AI/人工当成 USDC)

**不做:**中控代下单、中控触发买 ETH/卖 ETH、中控改 env 切模式.

---

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	预算预览、确认、半成品提示
中控只读	消费实例快照中的 options_margin_mode 等字段;卡片/文案可识别币本位;无下单 API
Gate	不纳入;禁止为本次需求修改 Gate 树

现货下单可与现有账户兑换/划转能力并列,但 桥必须可自动、可回滚,与「人工 USDT→USDC」不同.

共享 lib/options* / 快照序列化若调整:仅扩展 OKX 期权载荷;Binance/Gate 账户快照路径保持原样.

8.3 权限与账户

• API 需具备:交易账户现货市价、期权开平.
• 预算只认 交易账户 USDT;资金账户有钱但交易户不足 → 明确提示先划转(首版不自动划).

8.4 测试

• 预算计算:复利开/关、上限开/关、余额边界.
• 状态机:开仓失败回滚卖币;平仓后卖币失败 → 待卖回 → 重试成功.
• 门禁:有仓切换拒绝;一次一仓.
• 回归: margin_mode=usdc 时行为与现网一致;对冲仍仅 USDC.
• 中控只读:快照含本位字段时卡片/文案可区分 usdc/coin.
• Gate:本次 diff 不应出现 crypto_monitor_gate/ 业务文件变更.

---

9. 验收标准

1. usdc 模式:单笔期权行为与现网一致.
2. coin 模式:一轮开平后交易户 USDT 变化符合「买币→期权→卖币」;无异常残留币(或残留时必有待卖回告警).
3. 复利:人为把交易户从约 10U 做到约 20U 后,下一轮预览预算约为 20×0.95(上限关闭时).
4. 上限开关默认关;开启后预算不超过 N.
5. 有持仓或半成品时切换模式被拒绝.
6. 币本位下对冲不能误开币本位腿.
7. 开仓失败自动卖回 USDT,不留下无主现货.
8. 中控:无期权下单入口新增;监控/快照/持仓只读能看出当前为币本位或 USDC.
9. Gate:无相关代码改动;Gate 实例行为与改前一致.

---

10. 实现顺序建议

1. 模式 env + 有仓/半成品门禁 + OKX 实例 UI 展示当前模式
2. 现货桥(买/卖/回滚/待卖回) + 单测
3. 币本位合约适配 + 卖一开/买一平接入编排
4. 复利预算预览与开仓确认
5. 上限开关
6. 快照字段上报 + 中控只读识别币本位(卡片/文案;不下单)
7. 文档:期权用法.md 增补币本位章节;更新文档.md 记一笔

---

11. 决策摘要(已拍板)

决策	结论
对冲	暂不接币本位
单笔模式	env:usdc ↔ coin
有持仓切换	拒绝
买币方式	先买满预算 USDT 对应的币,再开满期权(不按权利金精算)
复利	交易账户 USDT × 0.95;人工转走控规模
单笔不超过 N U	独立开关,默认关闭
中控	不下单;只读字段/快照能识别币本位
Gate	本次不改
动机	币本位流动性往往优于 USDC,利于成交

---

12. 风险与说明

• 现货双边手续费与滑点会吃掉部分「名义预算」;小资金下占比更明显.
• 持仓期间若账户内残留标的币,平仓卖回时含现货汇率盈亏,需与期权腿区分看待.
• 流动性优势随到期、行权、标的变化,不保证每一张合约都厚于 USDC;开仓仍以当场卖一深度为准.
• 本方案不改变「符合机会才做、不符合就等」的交易纪律;仅改单笔期权的资金路径与合约族.