Broker API — HK

⚠️ Generated file — do not edit. Regenerate with python tools/webull-docgen/docgen.py <target> (reference, master, reconciliation or all).

Institutional Broker API for Hong Kong. Uses the DoBroker transport. The HK sandbox returns 401 ROUTE_NOT_PERMITTED (missing app scope).

<- Webull API Reference

Create Virtual Account

POST /broker/accounts/virtual-accounts/create

Creates a Virtual Account for a new customer.

SDK	broker.CreateVirtualAccount
Reference	broker-account-create.md

Request body

Field	Type	Required	Description
client_request_id	string	yes	Client Request ID, unique for each request. Maximum length is 32 characters. Allowed characters: letters (A–Z, a–z), digits (0–9), hyphen (-), underscore (_).
belong_account_id	string	yes	Belonging Account ID, the master account under which the VA account is created
external_account_number	string		The account number of the end customer in your own system, used as the client-defined segment of the virtual account number. The final account_number is composed as: V + Entity Code + this value, where the Entity Code is assigned by Webull during onboarding. Example: Entity Code ABCD + 10000001 → VABCD10000001. • Length: 1-10 characters. • Allowed characters: ASCII digits (0-9), English letters (a-z, A-Z), hyphen (-) and underscore (_). • Case-sensitive: ab123 and AB123 are treated as different accounts. • Leading zeros are significant: 00123 and 123 are different accounts. • No sequential or other format requirement beyond the above — any value is accepted as long as it is unique within your entity (which makes the composed account_number globally unique). • Immutable after account creation. • If omitted, the account number is generated by the system. The composed account_number is used consistently across order placement (FIX Tag 1), queries, and SOD reconciliation files.
account_type	string	yes	Account Type CASH: Cash Account MARGIN: Margin Account — one of: CASH, MARGIN
trading_permissions	array	yes	Trading Permissions for the VA account, list of permission codes
option_level	string		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 — one of: LV1, LV2, LV3, LV4
commission_code	string		Commission Code for the VA account, determining the commission structure.The specific value of the Commission Code needs to be confirmed with the Webull business team, as it determines how commissions will be charged. — one of: COMMISSION_GROUP_1, COMMISSION_GROUP_2, COMMISSION_GROUP_3, COMMISSION_GROUP_4, COMMISSION_GROUP_5
w8ben_info	object		W-8BEN Information,When trading U.S. stocks in the account, this information needs to be supplemented.
china_connect_investor_info	object		China Connect Investor Information,This information only needs to be supplemented when trading Chinese A-shares.

Nested — w8ben_info:

Field	Type	Required	Description
treaty_country	string	yes	Country of Treaty, using ISO 3166-1 alpha-2 format
tax_id	string	yes	Tax Identification Number
sign_date	string	yes	W-8BEN Form Sign Date, format: YYYY-MM-DD
first_name	string	yes	First Name of the account holder
last_name	string	yes	Last Name of the account holder
middle_name	string		Middle Name of the account holder
home_address	object	yes	W-8BEN Address Information
mail_address	object	yes	W-8BEN Address Information

Nested — home_address:

Field	Type	Required	Description
country	string	yes	Country, using ISO 3166-1 alpha-2 format
state	string	yes	State or Province
city	string	yes	City
street_address	string	yes	Street Address
postal_code	string	yes	Postal Code

Nested — mail_address:

Field	Type	Required	Description
country	string	yes	Country, using ISO 3166-1 alpha-2 format
state	string	yes	State or Province
city	string	yes	City
street_address	string	yes	Street Address
postal_code	string	yes	Postal Code

Nested — china_connect_investor_info:

Field	Type	Required	Description
first_name	string	yes	First Name
last_name	string	yes	Last Name
middle_name	string		Middle Name
id_type	string	yes	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 — one of: ID_CARD, PASSPORT, CERT_INCORP, LEI, OTHER_OFFICIAL_ID_DOC
id_number	string	yes	ID Number
country_of_issuance	string	yes	Country of Issuance, using ISO 3166-1 alpha-2 format

Response 200

Field	Type	Required	Description
client_request_id	string	yes	Create VA Account Request ID
account_number	string	yes	Account Number
account_id	string	yes	Account ID
account_status	string	yes	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 — one of: CREATED, ACTIVE, SUSPENDED, RESTRICTED, FROZEN, CLOSED

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Update Virtual Account

POST /broker/accounts/virtual-accounts/update

Updates Virtual Account information for an existing virtual account.

SDK	broker.UpdateVirtualAccount
Reference	broker-account-update.md

Request body

Field	Type	Required	Description
client_request_id	string	yes	Client Request ID, unique for each request. Maximum length is 32 characters. Allowed characters: letters (A–Z, a–z), digits (0–9), hyphen (-), underscore (_).
account_id	string	yes	VA Account ID to be updated
trading_permissions	array		Trading Permissions for the VA account, list of permission codes
option_level	string		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 — one of: LV1, LV2, LV3, LV4
commission_code	string		Commission Code for the VA account, determining the commission structure
w8ben_info	object		W-8BEN Information,When trading U.S. stocks in the account, this information needs to be supplemented.
china_connect_investor_info	object		China Connect Investor Information,This information only needs to be supplemented when trading Chinese A-shares.

Nested — w8ben_info:

Field	Type	Required	Description
treaty_country	string	yes	Country of Treaty, using ISO 3166-1 alpha-2 format
tax_id	string	yes	Tax Identification Number
sign_date	string	yes	W-8BEN Form Sign Date, format: YYYY-MM-DD
first_name	string	yes	First Name of the account holder
last_name	string	yes	Last Name of the account holder
middle_name	string		Middle Name of the account holder
home_address	object		W-8BEN Address Information
mail_address	object		W-8BEN Address Information

Nested — home_address:

Field	Type	Required	Description
country	string	yes	Country, using ISO 3166-1 alpha-2 format
state	string	yes	State or Province
city	string	yes	City
street_address	string	yes	Street Address
postal_code	string	yes	Postal Code

Nested — mail_address:

Field	Type	Required	Description
country	string	yes	Country, using ISO 3166-1 alpha-2 format
state	string	yes	State or Province
city	string	yes	City
street_address	string	yes	Street Address
postal_code	string	yes	Postal Code

Nested — china_connect_investor_info:

Field	Type	Required	Description
first_name	string	yes	First Name
last_name	string	yes	Last Name
middle_name	string		Middle Name
id_type	string	yes	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 — one of: ID_CARD, PASSPORT, CERT_INCORP, LEI, OTHER_OFFICIAL_ID_DOC
id_number	string	yes	ID Number
country_of_issuance	string	yes	Country of Issuance, using ISO 3166-1 alpha-2 format

Response 200

Field	Type	Required	Description
client_request_id	string	yes	Create VA Account Request ID
account_number	string	yes	Account Number
account_id	string	yes	Account ID
account_status	string	yes	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 — one of: CREATED, ACTIVE, SUSPENDED, RESTRICTED, FROZEN, CLOSED

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Get Virtual Account Detail

GET /broker/accounts/virtual-accounts/get

Retrieves detailed information for a specific virtual account.

SDK	broker.GetVirtualAccount
Reference	broker-account-detail.md

Request — parameters

Name	In	Type	Required	Description
account_id	query	String	yes	Virtual Account ID to retrieve details for.

Response 200

Field	Type	Required	Description
belong_account_number	string	yes	Belonging Account Number, the master account belong to
belong_account_id	string	yes	Belonging Account ID, the master account belong to
account_number	string	yes	Account Number
account_id	string	yes	Account ID
account_type	string	yes	Account Type CASH: Cash Account MARGIN: Margin Account — one of: CASH, MARGIN
account_status	string	yes	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 — one of: CREATED, ACTIVE, SUSPENDED, RESTRICTED, FROZEN, CLOSED
trading_permissions	array	yes	Trading Permissions
option_level	string		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 — one of: LV1, LV2, LV3, LV4
commission_code	string		Commission Code
w8ben_info	object		W-8BEN Information,When trading U.S. stocks in the account, this information needs to be supplemented.
china_connect_investor_info	object		China Connect Investor Information,This information only needs to be supplemented when trading Chinese A-shares.

Nested — w8ben_info:

Field	Type	Required	Description
treaty_country	string	yes	Country of Treaty, using ISO 3166-1 alpha-2 format
tax_id	string	yes	Tax Identification Number
sign_date	string	yes	W-8BEN Form Sign Date, format: YYYY-MM-DD
first_name	string	yes	First Name of the account holder
last_name	string	yes	Last Name of the account holder
middle_name	string		Middle Name of the account holder
home_address	object	yes	W-8BEN Address Information
mail_address	object		W-8BEN Address Information

Nested — home_address:

Field	Type	Required	Description
country	string	yes	Country, using ISO 3166-1 alpha-2 format
state	string	yes	State or Province
city	string	yes	City
street_address	string	yes	Street Address
postal_code	string	yes	Postal Code

Nested — mail_address:

Field	Type	Required	Description
country	string	yes	Country, using ISO 3166-1 alpha-2 format
state	string	yes	State or Province
city	string	yes	City
street_address	string	yes	Street Address
postal_code	string	yes	Postal Code

Nested — china_connect_investor_info:

Field	Type	Required	Description
first_name	string	yes	First Name
last_name	string	yes	Last Name
middle_name	string		Middle Name
id_type	string	yes	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 — one of: ID_CARD, PASSPORT, CERT_INCORP, LEI, OTHER_OFFICIAL_ID_DOC
id_number	string	yes	ID Number
country_of_issuance	string	yes	Country of Issuance, using ISO 3166-1 alpha-2 format

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

List Virtual Accounts

GET /broker/accounts/virtual-accounts/list

Retrieves a paginated list of Virtual Accounts.

SDK	broker.ListVirtualAccounts
Reference	broker-account-list.md

Request — parameters

Name	In	Type	Required	Description
start_time	query	String		Inclusive start time for the query. formats: yyyy-MM-dd'T'HH:mm:ss.SSSZ
end_time	query	String		Inclusive end time for the query, formats: yyyy-MM-dd'T'HH:mm:ss.SSSZ
pagination_key	query	String		Pagination key from previous response for next page.

Response 200

Field	Type	Required	Description
data	array		Result data list
pagination_key	string		Pagination key for next page. If absent, indicates this is the last page.

Nested — data:

Field	Type	Required	Description
belong_account_number	string	yes	Belonging Account Number, the master account belong to
belong_account_id	string	yes	Belonging Account ID, the master account belong to
account_number	string	yes	Account Number
account_id	string	yes	Account ID
account_type	string	yes	Account Type CASH: Cash Account MARGIN: Margin Account — one of: CASH, MARGIN
account_status	string	yes	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 — one of: CREATED, ACTIVE, SUSPENDED, RESTRICTED, FROZEN, CLOSED
trading_permissions	array	yes	Trading Permissions
option_level	string		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 — one of: LV1, LV2, LV3, LV4
commission_code	string		Commission Code
w8ben_info	object		W-8BEN Information,When trading U.S. stocks in the account, this information needs to be supplemented.
china_connect_investor_info	object		China Connect Investor Information,This information only needs to be supplemented when trading Chinese A-shares.

Nested — w8ben_info:

Field	Type	Required	Description
treaty_country	string	yes	Country of Treaty, using ISO 3166-1 alpha-2 format
tax_id	string	yes	Tax Identification Number
sign_date	string	yes	W-8BEN Form Sign Date, format: YYYY-MM-DD
first_name	string	yes	First Name of the account holder
last_name	string	yes	Last Name of the account holder
middle_name	string		Middle Name of the account holder
home_address	object	yes	W-8BEN Address Information
mail_address	object		W-8BEN Address Information

Nested — home_address:

Field	Type	Required	Description
country	string	yes	Country, using ISO 3166-1 alpha-2 format
state	string	yes	State or Province
city	string	yes	City
street_address	string	yes	Street Address
postal_code	string	yes	Postal Code

Nested — mail_address:

Field	Type	Required	Description
country	string	yes	Country, using ISO 3166-1 alpha-2 format
state	string	yes	State or Province
city	string	yes	City
street_address	string	yes	Street Address
postal_code	string	yes	Postal Code

Nested — china_connect_investor_info:

Field	Type	Required	Description
first_name	string	yes	First Name
last_name	string	yes	Last Name
middle_name	string		Middle Name
id_type	string	yes	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 — one of: ID_CARD, PASSPORT, CERT_INCORP, LEI, OTHER_OFFICIAL_ID_DOC
id_number	string	yes	ID Number
country_of_issuance	string	yes	Country of Issuance, using ISO 3166-1 alpha-2 format

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Get Stock Instrument

GET /broker/instruments/stocks/profiles/list

Retrieves detail information of instruments associated to customer's account.

SDK	broker.GetStockInstruments
Reference	broker-instrument-list.md

Request — parameters

Name	In	Type	Required	Description
category	query	string	yes	Security type. — one of: US_STOCK, HK_STOCK, CN_STOCK
symbols	query	string		List of security symbols, maximum 100 symbols per query.
status	query	string		Tradable status: OC (Tradable), CO (Liquidate only), NT (Non-Tradable) — one of: OC, CO, NT
sub_category	query	string		Sub-category of the instrument. Only effective when symbols is not specified. When category = US_STOCK, supported values: COMMON_STOCK, ETF, PREFERRED_STOCK, WARRANT, UNITS, RIGHT. When category = HK_STOCK, CN_STOCK, supported values: COMMON_STOCK, ETF. If not specified, returns all sub-categories. — one of: COMMON_STOCK, ETF, PREFERRED_STOCK, WARRANT, UNITS, RIGHT
pagination_key	query	string		Pagination key from previous response for next page

Response 200

Field	Type	Required	Description
data	array		Result data list
pagination_key	string		Pagination key for next page. If absent, indicates this is the last page.

Nested — data:

Field	Type	Required	Description
name	string		Symbol name, e.g. Apple
instrument_id	string		Unique identifier of the security
exchange_code	string		Exchange code, e.g. CCC
category	string		Instrument Stock Category US_STOCK - US stock, HK_STOCK - HK stock, CN_STOCK - China A share — one of: US_STOCK, HK_STOCK, CN_STOCK
symbol	string		Symbol of the instrument
status	string		Tradable Status OC - Tradable: Security is available for trading CO - Liquidate only: Security can only be sold, no purchases allowed NT - Non-Tradable: Security cannot be traded — one of: OC, CO, NT
shortable	boolean		Instrument is shortable or not
fractionable	boolean		Instrument is fractionable or not
marginable	boolean		Instrument is marginable or not
overnight_trading_supported	boolean		Instrument support overnight trading or not
margin_requirement_long	string		Margin requirement ratio for long position
margin_requirement_short	string		Margin requirement ratio for short position
intraday_margin_long	string		Intraday margin requirement ratio for long position
intraday_margin_short	string		Intraday margin requirement ratio for short position
maintenance_margin_long	string		Maintenance margin requirement ratio for long position
maintenance_margin_short	string		Maintenance margin requirement ratio for short position
easy_to_borrow	boolean		Instrument is easy to borrow or not
lot_size	string		Lot size
currency	string		currency
sub_category	string		Sub-category of the instrument. — one of: COMMON_STOCK, ETF, PREFERRED_STOCK, WARRANT, UNITS, RIGHT
etf_leveraged_flag	string		Is Leveraged ETF. Allowed values: YES / NO. Null if not an ETF
etf_leveraged_factor	string		ETF Leveraged Factor. Numeric string, positive for bullish, negative for inverse. Null if not an ETF
inverse_etf	string		Is Inverse ETF. Allowed values: true / false. Null if not an ETF
crypto_etf	string		Is Crypto ETF. Allowed values: true / false. Null if not an ETF
single_stock_etf	string		Is Single Stock ETF. Allowed values: true / false. Null if not an ETF

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Get Stock Locate Detail

GET /broker/instruments/stock-locates/get

Retrieves stock short trading related information, including stock borrow type (ETB/HTB), available short quantity, short interest rate, etc. (Reference use only).

SDK	broker.GetStockLocate
Reference	broker-stock-locate-detail.md

Request — parameters

Name	In	Type	Required	Description
symbols	query	string	yes	List of security symbols, maximum 100 symbols per query.
category	query	string	yes	Security type. — one of: US_STOCK

Response 200

Array of objects:

Field	Type	Required	Description
symbol	string		Symbol of the instrument
shortable	string		Whether the security is shortable: Y = Yes, N = No
short_type	string		Short availability type: ETB (Easy To Borrow), HTB (Hard To Borrow)
available_num	integer		remaining available shares for short selling (not returned for ETB)
short_interest_rate	number		Annualized short interest rate

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Get Corporate Actions Detail

GET /broker/instruments/stocks/corporate-actions/get

Retrieves detailed information for corporate action events.

SDK	broker.GetCorporateActionsDetail
Reference	broker-corporate-actions-detail.md

Request — parameters

Name	In	Type	Required	Description
event_id	query	string	yes	Corporate Event Action ID

Response 200

