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

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

2025-12-18 19:53:58 UTC+8 25092 阅读

[//]:content-type-MARKDOWN-DONOT-DELETE
**Gate USDT 永续合约下单支持小数--字段类型变动说明**
为提升合约交易灵活性并全面支持小数张数下单，Gate 将对 USDT 永续合约相关接口进行分阶段升级。本次升级将影响 REST API 与 WebSocket 中与订单张数（size）相关的字段解析逻辑。请您根据阶段计划提前评估与调整策略逻辑，确保您的交易不受影响。

### 1.1 升级计划说明 （整体分为 3 个阶段）

**1. 阶段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. 阶段2：小数张数下单能力上线**

1. 计划于 2025 年 12 月 30 日上线 USDT 永续合约小数张数下单的系统能力，该阶段仅完成底层能力和接口支持，暂不开放任何合约市场实际支持小数张数下单，用户实际下单规则保持不变。
2. 自 2026 年 1 月底起，将逐步开放合约市场支持小数张数下单功能，具体开放市场及时间以平台后续公告为准。
3. 在合约市场开放小数张数下单功能后，仍使用旧字段类型且未适配的用户，将可能出现：
* 市场深度的精度解析异常
* 下单精度不一致
* 成交订单精度异常

***因此提醒所有 API 用户尽量在 2026 年 1 月底之前完成字段类型适配***

**3. 阶段 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/contracts 2. 查询单个合约信息 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/positions 2. 获取单个仓位信息 GET /futures/settle/positions/contract 3. 更新仓位保证金 POST /futures/settle/positions/contract/margin 4. 更新仓位杠杆 POST/futures/settle/positions/contract/leverage 5. 切换全逐仓模式 POST /futures/settle/positions/cross_mode 6. 双仓模式下切换全逐仓模式 POST /futures/settle/dual_comp/positions/cross_mode 7. 更新仓位风险限额 POST/futures/settle/positions/contract/risk_limit 8. 设置持仓模式 POST /futures/settle/dual_mode 9. 获取双仓模式下的持仓信息 GET /futures/settle/dual_comp/positions/contract 10. 更新双仓模式下的保证金 POST/futures/settle/dual_comp/positions/contract/margin 11. 更新双仓模式下的杠杆 POST/futures/settle/dual_comp/positions/contract/leverage 12. 更新双仓模式下的风险限额 POST/futures/settle/dual_comp/positions/contract/risk_limit | 持仓数量 size | |
| Private | 1. 合约下单交易 POST /futures/settle/orders 2. 查询合约订单列表 GET /futures/settle/orders 3. 批量取消挂单 DELETE /futures/settle/orders 4. 查询合约订单列表(时间区间) GET /futures/settle/orders_timerange 5. 合约交易批量下单 POST /futures/settle/batch_orders 6. 查询单个订单详情 GET /futures/settle/orders/order_id 7. 撤销单个订单 DELETE /futures/settle/orders/order_id 8. 修改单个订单 PUT /futures/settle/orders/order_id 9. 档位 bbo 合约下单 POST /futures/settle/bbo_orders | 交易数量 size 冰山委托显示数量 iceberg 未成交数量 left | |
| Private | 1. 查询个人成交记录 GET /futures/settle/my_trades 2. 查询个人成交记录(时间区间) 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_orders 2. 取消所有自动订单 DELETE /futures/settle/price_orders 3. 查询单个自动订单信息 GET /futures/settle/price_orders/order_id 4. 取消单个自动订单 DELETE /futures/settle/price_orders/order_id 5. 修改单个自动订单 PUT /futures/settle/price_orders/order_id | 新增张数字段 amount string 类型 | |

**2. Websocket 相关字段**

### 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文档。感谢您的支持与理解。

<sp>
Gate 团队
2025 年 12 月 18 日
<sp>
**加密货币之门**
安全、快捷、轻松交易超过 %Amount_of_Currency% 种加密货币
**立即行动**
<a href="https://www.gate.com/signup" target="_blank">注册账户</a>，最高可领 $10,000 迎新奖励
<a href="https://www.gate.com/referral" target="_blank">邀请他人注册</a>，可获 40% 佣金
**关注官方渠道**
<a href="https://www.gate.com/" target="_blank">访问 Gate 官网</a>
<a href="https://www.gate.com/mobileapp?ch=ann48788" target="_blank">下载 Gate App | 电脑端</a>
<a href="https://x.com/Gate_zh" rel="nofollow noopener noreferrer" target="_blank">关注 X (Twitter)</a>，获取最新福利
<a href="https://t.me/gate_zh" rel="nofollow noopener noreferrer" target="_blank">加入 Telegram 社群</a>，讨论热点话题
<a href="https://www.gate.com/community" target="_blank">进入全球社区</a>，获取最新资讯
**透明度保障**
<a href="https://www.gate.com/proof-of-reserves" target="_blank">查看 100% 储备金证明</a>

涨跌幅与 K 线开盘时间

涨跌颜色

Pay With

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

域名提示

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

域名提示

选择语言及地区

选择您所在的地区

法币汇率