跳至主要内容

Token

為符合香港監管標準並保護帳戶安全，所有 API 認證均需要 Token。Token 作為請求簽名之外的額外安全層。

SDK 用戶

如果您使用 Webull SDK，只需完成步驟 2：在 Webull App 中驗證。SDK 會自動處理其餘所有步驟。

Token 生命週期​

token-flow.png

步驟 1：建立 Token​

呼叫 建立 Token API 生成新的 Token。回應會返回狀態為 PENDING 的 Token，同時向您帳戶綁定的手機號碼發送簡訊驗證碼。

如果您使用 SDK，此步驟會在您首次呼叫 API 時自動執行。程式會循環等待驗證：

img.png

步驟 2：在 Webull App 中驗證​

開啟 Webull App，輸入簡訊驗證碼以啟用 Token。驗證成功後，Token 狀態變更為 NORMAL。

警告

請確保您的 Webull App 已更新至最新版本。

如果 App 正在運行且推送通知已開啟，驗證提示會自動彈出。如果未出現，請手動操作：

  1. 前往選單 → 訊息 → OpenAPI 通知，點擊最新的驗證訊息。
  2. 點擊立即查看開始驗證。
  3. 輸入簡訊驗證碼並點擊確認。
Example banner Example banner Example banner
驗證逾時

如果未在 5 分鐘內完成驗證，Token 將會過期。您需要建立新的 Token 並重新開始流程。

步驟 3：檢查 Token 狀態​

使用 檢查 Token API 驗證 Token 的當前狀態：

狀態說明
PENDING新建立，等待驗證
NORMAL已啟用，可用於 API 呼叫
INVALID連續 15 天未使用 Token 進行 API 呼叫，或 Token 不存在
EXPIRED未在 5 分鐘內完成驗證
沙盒環境

在沙盒環境中建立的 Token 預設為 NORMAL 狀態 — 無需驗證。

步驟 4：儲存並重複使用 Token​

有效的 Token 可在多次 API 呼叫中重複使用。為避免每次都建立新的 Token，請安全儲存並重複使用，直到其變為無效或過期。

步驟 5：在請求中包含 Token​

在 API 請求中加入 x-access-token 標頭，傳入已啟用的 Token：

headers = {
    'x-app-key': '<your_app_key>',
    'x-timestamp': '2025-11-13T01:37:20Z',
    'x-signature-version': '1.0',
    'x-signature-algorithm': 'HMAC-SHA1',
    'x-signature-nonce': '<unique_nonce>',
    'x-version': 'v2',
    'x-signature': '<computed_signature>',
    'x-access-token': '<your_active_token>',
}
資訊

app_secret 僅在客戶端用於計算簽名，不會作為請求標頭發送。詳見簽名。