Gate 關於 USDT 永續合約下單張數欄位型態變更與功能上線計劃公告
Gate 關於 USDT 永續合約下單張數欄位型態變更與功能上線計劃公告
2025-12-18 19:53:58 UTC+813,146 瀏覽量
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：小數張數下單能力上線
- 計畫於 2025 年 12 月 30 日上線 USDT 永續合約小數張數下單的系統能力，該階段僅完成底層能力和介面支持，暫不開放任何合約市場實際支持小數張數下單，使用者實際下單規則保持不變。
- 自 2026 年 1 月底起，將逐步開放合約市場支持小數張數下單功能，具體開放市場及時間以平台後續公告為準。
- 在合約市場開放小數張數下單功能後，仍使用舊欄位類型且未適配的使用者，將可能出現：
- 市場深度的精度解析異常
- 下單精度不一致
- 成交訂單精度異常
因此提醒所有 API 使用者盡量在 2026 年 1 月底之前完成欄位類型適配
3. 階段 3 ：全面市場支持 + 欄位全面切換為 String 類型
- 將全面開放所有合約交易對小數張數下單能力。
- 將在某固定時間，系統預設返回 String 類型，並且調整 header（X-Gate-Size-Decimal）的預設值，預設解析行為由 0 切換為 1，為仍未完成適配的使用者提供短暫的過渡期。
- 過渡期結束後，正式廢止 X-Gate-Size-Decimal header 請求頭欄位，其配置不再生效。
- 所有與訂單張數相關的欄位將統一使用 String 類型。 為確保精度與相容性，舊類型 Integer 將不再支持。
- 具體生效時間將提前透過官方公告通知，請務必提前完成適配。
1.2 階段 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. 精度處理-向下取整 |
建議：客戶端及時調整合約張數欄位類型變更，待合約支持下單小數交易功能正式上線，可以快速體驗和使用該功能。
- 設定 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 相關欄位
| 頻道類型 | 頻道 | 回傳欄位 | 備註 |
|---|---|---|---|
| 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_size trade_size |
|
| Private | 1. 強平訂單頻道 futures.liquidates |
剩餘可交易數量 left 持倉數量 size |
|
| Private | 1. 下單 futures.order_place 2. 批量下單 futures.order_batch_place 3. 撤單 futures.order_cancel 4. 根據id批量撤單 futures.order_cancel_cp 5. 改單 futures.order_amend 6. 查詢訂單列表 futures.order_list 7. 查詢訂單詳情 futures.order_status |
下單數量 size 剩餘可交易數量 left 冰山委託顯示數量 iceberg |
1.4 查詢支持小數下單的合約資訊
-
設定 header ：X-Gate-Size-Decimal=1
-
請求合約資訊介面
curl --location 'https://api.gateio.ws/api/v4/futures/usdt/contracts' \ --header 'X-Gate-Size-Decimal: 1' -
回傳欄位 order_size_min 若為小數，即表示該合約支持小數張數下單交易。
1.5 更多說明
API更新日誌：https://www.gate.com/zh-tw/docs/developers/apiv4/zh_CN/#changelog
如有疑問，請聯繫API技術支援或參考API文件。感謝您的支持與理解。