Field	Type	Required	Description
event_id	string		Company Event ID
event_type	string		Corporate Event Type IDENTIFIER_CHANGE - Identifier-related changes to a security without economic impact, including symbol, exchange, ISIN, CUSIP, or instrument name changes DIVIDEND - Dividend and distribution events, including cash dividend, stock dividend, optional dividend, and return of capital REVERSE_SPLIT - Reverse stock split that consolidates shares and reduces the number of outstanding shares FORWARD_SPLIT - Forward stock split that increases the number of outstanding shares BONUS_ISSUE - Bonus issue of additional shares distributed to existing shareholders at no cost RIGHTS_OFFERING - Rights offering allowing shareholders to subscribe for additional shares DISTRIBUTION - Distribution of cash, securities, or other assets to shareholders SPIN_OFF - Spin-off event where shares of a subsidiary or new entity are distributed to existing shareholders UNIT_SPLIT - Unit split event affecting composite or unit-based securities MERGER - Merger or acquisition event involving the combination of two or more entities FULL_CALL - Full call redemption of the entire outstanding security issue PARTIAL_CALL - Partial call redemption affecting only a portion of the outstanding issue EXCHANGE - Exchange event where existing securities are exchanged for new securities or other consideration DTC_EXIT - Event indicating a security is no longer eligible for DTC settlement or custody LIQUIDATION - Liquidation event involving the winding up of an issuer and asset distribution WORTHLESS - Worthless security event indicating the security has no residual value ADR_GDR_TERMINATION - Termination of an ADR or GDR program MATURITY - Maturity event where a security reaches its contractual maturity date ADR_FEE - ADR fee charged to holders of American Depositary Receipts CONVERSION - Conversion event where securities are converted into another class or form OPEN_OFFER - Open offer allowing shareholders to subscribe for additional securities PREFERENTIAL_OFFER - Preferential offer made to selected shareholders under specific terms PERFORMANCE_COMPENSATION - Performance compensation event related to performance commitments, commonly in A-share markets DELISTING - Delisting event where a security is removed from exchange trading — one of: IDENTIFIER_CHANGE, DIVIDEND, REVERSE_SPLIT, FORWARD_SPLIT, BONUS_ISSUE, RIGHTS_OFFERING, DISTRIBUTION, SPIN_OFF, UNIT_SPLIT, MERGER, FULL_CALL, PARTIAL_CALL, EXCHANGE, DTC_EXIT, LIQUIDATION, WORTHLESS, ADR_GDR_TERMINATION, MATURITY, ADR_FEE, CONVERSION, OPEN_OFFER, PREFERENTIAL_OFFER, PERFORMANCE_COMPENSATION, DELISTING
event_version	string		Event Version
instrument_id	string		Instrument ID
category	string		Instrument Stock Category US_STOCK - US stock, HK_STOCK - HK stock, CN_STOCK - China A share — one of: US_STOCK, HK_STOCK, CN_STOCK
record_date	string		Record Date (YYYY-MM-DD)
ex_date	string		Ex Date (YYYY-MM-DD)
payment_date	string		Payment Date (YYYY-MM-DD)
final_pay_date	string		Final Payment Date (YYYY-MM-DD)
country_code	string		Country Code, ISO 3166-1 alpha-2 format
listing_country_of_code	string		Listing Country Code, ISO 3166-1 alpha-2 format
issuer_country_code	string		Issuer Country Code, ISO 3166-1 alpha-2 format
from	object		Event From Info. Position's instrument information
to	array		Event To Info. Corporate action's target instrument information

Nested — from:

Field	Type	Required	Description
symbol	string		Symbol of the instrument
name	string		Name of the instrument
exchange	string		Exchange code

Nested — to:

Field	Type	Required	Description
option_number	string		Option Number. Identifier for the payout option
description	string		Description of the payout option
default_option_flag	string		Default Option Flag. Indicates if the default payout option is exposed
payouts	array		Payouts associated with this option

Nested — payouts:

Field	Type	Required	Description
type	string		Payout Nature Type DV - Dividend: Cash or stock distribution paid to shareholders FR - Franked Dividend: Dividend paid with franking credits attached IN - Interest: Interest income distribution L2 - Long Term Capital Gains: Gains from disposal of assets held longer than one year OT - Other: Other types of income or entitlement (see extended terms) C - Cash: Cash payment (only applicable to events created prior to release 2) PC - Cash/Principal/Return of Capital: Cash returned as principal or capital PM - Premium: Additional amount paid over base entitlement S - Securities: Distribution of securities instead of cash ST - Short Term Capital Gains: Gains from disposal of assets held less than one year SI - Sundry Income: Miscellaneous income distributions UF - Unfranked Dividend: Dividend paid without franking credits PI - Property Income Distribution: Income derived from property assets TD - Tax Deferred: Income deferred for tax purposes TE - Tax Exempted: Income exempted from taxation FI - Foreign Income: Income sourced from foreign jurisdictions CD - Capital gain on disposal of taxable property - Discounted CO - Capital gain on disposal of taxable property - Other CC - Capital gain on disposal of taxable property - Concessional CN - Capital gain on disposal of non-taxable property RT - Royalties: Payment received for intellectual property usage TX - Tax Credit: Credit applied against tax liability BP - Buy Permitted: Security is eligible for purchase under corporate action CL - Cash in Lieu of Fractional Share: Cash payment for fractional share entitlement DF - Drop Fraction: Fractional shares are dropped without compensation EX - Extend and Retain Fractions: Fractional shares are retained and adjusted NC - Round to Nearest Cent: Monetary amounts rounded to the nearest cent NW - Round to Nearest Whole Number if .5 or above: Rounding rule for fractional shares PR - Purchase Required: Mandatory purchase of securities as part of corporate action RD - Round Down to Nearest Whole Number: Fractional shares rounded down RU - Round Up to Nearest Whole Number: Fractional shares rounded up SR - Sale Required: Mandatory sale of securities as part of corporate action BU - Round up: Generic rounding up rule BC - Beneficial Owner Cash in Lieu: Cash payment to beneficial owner for fractional share BD - Beneficial Owner Round Down: Fractional shares of beneficial owner rounded down CT - Security Convert To Cash: Conversion of security into cash (used for tokenized assets) — one of: DV, FR, IN, L2, OT, C, PC, PM, S, ST, SI, UF, PI, TD, TE, FI, CD, CO, CC, CN, RT, TX, BP, CL, DF, EX, NC, NW, PR, RD, RU, SR, BU, BC, BD, CT
pay_type	string		Payout Delivery Type CASH - Cash settlement SECURITY - Security settlement (stock, right, warrant, etc.) SCRIP - Scrip dividend (dividend paid in shares instead of cash) SECURITY_AND_CASH - Combination of security and cash (logical type, not for persistence) — one of: CASH, SECURITY, SCRIP, SECURITY_AND_CASH
payout_number	integer		Sequence number of the payout within the same option. Used for ordering and identification.
adr_fee_rate	string		ADR fee rate applied to this payout, if applicable.
fraction_share_rule	string		Fraction Share Rule NONE - No special handling for fractional shares ROUND_DOWN - Round down fractional shares ROUND_UP - Round up fractional shares CASH_IN_LIEU - Cash in lieu for fractional shares DISTRIBUTION - Fractional share distribution STANDARD - Standard rounding for fractional shares — one of: NONE, ROUND_DOWN, ROUND_UP, CASH_IN_LIEU, DISTRIBUTION, STANDARD
cancellation_fee	string		Cancellation fee rate applied if the corporate action is cancelled.
issuance_fee	string		Issuance fee rate applied for newly issued securities.
tax_status	string		IRS income classification for tax reporting purposes.
currency	string		Currency of the cash payout. Applicable only when payType involves CASH.
amount	string		Cash amount paid per share held. Applicable only when payType involves CASH.
withholding_tax_rate	string		Withholding tax rate applied to the cash payout.
symbol	string		Trading symbol of the distributed security.
name	string		Name of the distributed security.
exchange	string		Exchange where the distributed security is listed.
from_ratio	string		Original holding quantity used as the base for ratio calculation.
to_ratio	string		Distributed quantity received for the given base holding.
cash_in_lieu_price	string		Cash-in-lieu price used to settle fractional shares.
reinvest_price	string		Reinvestment price used for scrip dividend calculation.

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Account Activities By Type

GET /broker/activities/cash-activities/list

Retrieves account transaction activities records with details.

SDK	broker.GetCashActivities
Reference	broker-activity-by-type.md

Request — parameters

Name	In	Type	Required	Description
account_id	query	String	yes	Provide the target account id
activity_types	query	string		Account activity types — one of: ADJUSTMENT, ALLOCATION, DEPOSIT, DIVIDENDS, EXECUTION, FEES, INTERESTS, JOURNAL, OPTION_EA, REORGANIZATION, SUBSCRIBE, TAX, TRADE, TRANSFER, WITHDRAW
start_time	query	String		Activity query start time, formats: yyyy-MM-dd'T'HH:mm:ss.SSSZ
end_time	query	String		Activity query end time, formats: yyyy-MM-dd'T'HH:mm:ss.SSSZ
pagination_key	query	String		Pagination key from previous response for next page.

Response 200

Field	Type	Required	Description
data	array		Result data list
pagination_key	string		Pagination key for next page. If absent, indicates this is the last page.

Nested — data:

Field	Type	Required	Description
id	string	yes	Unique ID
account_id	string	yes	Account ID
account_number	string	yes	Account Number
activity_type	string	yes	Activity Type ADJUSTMENT - Adjustment Activity Type ALLOCATION - Allocation Activity Type DEPOSIT - Deposit Activity Type DIVIDENDS - Dividends Activity Type EXECUTION - Execution Activity Type FEES - Fees Activity Type INTERESTS - Interests Activity Type JOURNAL - Journal Activity Type OPTION_EA - Option EA Activity Type REORGANIZATION - Reorganization Activity Type SUBSCRIBE - Subscribe Activity Type TAX - Tax Activity Type TRADE - Trade Activity Type TRANSFER - Transfer Activity Type WITHDRAW - Withdraw Activity Type OTHER - Other Activity Type — one of: ADJUSTMENT, ALLOCATION, DEPOSIT, DIVIDENDS, EXECUTION, FEES, INTERESTS, JOURNAL, OPTION_EA, REORGANIZATION, SUBSCRIBE, TAX, TRADE, TRANSFER, WITHDRAW, OTHER
activity_sub_type	string	yes	Activity Sub Type. Provides detailed classification under each ActivityType. Multiple sub-types may share the same enum value but belong to different parent types. For example, FOREIGN_TAX_WITHHELD can appear under DIVIDENDS, FEES, or TAX types. NOT_SET - No sub type CASH_ADJUSTMENT - Cash Adjustment Sub Type, super type is ADJUSTMENT WIRE - Wire Deposit Sub Type, super type is DEPOSIT or WITHDRAW TAX_WITHHOLD - Tax Withhold Dividend Sub Type, super type is DIVIDENDS COLLECTION_FEE - Collection Fee Dividend Sub Type, super type is DIVIDENDS or INTERESTS INCOME - Income Dividend Sub Type, super type is DIVIDENDS PAYMENT_IN_LIEU - Payment In Lieu Dividend Sub Type, super type is DIVIDENDS SCRIP_FEE - Scrip Fee Dividend Sub Type, super type is DIVIDENDS or REORGANIZATION US_TAX_WITHHOLDING - US Tax Withholding Dividend or Tax Sub Type, super type is DIVIDENDS or TAX CA_HANDLING_FEE - CA Handling Fee Sub Type, super type is DIVIDENDS or REORGANIZATION FOREIGN_TAX_WITHHELD - Foreign Tax Withheld Sub Type, super type is DIVIDENDS or FEES or TAX CASH_IN_LIEU - Cash In Lieu Sub Type, super type is DIVIDENDS or REORGANIZATION ADJUSTMENT - Adjustment Dividend Sub Type, super type is DIVIDENDS ADR - ADR Fees Sub Type, super type is FEES IPO_SUBSCRIPTION_FEE - IPO Subscription Fee Sub Type, super type is FEES TRANSACTION_FEES - Transaction Fees Sub Type, super type is FEES CCASS_SETTLEMENT_FEE - CCASS Settlement Fee Sub Type, super type is FEES JOURNAL_BETWEEN_ACCOUNTS - Journal Between Accounts Sub Type, super type is FEES or JOURNAL CUSTODIAN_FEE - Custodian Fee Sub Type, super type is FEES SETTLEMENT_FEES - Settlement Fees Sub Type, super type is FEES TRANSFER_FOP - Transfer FOP Fees Sub Type, super type is FEES FTT - FTT Fees Sub Type, super type is FEES COMMISSION - Commission Fees Sub Type, super type is FEES SYSTEM_FEE - System Fee Sub Type, super type is FEES CORRESPONDENT_BILLING - Correspondent Billing Fees Sub Type, super type is FEES CUSTODY_FEE - Custody Fee Sub Type, super type is FEES STOCK_BORROW_INTEREST - Stock Borrow Interest Sub Type, super type is INTERESTS DEBIT_CASH - Debit Cash Sub Type, super type is INTERESTS IPO_FINANCING - IPO Financing Interest Sub Type, super type is INTERESTS PAYMENT - Payment Interests Sub Type, super type is INTERESTS ACCOUNT_MIGRATION - Account Migration Sub Type, super type is JOURNAL IPO_REFUND - IPO Refund Sub Type, super type is JOURNAL JOURNAL_BETWEEN_TYPES - Journal Between Types Sub Type, super type is JOURNAL GIFTING - Gifting Sub Type, super type is JOURNAL BANK_TRANSFER - Bank Transfer Sub Type, super type is JOURNAL FX_EXCHANGE - FX Exchange Sub Type, super type is JOURNAL CA_BREAK_RESOLVING - CA Break Resolving Sub Type, super type is JOURNAL MARK_TO_MARKET - Mark To Market Sub Type, super type is JOURNAL INV_DEPOSIT - INV Deposit Sub Type, super type is JOURNAL IPO_SUBSCRIPTION - IPO Subscription Sub Type, super type is JOURNAL FIXED_INCOME_SPREAD - Fixed Income Spread Sub Type, super type is JOURNAL HK_CBBC_EXERCISE - HK CBBC Exercise Sub Type, super type is OPTION_EA HK_CBBC_EXPIRATION - HK CBBC Expiration Sub Type, super type is OPTION_EA HK_WARRANT_EXERCISE - HK Warrant Exercise Sub Type, super type is OPTION_EA OPTION_EXERCISE - Option Exercise Sub Type, super type is OPTION_EA or TRADE HK_INLINE_WARRANT_EXERCISE - HK Inline Warrant Exercise Sub Type, super type is OPTION_EA OPTION_ASSIGNMENT - Option Assignment Sub Type, super type is OPTION_EA or TRADE MERGER - Merger Sub Type, super type is REORGANIZATION RIGHT_SUBSCRIPTION - Right Subscription Sub Type, super type is REORGANIZATION CORP_ACTION_FEE - Corp Action Fee Sub Type, super type is REORGANIZATION LIQUIDATION - Liquidation Sub Type, super type is REORGANIZATION REDEMPTION - Redemption Sub Type, super type is REORGANIZATION REPURCHASE - Repurchase Sub Type, super type is REORGANIZATION FEE - Subscribe Fee Sub Type, super type is SUBSCRIBE FEE_RETURN - Subscribe Fee Return Sub Type, super type is SUBSCRIBE INTERNAL_TRANSFER - Internal Transfer Sub Type, super type is TRANSFER DTC_OUT - DTC Out Sub Type, super type is TRANSFER WIRE_FEE_LOCAL - Wire Fee Local Sub Type, super type is WITHDRAW OPTION_TRADE - Option Trade Sub Type, super type is TRADE FUND_TRADE - Fund Trade Sub Type, super type is TRADE OTHER - Other — one of: NOT_SET, CASH_ADJUSTMENT, WIRE, TAX_WITHHOLD, COLLECTION_FEE, INCOME, PAYMENT_IN_LIEU, SCRIP_FEE, US_TAX_WITHHOLDING, CA_HANDLING_FEE, FOREIGN_TAX_WITHHELD, CASH_IN_LIEU, ADJUSTMENT, ADR, IPO_SUBSCRIPTION_FEE, TRANSACTION_FEES, CCASS_SETTLEMENT_FEE, JOURNAL_BETWEEN_ACCOUNTS, CUSTODIAN_FEE, SETTLEMENT_FEES, TRANSFER_FOP, FTT, COMMISSION, SYSTEM_FEE, CORRESPONDENT_BILLING, CUSTODY_FEE, STOCK_BORROW_INTEREST, DEBIT_CASH, IPO_FINANCING, PAYMENT, ACCOUNT_MIGRATION, IPO_REFUND, JOURNAL_BETWEEN_TYPES, GIFTING, BANK_TRANSFER, FX_EXCHANGE, CA_BREAK_RESOLVING, MARK_TO_MARKET, INV_DEPOSIT, IPO_SUBSCRIPTION, FIXED_INCOME_SPREAD, HK_CBBC_EXERCISE, HK_CBBC_EXPIRATION, HK_WARRANT_EXERCISE, OPTION_EXERCISE, HK_INLINE_WARRANT_EXERCISE, OPTION_ASSIGNMENT, MERGER, RIGHT_SUBSCRIPTION, CORP_ACTION_FEE, LIQUIDATION, REDEMPTION, REPURCHASE, FEE, FEE_RETURN, INTERNAL_TRANSFER, DTC_OUT, WIRE_FEE_LOCAL, OPTION_TRADE, FUND_TRADE, OTHER
currency	string	yes	Currency CNH - RMB HKD - Hong Kong Dollar USD - US Dollar — one of: CNH, HKD, USD
market	string		Market Code HK - Hong Kong Market US - US Market CN - China Market — one of: HK, US, CN
symbol	string		Activity Symbol
trade_date	string	yes	Accounting date of the transaction (trade date), format: yyyy-MM-dd
net_amount	string	yes	Net change amount of the transaction (positive for credit, negative for debit)
biz_time	string	yes	Business event time when the transaction occurred

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Account Balance

