Token

Clients may optionally enable Two-Factor Authentication (2FA). When 2FA is activated, an additional Token parameter (as part of the 2FA verification process) is required when connecting to the OpenAPI. If 2FA is not enabled, this section may be ignored.

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 the Token Creation Process.

Token Creation Process

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.

Then, click the Check Now button to begin verification

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

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 NORMAL.

• 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 Test Environment are valid by default. In the production environment, if you have enabled 2FA, you need to complete the 2FA verification to activate the token.

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:

Python

import http.client

conn = http.client.HTTPSConnection("<api_endpoint>")
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"))