crypto_monitor/docs/期权方案.md

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）

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