GET /broker/assets/balances/get

Retrieves account asset information, including cash balance, position market value, profit & loss, buying power, interest payable, etc.

SDK	broker.GetBalance
Reference	broker-assets-balance.md

Request — parameters

Name	In	Type	Required	Description
account_id	query	String	yes	Account identifier.

Response 200

Field	Type	Required	Description
total_asset_currency	string	yes	Currency — one of: CNH, HKD, USD
total_cash_balance	string	yes	Cash Balance
total_market_value	string	yes	Total holding market value
total_unrealized_profit_loss	string	yes	Open P&L
init_margin	string		Initial margin
account_currency_assets	array	yes	Currency assets Details

Nested — account_currency_assets:

Field	Type	Required	Description
currency	string	yes	Currency — one of: CNH, HKD, USD
cash_balance	string	yes	Cash Balance
settled_cash	string	yes	Settled Cash
unsettled_cash	string	yes	Unsettled Cash
market_value	string	yes	holding market value
held_amount	string		In-transit funds
frozen_amount	string		Frozen funds
buying_power	string	yes	Buying Power
unrealized_profit_loss	string	yes	Open P&L
available_withdrawal	string	yes	The withdrawable amount
interests_unpaid	string	yes	Interest to be paid
init_margin	string		Init margin

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Account Positions

GET /broker/assets/positions/list

Retrieves position details for a specific account.

SDK	broker.GetPositions
Reference	broker-assets-positions.md

Request — parameters

Name	In	Type	Required	Description
account_id	query	String	yes	Account identifier.

Response 200

Field	Type	Required	Description
position_id	string	yes	Position ID
currency	string	yes	Currency — one of: CNH, HKD, USD
quantity	string	yes	Quantity of the order. Specifies the number of shares or units to transact. For US stocks, fractional quantities are allowed and can include decimals.
symbol	string	yes	Trading symbol of the financial instrument.Represents the unique identifier of the security in the specified market (e.g., ticker symbol for equities or option symbol code for derivatives).
option_strategy	string	yes	Type of options strategy - SINGLE: Single-leg options order - COVERED_STOCK: Covered call (stock + sell CALL) - STRADDLE: Same strike, same expiry CALL + PUT - STRANGLE: Different strike, same expiry CALL + PUT - VERTICAL: Same expiry, different strike, same type (Bull/Bear Spread) - CALENDAR: Same strike, different expiry, same type - DIAGONAL: Different strike, different expiry, same type - COLLAR_WITH_STOCK: Stock + buy PUT + sell CALL - BUTTERFLY: Buy low + sell 2 mid + buy high (same type) - CONDOR: Four different strikes, same type - IRON_BUTTERFLY: Buy low PUT + sell mid PUT + sell mid CALL + buy high CALL - IRON_CONDOR: Buy low PUT + sell mid-low PUT + sell mid-high CALL + buy high CALL - RATIO: Same expiry, same option type, unequal leg quantities (e.g. buy 1 low-strike CALL + sell 2 high-strike CALLs) — one of: SINGLE, COVERED_STOCK, STRADDLE, STRANGLE, VERTICAL, CALENDAR, DIAGONAL, COLLAR_WITH_STOCK, BUTTERFLY, CONDOR, IRON_BUTTERFLY, IRON_CONDOR, RATIO
instrument_type	string	yes	Type of financial instrument associated with the request. — one of: EQUITY, OPTION
last_price	string	yes	Last Price
cost_price	string	yes	Cost Basis
unrealized_profit_loss	string	yes	Open P&L
legs	array		legs

Nested — legs:

Field	Type	Required	Description
symbol	string	yes	Trading symbol of the financial instrument.Represents the unique identifier of the security in the specified market (e.g., ticker symbol for equities or option symbol code for derivatives).
leg_id	string	yes	Leg Id
quantity	string		Quantity of the order. Specifies the number of shares or units to transact.
option_type	string		Type of the option. - CALL: Right to buy the underlying asset. - PUT: Right to sell the underlying asset. — one of: CALL, PUT
option_expire_date	string		Option expiration date. Format: yyyy-MM-dd
option_exercise_price	string		Exercise Price
option_contract_multiplier	string		The number of shares corresponding to each option contract
option_contract_deliverable	string		The number of shares required to exercise each contract
expiration_type	string		Option expiration types

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Order Preview

POST /broker/orders/preview

Calculates the estimated trading cost and fees based on the provided trade information.

SDK	broker.PreviewOrder
Reference	broker-order-preview.md

Request body

Field	Type	Required	Description
account_id	string	yes	Account identifier
client_combo_order_id	string		Unique client-defined identifier for the combined order If combo_type = NORMAL and client_combo_order_id not need to set If combo_type != NORMAL and client_combo_order_id not provided the server will automatically generate one.
new_orders	array	yes	Order Details

Nested — new_orders:

Field	Type	Required	Description
combo_type	string	yes	Specifies the type of order combination. For details, please refer to Combo Order. - NORMAL: A standard single order. - MASTER: A primary order that triggers a take-profit or stop-loss order upon execution - STOP_PROFIT: A take-profit order - STOP_LOSS: A stop-loss order - OTO: An order that triggers another order upon execution (One-Triggers-the-Other) - OCO: A pair of orders where the execution of one cancels the other (One-Cancels-the-Other) - OTOCO: An order that triggers an OCO order set upon execution (One-Triggers-One-Cancels-the-Other)
client_order_id	string	yes	Unique client-defined identifier for the order. Maximum length is 32 characters. Allowed characters: letters (A–Z, a–z), digits (0–9), hyphen (-), underscore (_).
instrument_type	string	yes	Type of financial instrument associated with the request. — one of: EQUITY, OPTION
market	string	yes	Market code indicating the trading venue or regulatory region of the financial instrument. Used together with symbol and instrument_type to uniquely identify a tradable instrument. — one of: US, HK, CN
symbol	string	yes	Trading symbol of the financial instrument. Represents the unique identifier of the security in the specified market.
order_type	string	yes	Specifies the type of order to be placed. Determines how the order will be executed in the market. Available order types depend on the market and instrument type. Options trading Only LIMIT,STOP_LOSS,STOP_LOSS_LIMIT are supported. U.S. Stock - LIMIT: Limit Order - MARKET: Market Order - STOP_LOSS: Stop Order - STOP_LOSS_LIMIT: Stop Limit Order - MARKET_ON_OPEN: Opening market order - MARKET_ON_CLOSE: Closing market order Hong Kong Stock - ENHANCED_LIMIT: Enhanced Limit Order - AT_AUCTION: At-auction order - AT_AUCTION_LIMIT: At-auction limit order - STOP_LOSS: Stop Order - STOP_LOSS_LIMIT: Stop Limit Order - TRAILING_STOP_LOSS: Trailing Stop Order - TRAILING_STOP_LOSS_LIMIT: Trailing Stop Limit Order - TOUCH_MKT: Touch Market Order - TOUCH_LMT: Touch Limit Order - MARKET: Market Order - ODD_LOT_LIMIT: Odd Lot Limit Order - MARKET_ON_OPEN: Opening market order - MARKET_ON_CLOSE: Closing market order HK Options - LIMIT: Limit Order - MARKET: Market Order - STOP_LOSS: Stop Order - STOP_LOSS_LIMIT: Stop Limit Order China Connect - LIMIT: Limit Order — one of: LIMIT, MARKET, STOP_LOSS, STOP_LOSS_LIMIT, ENHANCED_LIMIT, AT_AUCTION, AT_AUCTION_LIMIT, MARKET_ON_OPEN, MARKET_ON_CLOSE, TRAILING_STOP_LOSS, TRAILING_STOP_LOSS_LIMIT, TOUCH_MKT, TOUCH_LMT, ODD_LOT_LIMIT
entrust_type	string	yes	Specifies the method for placing the order. - QTY: Order specified by quantity of shares or units. - AMOUNT: Order specified by total cash amount, applicable for fractional share trading of US stocks. — one of: QTY, AMOUNT
support_trading_session	string	yes	Specifies the trading session for the order. Applicable to U.S. stock market orders only. Deprecated values: - Y: [Deprecated]Include extended trading hours. - N: [Deprecated]Only support regular trading hours. Active values: - NIGHT: Only supports night trading. - ALL: Include extended trading hours. - CORE: Only support regular trading hours. - ALL_DAY: Included Overnight Hours, 8:00 p.m.ET - 8:00 p.m.ET(the next day) — one of: Y, N, NIGHT, ALL, CORE, ALL_DAY
time_in_force	string	yes	Specifies the duration for which the order remains active in the market (Time-In-Force). - DAY: The order is valid only for the current trading day and expires at the end of the day. - GTC: Good-Till-Canceled, the order remains active until it is executed, explicitly canceled, or reaches the maximum allowed duration (typically 90 days). — one of: DAY, GTC
side	string	yes	The order side indicating the intended trading direction of the transaction. The meaning of side may vary depending on the instrument_type and account type (e.g., margin vs. cash). — one of: BUY, SELL, SHORT
quantity	string		Transaction quantity. You can specify decimals when placing fractional lot orders for US stocks.
limit_price	string		Limit price of the order. Required when order_type is LIMIT, STOP_LOSS_LIMIT. Specifies the maximum (for buy) or minimum (for sell) price at which the order can be executed.
stop_price	string		Stop price of the order. Required when order_type is STOP_LOSS or STOP_LOSS_LIMIT. Specifies the trigger price at which the stop order becomes active.
option_strategy	string		Type of options strategy - SINGLE: Single-leg options order - COVERED_STOCK: Covered call (stock + sell CALL) - STRADDLE: Same strike, same expiry CALL + PUT - STRANGLE: Different strike, same expiry CALL + PUT - VERTICAL: Same expiry, different strike, same type (Bull/Bear Spread) - CALENDAR: Same strike, different expiry, same type - DIAGONAL: Different strike, different expiry, same type - COLLAR_WITH_STOCK: Stock + buy PUT + sell CALL - BUTTERFLY: Buy low + sell 2 mid + buy high (same type) - CONDOR: Four different strikes, same type - IRON_BUTTERFLY: Buy low PUT + sell mid PUT + sell mid CALL + buy high CALL - IRON_CONDOR: Buy low PUT + sell mid-low PUT + sell mid-high CALL + buy high CALL - RATIO: Same expiry, same option type, unequal leg quantities (e.g. buy 1 low-strike CALL + sell 2 high-strike CALLs) — one of: SINGLE, COVERED_STOCK, STRADDLE, STRANGLE, VERTICAL, CALENDAR, DIAGONAL, COLLAR_WITH_STOCK, BUTTERFLY, CONDOR, IRON_BUTTERFLY, IRON_CONDOR, RATIO
legs	array		Option leg detail. Only required when previewing option orders.

Nested — legs:

Field	Type	Required	Description
instrument_type	string	yes	Type of financial instrument associated with the request. — one of: EQUITY, OPTION
market	string	yes	Market code indicating the trading venue or regulatory region of the financial instrument. Used together with symbol and instrument_type to uniquely identify a tradable instrument. — one of: US, HK, CN
symbol	string	yes	Trading symbol of the financial instrument. Represents the unique identifier of the security in the specified market (e.g., ticker symbol for equities or option symbol code for derivatives).
side	string	yes	The order side indicating the intended trading direction of the transaction. The meaning of side may vary depending on the instrument_type and account type (e.g., margin vs. cash). — one of: BUY, SELL, SHORT
strike_price	string		Exercise price (strike price) of the option. Specifies the price at which the underlying asset can be bought (CALL) or sold (PUT) upon exercise.
option_expire_date	string		Expiration date. Format: yyyy-MM-dd
option_type	string		Type of the option. - CALL: Right to buy the underlying asset. - PUT: Right to sell the underlying asset. — one of: CALL, PUT
quantity	string		Quantity of the order or strategy leg. For stock legs, specifies the number of shares to transact For option legs, specifies the number of option contracts to transact for this leg and is expressed in whole contracts.

Response 200

Field	Type	Required	Description
estimated_cost	string	yes	Estimated capital required for the order. The meaning varies by product type: The actual fee may differ based on final execution.
estimated_transaction_fee	string	yes	Estimated transaction fee for placing the order, including exchange, clearing, and commission fees. The actual fee may differ based on final execution.
estimated_transaction_fee_detail	object		Breakdown of the estimated transaction fee, including commission and itemized fees.

Nested — estimated_transaction_fee_detail:

Field	Type	Required	Description
commission	object		Commission breakdown
fees	array		Fee breakdown

Nested — commission:

Field	Type	Required	Description
actual_commission	string		Actual commission collected
receivable_commission	string		Receivable commission

Nested — fees:

Field	Type	Required	Description
type	string		Fee type
actual_value	string		Actual fee collected
receivable_value	string		Receivable fee

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Order Place

POST /broker/orders/place

Places an order for a specific account. For order execution of accounts with Omnibus with VA model, please submit virtual account number instead of omnibus master account number.

SDK	broker.PlaceOrder
Reference	broker-order-place.md

Request body

Field	Type	Required	Description
account_id	string	yes	Account identifier
client_combo_order_id	string		Unique client-defined identifier for the combined order If combo_type = NORMAL and client_combo_order_id not need to set If combo_type != NORMAL and client_combo_order_id not provided the server will automatically generate one.
new_orders	array	yes	Order Details

Nested — new_orders:

