Gate 关于USDT永续合约下单张数字段类型变更与功能上线计划公告

### Gate USDT 永续合约下单支持小数--字段类型变动说明 为提升合约交易灵活性并全面支持小数张数下单，Gate 将对 USDT 永续合约相关接口进行分阶段升级。本次升级将影响 REST API 与 WebSocket 中与订单张数（size）相关的字段解析逻辑。请您根据阶段计划提前评估与调整策略逻辑，确保您的交易不受影响。 ### 1.1 升级计划说明 （整体分为 3 个阶段） 阶段1: 字段类型兼容性升级 ( 2025-12-09 已上线)： 已经完成底层数据结构调整。 合约张数相关字段类型有原来的 Integer 升级为 String 类型。 当前处于兼容模中，通过在请求Header 中传入 X-Gate-Size-Decimal字段，以实现合约张数字段兼容处理。 设置方式如下： | Header参数 | 说明 | 备注 | | :--- | :--- | :--- | | X-Gate-Size-Decimal = 1 | 张数相关字段类型 Integer 改为 String 类型| 1.支持接收和响应 String 类型；本阶段不支持小数 | | X-Gate-Size-Decimal = 0 或者不使用该 header 字段 默认为不使用该字段 | 张数相关字段类型为 Integer | 1.不支持接收小数数据 2.精度处理-向下取整 | 如果不设置 header（ X-Gate-Size-Decimal ）字段，默认情况下，size 字段接收和响应依然返回 Integer 类型 阶段2：小数张数下单能力上线 1. 计划于 2025 年 12 月 30 日上线 USDT 永续合约小数张数下单的系统能力，该阶段仅完成底层能力和接口支持，暂不开放任何合约市场实际支持小数张数下单，用户实际下单规则保持不变。 2. 自 2026 年 1 月底起，将逐步开放合约市场支持小数张数下单功能，具体开放市场及时间以平台后续公告为准。 3. 在合约市场开放小数张数下单功能后，仍使用旧字段类型且未适配的用户，将可能出现： 市场深度的精度解析异常 下单精度不一致 成交订单精度异常 因此提醒所有 API 用户尽量在 2026 年 1 月底之前完成字段类型适配 阶段 3 ：全面市场支持 + 字段全面切换为 String 类型 - 将全面开放所有合约交易对小数张数下单能力。 - 将在某固定时间，系统默认返回 String 类型，并且调整 header （ X-Gate-Size-Decimal ）的默认值， 默认解析行为从 0 切换为 1 ，为仍未完成适配的用户提供短暂的过渡期。 - 过渡期结束后，正式废弃 X-Gate-Size-Decimal header 请求头字段，其配置不再生效。 - 所有与订单张数相关的字段将统一使用 String 类型。 为确保精度与兼容性，旧类型 Integer 将不在支持。 - 具体生效时间将提前通过官方公告通知，请务必提前完成适配。 ###1.2 阶段 1 升级详细说明 1.Rest 和 Websocket 新增 header 字段 X-Gate-Size-Decimal 控制张数相关字段精度 | header参数 | 说明 | 备注 | | :--- | :--- | :--- | | X-Gate-Size-Decimal = 1 | 张数相关字段类型由 Integer 改为 String 类型| 1. 支持接收和响应 String 类型；本阶段不支持小数 | | X-Gate-Size-Decimal = 0 或者不使用该header字段 默认为不使用该字段 | 张数相关字段类型为 Integer | 1.不支持接收小数数据 2.精度处理-向下取整 | 建议：客户端及时调整合约张数字段类型变更，待合约支持下单小数交易功能正式上线，可以快速体验和使用该功能。 2.设置 header 参考示例 Rest ``` # 设置请求头 headers = { 'KEY': API_KEY, 'Timestamp': timestamp, 'SIGN': signature, 'X-Gate-Size-Decimal' : '1' , # 启用小数张数 'Content-Type': 'application/json', 'Accept': 'application/json' } ``` Websocket ``` # 设置请求头 # 启用小数张数 headers[' X-Gate-Size-Decimal '] = '1' ``` ### 1.3 合约张数字段类型变更接口（请详细对比） 1. Rest 相关字段 | 接口类型| 接口 | 字段 | 备注 | | :--- | :--- | :--- | :--- | | Public | 1. 查询所有合约信息GET /futures/settle/contracts2. 查询单个合约信息GET /futures/settle/contracts/contract | 最小下单数量order_size_min最大下单数量order_size_max历史累计成交trade_size当前做多用户持有仓位总和position_size | 1. 使用header字段 X-Gate-Size-Decimal=1 上述的字段类型会由Integer类型变更为String类型 2. 客户端需要调整字段的接收类型 | | Public | 1. 查询合约市场深度信息GET /futures/settle/order_book | 数量s | | | Public | 1. 查询合约市场成交记录GET /futures/settle/trades | 成交数量size | | | Public | 1. 查询合约市场K线GET /futures/settle/candlesticks | 交易量(张数)v | | | Public | 1. 查询合约统计信息GET /futures/settle/contract_stats | 做多爆仓量(张)long_liq_size做空爆仓量(张)short_liq_size总持仓量(张)open_interest大户多空持仓比top_lsr_size大户做多持仓量(张) top_long_size 大户做空持仓量(张)top_short_size做多taker持仓量(张)long_taker_size 做空taker持仓量(张)short_taker_size | | | Public | 1. 查询强平历史数据GET /futures/settle/liq_orders | 持仓数量size强平委托数量order_size系统强平委托挂单大小left | | | Private | 1. 查询用户仓位列表GET /futures/settle/positions2. 获取单个仓位信息GET /futures/settle/positions/contract3. 更新仓位保证金POST /futures/settle/positions/contract/margin4. 更新仓位杠杆POST /futures/settle/positions/contract/leverage5. 切换全逐仓模式POST /futures/settle/positions/cross_mode6. 双仓模式下切换全逐仓模式POST /futures/settle/dual_comp/positions/cross_mode7. 更新仓位风险限额POST /futures/settle/positions/contract/risk_limit8. 设置持仓模式POST /futures/settle/dual_mode9. 获取双仓模式下的持仓信息GET /futures/settle/dual_comp/positions/contract10. 更新双仓模式下的保证金POST /futures/settle/dual_comp/positions/contract/margin11. 更新双仓模式下的杠杆POST /futures/settle/dual_comp/positions/contract/leverage12. 更新双仓模式下的风险限额POST /futures/settle/dual_comp/positions/contract/risk_limit | 持仓数量size | | | Private | 1. 合约下单交易POST /futures/settle/orders2. 查询合约订单列表GET /futures/settle/orders3. 批量取消挂单DELETE /futures/settle/orders4. 查询合约订单列表(时间区间)GET /futures/settle/orders_timerange5. 合约交易批量下单POST /futures/settle/batch_orders6. 查询单个订单详情GET /futures/settle/orders/order_id7. 撤销单个订单DELETE /futures/settle/orders/order_id8. 修改单个订单PUT /futures/settle/orders/order_id9. 档位bbo合约下单POST /futures/settle/bbo_orders | 交易数量size冰山委托显示数量iceberg未成交数量left | | | Private | 1. 查询个人成交记录GET /futures/settle/my_trades2. 查询个人成交记录(时间区间)GET /futures/settle/my_trades_timerange | 成交数量size平仓数量close_size | | | Private | 1. 查询平仓GET /futures/settle/position_close | 最大持仓量max_size累计平仓量accum_size | | | Private | 1. 查询强制平仓历史GET /futures/settle/liquidates | 持仓数量size强平委托挂单大小left | | | Private | 1. 查询ADL自动减仓订单信息GET /futures/settle/auto_deleverages | 成交数量trade_size自动减仓后的持仓量position_size | | | Private | 1. 查询自动订单列表GET /futures/settle/price_orders2. 取消所有自动订单DELETE /futures/settle/price_orders3. 查询单个自动订单信息GET /futures/settle/price_orders/order_id4. 取消单个自动订单DELETE /futures/settle/price_orders/order_id5. 修改单个自动订单PUT /futures/settle/price_orders/order_id | 新增张数字段amount string 类型 | | 2. Websocket 相关字段 | 频道类型 | 频道 | 返回字段 | 备注 | | :--- | :--- | :--- | :--- | | Public | 1. 公共成交频道futures.trades | 成交数量size | 1. 使用header字段X-Gate-Size-Decimal=1上述的字段类型会由 Integer 类型变更为 String类型2. 客户端需要调整字段的接收类型 | | Public | 1. ticker频道futures.tickers | 总数量total_size | | | Public | 1. BBO频道futures.book_ticker | 最佳卖方的数量A最佳买方的数量 B | | | Public | 1. 深度更新频道futures.order_book_update | 卖方档位的待成交数量a.s 买方档位的待成交数量 b.s | | | Public | 1. 全量深度频道futures.order_book | 卖方档位的待成交数量a.s 买方档位的待成交数量b.s | | | Public | 1. 深度V2频道futures.obu | [price,size]size可能推送小数 | | | Public | 1. K线频道futures.candlesticks | 成交量v | | | Public | 1. 公共强平频道futures.public_liquidates | 强平订单数量size | | | Public | 1. 合约统计数据频道futures.contract_stats | 做多爆仓量（张）long_liq_size 做空爆仓量（张）short_liq_size 总持仓量（张）open_interest | | | Private | 1. 订单频道futures.orders | 冰山下单显示的数量iceberg 剩余可交易数量left 订单数量size | | | Private | 1. 私有成交频道futures.usertrades | 成交数量size | | | Private | 1. ADL频道 futures.auto_deleverages | 持仓数量position_size 交易数量trade_size | | | Private | 1. 持仓频道futures.positions | 持仓数量size | | | Private | 1. 价格触发订单频道futures.autoorders | position_sizetrade_size | | | Private | 1. 强平订单频道futures.liquidates | 剩余可交易数量left 持仓数量size | | | Private | 1. 下单futures.order_place2. 批量下单futures.order_batch_place3. 撤单futures.order_cancel4. 根据id批量撤单futures.order_cancel_cp5. 改单futures.order_amend6. 查询订单列表futures.order_list7. 查询订单详情futures.order_status | 下单数量size 剩余可交易数量left冰山委托显示数量iceberg | | ### 1.4 查询支持小数下单的合约信息 1. 设置 header ：X-Gate-Size-Decimal=1 2. 请求合约信息接口 ``` curl --location 'https://api.gateio.ws/api/v4/futures/usdt/contracts' \\ --header 'X-Gate-Size-Decimal: 1' ``` 3. 返回字段 order_size_min 如果是小数，即表示该合约支持小数张数下单交易。 ### 1.5 更多说明 API更新日志：https://www.gate.com/docs/developers/apiv4/zh_CN/#changelog 如有疑问，请联系API技术支持或参考API文档。感谢您的支持与理解。 Gate 团队 2025 年 12 月 18 日(Gate)