Token

基於香港合規要求以及賬戶安全性考慮，客戶端連接OpenAPI時須額外傳遞Token參數。

提示

若閣下是使用 Webull SDK 的用戶，調用接口時會自動發起建立 Token，只需在 Webull App 內完成驗證即可。詳情請參閱輸入驗證碼以完成驗證；若閣下未使用 Webull SDK，請參考 Token驗證流程。

Token驗證流程

1. 建立Token

使用建立 Token API 建立一個 Token，建立成功後，系統會返回狀態為「待驗證」的 Token，並向閣下帳戶已綁定的手機號碼發送簡訊驗證碼。

2. 輸入驗證碼以完成驗證

打開Webull App，輸入簡訊驗證碼以完成驗證流程，驗證成功後，Token狀態將會變為「有效」

注意： 請確保閣下的Webull App已更新至最新版本

當Webull App正在運行且已啟用推播通知時，驗證碼輸入視窗將自動彈出。若未出現，可前往「選單」→「訊息」→「OpenAPI 通知」，點擊最新的驗證訊息，然後輸入驗證碼以完成驗證。您可以參考以下的步驟來完成驗證：

首先，您將收到來自Open API的通知；點擊訊息以查看詳細資料

然後，點擊「Check Now」按鈕以開始驗證

請在輸入框中輸入短信驗證碼，並點擊確認以完成驗證

提示

若未在5分鐘內完成驗證，檢查 Token介面將返回「驗證逾時」錯誤，此時需重新啟動程式並再次發起驗證流程

3. 檢查 Token 狀態

請使用驗證 Token API 確認Token是否有效，有關Token狀態說明如下：

PENDING：Token 待驗證
說明：新建立的「Token」預設為待驗證狀態
NORMAL：Token 有效
說明：待驗證的「Token」完成驗證後，其狀態會變更為有效
INVALID：Token 無效
說明：當有效狀態的「Token」連續15天未調用任何介面時，該「Token」將被判定為無效；「Token」在繫統中不存在時判定爲無效
EXPIRED：Token 已過期
說明：當待驗證的「Token」未在5分鐘內完成驗證，該「Token」將被判定為過期

注意

在 Sandbox 環境中建立的Token，預設狀態為NORMAL

4. 儲存 Token（可選）

一個有效狀態的Token可重複使用。為避免每次呼叫OpenAPI時都需重新產生新的Token，建議閣下將Token儲存起來，以便日後使用。

5. 使用 Token

Token建立與驗證完成後，請在請求標頭中新增 x-access-token 欄位，並傳入狀態為「NORMAL」的Token以發起請求，以下為請求示例：

Python

import http.client

conn = http.client.HTTPSConnection("api.webull.hk")
payload = ''
headers = {
  'Accept': 'application/json',
  'x-app-key': '<your_app_key>',
  'x-app-secret': '<your_app_secret>',
  'x-timestamp': '2025-11-13T01:37:20Z',
  'x-signature-version': '1.0',
  'x-signature-algorithm': 'HMAC-SHA1',
  'x-signature-nonce': '84537259051719556825112039',
  
  # Add the field to the request header and pass in an active Token
  'x-access-token': '30434052718254686395872559',
  
  'x-version': 'v2',
  'x-signature': '68286690219370539858034209'
}
conn.request("GET", "/instrument/list?symbols=BULL&category=US_STOCK", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Token驗證流程​

1. 建立Token​

2. 輸入驗證碼以完成驗證​

3. 檢查 Token 狀態​

4. 儲存 Token（可選）​

5. 使用 Token​