dekun/crypto_monitor
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge OKX dual APIs into one OKX_API_* account for perp and options.

Browse Source 
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
dekun
2026-08-05 21:28:33 +08:00
parent 22e6b68e6d
commit 09a763e47d
26 changed files with 166 additions and 473 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/env配置说明.md
+4 -5
View File
@@ -61,14 +61,14 @@ Binance / Gate 无期权模块时,第三列最后一格不显示或显示「本
| 中文名 | 说明 | 重启 |
|--------|------|------|
| 开启实盘下单 | 关闭时仅走本地流程,不向交易所发单 | 需重启 |
| API Key | 永续子账户 API Key | 需重启 |
| API Secret | 永续子账户 Secret | 需重启 |
| API Key | 账户 API Key(永续+期权共用) | 需重启 |
| API Secret | 账户 API Secret | 需重启 |
| API Passphrase | 仅 OKX 显示 | 需重启 |
| 保证金模式 | 全仓 / 逐仓 | 需重启 |
| 持仓模式 | 双向 / 单向净持仓等(按所) | 需重启 |
| 仓位查询类型 | 仅 OKX:如 SWAP | 需重启 |
| 账户备注 | 企业微信推送中显示的交易所备注 | 保存即生效 |
| 显示永续资金 | 仅 OKX:关闭后顶栏隐藏永续资金账户与交易账户,总资金仅计期权侧 | 保存即生效 |
| 显示永续资金 | 仅 OKX:关闭后顶栏隐藏 USDT 资金/交易账户,总资金仅计期权 USDC 侧 | 保存即生效 |
**本卡片不包含**:网页登录账号密码,是否关闭登录校验,中控通信密钥.
@@ -170,8 +170,7 @@ AI 相关环境变量(`AI_PROVIDER`,`OPENAI_*`,`OLLAMA_*`,`AI_MODEL`,`AI_TIMEOUT
| 中文名 | 说明 |
|--------|------|
| 启用期权模块 | |
| 期权 API Key / Secret / Passphrase | 主账户,与永续子账户分离 |
| 启用期权模块 | 与永续共用 `OKX_API_*`;不再单独配置期权密钥 |
| 期权账户备注 | |
| 单笔预算(USDC) | |
| 预算缓冲比例 | |
docs/对冲计划开发方案.md
+3 -3
View File
@@ -12,8 +12,8 @@
| 产品名 | 英文键 | 含义 |
|--------|--------|------|
| **永期对冲** | `perp_options` | 永续(子账户) + 买方期权(主账户) |
| **期期对冲** | `options_options` | 主账户内两条买方期权腿 |
| **永期对冲** | `perp_options` | 同账户永续 + 买方期权 |
| **期期对冲** | `options_options` | 同账户内两条买方期权腿 |
页面/导航展示用中文名;API/DB 用英文键.
@@ -217,7 +217,7 @@
| 侧 | 来源 |
|----|------|
| 永续行情/规格 | OKX 子账户 ccxt:ticker + 现有 `/api/hub/market` 规格逻辑 |
| 永续行情/规格 | OKX 账户 ccxt:ticker + 现有 `/api/hub/market` 规格逻辑 |
| 期权链 | `build_option_chain` / `/api/options/chain`(本实例直连,无需中控代理) |
| 指数价 | 期权 `index_px`,左右对齐 |
docs/对冲计划策略与P0校验.md
+2 -2
View File
@@ -9,8 +9,8 @@
| 类型 | 账户 | 作用 |
|------|------|------|
| **永期对冲** | 永续子账户 + 期权主账户买方 | 全仓做方向,期权买保险 |
| **期期对冲** | 仅期权主账户双买方 | 目标价兑现盈利腿,亏损腿到期 |
| **永期对冲** | 同账户永续 + 期权买方 | 全仓做方向,期权买保险 |
| **期期对冲** | 同账户双买方期权 | 目标价兑现盈利腿,亏损腿到期 |
### 永期结束与统计
docs/期权对冲方案分析.md
+4 -4
View File
@@ -1,15 +1,15 @@
# 期权对冲方案分析
> 适用范围:OKX **永续子账户**(USDT 本位) + **期权主账户**(USDⓈ 本位买方).
> 适用范围:OKX **同一账户**(`OKX_API_*`):USDT 永续 + USDⓈ 期权买方.
> 本文档为 **策略与操盘说明**,非系统自动下单功能;组合须 **人工** 在永续页与期权页分别执行.
---
## 1. 前提与账户分工
| 维度 | 永续合约(子账户) | 期权(主账户) |
|------|------------------|--------------|
| API | `OKX_API_*` | `OKX_OPTIONS_API_*` |
| 维度 | 永续合约 | 期权 |
|------|----------|------|
| API | `OKX_API_*`(swap 客户端) | `OKX_API_*`(option 客户端) |
| 系统页面 | 实盘下单 / 关键位 / 策略 | 期权 |
| 保证金 | USDT | USDC / USDG |
| 本系统能力 | 开平仓、止损、关键位 | **仅买方** 开平仓,无组合单 |
docs/期权方案.md
+26 -99
View File
@@ -1,15 +1,15 @@
# OKX 期权模块 — 技术方案
> 适用范围:`crypto_monitor_okx` 实例;与永续子账户并行,不新增 PM2 进程.
> 适用范围:`crypto_monitor_okx` 实例;永续与期权共用同一套 `OKX_API_*`,不新增 PM2 进程.
## 1. 目标
在现有 OKX 监控实例中增加 **USDⓈ 本位期权(买方)** 能力:
- 永续/关键位:继续走 **子账户 API-A**(现有 `OKX_API_*`)
- 期权:走 **主账户 API-B**(`OKX_OPTIONS_API_*`)
- 资金展示对齐 OKX:**资金账户 / 交易账户**,分币种显示 USDT,USDC,USDG
- 支持 **手动 USDT→USDC 兑换** 与 **USDC 账户划转**
- 永续/关键位与期权:**同一账户 API**(`OKX_API_*`)
- 两个 ccxt 客户端:`exchange`(defaultType=swap)与 `exchange_options`(defaultType=option),身份相同
- 顶栏资金:**资金账户/交易账户=USDT**;**期权资金/期权交易=USDC**
- 支持 **手动 USDT→USDC 兑换** 与 **账户内划转**(无主↔子划转)
- **无总资金池上限**;单笔权利金上限可配置(默认 10 USDC)
## 2. 交易规则(硬约束)
@@ -32,8 +32,8 @@
```
crypto_okx(单 PM2)
├── exchange (swap) ← OKX_API_* 子账户
└── exchange_options ← OKX_OPTIONS_API_* 主账户
├── exchange (swap) ← OKX_API_*
└── exchange_options (option)← 同一套 OKX_API_*
lib/options/
├── okx_options_lib.py # 封装于 lib/exchange/
@@ -43,109 +43,36 @@ lib/options/
└── options_register.py # 路由 + 监控线程
```
**隔离:** 期权模块只调用 `exchange_options`;永续逻辑只调用 `exchange`.
**说明:** `defaultType` 分离避免错路由;密钥身份唯一.旧 `OKX_OPTIONS_API_*` 已废弃.
## 4. 资金与兑换
### 4.1 展示(期权页顶栏)
### 4.1 展示(实例顶栏)
| 账户 | 币种 |
|------|------|
| 资金账户 | USDT,USDC(若有) |
| 交易账户 | USDT,USDC,USDG(若有) |
- **资金账户 / 交易账户**:USDT(永续侧)
- **期权资金账户 / 期权交易账户**:USDC
- 总资金:USDT + USDC(1:1),同账户 USDT 不重复累加期权侧 USDT
不展示「练手池」等抽象记账名称.
### 4.2 兑换与划转
### 4.2 推荐操作流程
- 系统设置「币种兑换」:资金账户内 USDT ↔ USDC
- 「期权划转」:同账户 funding ↔ trading(USDC/USDT)
- **已移除**主↔子账户划转
```
资金账户 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`)
## 5. 环境变量(要点)
```bash
OKX_OPTIONS_ENABLED=false
OKX_OPTIONS_API_KEY=
OKX_OPTIONS_API_SECRET=
OKX_OPTIONS_API_PASSPHRASE=
OKX_OPTIONS_ACCOUNT_LABEL=主账户·期权
OKX_API_KEY=
OKX_API_SECRET=
OKX_API_PASSPHRASE=
OKX_OPTIONS_ENABLED=true
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
OKX_OPTIONS_CLOSE_RECYCLE_MULT=2
OKX_OPTIONS_CLOSE_HOLD_SECONDS=120
# 平仓限价挂单超时自动撤(秒),默认 600=10 分钟;联调可临时改 60
OKX_OPTIONS_PENDING_TTL_SECONDS=600
OKX_OPTIONS_ACCOUNT_LABEL=账户·期权
```
平仓执行:**只锁买一限价**,说明见 [期权开平仓与监控说明.md](./期权开平仓与监控说明.md);线上 `/options/guide`.
详见 [env配置说明.md](./env配置说明.md) 与 `.env.example`.
修改 `.env` 后须 `pm2 restart crypto_okx`.
## 6. 相关文档
## 6. 数据库
### `options_trades`
记录本地开仓/平仓,权利金,翻倍提醒状态.
### `options_convert_log` / `options_transfer_log`
可选记录兑换与划转操作.
## 7. HTTP 路由
| 方法 | 路径 |
|------|------|
| GET | `/options` |
| GET | `/options/guide` | 开平仓与监控说明(独立页) |
| 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`
- [期权用法.md](./期权用法.md)
- [对冲计划开发方案.md](./对冲计划开发方案.md)
docs/期权用法.md
+23 -82
View File
@@ -2,37 +2,37 @@
## 1. 前置条件
1. OKX **主账户**已开通期权(USDⓈ 本位),且 App 中可见 `ETHUSD UM` / `BTCUSD UM`.
2. 在 `crypto_monitor_okx/.env` 配置 **期权专用 API**(与永续子账户分开):
1. OKX 账户已开通期权(USDⓈ 本位),且 App 中可见 `ETHUSD UM` / `BTCUSD UM`.
2. 在 `crypto_monitor_okx/.env` 配置 **唯一账户 API**(永续与期权共用):
```bash
OKX_API_KEY=你的账户Key
OKX_API_SECRET=...
OKX_API_PASSPHRASE=...
OKX_OPTIONS_ENABLED=true
OKX_OPTIONS_API_KEY=你的主账户Key
OKX_OPTIONS_API_SECRET=...
OKX_OPTIONS_API_PASSPHRASE=...
```
3. 重启实例:`pm2 restart crypto_okx`
3. 重启实例:`pm2 restart crypto_okx --update-env`
> 永续仍用原有 `OKX_API_*`(子账户);期权只用 `OKX_OPTIONS_API_*`(主账户).
> 旧 `OKX_OPTIONS_API_*` 已废弃.若仅残留 OPTIONS 键而 `OKX_API_*` 为空,启动会自动回填.
## 2. 资金准备
期权权利金使用 **USDC 或 USDG**,不能直接用 USDT 买入.
期权权利金使用 **USDC**,不能直接用 USDT 买入.
### 推荐步骤
1. 打开 **期权** 页,查看顶栏:
- **资金账户**:USDT 余额
- **交易账户**:USDC 余额(买期权从这里扣)
1. 查看顶栏:
- **资金账户 / 交易账户**:USDT
- **期权资金账户 / 期权交易账户**:USDC
2. **币种兑换**(资金账户内)
- 从 USDT 兑换为 USDC
- 先点 **询价**,确认预估获得量后点 **确认兑换**
3. **账户划转**
3. **账户内划转**
- 从:资金账户 → 到:交易账户
- 币种:USDC
- 将兑换得到的 USDC 划到交易账户
4. 确认 **交易账户 USDC** 足够支付本笔权利金
4. 确认 **期权交易账户 USDC** 足够支付本笔权利金
系统 **不会** 自动兑换或划转,避免误动资金.
@@ -85,82 +85,23 @@ OKX_OPTIONS_API_PASSPHRASE=...
## 6. 与永续 / 对冲计划的关系
| | 永续(子账户) | 期权(主账户) |
|--|----------------|----------------|
| API | `OKX_API_*` | `OKX_OPTIONS_API_*` |
| | 永续 | 期权 |
|--|------|------|
| API | `OKX_API_*`(同一套) | `OKX_API_*`(同一套) |
| 页面 | 实盘下单 / 关键位 | 期权 · 对冲计划 |
| 资金顶栏 | USDT 资金户+交易户 | 期权页单独显示 USDC 等 |
两套资金 **不合并** 显示.
| 顶栏 | USDT 资金户+交易户 | USDC 期权资金+期权交易 |
**期期对冲张数**(对冲计划页,与单独开期权共用预算算法):
| 模式 | 说明 |
|------|------|
| 同张数(默认) | 两腿同 `n`,总权利金 ≤ 预算 |
| 做多 | Call:Put 按主腿占比(默认 7:3) |
| 做空 | Put:Call 按主腿占比(默认 7:3) |
| 按比例 | 主腿/次腿按 `HEDGE_PLAN_OO_BIAS_*` |
拆分口径与比例见 env:`HEDGE_PLAN_OO_BIAS_SPLIT_BY`(`budget` 默认 / `sheets`=先算同张数总张数 `2n` 再拆)、`HEDGE_PLAN_OO_BIAS_RATIO`(默认 `0.7`)。细则见 [对冲计划开发方案.md](./对冲计划开发方案.md) §4.1、[系统说明.md](./系统说明.md)。
## 7. 常见问题
## 7. 配置说明
**Q:以前的期权专用密钥还要配吗?**
- 不需要.统一写到 `OKX_API_*`.
| 变量 | 默认 | 含义 |
|------|------|------|
| `OKX_OPTIONS_TRADE_BUDGET_USDC` | 10 | 单笔权利金上限 |
| `OKX_OPTIONS_BUDGET_BUFFER` | 0.95 | 算张数时预留 5% 缓冲 |
| `OKX_OPTIONS_MAX_DTE_DAYS` | 2 | 最多选几天内到期 |
| `OKX_OPTIONS_ITM_MAX_DIST_USD` | 30 | 轻度实值:价内不超过多少 USD |
| `OKX_OPTIONS_PROFIT_ALERT_RATIO` | 1.0 | 浮盈/权利金 ≥ 此值推送 |
| `HEDGE_PLAN_OO_BIAS_SPLIT_BY` | budget | 期期做多/做空:按预算或按张数拆 |
| `HEDGE_PLAN_OO_BIAS_RATIO` | 0.7 | 期期做多/做空主腿占比 |
## 8. 期权复盘(含对冲)
仅 **OKX** 实例提供独立页 **期权复盘**(`/options/review`),与合约「交易记录与复盘」完全隔离.
### 数据来源
| 类型 | source_type | 来源 | 粒度 |
|------|-------------|------|------|
| 纯期权 | `option_spot` | 本地 `options_trades` 已平仓 | 一仓一条 |
| 永期对冲 | `perp_options` | 本地 `hedge_plans` 且 `status=closed` | **一计划一条** |
| 期期对冲 | `options_options` | 同上 | **一计划一条** |
- 打开复盘页即自动读取本地记录,**不访问交易所**.
- 对冲盈亏主口径:`realized_pnl_total`;详情另显永续/期权分项.
- 若某纯期权 `inst_id` 已出现在对冲腿中,默认标记排除,避免总盈亏双计.
- 人工复盘字段存在 `options_review_entries`,刷新本地源**不会覆盖**.
### 图片
- 目录:`static/images/options_journal/`
- 文件名:`options_journal_{draftId}_{5m|15m|1h|4h}.ext`(与合约复盘同周期槽位)
- 备份时与 `crypto.db` 一并打包即可;勿与合约 `journal_*` 截图混用.
### 页面
顶部三个 Tab:**期权交易记录** / **期期对冲记录** / **永期对冲记录**.点击列表行后在下方打开「复盘记录上传」,支持四周期即时截图与情绪标签.
### 统计
同页 KPI + 分组:类型、标的、策略标签、对冲结束原因、持有周期、Call/Put.策略维度仅统计已填策略标签的记录.
## 9. 常见问题
**Q:为什么买不了?**
- 交易账户 USDC 不足 → 先兑换再划转
- 卖一价过高,10U 预算买不到 1 张 → 选更便宜合约或提高 `OKX_OPTIONS_TRADE_BUDGET_USDC`
- 期权 API 未配置或 `OKX_OPTIONS_ENABLED=false`
**Q:报价 15 是每张 15U 吗?**
- 不是.15 是 **每 1 ETH** 的报价;每张(0.01 ETH)约 0.15 USDC.
**Q:子账户能开期权吗?**
- 本系统期权走主账户 API;子账户永续不受影响.
## 10. 风险说明
- 买方最大亏损为 **权利金**;近期实值仍会时间衰减
- 限价单可能因无流动性未成交
- 请先在小额下验证兑换,划转,开平仓全流程
**Q:还能主↔子划转吗?**
- 已移除.只保留同账户内划转与币种兑换.
docs/系统设置说明.md
+1 -1
View File
@@ -84,7 +84,7 @@
### 用途
在 **子账户永续** 场景下,于 **资金账户(funding)** 与 **交易账户(swap)** 之间手动划转 USDT.
在 **OKX 账户** 场景下,于 **资金账户(funding)** 与 **交易账户(swap)** 之间手动划转 USDT.
### 与 env 配置的关系