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

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

2025-12-18 11:53:58 UTC 25060 閱讀

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

<sp>
Gate 團隊
2025 年 12 月 18 日
<sp>
**加密貨幣之門**
安全、快捷、輕鬆交易超過 %Amount_of_Currency% 種加密貨幣
**立即行動**
<a href="https://www.gate.com/zh-tw/signup" target="_blank">註冊帳戶</a>，最高可領 $10,000 迎新獎勵
<a href="https://www.gate.com/zh-tw/referral" target="_blank">邀請他人註冊</a>，可獲 40% 佣金
**關注官方渠道**
<a href="https://www.gate.com/zh-tw/" target="_blank">訪問 Gate 官網</a>
<a href="https://www.gate.com/zh-tw/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/zh-tw/community" target="_blank">進入全球社群</a>，獲取最新資訊
**透明度保障**
<a href="https://www.gate.com/zh-tw/proof-of-reserves" target="_blank">查看 100% 儲備金證明</a>

漲跌幅與 K 線開盤時間

漲跌顏色

Pay With

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

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

選擇語言及地區

選擇您所在的地區

法幣匯率