Gate 關於 USDT 永續合約下單張數欄位型態變更與功能上線計劃公告

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 相關欄位

頻道類型	頻道	回傳欄位	備註
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 查詢支持小數下單的合約資訊

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/zh-tw/docs/developers/apiv4/zh_CN/#changelog
如有疑問，請聯繫API技術支援或參考API文件。感謝您的支持與理解。

Gate 團隊 2025 年 12 月 18 日 **加密貨幣之門** 安全、快捷、輕鬆交易超過 5,400 種加密貨幣 **立即行動** 註冊帳戶，最高可領 $10,000 迎新獎勵 邀請他人註冊，可獲 40% 佣金 **關注官方渠道** 訪問 Gate 官網 下載 Gate App | 電腦端 關注 X (Twitter)，獲取最新福利 加入 Telegram 社群，討論熱點話題 進入全球社群，獲取最新資訊 **透明度保障** 查看 100% 儲備金證明