Field	Type	Required	Description
combo_type	string	yes	Specifies the type of order combination. For details, please refer to Combo Order. - NORMAL: A standard single order. - MASTER: A primary order that triggers a take-profit or stop-loss order upon execution - STOP_PROFIT: A take-profit order - STOP_LOSS: A stop-loss order - OTO: An order that triggers another order upon execution (One-Triggers-the-Other) - OCO: A pair of orders where the execution of one cancels the other (One-Cancels-the-Other) - OTOCO: An order that triggers an OCO order set upon execution (One-Triggers-One-Cancels-the-Other)
client_order_id	string	yes	Unique client-defined identifier for the order. Maximum length is 32 characters. Allowed characters: letters (A–Z, a–z), digits (0–9), hyphen (-), underscore (_).
instrument_type	string	yes	Type of financial instrument associated with the request. — one of: EQUITY, OPTION
market	string	yes	Market code indicating the trading venue or regulatory region of the financial instrument. Used together with symbol and instrument_type to uniquely identify a tradable instrument. — one of: US, HK, CN
symbol	string	yes	Trading symbol of the financial instrument. Represents the unique identifier of the security in the specified market.
order_type	string	yes	Specifies the type of order to be placed. Determines how the order will be executed in the market. Available order types depend on the market and instrument type. Options trading Only LIMIT,STOP_LOSS,STOP_LOSS_LIMIT are supported. U.S. Stock - LIMIT: Limit Order - MARKET: Market Order - STOP_LOSS: Stop Order - STOP_LOSS_LIMIT: Stop Limit Order - MARKET_ON_OPEN: Opening market order - MARKET_ON_CLOSE: Closing market order Hong Kong Stock - ENHANCED_LIMIT: Enhanced Limit Order - AT_AUCTION: At-auction order - AT_AUCTION_LIMIT: At-auction limit order - STOP_LOSS: Stop Order - STOP_LOSS_LIMIT: Stop Limit Order - TRAILING_STOP_LOSS: Trailing Stop Order - TRAILING_STOP_LOSS_LIMIT: Trailing Stop Limit Order - TOUCH_MKT: Touch Market Order - TOUCH_LMT: Touch Limit Order - MARKET: Market Order - ODD_LOT_LIMIT: Odd Lot Limit Order - MARKET_ON_OPEN: Opening market order - MARKET_ON_CLOSE: Closing market order HK Options - LIMIT: Limit Order - MARKET: Market Order - STOP_LOSS: Stop Order - STOP_LOSS_LIMIT: Stop Limit Order China Connect - LIMIT: Limit Order — one of: LIMIT, MARKET, STOP_LOSS, STOP_LOSS_LIMIT, ENHANCED_LIMIT, AT_AUCTION, AT_AUCTION_LIMIT, MARKET_ON_OPEN, MARKET_ON_CLOSE, TRAILING_STOP_LOSS, TRAILING_STOP_LOSS_LIMIT, TOUCH_MKT, TOUCH_LMT, ODD_LOT_LIMIT
entrust_type	string	yes	Specifies the method for placing the order. - QTY: Order specified by quantity of shares or units. - AMOUNT: Order specified by total cash amount, applicable for fractional share trading of US stocks. — one of: QTY, AMOUNT
support_trading_session	string		Specifies the trading session for the order. Applicable to U.S. stock market orders only. Deprecated values: - Y: [Deprecated]Include extended trading hours. - N: [Deprecated]Only support regular trading hours. Active values: - NIGHT: Only supports night trading. - ALL: Include extended trading hours. - CORE: Only support regular trading hours. - ALL_DAY: Included Overnight Hours, 8:00 p.m.ET - 8:00 p.m.ET(the next day) — one of: Y, N, NIGHT, ALL, CORE, ALL_DAY
time_in_force	string	yes	Specifies the duration for which the order remains active in the market (Time-In-Force). - DAY: The order is valid only for the current trading day and expires at the end of the day. - GTC: Good-Till-Canceled, the order remains active until it is executed, explicitly canceled, or reaches the maximum allowed duration (typically 90 days). — one of: DAY, GTC
side	string	yes	The order side indicating the intended trading direction of the transaction. The meaning of side may vary depending on the instrument_type and account type (e.g., margin vs. cash). — one of: BUY, SELL, SHORT
quantity	string		Transaction quantity. You can specify decimals when placing fractional lot orders for US stocks.
total_cash_amount	string		The total order amount is currently only applicable to US stock fractional share transactions and when the order is placed by amount.
limit_price	string		Limit price of the order. Required when order_type is LIMIT, STOP_LOSS_LIMIT or TOUCH_LMT. Specifies the maximum (for buy) or minimum (for sell) price at which the order can be executed.
stop_price	string		Stop price of the order. Required when order_type is STOP_LOSS, STOP_LOSS_LIMIT, TOUCH_MKT or TOUCH_LMT. Specifies the trigger price at which the stop order becomes active.
trailing_type	string		When market continues to fall, the stop price to buy follows, or trails, the lowest price of a stock by a trail that you set. Required when order_type is TRAILING_STOP_LOSS or TRAILING_STOP_LOSS_LIMIT. - AMOUNT: By amount. - PERCENTAGE: By percentage. — one of: AMOUNT, PERCENTAGE
trailing_stop_step	string		Trailing Stop Spread. If the tracking type is percentage, the tracking spread can not exceed 1,0.01 means 1%. Required when order_type is TRAILING_STOP_LOSS or TRAILING_STOP_LOSS_LIMIT.
trailing_limit_price_offset	string		The offset amount between the triggered stop price and the submitted limit price for a trailing stop-limit order. Required when order_type is TRAILING_STOP_LOSS_LIMIT. When triggered, the limit order price is calculated as: - Buy: limit price = stop price + trailing_limit_price_offset - Sell: limit price = stop price - trailing_limit_price_offset If the calculated limit price does not align with the instrument's tick size, it will be rounded to the nearest valid tick: rounded up for buy orders, rounded down for sell orders.
trigger_price_type	string		Trigger price type of the order - PRICE: Latest transaction price. - PRICE_BID: Buy at one price. - PRICE_ASK: Sell at one price. — one of: PRICE, PRICE_BID, PRICE_ASK
sender_sub_id	string		Identifier for the firm or sub-account in third-party transactions. For brokers, this field should contain the UUID of the broker user. Used to distinguish different entities or users within the same firm.
no_party_ids	array		List of party identifiers. Applicable only for Hong Kong stock orders. Required for Relevant Regulated Intermediaries; should be omitted otherwise.
option_strategy	string		Type of options strategy - SINGLE: Single-leg options order - COVERED_STOCK: Covered call (stock + sell CALL) - STRADDLE: Same strike, same expiry CALL + PUT - STRANGLE: Different strike, same expiry CALL + PUT - VERTICAL: Same expiry, different strike, same type (Bull/Bear Spread) - CALENDAR: Same strike, different expiry, same type - DIAGONAL: Different strike, different expiry, same type - COLLAR_WITH_STOCK: Stock + buy PUT + sell CALL - BUTTERFLY: Buy low + sell 2 mid + buy high (same type) - CONDOR: Four different strikes, same type - IRON_BUTTERFLY: Buy low PUT + sell mid PUT + sell mid CALL + buy high CALL - IRON_CONDOR: Buy low PUT + sell mid-low PUT + sell mid-high CALL + buy high CALL - RATIO: Same expiry, same option type, unequal leg quantities (e.g. buy 1 low-strike CALL + sell 2 high-strike CALLs) — one of: SINGLE, COVERED_STOCK, STRADDLE, STRANGLE, VERTICAL, CALENDAR, DIAGONAL, COLLAR_WITH_STOCK, BUTTERFLY, CONDOR, IRON_BUTTERFLY, IRON_CONDOR, RATIO
position_intent	string		Position intent for option orders, indicating whether the trade is opening or closing a position. - BUY_TO_OPEN: Buy to open a new position - BUY_TO_CLOSE: Buy to close an existing position - SELL_TO_OPEN: Sell to open a new position - SELL_TO_CLOSE: Sell to close an existing position — one of: BUY_TO_OPEN, BUY_TO_CLOSE, SELL_TO_OPEN, SELL_TO_CLOSE
legs	array		Option leg detail. Only required when placing option orders.

Nested — no_party_ids:

Field	Type	Required	Description
party_id	string	yes	ID of the broker client submitting the order. Format examples: - CE Number Format: ABC123 - BCAN Format: 2568 Combined format example: ABC123.2568 Must be certified by the BCAN system of the Hong Kong Stock Exchange.
party_id_source	string	yes	Source of the party ID. Value must be "D" (Proprietary/Custom Code).
party_role	string	yes	Role of the party. Value must be "3" (Client ID, BCAN Field).

Nested — legs:

Field	Type	Required	Description
instrument_type	string	yes	Type of financial instrument associated with the request. — one of: EQUITY, OPTION
market	string	yes	Market code indicating the trading venue or regulatory region of the financial instrument. Used together with symbol and instrument_type to uniquely identify a tradable instrument. — one of: US, HK, CN
symbol	string	yes	Trading symbol of the financial instrument. Represents the unique identifier of the security in the specified market (e.g., ticker symbol for equities or option symbol code for derivatives).
side	string	yes	The order side indicating the intended trading direction of the transaction. The meaning of side may vary depending on the instrument_type and account type (e.g., margin vs. cash). — one of: BUY, SELL, SHORT
strike_price	string		Exercise price (strike price) of the option. Specifies the price at which the underlying asset can be bought (CALL) or sold (PUT) upon exercise.
option_expire_date	string		Expiration date. Format: yyyy-MM-dd
option_type	string		Type of the option. - CALL: Right to buy the underlying asset. - PUT: Right to sell the underlying asset. — one of: CALL, PUT
quantity	string		Quantity of the order or strategy leg. For stock legs, specifies the number of shares to transact For option legs, specifies the number of option contracts to transact for this leg and is expressed in whole contracts.

Response 200

Field	Type	Required	Description
client_order_id	string		Client-defined order identifier. Returned in the response for simple orders. Represents the unique order ID assigned by the user when placing the order for NORMAL order.
order_id	string		System-generated order identifier. Returned in the response for simple orders. Represents the unique Webull order ID assigned by the system when placing the order for NORMAL order.

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Order Replace

POST /broker/orders/replace

Modifies a submitted order with updated parameters.

SDK	broker.ReplaceOrder
Reference	broker-order-replace.md

Request body

Field	Type	Required	Description
account_id	string	yes	Account identifier
modify_orders	array	yes	Order Details

Nested — modify_orders:

Field	Type	Required	Description
combo_type	string	yes	Specifies the type of order combination. For details, please refer to Combo Order. - NORMAL: A standard single order. - MASTER: A primary order that triggers a take-profit or stop-loss order upon execution - STOP_PROFIT: A take-profit order - STOP_LOSS: A stop-loss order - OTO: An order that triggers another order upon execution (One-Triggers-the-Other) - OCO: A pair of orders where the execution of one cancels the other (One-Cancels-the-Other) - OTOCO: An order that triggers an OCO order set upon execution (One-Triggers-One-Cancels-the-Other)
client_order_id	string	yes	Unique client-defined identifier for the order. Maximum length is 32 characters. Allowed characters: letters (A–Z, a–z), digits (0–9), hyphen (-), underscore (_).
time_in_force	string		Specifies the duration for which the order remains active in the market (Time-In-Force). - DAY: The order is valid only for the current trading day and expires at the end of the day. - GTC: Good-Till-Canceled, the order remains active until it is executed, explicitly canceled, or reaches the maximum allowed duration (typically 90 days). — one of: DAY, GTC
limit_price	string		Limit price of the order. Required when order_type is LIMIT, STOP_LOSS_LIMIT or TOUCH_LMT. Specifies the maximum (for buy) or minimum (for sell) price at which the order can be executed.
stop_price	string		Stop price of the order. Required when order_type is STOP_LOSS, STOP_LOSS_LIMIT, TOUCH_MKT or TOUCH_LMT. Specifies the trigger price at which the stop order becomes active.
trailing_type	string		When market continues to fall, the stop price to buy follows, or trails, the lowest price of a stock by a trail that you set. Required when order_type is TRAILING_STOP_LOSS or TRAILING_STOP_LOSS_LIMIT. - AMOUNT: By amount. - PERCENTAGE: By percentage. — one of: AMOUNT, PERCENTAGE
trailing_stop_step	string		Trailing Stop Spread. If the tracking type is percentage, the tracking spread can not exceed 1,0.01 means 1%. Required when order_type is TRAILING_STOP_LOSS or TRAILING_STOP_LOSS_LIMIT.
trailing_limit_price_offset	string		The offset amount between the triggered stop price and the submitted limit price for a trailing stop-limit order. Required when order_type is TRAILING_STOP_LOSS_LIMIT. When triggered, the limit order price is calculated as: - Buy: limit price = stop price + trailing_limit_price_offset - Sell: limit price = stop price - trailing_limit_price_offset If the calculated limit price does not align with the instrument's tick size, it will be rounded to the nearest valid tick: rounded up for buy orders, rounded down for sell orders.
trigger_price_type	string		Trigger price type of the order - PRICE: Latest transaction price. - PRICE_BID: Buy at one price. - PRICE_ASK: Sell at one price. — one of: PRICE, PRICE_BID, PRICE_ASK
quantity	string		Transaction quantity. You can specify decimals when placing fractional lot orders for US stocks.
legs	array		Option leg detail for modifying option orders.

Nested — legs:

Field	Type	Required	Description
id	string	yes	Unique defined identifier for the leg.
quantity	string	yes	Quantity of the order or strategy leg. For stock legs, specifies the number of shares to transact For option legs, specifies the number of option contracts to transact for this leg and is expressed in whole contracts.

Response 200

Field	Type	Required	Description
client_order_id	string		Client-defined order identifier. Returned in the response for simple orders. Represents the unique order ID assigned by the user when placing the order for NORMAL order.
order_id	string		System-generated order identifier. Returned in the response for simple orders. Represents the unique Webull order ID assigned by the system when placing the order for NORMAL order.

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Order Cancel

POST /broker/orders/cancel

Cancels a submitted order that is still under open status.

SDK	broker.CancelOrder
Reference	broker-order-cancel.md

Request body

Field	Type	Required	Description
account_id	string	yes	Account identifier
client_order_id	string	yes	Unique client-defined identifier for the order. Maximum length is 32 characters. Allowed characters: letters (A–Z, a–z), digits (0–9), hyphen (-), underscore (_).

Response 200

Field	Type	Required	Description
client_order_id	string		Client-defined order identifier. Returned in the response for simple orders. Represents the unique order ID assigned by the user when placing the order for NORMAL order.
order_id	string		System-generated order identifier. Returned in the response for simple orders. Represents the unique Webull order ID assigned by the system when placing the order for NORMAL order.

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Order Detail

GET /broker/orders/get

Retrieves the order details for a specific trade via the order ID.

SDK	broker.GetOrderDetail
Reference	broker-order-detail.md

Request — parameters

Name	In	Type	Required	Description
account_id	query	String	yes	Account identifier.
client_order_id	query	String	yes	Unique client-defined identifier for the order. Maximum length is 32 characters and must be unique per user/account. Used to track or reference the order when interacting with the system.

Response 200

Field	Type	Required	Description
client_order_id	string	yes	Client-defined order identifier. Returned in the response for simple orders. Represents the unique order ID assigned by the user when placing the order.
combo_type	string		Specifies the type of order combination. For details, please refer to Combo Order. - NORMAL: A standard single order. - MASTER: A primary order that triggers a take-profit or stop-loss order upon execution - STOP_PROFIT: A take-profit order - STOP_LOSS: A stop-loss order - OTO: An order that triggers another order upon execution (One-Triggers-the-Other) - OCO: A pair of orders where the execution of one cancels the other (One-Cancels-the-Other) - OTOCO: An order that triggers an OCO order set upon execution (One-Triggers-One-Cancels-the-Other) — one of: NORMAL, MASTER, STOP_PROFIT, STOP_LOSS, OTO, OCO, OTOCO
orders	array	yes	Order Details

Nested — orders:

Field	Type	Required	Description
client_order_id	string	yes	Client-defined order identifier. Returned in the response for simple orders. Represents the unique order ID assigned by the user when placing the order.
order_id	string	yes	System-generated order identifier. Returned in the response for simple orders. Represents the unique Webull order ID assigned by the system.
symbol	string	yes	Trading symbol of the financial instrument.Represents the unique identifier of the security in the specified market (e.g., ticker symbol for equities or option symbol code for derivatives).
side	string	yes	The order side indicating the intended trading direction of the transaction. The meaning of side may vary depending on the instrument_type and account type (e.g., margin vs. cash). — one of: BUY, SELL, SHORT
status	string	yes	- PENDING: Indicates that the order has been submitted to the exchange and is awaiting completion - SUBMITTED: Indicates that the order has been submitted to the exchange and is awaiting completion - CANCELLED: Indicates that the order has been successfully cancelled - FILLED: Indicates that the order has been fully executed - FAILED: Indicates a failed order, such as REJECTED - PARTIAL_FILLED: Refers to the portion of the order that has been completed, but not all of it has been completed — one of: PENDING, SUBMITTED, CANCELLED, FILLED, FAILED, PARTIAL_FILLED
order_type	string	yes	Specifies the type of order to be placed. Determines how the order will be executed in the market. Available order types depend on the market and instrument type. Options trading Only LIMIT,STOP_LOSS,STOP_LOSS_LIMIT are supported. U.S. Stock - LIMIT: Limit Order - MARKET: Market Order - STOP_LOSS: Stop Order - STOP_LOSS_LIMIT: Stop Limit Order - MARKET_ON_OPEN: Opening market order - MARKET_ON_CLOSE: Closing market order Hong Kong Stock - ENHANCED_LIMIT: Enhanced Limit Order - AT_AUCTION: At-auction order - AT_AUCTION_LIMIT: At-auction limit order - STOP_LOSS: Stop Order - STOP_LOSS_LIMIT: Stop Limit Order - TRAILING_STOP_LOSS: Trailing Stop Order - TRAILING_STOP_LOSS_LIMIT: Trailing Stop Limit Order - TOUCH_MKT: Touch Market Order - TOUCH_LMT: Touch Limit Order - MARKET: Market Order - ODD_LOT_LIMIT: Odd Lot Limit Order - MARKET_ON_OPEN: Opening market order - MARKET_ON_CLOSE: Closing market order HK Options - LIMIT: Limit Order - MARKET: Market Order - STOP_LOSS: Stop Order - STOP_LOSS_LIMIT: Stop Limit Order China Connect - LIMIT: Limit Order — one of: LIMIT, MARKET, STOP_LOSS, STOP_LOSS_LIMIT, ENHANCED_LIMIT, AT_AUCTION, AT_AUCTION_LIMIT, MARKET_ON_OPEN, MARKET_ON_CLOSE, TRAILING_STOP_LOSS, TRAILING_STOP_LOSS_LIMIT, TOUCH_MKT, TOUCH_LMT, ODD_LOT_LIMIT
instrument_type	string		Type of financial instrument associated with the request. — one of: EQUITY, OPTION
support_trading_session	string		Specifies the trading session for the order. Applicable to U.S. stock market orders only. Deprecated values: - Y: [Deprecated]Include extended trading hours. - N: [Deprecated]Only support regular trading hours. Active values: - NIGHT: Only supports night trading. - ALL: Include extended trading hours. - CORE: Only support regular trading hours. - ALL_DAY: Included Overnight Hours, 8:00 p.m.ET - 8:00 p.m.ET(the next day) — one of: Y, N, NIGHT, ALL, CORE, ALL_DAY
time_in_force	string	yes	Specifies the duration for which the order remains active in the market (Time-In-Force). - DAY: The order is valid only for the current trading day and expires at the end of the day. - GTC: Good-Till-Canceled, the order remains active until it is executed, explicitly canceled, or reaches the maximum allowed duration (typically 90 days). — one of: DAY, GTC
total_quantity	string	yes	Total order quantity. Represents the total number of units submitted for this order.
filled_quantity	string		Quantity that has been executed. Represents the number of units that have been filled so far.
filled_price	string		Average transaction price of the filled quantity. If the order has not been executed yet, this may be zero or null.
limit_price	string		Limit price of the order. Required when order_type is LIMIT, STOP_LOSS_LIMIT, ENHANCED_LIMIT, or AT_AUCTION_LIMIT or TOUCH_LMT. Specifies the maximum (for buy) or minimum (for sell) price at which the order can be executed.
stop_price	string		Stop price of the order. Required when order_type is STOP_LOSS, STOP_LOSS_LIMIT, TOUCH_MKT or TOUCH_LMT. Specifies the trigger price at which the stop order becomes active.
trailing_type	string		When market continues to fall, the stop price to buy follows, or trails, the lowest price of a stock by a trail that you set. Required when order_type is TRAILING_STOP_LOSS or TRAILING_STOP_LOSS_LIMIT. - AMOUNT: By amount. - PERCENTAGE: By percentage. — one of: AMOUNT, PERCENTAGE
trailing_stop_step	string		Trailing Stop Spread. If the tracking type is percentage, the tracking spread can not exceed 1,0.01 means 1%. Required when order_type is TRAILING_STOP_LOSS or TRAILING_STOP_LOSS_LIMIT.
trailing_limit_price_offset	string		The offset amount between the triggered stop price and the submitted limit price for a trailing stop-limit order. Required when order_type is TRAILING_STOP_LOSS_LIMIT. When triggered, the limit order price is calculated as: - Buy: limit price = stop price + trailing_limit_price_offset - Sell: limit price = stop price - trailing_limit_price_offset If the calculated limit price does not align with the instrument's tick size, it will be rounded to the nearest valid tick: rounded up for buy orders, rounded down for sell orders.
trigger_price_type	string		Trigger price type of the order - PRICE: Latest transaction price. - PRICE_BID: Buy at one price. - PRICE_ASK: Sell at one price. — one of: PRICE, PRICE_BID, PRICE_ASK
place_time	string		Order placement time in milliseconds since Unix epoch.
place_time_at	string	yes	Order placement time in ISO8601 format (UTC). Format: YYYY-MM-DDThh:mm:ssZ
filled_time	string		Time of the last executed trade in milliseconds since Unix epoch.
filled_time_at	string		Time of the last executed trade in ISO8601 format (UTC). Format: YYYY-MM-DDThh:mm:ssZ
commission	object		Commission breakdown
fees	array		Fee breakdown
legs	array		Leg detail

