import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# 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](../sdk.md))
- App Key and App Secret ([Trading API Application](../authentication/TradingAPIApplication.md))
- A valid access token with `NORMAL` status ([Token](../authentication/token.md))

## Step 1: Retrieve Your Account List

Before placing any orders, you need your Account ID.

<Tabs groupId="programming-language">
  <TabItem value="python" label="Python" default>

```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())
```

  </TabItem>
  <TabItem value="java" label="Java">

```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());
```

  </TabItem>
</Tabs>

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

:::tip 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

<Tabs groupId="programming-language">
  <TabItem value="python" label="Python" default>

```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())
```

  </TabItem>
  <TabItem value="java" label="Java">

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

  </TabItem>
</Tabs>

## Step 3: Place a Stock Order

Place a simple limit order to buy 100 shares:

<Tabs groupId="programming-language">
  <TabItem value="python" label="Python" default>

```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())
```

  </TabItem>
  <TabItem value="java" label="Java">

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

  </TabItem>
</Tabs>

## Step 4: Subscribe to Order Status Updates

Monitor order status changes in real time via gRPC streaming:

<Tabs groupId="programming-language">
  <TabItem value="python" label="Python" default>

```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>"])
```

  </TabItem>
  <TabItem value="java" label="Java">

```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();
```

  </TabItem>
</Tabs>

:::tip
- Production gRPC: `events-api.webull.hk`
- Sandbox gRPC: `events-api.sandbox.webull.hk`
:::

## What's Next

- [Accounts](account.md) — Query balances and positions
- [Stock Trading](stock.md) — Stock and ETF order management
- [Options](options.md) — Options trading
- [Trading API FAQ](faq.md) — Common questions and troubleshooting