# 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
```

修改 `.env` 后须 `pm2 restart crypto_okx`。

## 6. 数据库

### `options_trades`

记录本地开仓/平仓、权利金、翻倍提醒状态。

### `options_convert_log` / `options_transfer_log`

可选记录兑换与划转操作。

## 7. HTTP 路由

| 方法 | 路径 |
|------|------|
| GET | `/options` |
| 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`