Nested — commission:

Field	Type	Required	Description
actual_commission	string		Actual commission collected
receivable_commission	string		Receivable commission

Nested — fees:

Field	Type	Required	Description
type	string		Fee type
actual_value	string		Actual fee collected
receivable_value	string		Receivable fee

Nested — legs:

Field	Type	Required	Description
id	string		Unique identifier for the leg.
symbol	string	yes	Trading symbol of the financial instrument.Represents the unique identifier of the security in the specified market (e.g., ticker symbol for equities or option symbol code for derivatives).
side	string	yes	The order side indicating the intended trading direction of the transaction. The meaning of side may vary depending on the instrument_type and account type (e.g., margin vs. cash). — one of: BUY, SELL, SHORT
quantity	string	yes	Quantity of the order. Specifies the number of shares or units to transact. For US stocks, fractional quantities are allowed and can include decimals.
option_type	string		Type of the option. - CALL: Right to buy the underlying asset. - PUT: Right to sell the underlying asset. — one of: CALL, PUT
option_category	string		Category of the option, indicating its exercise style. Possible values: - AMERICAN: Can be exercised any time before expiration. - EUROPEAN: Can only be exercised at expiration. — one of: AMERICAN, EUROPEAN
option_strategy	string		Type of options strategy - SINGLE: Single-leg options order - COVERED_STOCK: Covered call (stock + sell CALL) - STRADDLE: Same strike, same expiry CALL + PUT - STRANGLE: Different strike, same expiry CALL + PUT - VERTICAL: Same expiry, different strike, same type (Bull/Bear Spread) - CALENDAR: Same strike, different expiry, same type - DIAGONAL: Different strike, different expiry, same type - COLLAR_WITH_STOCK: Stock + buy PUT + sell CALL - BUTTERFLY: Buy low + sell 2 mid + buy high (same type) - CONDOR: Four different strikes, same type - IRON_BUTTERFLY: Buy low PUT + sell mid PUT + sell mid CALL + buy high CALL - IRON_CONDOR: Buy low PUT + sell mid-low PUT + sell mid-high CALL + buy high CALL - RATIO: Same expiry, same option type, unequal leg quantities (e.g. buy 1 low-strike CALL + sell 2 high-strike CALLs) — one of: SINGLE, COVERED_STOCK, STRADDLE, STRANGLE, VERTICAL, CALENDAR, DIAGONAL, COLLAR_WITH_STOCK, BUTTERFLY, CONDOR, IRON_BUTTERFLY, IRON_CONDOR, RATIO
strike_price	string		Exercise price (strike price) of the option. Specifies the price at which the underlying asset can be bought (CALL) or sold (PUT) upon exercise.
option_contract_multiplier	string		The number of shares corresponding to each option contract
option_contract_deliverable	string		The number of shares required to exercise each contract
option_expire_date	string		Expiration date of the option. Format: yyyy-MM-dd. After this date, the option will no longer be valid.

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Order History

GET /broker/orders/historical-orders/list

Retrieves historical orders.

SDK	broker.GetOrderHistory
Reference	broker-order-history.md

Request — parameters

Name	In	Type	Required	Description
account_id	query	String	yes	Account identifier.
start_date	query	String		The start date of the query period. If not provided, the default query period is the last 7 days. Users can specify an earlier date, but the maximum allowed look-back period is 6 months. Format: yyyy-MM-dd.
pagination_key	query	String		Pagination key from previous response for next page.

Response 200

Field	Type	Required	Description
client_order_id	string	yes	Client-defined order identifier. Returned in the response for simple orders. Represents the unique order ID assigned by the user when placing the order.
combo_type	string		Specifies the type of order combination. For details, please refer to Combo Order. - NORMAL: A standard single order. - MASTER: A primary order that triggers a take-profit or stop-loss order upon execution - STOP_PROFIT: A take-profit order - STOP_LOSS: A stop-loss order - OTO: An order that triggers another order upon execution (One-Triggers-the-Other) - OCO: A pair of orders where the execution of one cancels the other (One-Cancels-the-Other) - OTOCO: An order that triggers an OCO order set upon execution (One-Triggers-One-Cancels-the-Other) — one of: NORMAL, MASTER, STOP_PROFIT, STOP_LOSS, OTO, OCO, OTOCO
orders	array	yes	Order Details

Nested — orders:

Field	Type	Required	Description
client_order_id	string	yes	Client-defined order identifier. Returned in the response for simple orders. Represents the unique order ID assigned by the user when placing the order.
order_id	string	yes	System-generated order identifier. Returned in the response for simple orders. Represents the unique Webull order ID assigned by the system.
symbol	string	yes	Trading symbol of the financial instrument.Represents the unique identifier of the security in the specified market (e.g., ticker symbol for equities or option symbol code for derivatives).
side	string	yes	The order side indicating the intended trading direction of the transaction. The meaning of side may vary depending on the instrument_type and account type (e.g., margin vs. cash). — one of: BUY, SELL, SHORT
status	string	yes	- PENDING: Indicates that the order has been submitted to the exchange and is awaiting completion - SUBMITTED: Indicates that the order has been submitted to the exchange and is awaiting completion - CANCELLED: Indicates that the order has been successfully cancelled - FILLED: Indicates that the order has been fully executed - FAILED: Indicates a failed order, such as REJECTED - PARTIAL_FILLED: Refers to the portion of the order that has been completed, but not all of it has been completed — one of: PENDING, SUBMITTED, CANCELLED, FILLED, FAILED, PARTIAL_FILLED
order_type	string	yes	Specifies the type of order to be placed. Determines how the order will be executed in the market. Available order types depend on the market and instrument type. Options trading Only LIMIT,STOP_LOSS,STOP_LOSS_LIMIT are supported. U.S. Stock - LIMIT: Limit Order - MARKET: Market Order - STOP_LOSS: Stop Order - STOP_LOSS_LIMIT: Stop Limit Order - MARKET_ON_OPEN: Opening market order - MARKET_ON_CLOSE: Closing market order Hong Kong Stock - ENHANCED_LIMIT: Enhanced Limit Order - AT_AUCTION: At-auction order - AT_AUCTION_LIMIT: At-auction limit order - STOP_LOSS: Stop Order - STOP_LOSS_LIMIT: Stop Limit Order - TRAILING_STOP_LOSS: Trailing Stop Order - TRAILING_STOP_LOSS_LIMIT: Trailing Stop Limit Order - TOUCH_MKT: Touch Market Order - TOUCH_LMT: Touch Limit Order - MARKET: Market Order - ODD_LOT_LIMIT: Odd Lot Limit Order - MARKET_ON_OPEN: Opening market order - MARKET_ON_CLOSE: Closing market order HK Options - LIMIT: Limit Order - MARKET: Market Order - STOP_LOSS: Stop Order - STOP_LOSS_LIMIT: Stop Limit Order China Connect - LIMIT: Limit Order — one of: LIMIT, MARKET, STOP_LOSS, STOP_LOSS_LIMIT, ENHANCED_LIMIT, AT_AUCTION, AT_AUCTION_LIMIT, MARKET_ON_OPEN, MARKET_ON_CLOSE, TRAILING_STOP_LOSS, TRAILING_STOP_LOSS_LIMIT, TOUCH_MKT, TOUCH_LMT, ODD_LOT_LIMIT
instrument_type	string		Type of financial instrument associated with the request. — one of: EQUITY, OPTION
support_trading_session	string		Specifies the trading session for the order. Applicable to U.S. stock market orders only. Deprecated values: - Y: [Deprecated]Include extended trading hours. - N: [Deprecated]Only support regular trading hours. Active values: - NIGHT: Only supports night trading. - ALL: Include extended trading hours. - CORE: Only support regular trading hours. - ALL_DAY: Included Overnight Hours, 8:00 p.m.ET - 8:00 p.m.ET(the next day) — one of: Y, N, NIGHT, ALL, CORE, ALL_DAY
time_in_force	string	yes	Specifies the duration for which the order remains active in the market (Time-In-Force). - DAY: The order is valid only for the current trading day and expires at the end of the day. - GTC: Good-Till-Canceled, the order remains active until it is executed, explicitly canceled, or reaches the maximum allowed duration (typically 90 days). — one of: DAY, GTC
total_quantity	string	yes	Total order quantity. Represents the total number of units submitted for this order.
filled_quantity	string		Quantity that has been executed. Represents the number of units that have been filled so far.
filled_price	string		Average transaction price of the filled quantity. If the order has not been executed yet, this may be zero or null.
limit_price	string		Limit price of the order. Required when order_type is LIMIT, STOP_LOSS_LIMIT, ENHANCED_LIMIT, or AT_AUCTION_LIMIT or TOUCH_LMT. Specifies the maximum (for buy) or minimum (for sell) price at which the order can be executed.
stop_price	string		Stop price of the order. Required when order_type is STOP_LOSS, STOP_LOSS_LIMIT, TOUCH_MKT or TOUCH_LMT. Specifies the trigger price at which the stop order becomes active.
trailing_type	string		When market continues to fall, the stop price to buy follows, or trails, the lowest price of a stock by a trail that you set. Required when order_type is TRAILING_STOP_LOSS or TRAILING_STOP_LOSS_LIMIT. - AMOUNT: By amount. - PERCENTAGE: By percentage. — one of: AMOUNT, PERCENTAGE
trailing_stop_step	string		Trailing Stop Spread. If the tracking type is percentage, the tracking spread can not exceed 1,0.01 means 1%. Required when order_type is TRAILING_STOP_LOSS or TRAILING_STOP_LOSS_LIMIT.
trailing_limit_price_offset	string		The offset amount between the triggered stop price and the submitted limit price for a trailing stop-limit order. Required when order_type is TRAILING_STOP_LOSS_LIMIT. When triggered, the limit order price is calculated as: - Buy: limit price = stop price + trailing_limit_price_offset - Sell: limit price = stop price - trailing_limit_price_offset If the calculated limit price does not align with the instrument's tick size, it will be rounded to the nearest valid tick: rounded up for buy orders, rounded down for sell orders.
trigger_price_type	string		Trigger price type of the order - PRICE: Latest transaction price. - PRICE_BID: Buy at one price. - PRICE_ASK: Sell at one price. — one of: PRICE, PRICE_BID, PRICE_ASK
place_time	string		Order placement time in milliseconds since Unix epoch.
place_time_at	string	yes	Order placement time in ISO8601 format (UTC). Format: YYYY-MM-DDThh:mm:ssZ
filled_time	string		Time of the last executed trade in milliseconds since Unix epoch.
filled_time_at	string		Time of the last executed trade in ISO8601 format (UTC). Format: YYYY-MM-DDThh:mm:ssZ
option_strategy	string		Type of options strategy - SINGLE: Single-leg options order - COVERED_STOCK: Covered call (stock + sell CALL) - STRADDLE: Same strike, same expiry CALL + PUT - STRANGLE: Different strike, same expiry CALL + PUT - VERTICAL: Same expiry, different strike, same type (Bull/Bear Spread) - CALENDAR: Same strike, different expiry, same type - DIAGONAL: Different strike, different expiry, same type - COLLAR_WITH_STOCK: Stock + buy PUT + sell CALL - BUTTERFLY: Buy low + sell 2 mid + buy high (same type) - CONDOR: Four different strikes, same type - IRON_BUTTERFLY: Buy low PUT + sell mid PUT + sell mid CALL + buy high CALL - IRON_CONDOR: Buy low PUT + sell mid-low PUT + sell mid-high CALL + buy high CALL - RATIO: Same expiry, same option type, unequal leg quantities (e.g. buy 1 low-strike CALL + sell 2 high-strike CALLs) — one of: SINGLE, COVERED_STOCK, STRADDLE, STRANGLE, VERTICAL, CALENDAR, DIAGONAL, COLLAR_WITH_STOCK, BUTTERFLY, CONDOR, IRON_BUTTERFLY, IRON_CONDOR, RATIO
legs	array		Leg detail

Nested — legs:

Field	Type	Required	Description
id	string		Unique identifier for the leg.
symbol	string	yes	Trading symbol of the financial instrument.Represents the unique identifier of the security in the specified market (e.g., ticker symbol for equities or option symbol code for derivatives).
side	string	yes	The order side indicating the intended trading direction of the transaction. The meaning of side may vary depending on the instrument_type and account type (e.g., margin vs. cash). — one of: BUY, SELL, SHORT
quantity	string	yes	Quantity of the order. Specifies the number of shares or units to transact. For US stocks, fractional quantities are allowed and can include decimals.
option_type	string		Type of the option. - CALL: Right to buy the underlying asset. - PUT: Right to sell the underlying asset. — one of: CALL, PUT
option_category	string		Category of the option, indicating its exercise style. Possible values: - AMERICAN: Can be exercised any time before expiration. - EUROPEAN: Can only be exercised at expiration. — one of: AMERICAN, EUROPEAN
option_strategy	string		Type of options strategy - SINGLE: Single-leg options order - COVERED_STOCK: Covered call (stock + sell CALL) - STRADDLE: Same strike, same expiry CALL + PUT - STRANGLE: Different strike, same expiry CALL + PUT - VERTICAL: Same expiry, different strike, same type (Bull/Bear Spread) - CALENDAR: Same strike, different expiry, same type - DIAGONAL: Different strike, different expiry, same type - COLLAR_WITH_STOCK: Stock + buy PUT + sell CALL - BUTTERFLY: Buy low + sell 2 mid + buy high (same type) - CONDOR: Four different strikes, same type - IRON_BUTTERFLY: Buy low PUT + sell mid PUT + sell mid CALL + buy high CALL - IRON_CONDOR: Buy low PUT + sell mid-low PUT + sell mid-high CALL + buy high CALL - RATIO: Same expiry, same option type, unequal leg quantities (e.g. buy 1 low-strike CALL + sell 2 high-strike CALLs) — one of: SINGLE, COVERED_STOCK, STRADDLE, STRANGLE, VERTICAL, CALENDAR, DIAGONAL, COLLAR_WITH_STOCK, BUTTERFLY, CONDOR, IRON_BUTTERFLY, IRON_CONDOR, RATIO
strike_price	string		Exercise price (strike price) of the option. Specifies the price at which the underlying asset can be bought (CALL) or sold (PUT) upon exercise.
option_contract_multiplier	string		The number of shares corresponding to each option contract
option_contract_deliverable	string		The number of shares required to exercise each contract
option_expire_date	string		Expiration date of the option. Format: yyyy-MM-dd. After this date, the option will no longer be valid.

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Open Orders

GET /broker/orders/open-orders/list

Retrieves current pending orders list with pagination support.

SDK	broker.GetOpenOrders
Reference	broker-order-open.md

Request — parameters

Name	In	Type	Required	Description
account_id	query	String	yes	Account identifier.
pagination_key	query	String		Pagination key from previous response for next page.

Response 200

