package com.xcong.excoin.modules.gateApi; import java.math.BigDecimal; import java.util.ArrayList; import java.util.List; /** * Gate 交易模块全局配置，策略的唯一参数入口。 * *

定位

* 通过 Builder 模式将所有运行参数集中管理，避免策略参数散落在多个类中。 * 运行时动态参数（step、gridElements、baseLongTraderParam、baseShortTraderParam） * 由 {@link GateGridTradeService} 在策略执行过程中写入。 * *

参数分类

* * * * * * * * * * *
类别参数用途
认证apiKey, apiSecretREST/WS 签名认证
交易标的contract, leverage, quantity, contractMultiplier合约、杠杆、张数、乘数
持仓marginMode, positionMode全仓/逐仓、单向/双向
网格策略gridRate, gridQueueSize, priceScale间距比例、队列容量、价格精度（交易所tick）
止盈止损overallTp, maxLoss整体止盈/亏损阈值（USDT），触发后策略停止
风控marginRatioLimit, reopenMaxRetries保证金占比上限、补仓重试次数
盈亏计算contractMultiplier, unrealizedPnlPriceMode合约乘数、未实现盈亏计价模式
运行时step, gridElements, baseLongTraderParam, baseShortTraderParam由策略动态填充
* *

priceScale 说明

* 价格精度表示交易所允许的最小价格单位的小数位数： * * 所有价格计算必须对齐到 tick 整数倍，否则 Gate API 返回 * {@code invalid argument: trigger.price price is not an integer multiple of a price unit}。 * *

gridElements 生命周期

*
    *
  1. 项目启动时初始化为空 ArrayList
    2. *
  2. {@code tryGenerateQueues()} 中通过 {@code updateGridElements()} 填充，同时触发 * {@link GridElement#rebuildIndex(List)} 建立全局 O(1) 索引
    3. *
  3. 每次挂单/止盈操作后通过 {@link GridElement#refreshIndices()} 更新索引
    4. *
* * @author Administrator */ public class GateConfig { /** * 未实现盈亏（unrealizedPnl）计价模式。 * * */ public enum PnLPriceMode { /** 按最新成交价计算未实现盈亏 */ LAST_PRICE, /** 按标记价格计算未实现盈亏，需通过 {@link GateGridTradeService#setMarkPrice(BigDecimal)} 注入 */ MARK_PRICE } /** Gate API v4 密钥 */ private final String apiKey; /** Gate API v4 签名密钥 */ private final String apiSecret; /** 合约名称（如 XAU_USDT） */ private final String contract; /** 杠杆倍数 */ private final String leverage; /** 保证金模式（cross / isolated） */ private final String marginMode; /** 持仓模式（single / dual / dual_plus） */ private final String positionMode; /** 网格间距比例（如 0.0035 表示 0.35%） */ private final BigDecimal gridRate; /** 整体止盈阈值（USDT） */ private final BigDecimal overallTp; /** 最大亏损阈值（USDT） */ private final BigDecimal maxLoss; /** 下单数量（合约张数） */ private final String quantity; /** 是否为生产环境 */ private final boolean isProduction; /** 补仓最大重试次数 */ private final int reopenMaxRetries; /** 网格队列容量 */ private final int gridQueueSize; /** 保证金占初始本金比例上限 */ private final BigDecimal marginRatioLimit; /** 合约乘数（单张合约代表的基础资产数量，如 BTC_USDT=0.001, ETH_USDT=0.01） */ private final BigDecimal contractMultiplier; /** 价格精度（交易所价格的最小小数位数，如 XAU_USDT=1 表示 0.1 精度，ETH_USDT=2 表示 0.01 精度） */ private final int priceScale; /** 未实现盈亏计价模式：最新价 / 标记价格 */ private final PnLPriceMode unrealizedPnlPriceMode; /** 网格绝对步长（shortBaseEntryPrice × gridRate），运行时由队列生成逻辑设置 */ private BigDecimal step; /** 网格元素列表，由队列初始化时同步填充，包含完整的多空仓挂单状态 */ private volatile List gridElements = new ArrayList<>(); /** 基座多头挂单参数，在基座成交后由 tryGenerateQueues 填充 */ private TraderParam baseLongTraderParam; /** 基座空头挂单参数，在基座成交后由 tryGenerateQueues 填充 */ private TraderParam baseShortTraderParam; private GateConfig(Builder builder) { this.apiKey = builder.apiKey; this.apiSecret = builder.apiSecret; this.contract = builder.contract; this.leverage = builder.leverage; this.marginMode = builder.marginMode; this.positionMode = builder.positionMode; this.gridRate = builder.gridRate; this.overallTp = builder.overallTp; this.maxLoss = builder.maxLoss; this.quantity = builder.quantity; this.isProduction = builder.isProduction; this.reopenMaxRetries = builder.reopenMaxRetries; this.gridQueueSize = builder.gridQueueSize; this.marginRatioLimit = builder.marginRatioLimit; this.contractMultiplier = builder.contractMultiplier; this.priceScale = builder.priceScale; this.unrealizedPnlPriceMode = builder.unrealizedPnlPriceMode; } // ==================== REST/WS 地址 ==================== /** * 根据环境返回 REST API 基础路径。 * */ public String getRestBasePath() { return isProduction ? "https://api.gateio.ws/api/v4" : "https://api-testnet.gateapi.io/api/v4"; } /** * 根据环境返回 WebSocket 地址。 * */ public String getWsUrl() { return isProduction ? "wss://fx-ws.gateio.ws/v4/ws/usdt" : "wss://ws-testnet.gate.com/v4/ws/futures/usdt"; } // ==================== 认证信息 ==================== /** @return Gate API v4 密钥 */ public String getApiKey() { return apiKey; } /** @return Gate API v4 签名密钥，用于 HMAC-SHA512 签名 */ public String getApiSecret() { return apiSecret; } // ==================== 交易标的 ==================== /** @return 合约名称（如 ETH_USDT、XAU_USDT） */ public String getContract() { return contract; } /** @return 杠杆倍数（如 "100" 表示 100x） */ public String getLeverage() { return leverage; } // ==================== 持仓配置 ==================== /** @return 保证金模式（cross=全仓 / isolated=逐仓） */ public String getMarginMode() { return marginMode; } /** @return 持仓模式（single=单向 / dual=双向 / dual_plus） */ public String getPositionMode() { return positionMode; } // ==================== 策略参数 ==================== /** @return 网格间距比例（如 0.0015 表示 0.15%），用于生成价格队列和计算止盈价 */ public BigDecimal getGridRate() { return gridRate; } /** @return 整体止盈阈值（USDT），累计已实现盈亏 ≥ 此值时策略停止 */ public BigDecimal getOverallTp() { return overallTp; } /** @return 最大亏损阈值（USDT），累计已实现盈亏 ≤ -此值时策略停止 */ public BigDecimal getMaxLoss() { return maxLoss; } /** @return 每次下单的张数（如 "1" 表示 1 张合约） */ public String getQuantity() { return quantity; } /** @return 网格价格队列的容量上限（超出时截断尾部） */ public int getGridQueueSize() { return gridQueueSize; } // ==================== 风险控制 ==================== /** @return 保证金占初始本金比例上限（默认 0.2 即 20%），超限跳过开仓 */ public BigDecimal getMarginRatioLimit() { return marginRatioLimit; } /** @return 补仓最大重试次数（当前版本未使用） */ public int getReopenMaxRetries() { return reopenMaxRetries; } // ==================== 盈亏计算 ==================== /** @return 合约乘数（单张合约代表的基础资产数量，如 ETH_USDT=0.01） */ public BigDecimal getContractMultiplier() { return contractMultiplier; } /** @return 价格精度（交易所价格的小数位数，如 1=0.1精度，2=0.01精度），用于价格四舍五入 */ public int getPriceScale() { return priceScale; } /** @return 未实现盈亏计价模式：LAST_PRICE（最新成交价）/ MARK_PRICE（标记价格） */ public PnLPriceMode getUnrealizedPnlPriceMode() { return unrealizedPnlPriceMode; } // ==================== 运行时参数 ==================== /** @return 网格绝对步长（shortBaseEntryPrice × gridRate），运行时设置 */ public BigDecimal getStep() { return step; } /** 设置网格绝对步长（由 generateShortQueue 在运行时计算并注入） */ public void setStep(BigDecimal step) { this.step = step; } // ==================== 网格元素列表 ==================== /** @return 网格元素列表（队列初始化后填充），线程不安全，仅由策略线程单线程写入 */ public List getGridElements() { return gridElements; } /** 设置网格元素列表（由队列生成逻辑写入），同时重建全局 ID 索引 */ public void setGridElements(List gridElements) { this.gridElements = gridElements; GridElement.rebuildIndex(gridElements); } // ==================== 基座挂单参数 ==================== /** @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; } // ==================== 环境 ==================== /** @return 是否为生产环境（true=实盘生产网 / false=模拟盘测试网） */ public boolean isProduction() { return isProduction; } public static Builder builder() { return new Builder(); } /** * GateConfig 的流式构造器，提供合理的默认值。 * *

必填项

* {@code apiKey} 和 {@code apiSecret} 必须设置，其余参数均有默认值。 * *

默认值

* BTC_USDT / 10x / cross(全仓) / dual(双向) / gridRate=0.35% / * overallTp=0.5 / maxLoss=7.5 / quantity=1 / isProduction=false */ public static class Builder { /** Gate API v4 密钥（必填） */ private String apiKey; /** Gate API v4 签名密钥（必填） */ private String apiSecret; /** 合约名称，默认 BTC_USDT */ private String contract = "BTC_USDT"; /** 杠杆倍数，默认 "10" */ private String leverage = "10"; /** 保证金模式，默认 "cross"（全仓） */ private String marginMode = "cross"; /** 持仓模式，默认 "dual"（双向） */ private String positionMode = "dual"; /** 网格间距比例，默认 0.0035（0.35%） */ private BigDecimal gridRate = new BigDecimal("0.0035"); /** 整体止盈阈值（USDT），默认 0.5 */ private BigDecimal overallTp = new BigDecimal("0.5"); /** 最大亏损阈值（USDT），默认 7.5 */ private BigDecimal maxLoss = new BigDecimal("7.5"); /** 每次下单张数，默认 "1" */ private String quantity = "1"; /** 是否为生产环境，默认 false（测试网） */ private boolean isProduction = false; /** 补仓最大重试次数，默认 3 */ private int reopenMaxRetries = 3; /** 网格队列容量，默认 50 */ 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; /** 未实现盈亏计价模式，默认 LAST_PRICE（最新成交价） */ private PnLPriceMode unrealizedPnlPriceMode = PnLPriceMode.LAST_PRICE; /** 设置 API Key */ public Builder apiKey(String apiKey) { this.apiKey = apiKey; return this; } /** 设置 API Secret */ public Builder apiSecret(String apiSecret) { this.apiSecret = apiSecret; return this; } /** 设置合约名称 */ 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=双向） */ public Builder positionMode(String positionMode) { this.positionMode = positionMode; return this; } /** 设置网格间距比例 */ public Builder gridRate(BigDecimal gridRate) { this.gridRate = gridRate; return this; } /** 设置整体止盈阈值（USDT） */ public Builder overallTp(BigDecimal overallTp) { this.overallTp = overallTp; return this; } /** 设置最大亏损阈值（USDT） */ public Builder maxLoss(BigDecimal maxLoss) { this.maxLoss = maxLoss; return this; } /** 设置每次下单张数 */ public Builder quantity(String quantity) { this.quantity = quantity; return this; } /** 设置环境（true=实盘生产网 / false=模拟盘测试网） */ public Builder isProduction(boolean isProduction) { this.isProduction = isProduction; return this; } /** 设置补仓最大重试次数 */ public Builder reopenMaxRetries(int reopenMaxRetries) { this.reopenMaxRetries = reopenMaxRetries; return this; } /** 设置合约乘数（单张合约代表的基础资产数量） */ public Builder contractMultiplier(BigDecimal contractMultiplier) { this.contractMultiplier = contractMultiplier; return this; } /** 设置价格精度（交易所价格的小数位数，如 1=0.1精度，2=0.01精度） */ public Builder priceScale(int priceScale) { this.priceScale = priceScale; return this; } /** 设置未实现盈亏计价模式 */ public Builder unrealizedPnlPriceMode(PnLPriceMode mode) { this.unrealizedPnlPriceMode = mode; return this; } public GateConfig build() { return new GateConfig(this); } } }