From 5ae24effd360f2a6335045ccb40957474949ca40 Mon Sep 17 00:00:00 2001
From: Administrator <15274802129@163.com>
Date: Wed, 24 Jun 2026 14:39:52 +0800
Subject: [PATCH] feat(okx): 添加OKX私有频道WebSocket处理器和API文档
---
src/main/java/com/xcong/excoin/modules/okxApi/OkxConfig.java | 162 +++++++++++++++++++++++++++++++++---------------------
1 files changed, 99 insertions(+), 63 deletions(-)
diff --git a/src/main/java/com/xcong/excoin/modules/gateApi/GateConfig.java b/src/main/java/com/xcong/excoin/modules/okxApi/OkxConfig.java
similarity index 75%
rename from src/main/java/com/xcong/excoin/modules/gateApi/GateConfig.java
rename to src/main/java/com/xcong/excoin/modules/okxApi/OkxConfig.java
index 81e2209..4b6e74b 100644
--- a/src/main/java/com/xcong/excoin/modules/gateApi/GateConfig.java
+++ b/src/main/java/com/xcong/excoin/modules/okxApi/OkxConfig.java
@@ -1,21 +1,31 @@
-package com.xcong.excoin.modules.gateApi;
+package com.xcong.excoin.modules.okxApi;
import java.math.BigDecimal;
import java.util.ArrayList;
import java.util.List;
/**
- * Gate 交易模块全局配置，策略的唯一参数入口。
+ * OKX 交易模块全局配置，策略的唯一参数入口。
*
* <h3>定位</h3>
* 通过 Builder 模式将所有运行参数集中管理，避免策略参数散落在多个类中。
* 运行时动态参数（step、gridElements、baseLongTraderParam、baseShortTraderParam）
- * 由 {@link GateGridTradeService} 在策略执行过程中写入。
+ * 由 OkxGridTradeService 在策略执行过程中写入。
+ *
+ * <h3>与 GateConfig 的主要差异</h3>
+ * <ul>
+ * <li>新增 {@code passphrase} 字段 — OKX API 认证需要 passphrase</li>
+ * <li>REST 基础路径：生产环境 {@code https://www.okx.com}，测试环境 {@code https://www.okx.cab}</li>
+ * <li>WebSocket 分为 public/private 两个地址</li>
+ * <li>合约格式：{@code ETH-USDT-SWAP}（OKX 用短横线分隔）</li>
+ * <li>持仓模式默认值：{@code long_short_mode}（OKX）替代 {@code dual}（Gate）</li>
+ * <li>数据模型（GridElement、TraderParam）复用 gateApi 包中的定义</li>
+ * </ul>
*
* <h3>参数分类</h3>
* <table>
* <tr><th>类别</th><th>参数</th><th>用途</th></tr>
- * <tr><td>认证</td><td>apiKey, apiSecret</td><td>REST/WS 签名认证</td></tr>
+ * <tr><td>认证</td><td>apiKey, apiSecret, passphrase</td><td>REST/WS 签名认证</td></tr>
* <tr><td>交易标的</td><td>contract, leverage, quantity, contractMultiplier</td><td>合约、杠杆、张数、乘数</td></tr>
* <tr><td>持仓</td><td>marginMode, positionMode</td><td>全仓/逐仓、单向/双向</td></tr>
* <tr><td>网格策略</td><td>gridRate, gridQueueSize, priceScale</td><td>间距比例、队列容量、价格精度（交易所tick）</td></tr>
@@ -25,26 +35,17 @@
* <tr><td>运行时</td><td>step, gridElements, baseLongTraderParam, baseShortTraderParam</td><td>由策略动态填充</td></tr>
* </table>
*
- * <h3>priceScale 说明</h3>
- * 价格精度表示交易所允许的最小价格单位的小数位数：
- * <ul>
- * <li>XAU_USDT: tick=0.1 → priceScale=1</li>
- * <li>ETH_USDT: tick=0.01 → priceScale=2</li>
- * </ul>
- * 所有价格计算必须对齐到 tick 整数倍，否则 Gate API 返回
- * {@code invalid argument: trigger.price price is not an integer multiple of a price unit}。
- *
* <h3>gridElements 生命周期</h3>
* <ol>
* <li>项目启动时初始化为空 ArrayList</li>
- * <li>{@code tryGenerateQueues()} 中通过 {@code updateGridElements()} 填充，同时触发
+ * <li>队列生成逻辑中通过 {@code updateGridElements()} 填充，同时触发
* {@link GridElement#rebuildIndex(List)} 建立全局 O(1) 索引</li>
* <li>每次挂单/止盈操作后通过 {@link GridElement#refreshIndices()} 更新索引</li>
* </ol>
*
* @author Administrator
*/
-public class GateConfig {
+public class OkxConfig {
/**
* 未实现盈亏（unrealizedPnl）计价模式。
@@ -57,22 +58,32 @@
public enum PnLPriceMode {
/** 按最新成交价计算未实现盈亏 */
LAST_PRICE,
- /** 按标记价格计算未实现盈亏，需通过 {@link GateGridTradeService#setMarkPrice(BigDecimal)} 注入 */
+ /** 按标记价格计算未实现盈亏，需通过外部注入 */
MARK_PRICE
}
- /** Gate API v4 密钥 */
+ // ==================== 认证信息 ====================
+
+ /** OKX API v5 密钥 */
private final String apiKey;
- /** Gate API v4 签名密钥 */
+ /** OKX API v5 签名密钥 */
private final String apiSecret;
- /** 合约名称（如 XAU_USDT） */
+ /** OKX API v5 口令密码（passphrase），创建 API Key 时设置 */
+ private final String passphrase;
+
+ // ==================== 交易标的 ====================
+
+ /** 合约名称（如 ETH-USDT-SWAP，注意 OKX 使用短横线分隔） */
private final String contract;
/** 杠杆倍数 */
private final String leverage;
/** 保证金模式（cross / isolated） */
private final String marginMode;
- /** 持仓模式（single / dual / dual_plus） */
+ /** 持仓模式（long_short_mode=双向 / net_mode=单向） */
private final String positionMode;
+
+ // ==================== 策略参数 ====================
+
/** 网格间距比例（如 0.0035 表示 0.35%） */
private final BigDecimal gridRate;
/** 整体止盈阈值（USDT） */
@@ -93,9 +104,9 @@
private final int gridQueueSize;
/** 保证金占初始本金比例上限 */
private final BigDecimal marginRatioLimit;
- /** 合约乘数（单张合约代表的基础资产数量，如 BTC_USDT=0.001, ETH_USDT=0.01） */
+ /** 合约乘数（单张合约代表的基础资产数量，如 ETH-USDT-SWAP=0.01） */
private final BigDecimal contractMultiplier;
- /** 价格精度（交易所价格的最小小数位数，如 XAU_USDT=1 表示 0.1 精度，ETH_USDT=2 表示 0.01 精度） */
+ /** 价格精度（交易所价格的最小小数位数，如 1 表示 0.1 精度，2 表示 0.01 精度） */
private final int priceScale;
/** 未实现盈亏计价模式：最新价 / 标记价格 */
private final PnLPriceMode unrealizedPnlPriceMode;
@@ -103,18 +114,24 @@
private final int maxPositionSize;
/** 策略重启跨度阈值：多空两边止盈触发数量均达到此值后触发重启，0=禁用 */
private final int restartGridSpan;
+
+ // ==================== 运行时参数 ====================
+
/** 网格绝对步长（shortBaseEntryPrice × gridRate），运行时由队列生成逻辑设置 */
private BigDecimal step;
/** 网格元素列表，由队列初始化时同步填充，包含完整的多空仓挂单状态 */
private volatile List<GridElement> gridElements = new ArrayList<>();
- /** 基座多头挂单参数，在基座成交后由 tryGenerateQueues 填充 */
+ /** 基座多头挂单参数，在基座成交后由队列生成逻辑填充 */
private TraderParam baseLongTraderParam;
- /** 基座空头挂单参数，在基座成交后由 tryGenerateQueues 填充 */
+ /** 基座空头挂单参数，在基座成交后由队列生成逻辑填充 */
private TraderParam baseShortTraderParam;
- private GateConfig(Builder builder) {
+ // ==================== 构造器 ====================
+
+ private OkxConfig(Builder builder) {
this.apiKey = builder.apiKey;
this.apiSecret = builder.apiSecret;
+ this.passphrase = builder.passphrase;
this.contract = builder.contract;
this.leverage = builder.leverage;
this.marginMode = builder.marginMode;
@@ -139,41 +156,54 @@
// ==================== REST/WS 地址 ====================
/**
- * 根据环境返回 REST API 基础路径。
+ * 返回 REST API 基础路径。
+ * <p>实盘和模拟盘使用相同的 REST 地址，通过 {@code x-simulated-trading: 1} 请求头区分。
* <ul>
- * <li>测试网: {@code https://api-testnet.gateapi.io/api/v4}</li>
- * <li>生产网: {@code https://api.gateio.ws/api/v4}</li>
+ * <li>生产网/测试网: {@code https://openapi.okx.com}</li>
* </ul>
*/
public String getRestBasePath() {
- return isProduction
- ? "https://api.gateio.ws/api/v4"
- : "https://api-testnet.gateapi.io/api/v4";
+ return "https://openapi.okx.com";
}
/**
- * 根据环境返回 WebSocket 地址。
+ * 根据环境返回 WebSocket 公开频道地址。
* <ul>
- * <li>测试网: {@code wss://ws-testnet.gate.com/v4/ws/futures/usdt}</li>
- * <li>生产网: {@code wss://fx-ws.gateio.ws/v4/ws/usdt}</li>
+ * <li>测试网: {@code wss://wspap.okx.com:8443/ws/v5/public}</li>
+ * <li>生产网: {@code wss://ws.okx.com:8443/ws/v5/public}</li>
* </ul>
*/
- public String getWsUrl() {
+ public String getWsPublicUrl() {
return isProduction
- ? "wss://fx-ws.gateio.ws/v4/ws/usdt"
- : "wss://ws-testnet.gate.com/v4/ws/futures/usdt";
+ ? "wss://ws.okx.com:8443/ws/v5/public"
+ : "wss://wspap.okx.com:8443/ws/v5/public";
+ }
+
+ /**
+ * 根据环境返回 WebSocket 私有频道地址。
+ * <ul>
+ * <li>测试网: {@code wss://wspap.okx.com:8443/ws/v5/private}</li>
+ * <li>生产网: {@code wss://ws.okx.com:8443/ws/v5/private}</li>
+ * </ul>
+ */
+ public String getWsPrivateUrl() {
+ return isProduction
+ ? "wss://ws.okx.com:8443/ws/v5/private"
+ : "wss://wspap.okx.com:8443/ws/v5/private";
}
// ==================== 认证信息 ====================
- /** @return Gate API v4 密钥 */
+ /** @return OKX API v5 密钥 */
public String getApiKey() { return apiKey; }
- /** @return Gate API v4 签名密钥，用于 HMAC-SHA512 签名 */
+ /** @return OKX API v5 签名密钥，用于 HMAC-SHA256 签名 */
public String getApiSecret() { return apiSecret; }
+ /** @return OKX API v5 口令密码（passphrase） */
+ public String getPassphrase() { return passphrase; }
// ==================== 交易标的 ====================
- /** @return 合约名称（如 ETH_USDT、XAU_USDT） */
+ /** @return 合约名称（如 ETH-USDT-SWAP，OKX 使用短横线分隔） */
public String getContract() { return contract; }
/** @return 杠杆倍数（如 "100" 表示 100x） */
public String getLeverage() { return leverage; }
@@ -182,7 +212,7 @@
/** @return 保证金模式（cross=全仓 / isolated=逐仓） */
public String getMarginMode() { return marginMode; }
- /** @return 持仓模式（single=单向 / dual=双向 / dual_plus） */
+ /** @return 持仓模式（long_short_mode=双向 / net_mode=单向） */
public String getPositionMode() { return positionMode; }
// ==================== 策略参数 ====================
@@ -211,7 +241,7 @@
// ==================== 盈亏计算 ====================
- /** @return 合约乘数（单张合约代表的基础资产数量，如 ETH_USDT=0.01） */
+ /** @return 合约乘数（单张合约代表的基础资产数量，如 ETH-USDT-SWAP=0.01） */
public BigDecimal getContractMultiplier() { return contractMultiplier; }
/** @return 价格精度（交易所价格的小数位数，如 1=0.1精度，2=0.01精度），用于价格四舍五入 */
public int getPriceScale() { return priceScale; }
@@ -226,7 +256,7 @@
/** @return 网格绝对步长（shortBaseEntryPrice × gridRate），运行时设置 */
public BigDecimal getStep() { return step; }
- /** 设置网格绝对步长（由 generateShortQueue 在运行时计算并注入） */
+ /** 设置网格绝对步长（由队列生成逻辑在运行时计算并注入） */
public void setStep(BigDecimal step) { this.step = step; }
// ==================== 网格元素列表 ====================
@@ -243,12 +273,12 @@
/** @return 基座多头挂单参数 */
public TraderParam getBaseLongTraderParam() { return baseLongTraderParam; }
- /** 设置基座多头挂单参数（由 tryGenerateQueues 在基座成交后填充） */
+ /** 设置基座多头挂单参数（由队列生成逻辑在基座成交后填充） */
public void setBaseLongTraderParam(TraderParam baseLongTraderParam) { this.baseLongTraderParam = baseLongTraderParam; }
/** @return 基座空头挂单参数 */
public TraderParam getBaseShortTraderParam() { return baseShortTraderParam; }
- /** 设置基座空头挂单参数（由 tryGenerateQueues 在基座成交后填充） */
+ /** 设置基座空头挂单参数（由队列生成逻辑在基座成交后填充） */
public void setBaseShortTraderParam(TraderParam baseShortTraderParam) { this.baseShortTraderParam = baseShortTraderParam; }
// ==================== 环境 ====================
@@ -256,33 +286,37 @@
/** @return 是否为生产环境（true=实盘生产网 / false=模拟盘测试网） */
public boolean isProduction() { return isProduction; }
+ // ==================== Builder ====================
+
public static Builder builder() {
return new Builder();
}
/**
- * GateConfig 的流式构造器，提供合理的默认值。
+ * OkxConfig 的流式构造器，提供合理的默认值。
*
* <h3>必填项</h3>
- * {@code apiKey} 和 {@code apiSecret} 必须设置，其余参数均有默认值。
+ * {@code apiKey}、{@code apiSecret}、{@code passphrase} 必须设置，其余参数均有默认值。
*
* <h3>默认值</h3>
- * BTC_USDT / 10x / cross(全仓) / dual(双向) / gridRate=0.35% /
+ * ETH-USDT-SWAP / 10x / cross(全仓) / long_short_mode(双向) / gridRate=0.35% /
* overallTp=0.5 / maxLoss=7.5 / quantity=1 / isProduction=false
*/
public static class Builder {
- /** Gate API v4 密钥（必填） */
+ /** OKX API v5 密钥（必填） */
private String apiKey;
- /** Gate API v4 签名密钥（必填） */
+ /** OKX API v5 签名密钥（必填） */
private String apiSecret;
- /** 合约名称，默认 BTC_USDT */
- private String contract = "BTC_USDT";
+ /** OKX API v5 口令密码（必填） */
+ private String passphrase;
+ /** 合约名称，默认 ETH-USDT-SWAP */
+ private String contract = "ETH-USDT-SWAP";
/** 杠杆倍数，默认 "10" */
private String leverage = "10";
/** 保证金模式，默认 "cross"（全仓） */
private String marginMode = "cross";
- /** 持仓模式，默认 "dual"（双向） */
- private String positionMode = "dual";
+ /** 持仓模式，默认 "long_short_mode"（双向） */
+ private String positionMode = "long_short_mode";
/** 网格间距比例，默认 0.0035（0.35%） */
private BigDecimal gridRate = new BigDecimal("0.0035");
/** 整体止盈阈值（USDT），默认 0.5 */
@@ -299,14 +333,14 @@
private boolean isProduction = false;
/** 补仓最大重试次数，默认 3 */
private int reopenMaxRetries = 3;
- /** 网格队列容量，默认 50 */
+ /** 网格队列容量，默认 300 */
private int gridQueueSize = 300;
/** 保证金占初始本金比例上限，默认 0.2（20%） */
private BigDecimal marginRatioLimit = new BigDecimal("0.2");
- /** 合约乘数，默认 0.001 */
- private BigDecimal contractMultiplier = new BigDecimal("0.001");
- /** 价格精度（交易所价格的小数位数），默认 1（0.1 精度） */
- private int priceScale = 1;
+ /** 合约乘数，默认 0.01（ETH-USDT-SWAP=0.01） */
+ private BigDecimal contractMultiplier = new BigDecimal("0.01");
+ /** 价格精度（交易所价格的小数位数），默认 2（0.01 精度，适配 ETH） */
+ private int priceScale = 2;
/** 未实现盈亏计价模式，默认 LAST_PRICE（最新成交价） */
private PnLPriceMode unrealizedPnlPriceMode = PnLPriceMode.LAST_PRICE;
/** 最大持仓张数（单方向），默认 0=不限制 */
@@ -318,13 +352,15 @@
public Builder apiKey(String apiKey) { this.apiKey = apiKey; return this; }
/** 设置 API Secret */
public Builder apiSecret(String apiSecret) { this.apiSecret = apiSecret; return this; }
- /** 设置合约名称 */
+ /** 设置 API Passphrase */
+ public Builder passphrase(String passphrase) { this.passphrase = passphrase; return this; }
+ /** 设置合约名称（如 ETH-USDT-SWAP） */
public Builder contract(String contract) { this.contract = contract; return this; }
/** 设置杠杆倍数 */
public Builder leverage(String leverage) { this.leverage = leverage; return this; }
/** 设置保证金模式（cross=全仓 / isolated=逐仓） */
public Builder marginMode(String marginMode) { this.marginMode = marginMode; return this; }
- /** 设置持仓模式（single=单向 / dual=双向） */
+ /** 设置持仓模式（long_short_mode=双向 / net_mode=单向） */
public Builder positionMode(String positionMode) { this.positionMode = positionMode; return this; }
/** 设置网格间距比例 */
public Builder gridRate(BigDecimal gridRate) { this.gridRate = gridRate; return this; }
@@ -357,8 +393,8 @@
/** 设置策略重启跨度阈值：多空两边止盈触发数均达到此值后触发重启，0=禁用 */
public Builder restartGridSpan(int restartGridSpan) { this.restartGridSpan = restartGridSpan; return this; }
- public GateConfig build() {
- return new GateConfig(this);
+ public OkxConfig build() {
+ return new OkxConfig(this);
}
}
}
--
Gitblit v1.9.1