如何建立 WEEX API Key？依步驟連接 WEEX 市場
WEEX API讓開發者和演算法交易者直接連接 WEEX 的現貨和 USDT-M 合約市場——以程式化方式取得市場資料、管理帳戶和下單，而不必透過網頁或應用程式介面操作。本指南依據 WEEX 官方 API 文件，完整介紹建立 API 金鑰、了解權限、正確簽署請求，以及遵守 WEEX 速率限制的流程。
這是一份技術指南，不構成投資建議。建立或執行自動化交易系統會承擔與手動交易相同的市場風險，以及額外的技術風險（錯誤、連線問題和權限設定錯誤都可能造成意外交易或損失）。使用真實資金執行任何策略前，請充分測試。
WEEX API 涵蓋的內容
WEEX 在兩條主要產品線提供 REST 和 WebSocket API——現貨和 USDT-M 合約，此外也提供給經紀商、跟單交易和 AI Wars 整合使用的其他 API。針對現貨和合約，文件分為四個主要類別：
- 市場資料——行情資訊、K 線（涵蓋所有時間週期）、訂單簿深度，以及透過 WebSocket 取得的即時成交串流。
- 帳戶——餘額查詢和帳戶層級資訊。
- 交易——下單、撤單和查詢訂單。
- 設定/一般——伺服器時間、交易所資訊，以及所有端點共用的參考資料。
上述內容會在現貨和合約文件中分別說明，因為即使底層驗證機制相同，兩種產品的請求路徑、參數和部分行為仍有所不同。
步驟 1：建立 API Key
- 在網頁平台登入 WEEX 帳戶。
- 前往帳戶 → API 管理，或直接前往建立 API Key 頁面。
- 選擇建立 API Key並完成必要的安全驗證（通常需要透過帳戶現有的 2FA/驗證方式確認身分）。
- 設定金鑰權限，並且強烈建議將其繫結至特定 IP 位址或範圍（下文將詳細說明）。
- 建立後，WEEX 會顯示三項憑證。請立即儲存全部三項，因為它們只會顯示一次：
| 憑證 | 說明 |
|---|---|
| APIKey | 用於驗證請求身分的系統生成唯一識別碼。 |
| SecretKey | 用於以加密方式簽署請求的系統生成私密金鑰。 |
| Passphrase | 由使用者自行設定的存取密語。遺失後無法復原——你必須建立全新的 API Key。 |
每個 WEEX 帳戶最多可以建立10 組 API Key。如果你想為不同機器人、策略或唯讀監控工具分別使用金鑰，而不是在所有地方重複使用同一把金鑰，這項功能非常實用。
步驟 2：設定權限
每個新 API Key 預設都具有唯讀權限。如果希望金鑰能夠執行交易，就必須明確啟用與整合產品相對應的交易權限：
- 現貨——啟用 WEEX 現貨市場交易。
- 合約——啟用 WEEX 的 USDT-M 合約市場交易。
這些權限彼此獨立。因此，專門為儀表板取得市場資料或帳戶餘額的金鑰可以維持唯讀；而實際用來執行交易策略的金鑰，則必須明確開啟相關交易權限。一般安全做法是，為每個整合建立只涵蓋其實際需求的獨立金鑰，而不是在所有地方使用一把全權限金鑰。
步驟 3：繫結 IP 位址（強烈建議）
建立或編輯 API Key 時，你可以限制它只接受來自特定 IP 位址或位址清單的請求。WEEX 官方文件直接指出：未繫結 IP 位址的 API Key 會帶來安全風險，因為任何取得你的 APIKey 和 SecretKey 的人都能從任何地方使用它。將金鑰繫結至應用程式實際執行所在的伺服器 IP 位址，可以大幅降低憑證洩漏的影響。
了解公開與私有端點
WEEX 的 API 文件將端點分為兩類：
- 公開 API——用於取得設定和市場資料（例如行情價格或訂單簿深度）。這些 API 不需要驗證，完全可以不使用 API Key 呼叫。
- 私有 API——用於帳戶和訂單管理（餘額、下單、訂單歷史）。每個私有請求都必須使用 WEEX 的標準簽名方法進行驗證，詳見下文。
簽署請求（私有端點）
每次私有 API 呼叫都必須包含有效簽名，讓 WEEX 確認請求確實來自你本人且未遭竄改。簽名產生方式如下：
- 串接以下內容以建立訊息字串：
timestamp + method (uppercase) + requestPath + "?" + queryString + body——只有請求確實包含查詢參數時，才會加入"?" + queryString部分；否則省略。 - 使用 SecretKey 透過 HMAC SHA256簽署訊息：
Signature = hmac_sha256(secretKey, message)。 - 將結果進行 Base64 編碼，產生
ACCESS-SIGN標頭的最終值。
實務上還有幾項重要細節：
ACCESS-TIMESTAMP標頭必須使用毫秒，而且若時間戳與伺服器時間相差超過30 秒，WEEX 會拒絕請求。如果本地時鐘有偏差，請查詢 WEEX 的伺服器時間端點並與其同步，不要依賴裝置的本地時鐘。- GET 請求透過查詢字串傳遞參數；POST 請求透過 JSON 內容傳遞參數；DELETE 請求則視具體端點而定，可能使用其中任一方式。
- 簽名字串中的
method值必須使用大寫（GET、POST、DELETE）。
範例——簽署 GET 請求（取得 BTCUSDT 的市場深度）：
timestamp = 1591089508404
method = "GET"
requestPath = "/api/v3/market/depth"
queryString = "symbol=BTCUSDT&limit=20"
message = "1591089508404GET/api/v3/market/depth?symbol=BTCUSDT&limit=20"
範例——簽署 POST 請求（下單）：
timestamp = 1561022985382
method = "POST"
requestPath = "/api/v3/order"
body = {"symbol":"BTCUSDT","side":"BUY","type":"LIMIT","timeInForce":"GTC","quantity":"1","price":"68900","newClientOrderId":"my-order-001"}
message = '1561022985382POST/api/v3/order{"symbol":"BTCUSDT","side":"BUY","type":"LIMIT","timeInForce":"GTC","quantity":"1","price":"68900","newClientOrderId":"my-order-001"}'
在兩種情況下，訊息字串都會被傳入 HMAC SHA256 + Base64 流程，以產生最終的 ACCESS-SIGN 標頭值。
速率限制：實際運作方式
WEEX REST API 實施兩種獨立的速率限制。如果你正在建立主動交易系統，了解兩者的差異非常重要：
IP 速率限制（除下單外的所有操作）
幾乎所有端點——市場資料、帳戶查詢、撤單和查詢訂單狀態——都按IP 位址而不是 API Key 或帳戶進行限流。每個端點都有一個「權重」，消耗較多伺服器資源的端點權重較高。每個回應都會包含顯示目前使用量的標頭：
X-USED-WEIGHT-(intervalNum)(intervalLetter)——目前時間區間已使用的權重（例如，1 分鐘視窗使用X-USED-WEIGHT-1M）。X-REMAINING-WEIGHT-(intervalNum)(intervalLetter)——同一時間區間剩餘的權重。
ORDERS 速率限制（僅限下單）
單筆和批次下單端點專門按帳戶（userId）而非 IP 進行限流，而且完全不消耗 IP 權重——這些呼叫的 IP 速率限制計數器會顯示 0。相關回應標頭包括：
X-ORDER-COUNT-(intervalNum)(intervalLetter)——目前時間區間已下的訂單數。X-ORDER-REMAINING-(intervalNum)(intervalLetter)——該時間區間剩餘的訂單數。
其他訂單相關操作——例如撤單或查詢訂單——不受 ORDERS 限制，而是歸入標準的 IP 權重限制。
超過限制會發生什麼
超過速率限制會返回HTTP 429狀態碼。此時，WEEX 要求你停止傳送請求——在 429 後繼續呼叫 API 會被視為濫用，並導致10 秒封禁。對任何生產系統而言，最好預留餘量（在接近限制前退避），而不是被動等待 429 後才處理。
上線前的實用檢查清單
- 安全儲存 APIKey、SecretKey 和 Passphrase——建立金鑰後立即儲存，因為之後無法再次取得其中任何一項；Passphrase 遺失就必須建立全新金鑰。
- 將金鑰繫結至特定 IP，不要讓它不受限制。
- 將權限限定在每個整合實際需要的範圍——儀表板和監控工具使用唯讀權限，只有確實下單的金鑰才啟用交易權限。
- 將本地時鐘與 WEEX 伺服器時間同步，尤其是在遇到與時間戳相關的簽名失敗時。
- 讀取回應標頭，而不只是回應內容——權重和訂單計數標頭會告訴你距離速率限制還有多遠。
- 透過退避處理 429，不要立即重試，以免延長封禁。
- 若懷疑 API Key 已洩漏或遭入侵，請立即刪除該金鑰。
最後總結
建立 WEEX API Key 是一個短流程——產生金鑰、設定權限並安全儲存憑證——但正確使用它需要更深入了解兩件事：請求簽名的實際運作方式，以及兩套獨立的速率限制系統（基於 IP 的權重限制和基於帳戶的訂單限制）如何套用於不同端點類型。精確設定簽名格式並遵守兩種限制，是 API 新使用者最常遇到整合問題的兩個來源。
如需完整且最新的端點參考，請先查看官方API 簡介和現貨 API 準備指南。後者也連結到對應的合約文件、存取限制參考資料，以及每個市場、帳戶和交易呼叫的端點層級文件。
透過 API 交易承擔的底層市場風險與手動交易相同——自動化不會降低或消除虧損可能性。請充分測試任何整合，先從小額開始，並確保準確了解所建立金鑰具備的權限。
WEEX 不向美國、其屬地或某些其他受限制司法管轄區的使用者提供服務。建立帳戶或 API Key 前，請查看使用條款，了解目前排除的司法管轄區清單和資格要求。
