Token

Clients may optionally enable Two-Factor Authentication (2FA). When 2FA is activated, an additional Token is required for API authentication. If 2FA is not enabled, you can skip this page.

SDK Users

If you're using the Webull SDK, you only need to complete Step 2: Verify in the Webull App. The SDK handles everything else automatically.

Token Lifecycle

Step 1: Create a Token

Call the Create Token API to generate a new Token. The response returns a Token with status PENDING, and an SMS verification code is sent to the phone number bound to your account.

If you're using the SDK, this step happens automatically when you make your first API call. Your program will loop and wait for verification:

Step 2: Verify in the Webull App

Open the Webull App and enter the SMS verification code to activate the Token. Once verified, the Token status changes to NORMAL.

caution

Make sure your Webull App is updated to the latest version.

The verification prompt appears automatically if the app is running with push notifications enabled. If it doesn't appear, navigate manually:

1. Go to Menu → Messages → OpenAPI Notifications and tap the latest verification message.
2. Tap Check Now to begin verification.
3. Enter the SMS verification code and tap Confirm.

Verification Timeout

If verification is not completed within 5 minutes, the Token will expire. You'll need to create a new Token and start the process again.

Step 3: Check Token Status

Use the Check Token API to verify your Token's current status:

Status	Description
PENDING	Newly created, awaiting verification
NORMAL	Active and valid for API calls
INVALID	No API calls made for 15 consecutive days, or Token does not exist
EXPIRED	Verification was not completed within 5 minutes

Test Environment

Tokens created in the test environment are valid by default — no 2FA verification is needed.

Step 4: Store and Reuse the Token

A valid Token can be reused across multiple API calls. To avoid creating a new Token every time, store it securely and reuse it until it becomes invalid or expired.

Step 5: Include the Token in Requests

Add the x-access-token header to your API requests with an active 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>',
}

info

The app_secret is used only for computing the signature on the client side. It is not included as a request header. See Signature for details.