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

> 状态:**已实现首版**(按本文落地;改需求先改本文).  
> 范围:**`crypto_monitor_okx` 单笔期权开平** + **中控对 OKX 期权只读字段**(能识别币本位);对冲计划(永期/期期)**不接币本位**.  
> **硬约束:本次不改 Gate**(不改 `crypto_monitor_gate/`、不改 Gate 专用模板/静态/测试;共享 `lib` 若动刀不得改变 Gate 启动与交易行为).  
> 相关:[期权方案.md](./期权方案.md) · [期权用法.md](./期权用法.md) · [期权开平仓与监控说明.md](./期权开平仓与监控说明.md) · [position-sizing-mode.md](./position-sizing-mode.md) · [更新文档.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`(可改) |
| `OKX_OPTIONS_COIN_SPOT_BUY_BUFFER` | 现货买入相对权利金倍数(也可写 `0.10`=+10%) | `1.10` |

开仓买币:**先按预算估最大可开张数 → 买币 USDT ≈ 张数×卖一权利金×现货缓冲**,不全额把预算换成币。

说明:

- **主路径(复利开 + 上限关)**:`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;开仓仍以当场卖一深度为准.  
- 本方案不改变「符合机会才做、不符合就等」的交易纪律;仅改单笔期权的资金路径与合约族.