# List Virtual Accounts
Retrieves a paginated list of Virtual Accounts.
# OpenAPI definition
```json
{
"info": {
"title": "Webull Open API Reference",
"description": "application.yml\\ncom\\ni18n\\nMETA-INF\\nstatic\\n\\r\\n",
"contact": {
"name": "",
"url": "",
"email": ""
},
"version": "2.0",
"x-logo": {
"url": "static/png/logo.png"
}
},
"servers": [
{
"url": "https://broker-api.sandbox.webull.hk"
}
],
"path": "/broker/accounts/virtual-accounts/list",
"method": "get",
"tags": [
"Account (ND)"
],
"description": "Retrieves a paginated list of Virtual Accounts.",
"operationId": "brokerAccountList",
"parameters": [
{
"name": "start_time",
"in": "query",
"description": "Inclusive start time for the query. formats: yyyy-MM-dd'T'HH:mm:ss.SSSZ",
"required": false,
"schema": {
"type": "String"
},
"example": "2025-01-05T22:59:11.591Z"
},
{
"name": "end_time",
"in": "query",
"description": "Inclusive end time for the query, formats: yyyy-MM-dd'T'HH:mm:ss.SSSZ",
"required": false,
"schema": {
"type": "String"
},
"example": "2025-01-06T22:59:11.591Z"
},
{
"name": "pagination_key",
"in": "query",
"description": "Pagination key from previous response for next page.",
"required": false,
"schema": {
"type": "String"
},
"example": "eyJ2IjoxLCJsYXN0SWQiOiI5MTMyNDQ3NjkiLCJwYWdlSW===="
},
{
"name": "x-app-key",
"in": "header",
"description": "A unique identifier issued to a developer for accessing an application's API.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "x-app-secret",
"in": "header",
"description": "A unique key issued to developers to access the application's API.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "x-timestamp",
"in": "header",
"description": "Timestamp of the request, follows ISO8601 format: YYYY-MM-DDThh:mm:ssZ, e.g. 2023-07-16T19:23:51Z, only supports UTC time zone.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "x-signature-version",
"in": "header",
"description": "Signature algorithm version, default is 1.0.",
"required": true,
"schema": {
"type": "string",
"default": "1.0"
},
"examples": {
"1.0": {
"value": "1.0"
}
}
},
{
"name": "x-signature-algorithm",
"in": "header",
"description": "Signature algorithm, default is HMAC-SHA1.",
"required": true,
"schema": {
"type": "string",
"default": "HMAC-SHA1"
},
"examples": {
"HMAC-SHA1": {
"value": "HMAC-SHA1"
}
}
},
{
"name": "x-signature-nonce",
"in": "header",
"description": "Signature unique random number.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "x-version",
"in": "header",
"description": "API interface version. Supported values: `v2`, `v3`.",
"required": true,
"schema": {
"type": "string",
"default": "v3"
},
"examples": {
"v3": {
"value": "v3"
}
}
},
{
"name": "x-signature",
"in": "header",
"description": "A signature is a unique digital fingerprint, typically encrypted, that verifies the authenticity and integrity of a message or transaction, ensuring it has not been tampered with during transmission.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"description": "Result data list",
"items": {
"required": [
"account_id",
"account_number",
"account_status",
"account_type",
"belong_account_id",
"belong_account_number",
"trading_permissions"
],
"type": "object",
"properties": {
"belong_account_number": {
"type": "string",
"description": "Belonging Account Number, the master account belong to",
"example": "FV000123"
},
"belong_account_id": {
"type": "string",
"description": "Belonging Account ID, the master account belong to",
"example": "4942451778e14177b9ab066b9662bda9"
},
"account_number": {
"type": "string",
"description": "Account Number",
"example": "VA000000001"
},
"account_id": {
"type": "string",
"description": "Account ID",
"example": "943a9802f6c14983b3b4755c69c01717"
},
"account_type": {
"type": "string",
"description": "Account Type
CASH: Cash Account
MARGIN: Margin Account",
"example": "CASH",
"enum": [
"CASH",
"MARGIN"
]
},
"account_status": {
"type": "string",
"description": "Account Status
CREATED - Account is created but not yet active
ACTIVE - Account is active and operational
SUSPENDED - Account temporarily suspended
RESTRICTED - Account restricted, limited operations
FROZEN - Account frozen due to compliance or risk
CLOSED - Account permanently closed",
"example": "CREATED",
"enum": [
"CREATED",
"ACTIVE",
"SUSPENDED",
"RESTRICTED",
"FROZEN",
"CLOSED"
]
},
"trading_permissions": {
"type": "array",
"description": "Trading Permissions",
"example": [
"US_STOCK_NORMAL",
"US_STOCK_FRACTIONAL",
"US_STOCK_OVERNIGHT",
"HK_STOCK_NORMAL",
"HK_STOCK_FRACTIONAL"
],
"items": {
"type": "string",
"description": "Trading Permission
US_STOCK_NORMAL - US Stock Normal Trading Permission
HK_STOCK_NORMAL - HK Stock Normal Trading Permission
US_OPTION_NORMAL - US Option Normal Trading Permission
CN_STOCK_NORMAL - CN Stock Trading Permission",
"example": "[\"US_STOCK_NORMAL\",\"US_STOCK_FRACTIONAL\",\"US_STOCK_OVERNIGHT\",\"HK_STOCK_NORMAL\",\"HK_STOCK_FRACTIONAL\"]",
"enum": [
"US_STOCK_NORMAL",
"HK_STOCK_NORMAL",
"CN_STOCK_NORMAL",
"US_OPTION_NORMAL"
]
}
},
"option_level": {
"type": "string",
"description": "The option level must be less than or equal to the option level of the master account.When the trading_permissions contains US_OPTION_NORMAL, it needs to be filled in",
"example": "LV1",
"enum": [
"LV1",
"LV2",
"LV3",
"LV4"
]
},
"commission_code": {
"type": "string",
"description": "Commission Code",
"example": "STANDARD_COMMISSION"
},
"w8ben_info": {
"required": [
"first_name",
"home_address",
"last_name",
"sign_date",
"tax_id",
"treaty_country"
],
"type": "object",
"properties": {
"treaty_country": {
"type": "string",
"description": "Country of Treaty, using ISO 3166-1 alpha-2 format",
"example": "US"
},
"tax_id": {
"type": "string",
"description": "Tax Identification Number",
"example": "123-45-6789"
},
"sign_date": {
"type": "string",
"description": "W-8BEN Form Sign Date, format: YYYY-MM-DD",
"example": "2026-01-01"
},
"first_name": {
"type": "string",
"description": "First Name of the account holder",
"example": "John"
},
"last_name": {
"type": "string",
"description": "Last Name of the account holder",
"example": "Doe"
},
"middle_name": {
"type": "string",
"description": "Middle Name of the account holder",
"example": "Michael"
},
"home_address": {
"required": [
"city",
"country",
"postal_code",
"state",
"street_address"
],
"type": "object",
"properties": {
"country": {
"type": "string",
"description": "Country, using ISO 3166-1 alpha-2 format",
"example": "US"
},
"state": {
"type": "string",
"description": "State or Province",
"example": "California"
},
"city": {
"type": "string",
"description": "City",
"example": "Central"
},
"street_address": {
"type": "string",
"description": "Street Address",
"example": "1 Queen's Road"
},
"postal_code": {
"type": "string",
"description": "Postal Code",
"example": "999077"
}
},
"description": "W-8BEN Address Information",
"title": "W8BenAddress"
},
"mail_address": {
"required": [
"city",
"country",
"postal_code",
"state",
"street_address"
],
"type": "object",
"properties": {
"country": {
"type": "string",
"description": "Country, using ISO 3166-1 alpha-2 format",
"example": "US"
},
"state": {
"type": "string",
"description": "State or Province",
"example": "California"
},
"city": {
"type": "string",
"description": "City",
"example": "Central"
},
"street_address": {
"type": "string",
"description": "Street Address",
"example": "1 Queen's Road"
},
"postal_code": {
"type": "string",
"description": "Postal Code",
"example": "999077"
}
},
"description": "W-8BEN Address Information",
"title": "W8BenAddress"
}
},
"description": "W-8BEN Information,When trading U.S. stocks in the account, this information needs to be supplemented.\n\n",
"title": "W8BenInfoResult"
},
"china_connect_investor_info": {
"required": [
"country_of_issuance",
"first_name",
"id_number",
"id_type",
"last_name"
],
"type": "object",
"properties": {
"first_name": {
"type": "string",
"description": "First Name",
"example": "John"
},
"last_name": {
"type": "string",
"description": "Last Name",
"example": "Doe"
},
"middle_name": {
"type": "string",
"description": "Middle Name",
"example": "Michael"
},
"id_type": {
"type": "string",
"description": "ID Type
ID_CARD: Identification Card
PASSPORT: Passport
CERT_INCORP: Certificate of Incorporation
LEI: Legal Entity Identifier
OTHER_OFFICIAL_ID_DOC: Other Official ID Document",
"example": "ID_CARD",
"enum": [
"ID_CARD",
"PASSPORT",
"CERT_INCORP",
"LEI",
"OTHER_OFFICIAL_ID_DOC"
]
},
"id_number": {
"type": "string",
"description": "ID Number",
"example": "X12345678"
},
"country_of_issuance": {
"type": "string",
"description": "Country of Issuance, using ISO 3166-1 alpha-2 format",
"example": "US"
}
},
"description": "China Connect Investor Information,This information only needs to be supplemented when trading Chinese A-shares.\n\n",
"title": "ChinaConnectInvestorInfo"
}
},
"description": "VA Account Detail Result",
"title": "AccountVaDetailResult"
}
},
"pagination_key": {
"type": "string",
"description": "Pagination key for next page. If absent, indicates this is the last page.",
"example": "eyJ2IjoxLCJsYXN0SWQiOiI5MTMyNDQ3NjkiLCJwYWdlSW===="
}
},
"description": "Paginated result with cursor-based pagination",
"title": "PaginatedResultVoAccountVaDetailResult"
}
}
}
},
"401": {
"description": "Unauthorized: Authentication required",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error_code": {
"type": "string",
"description": "Internal logic error code",
"example": "UNAUTHORIZED"
},
"message": {
"type": "string",
"description": "Error message",
"example": "Insufficient permission"
}
}
}
}
}
},
"417": {
"description": "A business logic error triggered when the request cannot be processed due to domain-specific constraints.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error_code": {
"type": "string",
"description": "Internal logic error code",
"example": "INVALID_PARAMETER"
},
"message": {
"type": "string",
"description": "Error message",
"example": "Parameter error, phone"
}
}
}
}
}
},
"500": {
"description": "Internal Server Error.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error_code": {
"type": "string",
"description": "Internal logic error code",
"example": "SYSTEM_ERROR"
},
"message": {
"type": "string",
"description": "Error message",
"example": "Internal Server Error"
}
}
}
}
}
}
},
"postman": {
"name": "List Virtual Accounts",
"description": {
"content": "Retrieves a paginated list of Virtual Accounts.",
"type": "text/plain"
},
"url": {
"path": [
"broker",
"accounts",
"virtual-accounts",
"list"
],
"host": [
"{{baseUrl}}"
],
"query": [
{
"disabled": false,
"description": {
"content": "Inclusive start time for the query. formats: yyyy-MM-dd'T'HH:mm:ss.SSSZ",
"type": "text/plain"
},
"key": "start_time",
"value": ""
},
{
"disabled": false,
"description": {
"content": "Inclusive end time for the query, formats: yyyy-MM-dd'T'HH:mm:ss.SSSZ",
"type": "text/plain"
},
"key": "end_time",
"value": ""
},
{
"disabled": false,
"description": {
"content": "Pagination key from previous response for next page.",
"type": "text/plain"
},
"key": "pagination_key",
"value": ""
}
],
"variable": []
},
"header": [
{
"disabled": false,
"description": {
"content": "(Required) A unique identifier issued to a developer for accessing an application's API.",
"type": "text/plain"
},
"key": "x-app-key",
"value": ""
},
{
"disabled": false,
"description": {
"content": "(Required) A unique key issued to developers to access the application's API.",
"type": "text/plain"
},
"key": "x-app-secret",
"value": ""
},
{
"disabled": false,
"description": {
"content": "(Required) Timestamp of the request, follows ISO8601 format: YYYY-MM-DDThh:mm:ssZ, e.g. 2023-07-16T19:23:51Z, only supports UTC time zone.",
"type": "text/plain"
},
"key": "x-timestamp",
"value": ""
},
{
"disabled": false,
"description": {
"content": "(Required) Signature algorithm version, default is 1.0.",
"type": "text/plain"
},
"key": "x-signature-version",
"value": ""
},
{
"disabled": false,
"description": {
"content": "(Required) Signature algorithm, default is HMAC-SHA1.",
"type": "text/plain"
},
"key": "x-signature-algorithm",
"value": ""
},
{
"disabled": false,
"description": {
"content": "(Required) Signature unique random number.",
"type": "text/plain"
},
"key": "x-signature-nonce",
"value": ""
},
{
"disabled": false,
"description": {
"content": "(Required) API interface version. Supported values: `v2`, `v3`.",
"type": "text/plain"
},
"key": "x-version",
"value": ""
},
{
"disabled": false,
"description": {
"content": "(Required) A signature is a unique digital fingerprint, typically encrypted, that verifies the authenticity and integrity of a message or transaction, ensuring it has not been tampered with during transmission.",
"type": "text/plain"
},
"key": "x-signature",
"value": ""
},
{
"key": "Accept",
"value": "application/json"
}
],
"method": "GET"
}
}
```