Skip to main content

Token

To comply with Hong Kong's regulatory standards and protect account security, clients must provide an additional Token parameter when connecting to the OpenAPI.

Note

If you are a user of the Webull SDK, the Token creation will be initiated automatically when you call the API. You only need to complete the verification within the Webull App. For details, refer to Enter Verification Code to Complete Verification; if you are not using the Webull SDK, please refer to Token Creation Process.

Token Creation Process​

token-flow.png

1. Create Token​

Use the Create Token API to generate a Token. Upon successful creation, a Token with the status "Pending Verification" will be returned, and an SMS verification code will be sent to the phone number bound to your account.

2. Enter the Verification Code to Complete Verification​

Open the Webull App, enter the SMS verification code to complete the verification process. Upon successful verification, the Token status will change to "Active".

Note: Ensure your Webull App is updated to the latest version.

The verification code input window pops up automatically when the Webull App is running and push notifications are enabled. If it does not appear, you can go to Menu → Messages → OpenAPI Notifications, tap the latest verification message, and then enter the verification code to complete the verification. You can refer to the following steps

Firstly, you'll receive a notice from Open API; click the message to view details.

Example banner

Then, click the Check Now button to begin verification

Example banner

Enter the SMS verification code in the input box and click Confirm to complete the verification.

Example banner Example banner
Note

If verification is not completed within 5 minutes, the "Check Token" interface will return a "Verification Timeout" error. In this case, you need to restart the application and initiate the verification process again.

3. Check Token Status​

Use the Check Token API to verify if the Token is valid. The Token statuses are as follows:

  • PENDING: Token Pending Verification

    Description: A newly created Token is set to Pending Verification by default.

  • NORMAL: Token Active

    Description: After a pending Token completes verification, its status will change to Active.

  • INVALID: Token Invalid

    Description: An active Token will be marked as Invalid if no API calls are made using it for 15 consecutive days. When a token does not exist in the system, it will be marked as invalid.

  • EXPIRED: Token Expired

    Description: A pending Token will be marked as Expired if verification is not completed within 5 minutes.

Note

Tokens created in the Sandbox environment are set to NORMAL by default.

4. Store the Token (Optional)​

A valid Token can be reused. To avoid generating a new Token each time you call the OpenAPI, we recommend storing the Token for future use.

5. Using the Token​

After the Token is created and verified successfully, please add the x-access-token field to the request header and pass in a Token with the "Active" status to initiate the request. Below is a request example:

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 a field in the request header and pass in a "Token" with a valid status.
  '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"))