Field	Type	Required	Description
client_order_id	string	yes	Client-defined order identifier. Returned in the response for simple orders. Represents the unique order ID assigned by the user when placing the order.
combo_type	string		Specifies the type of order combination. For details, please refer to Combo Order. - NORMAL: A standard single order. - MASTER: A primary order that triggers a take-profit or stop-loss order upon execution - STOP_PROFIT: A take-profit order - STOP_LOSS: A stop-loss order - OTO: An order that triggers another order upon execution (One-Triggers-the-Other) - OCO: A pair of orders where the execution of one cancels the other (One-Cancels-the-Other) - OTOCO: An order that triggers an OCO order set upon execution (One-Triggers-One-Cancels-the-Other) — one of: NORMAL, MASTER, STOP_PROFIT, STOP_LOSS, OTO, OCO, OTOCO
orders	array	yes	Order Details

Nested — orders:

Field	Type	Required	Description
client_order_id	string	yes	Client-defined order identifier. Returned in the response for simple orders. Represents the unique order ID assigned by the user when placing the order.
order_id	string	yes	System-generated order identifier. Returned in the response for simple orders. Represents the unique Webull order ID assigned by the system.
symbol	string	yes	Trading symbol of the financial instrument.Represents the unique identifier of the security in the specified market (e.g., ticker symbol for equities or option symbol code for derivatives).
side	string	yes	The order side indicating the intended trading direction of the transaction. The meaning of side may vary depending on the instrument_type and account type (e.g., margin vs. cash). — one of: BUY, SELL, SHORT
status	string	yes	- PENDING: Indicates that the order has been submitted to the exchange and is awaiting completion - SUBMITTED: Indicates that the order has been submitted to the exchange and is awaiting completion - CANCELLED: Indicates that the order has been successfully cancelled - FILLED: Indicates that the order has been fully executed - FAILED: Indicates a failed order, such as REJECTED - PARTIAL_FILLED: Refers to the portion of the order that has been completed, but not all of it has been completed — one of: PENDING, SUBMITTED, CANCELLED, FILLED, FAILED, PARTIAL_FILLED
order_type	string	yes	Specifies the type of order to be placed. Determines how the order will be executed in the market. Available order types depend on the market and instrument type. Options trading Only LIMIT,STOP_LOSS,STOP_LOSS_LIMIT are supported. U.S. Stock - LIMIT: Limit Order - MARKET: Market Order - STOP_LOSS: Stop Order - STOP_LOSS_LIMIT: Stop Limit Order - MARKET_ON_OPEN: Opening market order - MARKET_ON_CLOSE: Closing market order Hong Kong Stock - ENHANCED_LIMIT: Enhanced Limit Order - AT_AUCTION: At-auction order - AT_AUCTION_LIMIT: At-auction limit order - STOP_LOSS: Stop Order - STOP_LOSS_LIMIT: Stop Limit Order - TRAILING_STOP_LOSS: Trailing Stop Order - TRAILING_STOP_LOSS_LIMIT: Trailing Stop Limit Order - TOUCH_MKT: Touch Market Order - TOUCH_LMT: Touch Limit Order - MARKET: Market Order - ODD_LOT_LIMIT: Odd Lot Limit Order - MARKET_ON_OPEN: Opening market order - MARKET_ON_CLOSE: Closing market order HK Options - LIMIT: Limit Order - MARKET: Market Order - STOP_LOSS: Stop Order - STOP_LOSS_LIMIT: Stop Limit Order China Connect - LIMIT: Limit Order — one of: LIMIT, MARKET, STOP_LOSS, STOP_LOSS_LIMIT, ENHANCED_LIMIT, AT_AUCTION, AT_AUCTION_LIMIT, MARKET_ON_OPEN, MARKET_ON_CLOSE, TRAILING_STOP_LOSS, TRAILING_STOP_LOSS_LIMIT, TOUCH_MKT, TOUCH_LMT, ODD_LOT_LIMIT
instrument_type	string		Type of financial instrument associated with the request. — one of: EQUITY, OPTION
support_trading_session	string		Specifies the trading session for the order. Applicable to U.S. stock market orders only. Deprecated values: - Y: [Deprecated]Include extended trading hours. - N: [Deprecated]Only support regular trading hours. Active values: - NIGHT: Only supports night trading. - ALL: Include extended trading hours. - CORE: Only support regular trading hours. - ALL_DAY: Included Overnight Hours, 8:00 p.m.ET - 8:00 p.m.ET(the next day) — one of: Y, N, NIGHT, ALL, CORE, ALL_DAY
time_in_force	string	yes	Specifies the duration for which the order remains active in the market (Time-In-Force). - DAY: The order is valid only for the current trading day and expires at the end of the day. - GTC: Good-Till-Canceled, the order remains active until it is executed, explicitly canceled, or reaches the maximum allowed duration (typically 90 days). — one of: DAY, GTC
total_quantity	string	yes	Total order quantity. Represents the total number of units submitted for this order.
filled_quantity	string		Quantity that has been executed. Represents the number of units that have been filled so far.
filled_price	string		Average transaction price of the filled quantity. If the order has not been executed yet, this may be zero or null.
limit_price	string		Limit price of the order. Required when order_type is LIMIT, STOP_LOSS_LIMIT, ENHANCED_LIMIT, or AT_AUCTION_LIMIT or TOUCH_LMT. Specifies the maximum (for buy) or minimum (for sell) price at which the order can be executed.
stop_price	string		Stop price of the order. Required when order_type is STOP_LOSS, STOP_LOSS_LIMIT, TOUCH_MKT or TOUCH_LMT. Specifies the trigger price at which the stop order becomes active.
trailing_type	string		When market continues to fall, the stop price to buy follows, or trails, the lowest price of a stock by a trail that you set. Required when order_type is TRAILING_STOP_LOSS or TRAILING_STOP_LOSS_LIMIT. - AMOUNT: By amount. - PERCENTAGE: By percentage. — one of: AMOUNT, PERCENTAGE
trailing_stop_step	string		Trailing Stop Spread. If the tracking type is percentage, the tracking spread can not exceed 1,0.01 means 1%. Required when order_type is TRAILING_STOP_LOSS or TRAILING_STOP_LOSS_LIMIT.
trailing_limit_price_offset	string		The offset amount between the triggered stop price and the submitted limit price for a trailing stop-limit order. Required when order_type is TRAILING_STOP_LOSS_LIMIT. When triggered, the limit order price is calculated as: - Buy: limit price = stop price + trailing_limit_price_offset - Sell: limit price = stop price - trailing_limit_price_offset If the calculated limit price does not align with the instrument's tick size, it will be rounded to the nearest valid tick: rounded up for buy orders, rounded down for sell orders.
trigger_price_type	string		Trigger price type of the order - PRICE: Latest transaction price. - PRICE_BID: Buy at one price. - PRICE_ASK: Sell at one price. — one of: PRICE, PRICE_BID, PRICE_ASK
place_time	string		Order placement time in milliseconds since Unix epoch.
place_time_at	string	yes	Order placement time in ISO8601 format (UTC). Format: YYYY-MM-DDThh:mm:ssZ
filled_time	string		Time of the last executed trade in milliseconds since Unix epoch.
filled_time_at	string		Time of the last executed trade in ISO8601 format (UTC). Format: YYYY-MM-DDThh:mm:ssZ
option_strategy	string		Type of options strategy - SINGLE: Single-leg options order - COVERED_STOCK: Covered call (stock + sell CALL) - STRADDLE: Same strike, same expiry CALL + PUT - STRANGLE: Different strike, same expiry CALL + PUT - VERTICAL: Same expiry, different strike, same type (Bull/Bear Spread) - CALENDAR: Same strike, different expiry, same type - DIAGONAL: Different strike, different expiry, same type - COLLAR_WITH_STOCK: Stock + buy PUT + sell CALL - BUTTERFLY: Buy low + sell 2 mid + buy high (same type) - CONDOR: Four different strikes, same type - IRON_BUTTERFLY: Buy low PUT + sell mid PUT + sell mid CALL + buy high CALL - IRON_CONDOR: Buy low PUT + sell mid-low PUT + sell mid-high CALL + buy high CALL - RATIO: Same expiry, same option type, unequal leg quantities (e.g. buy 1 low-strike CALL + sell 2 high-strike CALLs) — one of: SINGLE, COVERED_STOCK, STRADDLE, STRANGLE, VERTICAL, CALENDAR, DIAGONAL, COLLAR_WITH_STOCK, BUTTERFLY, CONDOR, IRON_BUTTERFLY, IRON_CONDOR, RATIO
legs	array		Leg detail

Nested — legs:

Field	Type	Required	Description
id	string		Unique identifier for the leg.
symbol	string	yes	Trading symbol of the financial instrument.Represents the unique identifier of the security in the specified market (e.g., ticker symbol for equities or option symbol code for derivatives).
side	string	yes	The order side indicating the intended trading direction of the transaction. The meaning of side may vary depending on the instrument_type and account type (e.g., margin vs. cash). — one of: BUY, SELL, SHORT
quantity	string	yes	Quantity of the order. Specifies the number of shares or units to transact. For US stocks, fractional quantities are allowed and can include decimals.
option_type	string		Type of the option. - CALL: Right to buy the underlying asset. - PUT: Right to sell the underlying asset. — one of: CALL, PUT
option_category	string		Category of the option, indicating its exercise style. Possible values: - AMERICAN: Can be exercised any time before expiration. - EUROPEAN: Can only be exercised at expiration. — one of: AMERICAN, EUROPEAN
option_strategy	string		Type of options strategy - SINGLE: Single-leg options order - COVERED_STOCK: Covered call (stock + sell CALL) - STRADDLE: Same strike, same expiry CALL + PUT - STRANGLE: Different strike, same expiry CALL + PUT - VERTICAL: Same expiry, different strike, same type (Bull/Bear Spread) - CALENDAR: Same strike, different expiry, same type - DIAGONAL: Different strike, different expiry, same type - COLLAR_WITH_STOCK: Stock + buy PUT + sell CALL - BUTTERFLY: Buy low + sell 2 mid + buy high (same type) - CONDOR: Four different strikes, same type - IRON_BUTTERFLY: Buy low PUT + sell mid PUT + sell mid CALL + buy high CALL - IRON_CONDOR: Buy low PUT + sell mid-low PUT + sell mid-high CALL + buy high CALL - RATIO: Same expiry, same option type, unequal leg quantities (e.g. buy 1 low-strike CALL + sell 2 high-strike CALLs) — one of: SINGLE, COVERED_STOCK, STRADDLE, STRANGLE, VERTICAL, CALENDAR, DIAGONAL, COLLAR_WITH_STOCK, BUTTERFLY, CONDOR, IRON_BUTTERFLY, IRON_CONDOR, RATIO
strike_price	string		Exercise price (strike price) of the option. Specifies the price at which the underlying asset can be bought (CALL) or sold (PUT) upon exercise.
option_contract_multiplier	string		The number of shares corresponding to each option contract
option_contract_deliverable	string		The number of shares required to exercise each contract
option_expire_date	string		Expiration date of the option. Format: yyyy-MM-dd. After this date, the option will no longer be valid.

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Get FX Rate

GET /broker/funding/fx-rates/get

Retrieves the currency exchange rate based on currency pair.

SDK	broker.GetFXRate
Reference	broker-funding-query-rate.md

Request — parameters

Name	In	Type	Required	Description
from_currency	query	string	yes	Which currency you use for exchange. — one of: CNH, HKD, USD
to_currency	query	string	yes	Target currency you plan to get for exchange. — one of: CNH, HKD, USD

Response 200

Field	Type	Required	Description
from_currency	string	yes	Currency — one of: CNH, HKD, USD
to_currency	string	yes	Currency — one of: CNH, HKD, USD
fx_rate	string	yes	FX rate
rate_effective_time	string	yes	Effective time of the FX rate (ISO 8601 format, UTC time zone).
rate_expire_time	string	yes	Expiration time of the FX rate (ISO 8601 format, UTC time zone).

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Create FX Request

POST /broker/funding/fx-exchanges/create

Creates a currency exchange request at the Omnibus master account level. Requires base currency, base amount and target currency as inputs. Uses the latest FX rate for currency exchange processing.

SDK	broker.CreateFXExchange
Reference	broker-funding-create-fx.md

Request body

Field	Type	Required	Description
account_id	string	yes	Account identifier, Exchange on which account id.
client_request_id	string	yes	Client Request ID, unique for each request. Maximum length is 32 characters. Allowed characters: letters (A–Z, a–z), digits (0–9), hyphen (-), underscore (_).
from_amount	string	yes	Base amount for exchange.
from_currency	string	yes	Currency — one of: CNH, HKD, USD
to_currency	string	yes	Currency — one of: CNH, HKD, USD

Response 200

Field	Type	Required	Description
account_id	string	yes	Account identifier, Exchange on which account id.
client_request_id	string	yes	Client Request ID, unique for each request.
fx_id	string	yes	Request id generated by the system.
from_amount	string	yes	Base amount for exchange.
from_currency	string	yes	Currency — one of: CNH, HKD, USD
to_currency	string	yes	Currency — one of: CNH, HKD, USD
status	string	yes	Request status — one of: SUBMITTED, CANCELED, REJECTED, FAILED, COMPLETED

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Get FX Detail

GET /broker/funding/fx-exchanges/get

Retrieves currency exchange record details at the Omnibus master account level.

SDK	broker.GetFXExchangeDetail
Reference	broker-funding-query-fx.md

Request — parameters

Name	In	Type	Required	Description
client_request_id	query	String	yes	Client Request ID, unique for each request. Maximum length is 32 characters. Allowed characters: letters (A–Z, a–z), digits (0–9), hyphen (-), underscore (_).
account_id	query	String	yes	Account identifier

Response 200

Field	Type	Required	Description
account_id	string	yes	Account identifier, Exchange on which account id.
client_request_id	string	yes	Client Request ID, unique for each request.
fx_id	string	yes	Request id generated by the system.
from_amount	string		Base amount for exchange.
to_amount	string		Amount after exchange.
from_currency	string	yes	Currency — one of: CNH, HKD, USD
to_currency	string	yes	Currency — one of: CNH, HKD, USD
fx_rate	string		FX rate
status	string	yes	Request status — one of: SUBMITTED, CANCELED, REJECTED, FAILED, COMPLETED
reason	string		Reason. If the terminal state is not “COMPLETED”, return the reason.

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Create Instant Exchange

POST /broker/funding/instant-exchanges/create

Creates an instant currency exchange request at the Virtual account level. Requires base currency, base amount, target currency, and target amount as inputs. This feature does not rely on the latest FX rate provided by Webull.

SDK	broker.CreateInstantExchange
Reference	broker-funding-create-instant-fx.md

Request body

Field	Type	Required	Description
account_id	string	yes	Account identifier, Exchange on which account id.
client_request_id	string	yes	Client Request ID, unique for each request. Maximum length is 32 characters. Allowed characters: letters (A–Z, a–z), digits (0–9), hyphen (-), underscore (_).
from_amount	string	yes	Base amount for exchange.
to_amount	string	yes	Amount after exchange.
from_currency	string	yes	Currency — one of: CNH, HKD, USD
to_currency	string	yes	Currency — one of: CNH, HKD, USD

Response 200

Field	Type	Required	Description
account_id	string	yes	Account identifier, Exchange on which account id.
client_request_id	string	yes	Client Request ID, unique for each request.
instant_exchange_id	string	yes	Request id generated by the system.
from_amount	string	yes	Base amount for exchange.
to_amount	string	yes	Amount after exchange.
from_currency	string	yes	Currency — one of: CNH, HKD, USD
to_currency	string	yes	Currency — one of: CNH, HKD, USD
status	string	yes	Request status — one of: SUBMITTED, CANCELED, REJECTED, FAILED, COMPLETED
reason	string		Reason. If the terminal state is not “COMPLETED”, return the reason.

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Get Instant Exchange Detail

GET /broker/funding/instant-exchanges/get

Retrieves instant currency exchange record details at the Omnibus master account level.

SDK	broker.GetInstantExchangeDetail
Reference	broker-funding-query-instant-fx.md

Request — parameters

Name	In	Type	Required	Description
client_request_id	query	String	yes	Client Request ID, unique for each request. Maximum length is 32 characters. Allowed characters: letters (A–Z, a–z), digits (0–9), hyphen (-), underscore (_).
account_id	query	String	yes	Account identifier

Response 200

Field	Type	Required	Description
account_id	string	yes	Account identifier, Exchange on which account id.
client_request_id	string	yes	Client Request ID, unique for each request.
instant_exchange_id	string	yes	Request id generated by the system.
from_amount	string	yes	Base amount for exchange.
to_amount	string	yes	Amount after exchange.
from_currency	string	yes	Currency — one of: CNH, HKD, USD
to_currency	string	yes	Currency — one of: CNH, HKD, USD
status	string	yes	Request status — one of: SUBMITTED, CANCELED, REJECTED, FAILED, COMPLETED
reason	string		Reason. If the terminal state is not “COMPLETED”, return the reason.

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Create Instant Funding

POST /broker/funding/instant-funding/create

Creates an instant funding request at the Virtual account level.

SDK	broker.CreateInstantFunding
Reference	broker-funding-instant-create.md

Request body

Field	Type	Required	Description
account_id	string	yes	Account identifier, Exchange on which account id.
type	string	yes	Instant Funding Request Type — one of: DEPOSIT, WITHDRAWAL
client_request_id	string	yes	Client Request ID, unique for each request. Maximum length is 32 characters. Allowed characters: letters (A–Z, a–z), digits (0–9), hyphen (-), underscore (_).
amount	string	yes	Amount.
currency	string	yes	Currency — one of: CNH, HKD, USD

