Trading API Getting Started

This guide walks you through making your first trade using the Webull SDK. By the end, you'll have queried your account list, checked balances, and placed an order.

Prerequisites

• Webull SDK installed (SDKs and Tools)
• App Key and App Secret (Trading API Application)
• A valid access token with NORMAL status (Token)

Step 1: Retrieve Your Account List

Before placing any orders, you need your Account ID.

Python

from webull.core.client import ApiClient
from webull.trade.trade_client import TradeClient

api_client = ApiClient("<your_app_key>", "<your_app_secret>", "hk")
api_client.add_endpoint("hk", "<api_endpoint>")

trade_client = TradeClient(api_client)
res = trade_client.get_account_list()
if res.status_code == 200:
    print("Accounts:", res.json())

Java

import com.webull.openapi.core.http.HttpApiConfig;
import com.webull.openapi.trade.TradeClient;

HttpApiConfig config = HttpApiConfig.builder()
        .appKey("<your_app_key>")
        .appSecret("<your_app_secret>")
        .regionId("hk")
        .endpoint("<api_endpoint>")
        .build();

TradeClient client = new TradeClient(config);
System.out.println("Accounts: " + client.getAccountList());

Save the account_id from the response — you'll need it for all subsequent calls.

API Endpoints

• Trading API PROD: api.webull.hk
• Broker API PROD: broker-api-event-push.webull.hk
• Sandbox: api.sandbox.webull.hk

Step 2: Query Account Balance

Python

account_id = "<your_account_id>"
res = trade_client.get_account_balance(account_id=account_id)
if res.status_code == 200:
    print("Balance:", res.json())

Java

String accountId = "<your_account_id>";
Object balance = client.getAccountBalance(accountId);
System.out.println("Balance: " + balance);

Step 3: Place a Stock Order

Place a simple limit order to buy 100 shares:

Python

order_params = {
    "account_id": "<your_account_id>",
    "instrument_id": "<instrument_id>",
    "side": "BUY",
    "order_type": "LIMIT",
    "quantity": "100",
    "price": "150.00",
    "time_in_force": "DAY"
}

res = trade_client.place_order(**order_params)
if res.status_code == 200:
    print("Order placed:", res.json())

Java

Object order = client.placeOrder(
        "<your_account_id>",
        "<instrument_id>",
        "BUY",
        "LIMIT",
        "100",
        "150.00",
        "DAY"
);
System.out.println("Order placed: " + order);

Step 4: Subscribe to Order Status Updates

Monitor order status changes in real time via gRPC streaming:

Python

from webull.trade.events.types import ORDER_STATUS_CHANGED, EVENT_TYPE_ORDER
from webull.trade.trade_events_client import TradeEventsClient

def on_event(event_type, subscribe_type, payload, raw_message):
    if EVENT_TYPE_ORDER == event_type and ORDER_STATUS_CHANGED == subscribe_type:
        print("Order update:", payload)

events_client = TradeEventsClient("<your_app_key>", "<your_app_secret>", "hk")
events_client.on_events_message = on_event
events_client.do_subscribe(["<your_account_id>"])

Java

import com.webull.openapi.trade.events.subscribe.*;
import com.webull.openapi.trade.events.subscribe.message.*;

ITradeEventClient eventClient = ITradeEventClient.builder()
        .appKey("<your_app_key>")
        .appSecret("<your_app_secret>")
        .regionId("hk")
        .onMessage(response -> {
            System.out.println("Order update: " + response.getPayload());
        })
        .build();

SubscribeRequest request = new SubscribeRequest("<your_account_id>");
ISubscription subscription = eventClient.subscribe(request);
subscription.blockingAwait();

tip

• Production gRPC: events-api.webull.hk
• Sandbox gRPC: events-api.sandbox.webull.hk

What's Next

• Accounts — Query balances and positions
• Stock Trading — Stock and ETF order management
• Options — Options trading
• Trading API FAQ — Common questions and troubleshooting