Gate API 合約時間驗證是 Gate 在合約交易 API 的撮合引擎(ME)端新增的時間驗證功能。系統透過兩個 HTTP 標頭確認請求是否在指定時間範圍內送出。用戶端將 X-Gate-Client-Send-Us 設為以微秒為單位的送出時間戳記,並將 X-Gate-Timeout-Window-Us 設為同樣以微秒為單位的最長有效時間範圍。本次更新僅適用於 Gate 3.0 交易架構。
此機制可因應演算法交易中的具體風險:滯留於網路佇列的請求、用戶端緩慢重試,或時鐘偏差,都可能讓請求在交易者預期之後很久才抵達撮合引擎。在價格快速變動的合約交易市場中,延遲訂單可能以不正確的價格成交,產生滑點風險及非預期成交。時間驗證讓用戶端能以宣告方式指定「N 微秒後將此請求視為無效」,將到期控制置於 ME 層,而非僅依賴網路時間。
Gate 合約交易 API 現在支援兩個用於撮合引擎(ME)端時間驗證的請求標頭:X-Gate-Client-Send-Us 和 X-Gate-Timeout-Window-Us,兩者皆以微秒為單位。
X-Gate-Client-Send-Us 包含用戶端自 Unix 時間起點以來、以微秒表示的送出時間戳記。伺服器會在接收請求時將此值與自身時鐘進行比較。
X-Gate-Timeout-Window-Us 定義請求最長有效時間範圍,單位為微秒。若送出時間戳記與伺服器接收時間之間的經過時間超過此範圍,請求將遭拒絕。
REST 端點已於 2026 年 11 月 16 日推出。WebSocket API 支援將於 2026 年 11 月 19 日推出。
此機制僅適用於 Gate 3.0 交易架構的合約(期貨)交易介面;其他架構目前不支援此功能。整合步驟包括:同步時鐘、計算以微秒為單位的送出時間戳記、設定兩個標頭,以及依最新欄位名稱檢查並更新 API 整合邏輯。
Gate API 合約時間驗證是一組 HTTP 標頭,讓用戶端可宣告請求應維持有效的時間長度。此機制會在撮合引擎處理請求前,於傳輸層運作。伺服器會讀取每個傳入合約 API 呼叫中的兩個標頭,計算自身接收時間與用戶端宣告送出時間戳記的差異,並將結果與宣告的逾時時間範圍比較。
X-Gate-Client-Send-Us 包含用戶端送出請求當下的時間戳記,自 Unix 時間起點起算,單位為微秒。數值 1,794,794,400,123,456 對應至特定的微秒級時間點。其單位為微秒,而非毫秒或秒;使用錯誤單位是常見的整合錯誤,可能導致「時間戳記過舊」或「時間戳記超出未來時間範圍」錯誤。
此標頭會告知伺服器請求何時離開用戶端。伺服器接著以自身的接收時間戳記減去此值,計算經過時間。即使網路延遲正常,若用戶端時鐘與伺服器嚴重不同步,計算出的經過時間仍會不正確。
X-Gate-Timeout-Window-Us 定義請求最長有效時間範圍,單位為微秒。伺服器會拒絕任何經過時間超過此範圍的請求。數值 5,000,000 相當於 5 秒。數值 500,000 相當於 0.5 秒,屬於較嚴格的時間範圍,適合對延遲敏感的下單操作。
此標頭讓用戶端能明確控制請求允許過時的程度。較嚴格的時間範圍可降低在過時市場條件下執行的風險。較寬鬆的時間範圍可容許網路波動及時鐘偏差,但也會讓市場價格在用戶端意圖與伺服器執行之間有更多變動時間。
在合約及期貨市場中,價格可在數毫秒內變動。原本預計以目前價格執行的訂單,可能在數秒後市場已變動時才抵達。若未進行時間驗證,API 無法判斷用戶端是否有意延遲,或請求是否遭重放、重複傳送或滯留於佇列中。
時間驗證可處理以下 3 種具體情境:
網路延遲尖峰。 請求抵達伺服器的時間若超過預期,可在撮合引擎處理前遭拒絕,避免以交易者不再接受的價格成交。
用戶端時鐘偏差。 若用戶端系統時鐘超前或落後於伺服器,計算出的經過時間將產生偏差。用戶端可從錯誤回應中偵測此情況,並調整時鐘同步設定。
遭重放或重複傳送的請求。 若請求遭攔截並在有效時間範圍到期後重放,伺服器會因經過時間超過宣告範圍而拒絕該請求。除了基於簽名的驗證外,此機制還能針對特定重放攻擊提供額外保護。
官方公告指出,此更新強化了合約交易請求在撮合引擎(ME)端的時間驗證功能。Gate 3.0 交易架構的使用者應依最新欄位名稱檢查並更新 API 整合邏輯,以確保時間驗證功能正常運作。
設定時間戳記標頭前,請確認用戶端時鐘已與可靠的時間來源同步。您可使用 NTP,或查詢 Gate 的伺服器時間端點,並記錄本機時鐘與伺服器之間的偏移量。定期重新同步可將偏差維持在可接受範圍內。多數標準 NTP 設定可將偏差控制在數毫秒內,遠低於常見的 1–5 秒逾時時間範圍。
準備每個請求時,擷取自 Unix 時間起點以來、以微秒為單位的目前時間。多數程式語言可直接取得此值:
import time
send_us = int(time.time() * 1_000_000)
const sendUs = Date.now() * 1000;
將此值寫入 X-Gate-Client-Send-Us 標頭。
請選擇符合您策略延遲容忍度的時間範圍。對於需要嚴格控制的做市或剝頭皮策略,500,000 微秒(0.5 秒)是合理選擇。對於網格交易或投資組合再平衡等較慢的策略,5,000,000 微秒(5 秒)可提供較高容忍度。
將此值寫入 X-Gate-Timeout-Window-Us 標頭。
當伺服器因經過時間超出範圍而拒絕請求時,API 會回傳錯誤回應。您的用戶端應:
請勿在重試時重複使用原始標頭。每個新請求都必須包含新的時間戳記及時間範圍。
隨著時間推移,用戶端時鐘可能相對於伺服器產生偏差。請排程定期 NTP 同步,或查詢 Gate 的伺服器時間端點並調整偏移量。您也可在主控台或監控儀表板加入輕量化健康檢查,在每次部署時回報本機時間與伺服器時間之間的偏移量。請將時間驗證失敗率作為營運健康指標;失敗率上升通常代表時鐘偏差,而非網路問題。
REST 端點已於 2026 年 11 月 16 日率先推出。WebSocket 支援將於 2026 年 11 月 19 日推出。兩者皆僅適用於 Gate 3.0 交易架構;其他架構目前不支援此功能。
每個 HTTP 請求都會獨立攜帶兩個標頭。用戶端會在準備請求時建立送出時間戳記。無須維護連線狀態,每個請求皆可獨立處理。
WebSocket 連線為持續性連線。用戶端會透過已建立的連線傳送訊息。送出時間戳記應反映訊息寫入 Socket 的時間,而非連線建立時間。
| 項目 | REST API | WebSocket API |
|---|---|---|
| 推出日期 | 2026 年 11 月 16 日 | 2026 年 11 月 19 日 |
| 連線模型 | 無狀態(每個請求) | 持續性(每個連線) |
| 時間戳記時間點 | 準備請求時 | 將訊息寫入 Socket 時 |
| 適用範圍 | 僅限 Gate 3.0 合約交易 | 僅限 Gate 3.0 合約交易 |
| 整合注意事項 | 在每個請求中設定兩個標頭 | 依每則訊息計算時間戳記,而非依連線計算 |
WebSocket 下單及訂閱管理同樣可受益於此時間驗證功能:過時的訂閱請求或延遲的訂單訊息,也會受到相同的 ME 端時間驗證。
最常見的整合錯誤,是使用毫秒或秒作為時間戳記,而非微秒。毫秒時間戳記比微秒時間戳記小 3 個數量級。伺服器將視為經過時間實際上為負值,或時間已遠在過去。若從秒開始計算,請務必乘以 1,000,000;若從毫秒開始計算,則乘以 1,000。
若用戶端時鐘超前或落後伺服器的幅度超過逾時時間範圍,所有請求都將遭拒絕。解決方法是同步時鐘。若您無法執行 NTP,可從 Gate 的伺服器時間端點計算偏移量,並在建立送出時間戳記前套用該偏移量。
100,000 微秒(0.1 秒)的時間範圍,對跨區域網路路徑或延遲波動較大的用戶端而言可能過於嚴格。若您在嚴格時間範圍下經常遭拒絕,請逐步擴大時間範圍,直到拒絕率降至可接受程度。多數策略可從 1,000,000 微秒(1 秒)開始。
非常大的時間範圍(例如 60,000,000 微秒或 60 秒)幾乎無法防止過時執行。在價格快速變動的合約市場中,已過 60 秒的請求幾乎肯定會以遠離目前市場價格的價格執行。請依您的策略實際延遲容忍度設定時間範圍。
若您省略任一標頭,API 可能會將請求視為未使用時間驗證。實際行為取決於端點及其設定,請查閱您所呼叫端點的官方 API 文件。一般而言,請務必一併設定兩個標頭。
Gate API 合約時間驗證在合約交易 API 的撮合引擎(ME)端新增時間驗證功能。用戶端會傳送 X-Gate-Client-Send-Us(請求準備當下的微秒時間戳記)及 X-Gate-Timeout-Window-Us(以微秒表示的最長有效時間範圍)。本次更新僅適用於 Gate 3.0 交易架構,可防範因網路延遲造成的執行、時鐘偏差及遭重放的請求。
整合需完成 4 個步驟:同步時鐘、計算以微秒為單位的送出時間戳記、在每個請求設定兩個標頭,以及實作重新計算時間戳記的重試邏輯。REST 支援已於 2026 年 11 月 16 日推出,WebSocket 將於 2026 年 11 月 19 日推出,涵蓋 Gate 3.0 合約交易介面。
Gate API 合約時間驗證是 Gate 在合約交易 API 的撮合引擎(ME)端新增的時間驗證功能。X-Gate-Client-Send-Us 與 X-Gate-Timeout-Window-Us 兩個請求標頭會共同確認請求是否在指定時間範圍內送出。本次更新僅適用於 Gate 3.0 交易架構。
合約市場價格可在數毫秒內變動。延遲訂單可能在交易者預期之後很久才抵達撮合引擎,導致非預期成交。時間驗證讓用戶端能以宣告方式指定「N 微秒後將此請求視為無效」,以防範網路延遲、時鐘偏差及遭重放的請求。
這兩個標頭設計為搭配使用。X-Gate-Client-Send-Us 提供送出時間戳記,而 X-Gate-Timeout-Window-Us 提供有效時間範圍。若省略其中任一標頭,伺服器便無法進行時間比較。請查閱官方 API 文件,了解各端點的特定要求。
省略 X-Gate-Timeout-Window-Us 時的預設行為,取決於端點設定。官方 Gate API 文件會說明預設值。需要明確控制的用戶端應一律設定此標頭,而非依賴預設值。
兩個標頭皆使用自 Unix 時間起點以來的微秒。1 秒等於 1,000,000 微秒。1 毫秒等於 1,000 微秒。
API 會回傳錯誤,指出請求未通過撮合引擎端的時間驗證。確切錯誤代碼及訊息格式記載於官方 Gate API 錯誤參考文件。用戶端應透過重新計算時間戳記並重試來處理此錯誤。
未傳送新標頭的現有用戶端,將繼續依原有行為運作。Gate 官方公告要求 Gate 3.0 API 使用者依最新欄位名稱檢查並更新整合邏輯,以確保時間驗證功能正常運作。
此機制僅適用於 Gate 3.0 交易架構的合約(期貨)交易 API。官方公告指出,其他架構目前不支援此功能。現貨交易、錢包及其他 API 群組則遵循各自的規範。
免責聲明: 以上內容僅供資訊及教育用途,不構成財務、投資或交易建議。期貨及衍生品交易涉及重大虧損風險。請查閱官方 Gate API 文件,以取得最新的端點規格、錯誤代碼及欄位要求。
* 投資有風險,入市須謹慎。本文不作為 Gate 提供的投資理財建議或其他任何類型的建議。
* 在未提及 Gate 的情況下,複製、傳播或抄襲本文將違反《版權法》,Gate 有權追究其法律責任。