Response 200

Field	Type	Required	Description
account_id	string	yes	Account identifier, Exchange on which account id.
type	string	yes	Instant Funding Request Type — one of: DEPOSIT, WITHDRAWAL
client_request_id	string	yes	Client Request ID, unique for each request.
instant_funding_id	string	yes	Request id generated by the system.
amount	string	yes	Amount.
currency	string	yes	Currency — one of: CNH, HKD, USD
status	string	yes	Request status — one of: SUBMITTED, CANCELED, REJECTED, FAILED, COMPLETED
reason	string		Reason. If the terminal state is not “COMPLETED”, return the reason.

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Get Instant Funding Detail

GET /broker/funding/instant-funding/get

Retrieves instant funding record details at the Virtual account level.

SDK	broker.GetInstantFundingDetail
Reference	broker-funding-instant-query.md

Request — parameters

Name	In	Type	Required	Description
client_request_id	query	String	yes	Client Request ID, unique for each request. Maximum length is 32 characters. Allowed characters: letters (A–Z, a–z), digits (0–9), hyphen (-), underscore (_).
account_id	query	String	yes	Account identifier

Response 200

Field	Type	Required	Description
account_id	string	yes	Account identifier, Exchange on which account id.
type	string	yes	Instant Funding Request Type — one of: DEPOSIT, WITHDRAWAL
client_request_id	string	yes	Client Request ID, unique for each request.
instant_funding_id	string	yes	Request id generated by the system.
amount	string	yes	Amount.
currency	string	yes	Currency — one of: CNH, HKD, USD
status	string	yes	Request status — one of: SUBMITTED, CANCELED, REJECTED, FAILED, COMPLETED
reason	string		Reason. If the terminal state is not “COMPLETED”, return the reason.

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Create Cash Journal

POST /broker/journals/cash-journals/create

Creates a cash journal request. Cash journal supports both Omnibus master account level and Virtual account level.

SDK	broker.CreateCashJournal
Reference	broker-journal-cash-create.md

Request body

Field	Type	Required	Description
from_account	string	yes	From account id.
to_account	string	yes	To account id.
client_request_id	string	yes	Client Request ID, unique for each request. Maximum length is 32 characters. Allowed characters: letters (A–Z, a–z), digits (0–9), hyphen (-), underscore (_).
amount	string	yes	Amount
currency	string	yes	Currency — one of: CNH, HKD, USD

Response 200

Field	Type	Required	Description
from_account	string	yes	From account id.
to_account	string	yes	To account id.
client_request_id	string	yes	Client Request ID, unique for each request.
journal_id	string	yes	Request id generated by the system.
amount	string	yes	Amount
currency	string	yes	Currency — one of: CNH, HKD, USD
status	string	yes	Request status — one of: SUBMITTED, CANCELED, REJECTED, FAILED, COMPLETED
reason	string		Reason. If the terminal state is not “COMPLETED”, return the reason.

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Get Cash Journal Detail

GET /broker/journals/cash-journals/get

Retrieves detailed information for a cash journal request.

SDK	broker.GetCashJournalDetail
Reference	broker-journal-cash-query.md

Request — parameters

Name	In	Type	Required	Description
client_request_id	query	String	yes	Client Request ID, unique for each request. Maximum length is 32 characters. Allowed characters: letters (A–Z, a–z), digits (0–9), hyphen (-), underscore (_).
account_id	query	String	yes	From account identifier.

Response 200

Field	Type	Required	Description
from_account	string	yes	From account id.
to_account	string	yes	To account id.
client_request_id	string	yes	Client Request ID, unique for each request.
journal_id	string	yes	Request id generated by the system.
amount	string	yes	Amount
currency	string	yes	Currency — one of: CNH, HKD, USD
status	string	yes	Request status — one of: SUBMITTED, CANCELED, REJECTED, FAILED, COMPLETED
reason	string		Reason. If the terminal state is not “COMPLETED”, return the reason.

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Create Position Journal

POST /broker/journals/position-journals/create

Creates a position journal request. Position journal only supports Virtual account level.

SDK	broker.CreatePositionJournal
Reference	broker-journal-position-create.md

Request body

Field	Type	Required	Description
from_account	string	yes	From account id.
to_account	string	yes	To account id.
client_request_id	string	yes	Client Request ID, unique for each request. Maximum length is 32 characters. Allowed characters: letters (A–Z, a–z), digits (0–9), hyphen (-), underscore (_).
instrument_type	string	yes	Type of financial instrument associated with the request. — one of: EQUITY, OPTION
market	string	yes	Market code indicating the trading venue or regulatory region of the financial instrument. Used together with symbol and instrument_type to uniquely identify a tradable instrument. — one of: US, HK, CN
quantity	string	yes	Quantity, positive number.
symbol	string	yes	Symbol name. Options use OCC format.

Response 200

Field	Type	Required	Description
from_account	string	yes	From account id.
to_account	string	yes	To account id.
client_request_id	string	yes	Client Request ID, unique for each request.
journal_id	string	yes	Request id generated by the system.
instrument_type	string	yes	Type of financial instrument associated with the request. — one of: EQUITY, OPTION
market	string	yes	Market code indicating the trading venue or regulatory region of the financial instrument. Used together with symbol and instrument_type to uniquely identify a tradable instrument. — one of: US, HK, CN
quantity	string	yes	Quantity, positive number.
symbol	string	yes	Symbol name. Options use OCC format.
status	string	yes	Request status — one of: SUBMITTED, CANCELED, REJECTED, FAILED, COMPLETED
reason	string		Reason for failure. Returned when the terminal state is not COMPLETED.

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Get Position Journal Detail

GET /broker/journals/position-journals/get

Retrieves detailed information for a position journal request.

SDK	broker.GetPositionJournalDetail
Reference	broker-journal-position-query.md

Request — parameters

Name	In	Type	Required	Description
client_request_id	query	String	yes	Client Request ID, unique for each request. Maximum length is 32 characters. Allowed characters: letters (A–Z, a–z), digits (0–9), hyphen (-), underscore (_).
account_id	query	String	yes	From account identifier.

Response 200

Field	Type	Required	Description
from_account	string	yes	From account id.
to_account	string	yes	To account id.
client_request_id	string	yes	Client Request ID, unique for each request.
journal_id	string	yes	Request id generated by the system.
instrument_type	string	yes	Type of financial instrument associated with the request. — one of: EQUITY, OPTION
market	string	yes	Market code indicating the trading venue or regulatory region of the financial instrument. Used together with symbol and instrument_type to uniquely identify a tradable instrument. — one of: US, HK, CN
quantity	string	yes	Quantity, positive number.
symbol	string	yes	Symbol name. Options use OCC format.
status	string	yes	Request status — one of: SUBMITTED, CANCELED, REJECTED, FAILED, COMPLETED
reason	string		Reason for failure. Returned when the terminal state is not COMPLETED.

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Trade Calendar

GET /broker/master-data/trading-calendars/list

Retrieves trading and settlement calendar based on markets and product types.

SDK	broker.GetTradeCalendar
Reference	broker-trade-calendar.md

Request — parameters

Name	In	Type	Required	Description
market	query	string	yes	Country code, US,HK,etc. — one of: US, HK, CN
instrument_type	query	string	yes	Type of financial instrument associated with the request. — one of: EQUITY, OPTION
year	query	String	yes	Query Year in YYYY format

Response 200

Array of objects:

Field	Type	Required	Description
date	string	yes	Date string in YYYY-MM-DD format.
settlement_date	string		Settlement Date string in YYYY-MM-DD format.
is_trading_day	boolean	yes	Is Trading Day
is_early_close	boolean		Whether it is a half-day trading session
is_settlement_day	boolean	yes	Is Settlement Day

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Account Events

SDK	—
Reference	broker-account-events.md
Note	gRPC subscription.

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Instrument Events

SDK	—
Reference	broker-instrument-events.md
Note	gRPC subscription.

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Corporate Actions Events

SDK	—
Reference	broker-ca-events.md
Note	gRPC subscription.

Errors — 401 unauthorized, 417 business error, 500 server error. See Errors.

Trade Events

Reference: broker-trade-events.md

SDK: —

Note: gRPC subscription.

To enable third-party systems to promptly obtain order execution results and order status updates, Broker OpenAPI provides an asynchronous active push mechanism for order trading events.

Clients can subscribe to order-related events to receive notifications, allowing them to monitor order processing results and execution status changes in real time.

Order

Order Event Notification

{
"id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",    
"event_type": "TRADE",    
"timestamp": "2025-03-29T07:02:33.200962333Z",    
"payload": {  
   "request_id": "1045474398137483264",
    "account_id": "4MHSOMIJ88O7E80VBG0O4G6E9A",
    "client_order_id": "db74f19918054a7e9bb72067731c9ae4",
    "instrument_id": "913256135",
    "order_status": "PARTIAL_FILLED",
    "symbol": "AAPL",
    "qty": "10.00",
    "filled_price": "180.00",
    "filled_qty": "1.00",
    "filled_time": "2025-11-21T06:27:43.312+0000",
    "side": "BUY",
    "category": "US_STOCK",
    "order_type": "LIMIT",
    "scene_type": "FILLED",
    "biz_type":"TRADE"
    }
}

{
"id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",    
"event_type": "TRADE",    
"timestamp": "2025-03-29T07:02:33.200962333Z",    
"payload": {  
   "request_id": "1045474398137483264",
    "account_id": "4MHSOMIJ88O7E80VBG0O4G6E9A",
    "order_id": "036LVV5P4I8BV0KHKN60000000",
    "client_order_id": "db74f19918054a7e9bb72067731c9ae4",
    "instrument_id": "913256135",
    "order_status": "FILLED",
    "symbol": "AAPL",
    "qty": "10.00",
    "filled_price": "180.00",
    "filled_qty": "10.00",
    "filled_time": "2025-11-21T06:27:43.312+0000",
    "side": "BUY",
    "category": "US_STOCK",
    "order_type": "LIMIT",
    "scene_type": "FINAL_FILLED",
    "biz_type":"TRADE"
    }
}

{
"id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",    
"event_type": "TRADE",    
"timestamp": "2025-03-29T07:02:33.200962333Z",    
"payload": {
    "request_id": "1045474643156140032",
    "account_id": "4MHSOMIJ88O7E80VBG0O4G6E9A",
    "order_id": "036LVV5P4I8BV0KHKN60000000",
    "client_order_id": "de2868b71c154bcaafd2baca61127966",
    "instrument_id": "913256135",
    "order_status": "FAILED",
    "symbol": "AAPL",
    "qty": "10.00",
    "side": "BUY",
    "category": "US_STOCK",
    "order_type": "LIMIT",
    "scene_type": "PLACE_FAILED",
    "biz_type":"TRADE"
    }
}

{
"id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",    
"event_type": "TRADE",      
"timestamp": "2025-03-29T07:02:33.200962333Z",    
"payload": {
    "account_id": "PHIUK08VAKH7EOVG85ULCAG3JB",
    "request_id": "036LVV5P4I8BV0KHKN60000000",
    "order_id": "036LVV5P4I8BV0KHKN60000000",
    "client_order_id": "04cda8db7ed940f6afeb26be6201ee53",
    "instrument_id": "913256135",
    "order_status": "SUBMITTED",
    "symbol": "AAPL",
    "qty": "4.0000000000",
    "filled_price": "0E-10",
    "filled_qty": "0E-10",
    "side": "BUY",
    "category": "US_STOCK",
    "order_type": "LIMIT",
    "scene_type": "MODIFY_SUCCESS",
    "biz_type":"TRADE"
}
}

{
"id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",    
"event_type": "TRADE",    
"timestamp": "2025-03-29T07:02:33.200962333Z",    
"payload": {
    "account_id": "PHIUK08VAKH7EOVG85ULCAG3JB",
    "request_id": "036LVV5P4I8BV0KHKN60000000",
    "order_id": "036LVV5P4I8BV0KHKN60000000",
    "client_order_id": "04cda8db7ed940f6afeb26be6201ee53",
    "instrument_id": "913256135",
    "order_status": "SUBMITTED",
    "symbol": "AAPL",
    "qty": "4.0000000000",
    "filled_price": "0E-10",
    "filled_qty": "0E-10",
    "side": "BUY",
    "category": "US_STOCK",
    "order_type": "LIMIT",
    "scene_type": "MODIFY_FAILED",
    "biz_type":"TRADE"
}
}

{
"id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",    
"event_type": "TRADE",      
"timestamp": "2025-03-29T07:02:33.200962333Z",    
"payload": {
    "account_id": "PHIUK08VAKH7EOVG85ULCAG3JB",
    "request_id": "036LVV5P4I8BV0KHKN60000000",
    "order_id": "036LVV5P4I8BV0KHKN60000000",
    "client_order_id": "04cda8db7ed940f6afeb26be6201ee53",
    "instrument_id": "913256135",
    "order_status": "CANCELLED",
    "symbol": "AAPL",
    "qty": "4.0000000000",
    "filled_price": "0E-10",
    "filled_qty": "0E-10",
    "side": "BUY",
    "category": "US_STOCK",
    "order_type": "LIMIT",
    "scene_type": "CANCEL_SUCCESS",
    "biz_type":"TRADE"
}
}

{
"id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",    
"event_type": "TRADE",      
"timestamp": "2025-03-29T07:02:33.200962333Z",    
"payload": {
    "account_id": "PHIUK08VAKH7EOVG85ULCAG3JB",
    "request_id": "036LVV5P4I8BV0KHKN60000000",
    "order_id": "036LVV5P4I8BV0KHKN60000000",
    "client_order_id": "04cda8db7ed940f6afeb26be6201ee53",
    "instrument_id": "913256135",
    "order_status": "SUBMITTED",
    "symbol": "AAPL",
    "qty": "4.0000000000",
    "filled_price": "0E-10",
    "filled_qty": "0E-10",
    "side": "BUY",
    "category": "US_STOCK",
    "order_type": "LIMIT",
    "scene_type": "CANCEL_FAILED",
    "biz_type":"TRADE"
}
}

Response Fields

Field	Type	Description
id	string	Unique event identifier
event_type	string	Event type, fixed as TRADE
timestamp	string	Event timestamp in ISO 8601 format
payload	object	Event payload data

Payload Fields

Field	Type	Description
account_id	string	Account id
request_id	string	Request Id
order_id	string	System-generated order identifier.
client_order_id	array	Client-defined order identifier.
instrument_id	string	Instrument Id
order_status	string	Order Status, See the status field in the Order Detail API response.
symbol	string	Trading symbol of the financial instrument.Represents the unique identifier of the security in the specified market.
qty	string	Total order quantity. Represents the total number of units submitted for this order.
filled_qty	string	Quantity that has been executed. Represents the number of units that have been filled so far.
filled_price	string	Average transaction price of the filled quantity. If the order has not been executed yet, this may be zero or null.
filled_time	string	Time of the last executed trade. Example: 2025-11-21T06:27:43.312+0000
side	string	Order Side, See the side field in the Order Detail API response.
category	string	Category, HK_STOCK or US_STOCK .
order_type	string	Order Type, See the order_type field in the Order Detail API response.
scene_type	string	Indicates the order event scenario or execution result.
biz_type	string	Business type, fixed as TRADE

Scene Types

scene_type	Description
FILLED	Partially filled
FINAL_FILLED	All filled
PLACE_FAILED	Order failed
MODIFY_SUCCESS	Change order successfully
MODIFY_FAILED	Change order failed
CANCEL_SUCCESS	Cancellation succeeded
CANCEL_FAILED	Cancellation failed

Funding Events

Reference: broker-funding-events.md

SDK: —

Note: gRPC subscription.

To enable third-party systems to promptly obtain the execution results of foreign exchange and deposit/withdrawal operations, Broker OpenAPI provides an asynchronous proactive event push mechanism for FX conversion and deposit/withdrawal transaction events.

Clients can subscribe to receive relevant events, allowing them to monitor transaction processing results and status changes in real time.

Instant Funding

Instant Funding Event Notification

{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "FUNDING",
    "timestamp": "2025-03-29T07:02:33.200962333Z",
    "payload": {
        "account_id": "93IUJ28O9VO2KBGHDHR4H9",
        "client_request_id": "LJIS16BACHQG9LPP44L9IQHGAB",
        "instant_funding_id": "89JGKD4LKIVI5UU6L3KHNU10IA",
        "amount": "100",
        "currency": "HKD",
        "type": "DEPOSIT",
        "status": "CANCELED",
        "reason": "xxxxxx",
        "biz_type": "INSTANT_FUNDING"
    }
}

{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "FUNDING",
    "timestamp": "2025-03-29T07:02:33.200962333Z",
    "payload": {
        "account_id": "93IUJ28O9VO2KBGHDHR4H9",
        "client_request_id": "LJIS16BACHQG9LPP44L9IQHGAB",
        "instant_funding_id": "89JGKD4LKIVI5UU6L3KHNU10IA",
        "amount": "100",
        "currency": "HKD",
        "type": "DEPOSIT",
        "status": "REJECTED",
        "reason": "xxxxxx",
        "biz_type": "INSTANT_FUNDING"
    }
}

