WEEX API 指南：設定、呼叫、權限與安全

如果您希望透過程式碼自動獲取價格、下單並管理帳戶，首先需要了解如何開啟、呼叫 WEEX API，以及最關鍵的——如何配置其權限範圍。WEEX API 是一套 WEEX 向開發者和量化交易者開放的程式設計介面，提供 REST 和 WebSocket 存取方式，讓您無需時刻盯著螢幕即可拉取市場數據、下單撤單以及查詢帳戶。本指南將圍繞 API 的定義、使用方法、呼叫方式及其安全性展開，並重點講解大多數教學容易忽略的部分：API 權限與安全，這正是資金安全最容易出問題的地方。

以下所有介面參數均來自 WEEX 官方 API 文件，反映了截至 2026 年 7 月的公開資訊。API 規則可能會發生變化，請在整合前與開發者中心核實。

什麼是 WEEX API：功能概覽

簡而言之：WEEX API 是讓程式碼操作您帳戶的通道，分為「公共」和「私有」兩類。公共端點用於獲取市場數據和系統配置，無需身份驗證；私有端點用於處理下單、撤單和帳戶管理，每個請求都必須簽名。在產品層面，它涵蓋了 100 多種資產的現貨和 USDT 本位合約。

選擇 REST 還是 WebSocket 取決於您是想「單次查詢」還是「持續監聽」。若要查詢餘額或發送單筆訂單，使用 REST 即可；若要接收即時價格、深度變化或訂單成交推送，請保持 WebSocket 連接——它更簡單且更及時。

如何獲取您的 WEEX API Key

登入 WEEX 網頁平台，在 API 管理頁面建立金鑰。系統會同時生成三項內容，您需要妥善保存：

• APIKey — 演算法生成的識別碼，相當於您的「使用者名稱」。
• SecretKey — 系統頒發的私鑰，用於對每個請求進行簽名。
• Passphrase — 您自行設定的存取短語。請務必注意：如果遺失 Passphrase 無法找回——您必須刪除該金鑰組並建立新的。

每個帳戶最多可建立 10 組 API Key，方便您按策略和環境分配不同的金鑰。建立時有兩個選項決定了金鑰的安全底線：您勾選的權限（見下節）和綁定的 IP。WEEX 明確指出，未綁定 IP 的「無限制」金鑰存在安全風險——如果您的伺服器 IP 固定，請務必填寫 IP 白名單。

WEEX API 權限：唯讀與交易的界限

本節請務必閱讀兩遍。新建立的 API Key 預設權限為「唯讀」。若要透過 API 進行交易，您必須手動啟用相應的「現貨」交易權限。權限過大意味著金鑰洩漏後的損失更大；權限過小則策略無法執行。原則只有一條：僅授予策略實際需要的最小權限。

一個容易被忽視但對安全至關重要的細節：截至 2026 年 7 月，WEEX 現貨 API 快速入門文件中列出的權限僅為「唯讀」和「現貨交易」這兩項，沒有單獨的「提現」開關。對於大多數策略而言，這是一個功能而非缺陷：即使金鑰洩漏，持有者也無法直接提取資產。請以您實際建立金鑰頁面顯示的選項為準。

如何呼叫：簽名請求的必要條件

私有端點呼叫的核心門檻在於「簽名」步驟。WEEX 使用 HMAC SHA256 生成簽名：用您的 SecretKey 加密預簽名字串，然後對結果進行 Base64 編碼。預簽名字串的拼接順序是固定的：

timestamp + method (大寫) + requestPath + "?" + queryString + body

當 queryString 為空時省略。以 GET 深度請求為例：/api/v3/market/depth?symbol=BTCUSDT&limit=20，時間戳為 1591089508404，生成的預簽名字串為 1591089508404GET/api/v3/market/depth?symbol=BTCUSDT&limit=20。

簽名後，每個私有請求需攜帶四個請求頭：

私有 WebSocket 通道的操作方式相同——對時間戳加上請求路徑 /v3/ws/private 進行簽名即可登入。新手最容易卡住的地方不是加密，而是時間戳：如果您的請求時間戳與伺服器時間偏差超過 30 秒，請求將被直接拒絕。本地時鐘錯誤或快取的時間戳過期會導致莫名其妙的 401 錯誤。在正式上線前同步 NTP 時間可以省去一半的除錯工作。完整欄位和範例請參考官方 整合準備文件 和 簽名參考。

必須了解的速率限制與存取規則

呼叫頻率有限制。預設上限為 10 次請求/秒，部分端點在文件中會有單獨說明；超過限制會返回 429 Too Many Requests。注意統計基準：已授權請求按 API Key 計算，未授權請求按公共 IP 計算——這意味著同一伺服器上多個共享出口 IP 的唯讀腳本可能會擠佔公共端點的配額。

