Skip to main content

Getting Started

This guide walks you through a complete onboarding flow: authenticate, open an account, fund it, place a trade, and subscribe to events.

  • UAT vs Production: base URLs, environments, and SDK entry points

please refer to the SDKs and Tools

  • Authentication & Signature: how to generate signatures and required headers

please refer to the Signature

  • Events Guide: how to connect and consume streaming events (gRPC)

please refer to the Event Subscription Demo zip file subscribe_demo.zip

0. Set up Broker API​

Generate API Keys and Signature​

Each API call requires authentication using the App Key and a signature generated using the secret key. Include them in request headers:

  • x-app-key
  • x-signature

Your Webull Account Relationship Manager will apply for the App Key and Secret and send them to your email.

For the signature algorithm, canonicalization rules, and header requirements, see: Signature

Confirm UAT vs Production settings​

Before testing requests, confirm you are using the correct base URL and environment configuration:

please refer to the SDKs and Tools

Make your first request​

A good first call is:

GET /openapi/broker/master-data/enums

This endpoint requires only the mandatory data_type field and returns all available values for that data_type.

Example response when data_type = INVESTMENT_EXPERIENCE:

[
  { "id": "1", "code": "NONE", "name": "0", "parent_code": null },
  { "id": "2", "code": "GENERAL", "name": "1–3 years", "parent_code": null },
  { "id": "3", "code": "LONG", "name": "4+ years", "parent_code": null }
]

1. Account Opening​

The first critical step is creating an account for your end customer. Required forms vary by account type.

Steps

  1. Retrieve all available forms: GET /openapi/broker/form/list
  2. Select required forms by account type:
    • Brokerage Account: NEW_ACCOUNT_BASIC_FORM and BROKERAGE_ADDITIONAL_FORM
    • Event Contract Account: NEW_ACCOUNT_BASIC_FORM and EVENT_CONTRACT_ADDITIONAL_FORM
  3. Retrieve form versions and required fields:
    • GET /openapi/broker/form/version/list
    • GET /openapi/broker/form/detail
  4. Assemble the forms and submit: POST /openapi/broker/account/create

2. Funding​

To use wire transfers, you must first establish a wire relationship.

Wire deposits are not supported at this time. Wire withdrawals are supported.

Endpoint: POST /openapi/broker/funding/bank-relationship/create

Create ACH Relationship (Plaid)​

To fund an account via ACH, you must establish an ACH relationship.

Webull integrates with Plaid to provide a streamlined ACH funding experience using Plaid tokens.

Endpoint: POST /openapi/broker/funding/ach-relationship/create

Initiate Transfer​

Initiate ACH Transfer​

Once the ACH relationship is established:

POST /openapi/broker/funding/transfer/create

direction can be:

  • DEPOSIT
  • WITHDRAWAL

Initiate Wire Transfer​

Once the bank relationship is established:

POST /openapi/broker/funding/transfer/create

direction can be:

  • WITHDRAWAL

3. Journal between Accounts​

To transfer funds between accounts owned by the same end customer (for example, brokerage to event contract):

POST /openapi/broker/journal/cash/create

4. Trading​

To place an order:

POST /openapi/broker/trade/order/place

5. Events​

Events use a persistent server-streaming connection based on gRPC, intended for real-time status updates across account opening, funding, journals, and trading.

For implementation details (subscription mechanics, payload formats, and client examples), see the Event Subscription Demo zip file: subscribe_demo.zip

Event types you can subscribe to​

Event TypeDescription
Application EventsStatus changes during the application process.
Account EventsUpdates regarding account changes, status, or configurations.
Funding EventsInformation on deposits, withdrawals, and ACH/wire transactions.
Journal EventsStatus changes of journals.
Master Data EventsChanges to reference data such as trade calendar.
Instrument EventsUpdates on instruments, such as changes to their basic attributes or properties.
Trade EventsNotifications about executed trades, fills, or order status updates.
Corporate Actions EventsEvents like dividends, splits, mergers, or spin-offs affecting securities.
Event Contract EventsUpdates related to event contract settlement.
SOD EventsNotifications that statement files or data are ready and available.

What’s next​

  • Browse the API reference for endpoint details and schemas.

  • Use the Events Guide to ensure your integration correctly tracks async operations.

  • Confirm environment switching rules before going production:

    https://developer.webull.com/apis/docs/sdk