{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "FUNDING",
    "timestamp": "2025-03-29T07:02:33.200962333Z",
    "payload": {
        "account_id": "93IUJ28O9VO2KBGHDHR4H9",
        "client_request_id": "LJIS16BACHQG9LPP44L9IQHGAB",
        "instant_funding_id": "89JGKD4LKIVI5UU6L3KHNU10IA",
        "amount": "100",
        "currency": "HKD",
        "type": "DEPOSIT",
        "status": "FAILED",
        "reason": "xxxxxx",
        "biz_type": "INSTANT_FUNDING"
    }
}

{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "FUNDING",
    "timestamp": "2025-03-29T07:02:33.200962333Z",
    "payload": {
        "account_id": "93IUJ28O9VO2KBGHDHR4H9",
        "client_request_id": "LJIS16BACHQG9LPP44L9IQHGAB",
        "instant_funding_id": "89JGKD4LKIVI5UU6L3KHNU10IA",
        "amount": "100",
        "currency": "HKD",
        "type": "DEPOSIT",
        "status": "COMPLETED",
        "biz_type": "INSTANT_FUNDING"
    }
}

Response Fields

Field	Type	Description
id	string	Unique event identifier
event_type	string	Event type, fixed as FUNDING
timestamp	string	Event timestamp in ISO 8601 format
payload	object	Event payload data

Payload Fields

Field	Type	Description
account_id	string	Account id
client_request_id	string	Client Request ID, unique for each request.
instant_funding_id	string	Request id generated by the system.
amount	string	Amount.
currency	string	Currency, See the currency field in the Get Instant Funding Detail API response.
type	string	Instant Funding Request Type, See the type field in the Get Instant Funding Detail API response.
status	string	Request status, See the status field in the Get Instant Funding Detail API response.
reason	string	Reason. If the terminal state is not “COMPLETED”, return the reason.
biz_type	string	Business type, fixed as INSTANT_FUNDING

Instant Exchange

Instant Exchange Event Notification

{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "FUNDING",
    "timestamp": "2025-03-29T07:02:33.200962333Z",
    "payload": {
        "account_id": "93IUJ28O9VO2KBGHDHR4H9",
        "client_request_id": "LJIS16BACHQG9LPP44L9IQHGAB",
        "instant_exchange_id": "89JGKD4LKIVI5UU6L3KHNU10IA",
        "from_amount": "100",
        "to_amount": "700",
        "from_currency": "USD",
        "to_currency": "HKD",
        "status": "CANCELED",
        "reason": "xxxxxx",
        "biz_type": "INSTANT_EXCHANGE"
    }
}

{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "FUNDING",
    "timestamp": "2025-03-29T07:02:33.200962333Z",
    "payload": {
        "account_id": "93IUJ28O9VO2KBGHDHR4H9",
        "client_request_id": "LJIS16BACHQG9LPP44L9IQHGAB",
        "instant_exchange_id": "89JGKD4LKIVI5UU6L3KHNU10IA",
        "from_amount": "100",
        "to_amount": "700",
        "from_currency": "USD",
        "to_currency": "HKD",
        "status": "REJECTED",
        "reason": "xxxxxx",
        "biz_type": "INSTANT_EXCHANGE"
    }
}

{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "FUNDING",
    "timestamp": "2025-03-29T07:02:33.200962333Z",
    "payload": {
        "account_id": "93IUJ28O9VO2KBGHDHR4H9",
        "client_request_id": "LJIS16BACHQG9LPP44L9IQHGAB",
        "instant_exchange_id": "89JGKD4LKIVI5UU6L3KHNU10IA",
        "from_amount": "100",
        "to_amount": "700",
        "from_currency": "USD",
        "to_currency": "HKD",
        "status": "FAILED",
        "reason": "xxxxxx",
        "biz_type": "INSTANT_EXCHANGE"
    }
}

{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "FUNDING",
    "timestamp": "2025-03-29T07:02:33.200962333Z",
    "payload": {
        "account_id": "93IUJ28O9VO2KBGHDHR4H9",
        "client_request_id": "LJIS16BACHQG9LPP44L9IQHGAB",
        "instant_exchange_id": "89JGKD4LKIVI5UU6L3KHNU10IA",
        "from_amount": "100",
        "to_amount": "700",
        "from_currency": "USD",
        "to_currency": "HKD",
        "status": "COMPLETED",
        "biz_type": "INSTANT_EXCHANGE"
    }
}

Response Fields

Field	Type	Description
id	string	Unique event identifier
event_type	string	Event type, fixed as FUNDING
timestamp	string	Event timestamp in ISO 8601 format
payload	object	Event payload data

Payload Fields

Field	Type	Description
account_id	string	Account id
client_request_id	string	Client Request ID, unique for each request.
instant_exchange_id	string	Request id generated by the system.
from_amount	string	Base amount for exchange.
to_amount	string	Amount after exchange.
from_currency	string	Base currency for exchange., See the from_currency field in the Get Instant Exchange Detail API response.
to_currency	string	Currency after exchange. , See the to_currency field in the Get Instant Exchange Detail API response.
status	string	Request status, See the status field in the Get Instant Exchange Detail API response.
reason	string	Reason. If the terminal state is not “COMPLETED”, return the reason.
biz_type	string	Business type, fixed as INSTANT_EXCHANGE

Exchange

Foreign Exchange Conversion Event Notification

{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "FUNDING",
    "timestamp": "2025-03-29T07:02:33.200962333Z",
    "payload": {
        "account_id": "93IUJ28O9VO2KBGHDHR4H9",
        "client_request_id": "LJIS16BACHQG9LPP44L9IQHGAB",
        "fx_id": "89JGKD4LKIVI5UU6L3KHNU10IA",
        "from_amount": "100",
        "from_currency": "USD",
        "to_currency": "HKD",
        "status": "CANCELED",
        "reason": "xxxxxx",
        "biz_type": "EXCHANGE"
    }
}

{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "FUNDING",
    "timestamp": "2025-03-29T07:02:33.200962333Z",
    "payload": {
        "account_id": "93IUJ28O9VO2KBGHDHR4H9",
        "client_request_id": "LJIS16BACHQG9LPP44L9IQHGAB",
        "fx_id": "89JGKD4LKIVI5UU6L3KHNU10IA",
        "from_amount": "100",
        "from_currency": "USD",
        "to_currency": "HKD",
        "status": "REJECTED",
        "reason": "xxxxxx",
        "biz_type": "EXCHANGE"
    }
}

{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "FUNDING",
    "timestamp": "2025-03-29T07:02:33.200962333Z",
    "payload": {
        "account_id": "93IUJ28O9VO2KBGHDHR4H9",
        "client_request_id": "LJIS16BACHQG9LPP44L9IQHGAB",
        "fx_id": "89JGKD4LKIVI5UU6L3KHNU10IA",
        "from_amount": "100",
        "from_currency": "USD",
        "to_currency": "HKD",
        "status": "FAILED",
        "reason": "xxxxxx",
        "biz_type": "EXCHANGE"
    }
}

{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "FUNDING",
    "timestamp": "2025-03-29T07:02:33.200962333Z",
    "payload": {
        "account_id": "93IUJ28O9VO2KBGHDHR4H9",
        "client_request_id": "LJIS16BACHQG9LPP44L9IQHGAB",
        "fx_id": "89JGKD4LKIVI5UU6L3KHNU10IA",
        "from_amount": "100",
        "to_amount": "801",
        "from_currency": "USD",
        "to_currency": "HKD",
        "fx_rate": "8.01",
        "status": "COMPLETED",
        "biz_type": "EXCHANGE"
    }
}

Response Fields

Field	Type	Description
id	string	Unique event identifier
event_type	string	Event type, fixed as FUNDING
timestamp	string	Event timestamp in ISO 8601 format
payload	object	Event payload data

Payload Fields

Field	Type	Description
account_id	string	Account id
client_request_id	string	Client Request ID, unique for each request.
fx_id	string	Request id generated by the system.
from_amount	string	Base amount for exchange.
to_amount	string	Amount after exchange.
from_currency	string	Base currency for exchange., See the from_currency field in the Get FX Detail API response.
to_currency	string	Currency after exchange. , See the to_currency field in the Get FX Detail API response.
fx_rate	string	FX ratre.
status	string	Request status, See the status field in the Get FX Detail API response.
reason	string	Reason. If the terminal state is not “COMPLETED”, return the reason.
biz_type	string	Business type, fixed as EXCHANGE

Journal Events

Reference: broker-journal-events.md

SDK: —

Note: gRPC subscription.

To enable third-party systems to promptly obtain the results of journal transfers (cash / position), Broker OpenAPI supports an asynchronous event push mechanism for journal transfer–related operations (cash / position).

When the status of a journal transfer operation (cash / position) changes, the system will deliver event notifications, and subscribed clients will receive the final or intermediate execution results.

Cash Journal

Cash Journal Event Notification

{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "JOURNAL",
    "timestamp": "2025-03-29T07:02:33.200962333Z",
    "payload": {
        "from_account": "93IUJ28O9VO2KBGHDHR4H9",
        "to_account": "41IO9QG4M5O65B0EA4LSJ4UJ99",
        "client_request_id": "LJIS16BACHQG9LPP44L9IQHGAB",
        "journal_id": "89JGKD4LKIVI5UU6L3KHNU10IA",
        "journal_type": "CASH",
        "amount": "100",
        "currency": "USD",
        "status": "CANCELED",
        "reason": "xxxxxx",
        "biz_type": "CASH_JOURNAL"
    }
}

{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "JOURNAL",
    "timestamp": "2025-03-29T07:02:33.200962333Z",
    "payload": {
        "from_account": "93IUJ28O9VO2KBGHDHR4H9",
        "to_account": "41IO9QG4M5O65B0EA4LSJ4UJ99",
        "client_request_id": "LJIS16BACHQG9LPP44L9IQHGAB",
        "journal_id": "89JGKD4LKIVI5UU6L3KHNU10IA",
        "journal_type": "CASH",
        "amount": "100",
        "currency": "USD",
        "status": "REJECTED",
        "reason": "xxxxxx",
        "biz_type": "CASH_JOURNAL"
    }
}

{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "JOURNAL",
    "timestamp": "2025-03-29T07:02:33.200962333Z",
    "payload": {
        "from_account": "93IUJ28O9VO2KBGHDHR4H9",
        "to_account": "41IO9QG4M5O65B0EA4LSJ4UJ99",
        "client_request_id": "LJIS16BACHQG9LPP44L9IQHGAB",
        "journal_id": "89JGKD4LKIVI5UU6L3KHNU10IA",
        "journal_type": "CASH",
        "amount": "100",
        "currency": "USD",
        "status": "FAILED",
        "reason": "xxxxxx",
        "biz_type": "CASH_JOURNAL"
    }
}

{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "JOURNAL",
    "timestamp": "2025-03-29T07:02:33.200962333Z",
    "payload": {
        "from_account": "93IUJ28O9VO2KBGHDHR4H9",
        "to_account": "41IO9QG4M5O65B0EA4LSJ4UJ99",
        "client_request_id": "LJIS16BACHQG9LPP44L9IQHGAB",
        "journal_id": "89JGKD4LKIVI5UU6L3KHNU10IA",
        "journal_type": "CASH",
        "amount": "100",
        "currency": "USD",
        "status": "COMPLETED",
        "biz_type": "CASH_JOURNAL"
    }
}

Response Fields

Field	Type	Description
id	string	Unique event identifier
event_type	string	Event type, fixed as JOURNAL
timestamp	string	Event timestamp in ISO 8601 format
payload	object	Event payload data

Payload Fields

Field	Type	Description
from_account	string	From account id.
to_account	string	To account id.
client_request_id	string	Client Request ID, unique for each request.
journal_id	string	Request id generated by the system.
journal_type	string	Journal type, fixed as CASH
amount	string	Amount
currency	string	Currency, See the currency field in the Query Cash Journal Detail API response.
status	string	Request status, See the status field in the Query Cash Journal Detail API response.
reason	string	Reason. If the terminal state is not “COMPLETED”, return the reason.
biz_type	string	Business type, fixed as CASH_JOURNAL

Position Journal

Position Journal Event Notification

{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "JOURNAL",
    "timestamp": "2025-03-29T07:02:33.200962333Z",
    "payload": {
        "from_account": "93IUJ28O9VO2KBGHDHR4H9",
        "to_account": "41IO9QG4M5O65B0EA4LSJ4UJ99",
        "client_request_id": "LJIS16BACHQG9LPP44L9IQHGAB",
        "journal_id": "89JGKD4LKIVI5UU6L3KHNU10IA",
        "journal_type": "POSITION",
        "instrument_type": "EQUITY",
        "market": "US",
        "symbol": "BULL",
        "quantity": "100",
        "status": "CANCELED",
        "reason": "xxxxxx",
        "biz_type": "POSITION_JOURNAL"
    }
}

{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "JOURNAL",
    "timestamp": "2025-03-29T07:02:33.200962333Z",
    "payload": {
        "from_account": "93IUJ28O9VO2KBGHDHR4H9",
        "to_account": "41IO9QG4M5O65B0EA4LSJ4UJ99",
        "client_request_id": "LJIS16BACHQG9LPP44L9IQHGAB",
        "journal_id": "89JGKD4LKIVI5UU6L3KHNU10IA",
        "journal_type": "POSITION",
        "instrument_type": "EQUITY",
        "market": "US",
        "symbol": "BULL",
        "quantity": "100",
        "status": "REJECTED",
        "reason": "xxxxxx",
        "biz_type": "POSITION_JOURNAL"
    }
}

{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "JOURNAL",
    "timestamp": "2025-03-29T07:02:33.200962333Z",
    "payload": {
        "from_account": "93IUJ28O9VO2KBGHDHR4H9",
        "to_account": "41IO9QG4M5O65B0EA4LSJ4UJ99",
        "client_request_id": "LJIS16BACHQG9LPP44L9IQHGAB",
        "journal_id": "89JGKD4LKIVI5UU6L3KHNU10IA",
        "journal_type": "POSITION",
        "instrument_type": "EQUITY",
        "market": "US",
        "symbol": "BULL",
        "quantity": "100",
        "status": "FAILED",
        "reason": "xxxxxx",
        "biz_type": "POSITION_JOURNAL"
    }
}

{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "JOURNAL",
    "timestamp": "2025-03-29T07:02:33.200962333Z",
    "payload": {
        "from_account": "93IUJ28O9VO2KBGHDHR4H9",
        "to_account": "41IO9QG4M5O65B0EA4LSJ4UJ99",
        "client_request_id": "LJIS16BACHQG9LPP44L9IQHGAB",
        "journal_id": "89JGKD4LKIVI5UU6L3KHNU10IA",
        "journal_type": "POSITION",
        "instrument_type": "EQUITY",
        "market": "US",
        "symbol": "BULL",
        "quantity": "100",
        "status": "COMPLETED",
        "biz_type": "POSITION_JOURNAL"
    }
}

Response Fields

Field	Type	Description
id	string	Unique event identifier
event_type	string	Event type, fixed as JOURNAL
timestamp	string	Event timestamp in ISO 8601 format
payload	object	Event payload data

Payload Fields

Field	Type	Description
from_account	string	From account id.
to_account	string	To account id.
client_request_id	string	Client Request ID, unique for each request.
journal_id	string	Request id generated by the system.
journal_type	string	Journal type, fixed as POSITION
market	string	Market code indicating the trading venue or regulatory region of the financial instrument. See the market field in the Query Position Journal Detail API response.
instrument_type	string	Type of financial instrument associated with the request. See the instrument_type field in the Query Position Journal Detail API response.
symbol	string	Symbol name.
quantity	string	Quantity
status	string	Request status, See the status field in the Query Position Journal Detail API response.
reason	string	Reason. If the terminal state is not “COMPLETED”, return the reason.
biz_type	string	Business type, fixed as POSITION_JOURNAL

Master Data Events

Reference: broker-master-data-events.md

SDK: —

Note: gRPC subscription.

Trade Calendar

To enable third-party systems to promptly obtain updates on changes to the trading and settlement calendar, Broker OpenAPI provides an asynchronous proactive event push mechanism for trading and settlement calendar events.

Clients can subscribe to receive these events, allowing them to monitor adjustments to trading days and settlement dates in real time, ensuring accurate time calculations in trading and fund management systems.

{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "MASTER_DATA",
    "timestamp": "2025-03-29T07:02:33.200962333Z",
    "payload": {
        "request_id": "036LVV5P4I8BV0KHKN60000000",
        "market": "HK",
        "instrument_type": "EQUITY",
        "year": 2026,
        "biz_type": "CALENDAR_UPDATE"
    }
}

Response Fields

Field	Type	Description
id	string	Unique event identifier
event_type	string	Event type, fixed as MASTER_DATA
timestamp	string	Event timestamp in ISO 8601 format
payload	object	Event payload data

Payload Fields

Field	Type	Description
request_id	string	Request Id.
market	string	See the market field in the Query Trade Calendar API request for details.
instrument_type	string	See the instrument_type field in the Query Trade Calendar API request for details.
year	string	Year in YYYY format.
biz_type	string	Business type, fixed as CALENDAR_UPDATE