有一條批量處理規則值得記住：一個包含 4 個交易對、每個交易對 10 個訂單的批量訂單請求，僅計為一次請求。透過合併訂單，高頻策略可以在提高吞吐量的同時節省配額。

WEEX API 安全嗎？區分可控與不可控因素

「安全嗎」這個問題不能簡單回答。在平台端，您擁有簽名驗證、IP 綁定、分級權限和基於時間戳的重放保護。但在 API 實際應用中，大多數事故發生在使用者側——金鑰儲存不當、權限範圍過大、憑證硬編碼在前端或公開倉庫中。可控的部分完全掌握在您手中：

• 將權限限制在最小範圍內；唯讀策略絕不應持有交易權限。
• 為每個金鑰綁定固定 IP——不要使用無限制金鑰。
• 將 SecretKey 和 Passphrase 存放在環境變數或金鑰管理器中，絕不要硬編碼在客戶端程式碼中或提交到 Git。
• 開發和生產環境使用不同的金鑰，避免相互干擾。
• 定期輪換金鑰，一旦發現異常呼叫，立即在網頁平台刪除金鑰——金鑰隨時可以撤銷並重建，這是止損的最快方法。
• 對帳戶活動和呼叫量設定監控和警報，以便異常頻率或訂單能立即被發現。

如需更廣泛的功能概覽和常見問題解答，請參閱 WEEX 關於 WEEX 是否支援 API 交易 的說明。只要做好上述檢查清單，WEEX API 的安全性主要取決於您的金鑰管理習慣，而非任何神秘因素。

簡要總結

接入 WEEX API 的路徑其實很清晰：在網頁平台建立具有最小權限的 API Key（預設唯讀，交易需手動開啟），收集 APIKey / SecretKey / Passphrase 三件套並綁定 IP；呼叫私有端點時，按固定格式使用 HMAC SHA256 簽名，發送全部四個請求頭，並遵守 30 秒時間戳視窗和 10 次/秒的速率限制；最後，嚴格把控金鑰管理、最小權限原則、IP 白名單和監控報警。若要上手，請先在 WEEX 開發者中心 對公共市場端點進行首次請求，然後再加入私有下單功能。

常見問題解答

1. WEEX 支援 API 交易嗎？

支援。WEEX 提供 REST 和 WebSocket 介面，用於自動化市場數據獲取、下單撤單以及帳戶管理，涵蓋現貨和 USDT 本位合約——適用於量化、網格和做市機器人。

2. 一個帳戶可以建立多少個 API Key？

最多 10 組。最好按策略和環境進行拆分——例如一個唯讀監控金鑰、一個現貨交易金鑰、一個開發/測試金鑰——這樣它們可以獨立執行並單獨撤銷。

3. 如果忘記了 Passphrase 怎麼辦？

無法找回。Passphrase 是您建立時自行定義的短語，系統不會以明文形式儲存。如果遺失，您只能刪除該 API Key 組並重新建立。

4. 為什麼我的私有請求一直被拒絕？

最常見的原因是時間戳。如果您的請求時間戳與 WEEX 伺服器時間偏差超過 30 秒，請求會被拒絕——請先同步本地時鐘。然後檢查預簽名字串的順序、方法名是否為大寫，以及四個請求頭是否齊全。

5. 如果我的 API Key 洩漏，攻擊者可以提走我的幣嗎？

對於現貨 API，風險相對可控——截至 2026 年 7 月，文件中說明的權限僅為「唯讀」和「現貨交易」，沒有獨立的提現權限。即便如此，也請立即在網頁平台刪除洩漏的金鑰，並檢查是否有異常訂單。

6. 呼叫有速率限制嗎？

有。預設限制為 10 次請求/秒；超過限制會返回 429。已授權請求按 API Key 計算，未授權請求按 IP 計算。批量訂單（例如 4 個交易對各 10 個訂單）計為一次請求，高頻策略可以利用這一點來節省配額。

風險提示

數位資產波動劇烈，透過 API 進行程式化交易可能會放大而非降低風險，可能導致本金部分或全部損失。API 交易特有的風險包括：金鑰洩漏導致的盜竊或未經授權的訂單、程式碼邏輯錯誤導致的級聯錯誤訂單、網路延遲或時間戳漂移導致的訂單失敗、因超過呼叫限制被限流而錯失市場，以及合約槓桿下的強平風險。請務必將金鑰權限限制在最小範圍，綁定 IP，妥善保管 SecretKey 和 Passphrase，並在正式上線前在小規模環境中進行充分測試。本文僅為技術整合指南，不構成投資建議。