Webull OpenAPI Skill
This skill lets you interact with Webull's trading platform through natural language. You can place orders, check market data, query account info, and manage positions — all via the official Webull Python SDK.
What You Can Do
- Trade: Place, preview, modify, and cancel orders for stocks, options, futures, crypto, and event contracts. Each asset type has dedicated actions:
- Stock/ETF →
place, preview, replace
- Option →
option-place, option-preview, option-replace, option-strategy-place
- Futures →
futures-place, futures-replace
- Crypto →
crypto-place
- Event →
event-place, event-replace
- Market Data: Get real-time snapshots, historical bars, tick data, quotes, and order flow for all asset classes (stocks, options, futures, crypto, event contracts)
- Option market data actions:
option-snapshot, option-bars, option-tick (category: US_OPTION, supports US/HK/JP)
- Accounts: List accounts, check balances, view positions
- Instruments: Look up stock, crypto, futures, option, and event contract instruments; get company profile, analyst ratings, and target prices
- Option contracts:
instrument-option-contracts (query by underlying symbol, expiry, strike, etc.)
- Screener: Top gainers/losers, most active stocks, market sectors, high dividend, and 52-week high/low
- Fundamentals: Financial statements, capital flow, industry comparison, earnings/dividend calendar, forecast EPS, and fund/ETF data
- Watchlist: Create, manage, and query watchlists and their instruments
Safety Rules
All order-mutating operations require user confirmation before execution.
Mutating actions: place, replace, cancel, batch-place, algo-place, option-place, option-replace, option-strategy-place, futures-place, futures-replace, crypto-place, event-place, event-replace.
Before executing any of these operations, the AI must:
- Display a clear summary of the operation to the user, including:
- Action type (place / replace / cancel)
- Symbol, side, order type, quantity, price
- Account being used
- Explicitly ask the user to confirm (e.g., "Confirm this order? [Yes/No]")
- Only proceed after receiving explicit user approval
Read-only operations (account-list, balance, position, open, history, detail, instrument-*, all market-data actions) do not require confirmation and can be executed immediately.
Quick Examples
CLI command: After pip install -e ., use webull-skill on all platforms (macOS, Linux, Windows). This console entry point is bound to the Python that ran pip, so it works regardless of what python3 or python points to on your system.
Passing order JSON: Prefer --order-file <path> (write JSON to a temp file first) over --order-json '<inline>'. Inline JSON with --order-json is fragile across shells — Windows bash, PowerShell, and some macOS terminals mangle quotes and escapes. Using --order-file avoids all shell quoting issues.
# Check your accounts
webull-skill trading --action account-list
# Get AAPL stock price
webull-skill market-data --action stock-snapshot --symbols AAPL
# Get account balance
webull-skill trading --action balance --account-id <id>
# Place a limit buy order (recommended: use --order-file)
# echo '{"symbol":"AAPL","side":"BUY","order_type":"LIMIT","limit_price":180,"quantity":10,"instrument_type":"EQUITY","market":"US","time_in_force":"DAY","entrust_type":"QTY","support_trading_session":"CORE","combo_type":"NORMAL"}' > /tmp/order.json
# webull-skill trading --action place --account-id <id> --order-file /tmp/order.json
# Cancel an order
webull-skill trading --action cancel --account-id <id> --client-order-id <oid>
CLI Entry Point
webull-skill [--env-file PATH] [--verbose-sdk-log] <module> --action <ACTION> [options]
Three modules: trading, market-data, auth.
Modules
trading
Instrument queries, account/asset operations, and all order operations (stock, option, futures, crypto, event contracts).
For full action list, order JSON formats, replace rules, and order type references, see Trading Guide.
market-data
Real-time and historical market data for all asset classes (stock, option, futures, crypto, event contracts), plus screener, fundamentals, and watchlist.
For full action list, options, category values, and examples, see Market Data Guide.
auth
webull-skill auth
Interactive 2FA authentication. Run once before first use. The SDK waits up to 5 minutes for you to approve in the Webull mobile app. Token is cached and auto-refreshes.
Output Format
All operations output formatted text directly to stdout, with a region-aware disclaimer at the top:
⚠️ Disclaimer: The information provided by this tool is for reference only ...
=== Stock Snapshot: AAPL ===
Symbol: AAPL
Price: 255.92
Pre Close: 255.63
Change: 0.29
...
- Success: disclaimer + formatted data to stdout, exit code 0
- Error: error message to stderr, exit code 1
- US/JP/SG/TH/MY/UK/MX/BR/EU/ZA/AU region: English disclaimer only
- HK region: English + Simplified Chinese + Traditional Chinese disclaimer
Configuration
Via .env file or environment variables. Required:
WEBULL_APP_KEY=<your_app_key>
WEBULL_APP_SECRET=<your_app_secret>
Region selection:
# Choose one region:
WEBULL_REGION_ID=us
# WEBULL_REGION_ID=hk
# WEBULL_REGION_ID=jp
# WEBULL_REGION_ID=sg
# WEBULL_REGION_ID=th
# WEBULL_REGION_ID=my
# WEBULL_REGION_ID=uk
# WEBULL_REGION_ID=mx
# WEBULL_REGION_ID=br
# WEBULL_REGION_ID=eu
# WEBULL_REGION_ID=za
# WEBULL_REGION_ID=au
# Sandbox by default; set prod only for live trading.
WEBULL_ENVIRONMENT=uat
.env lookup order (when --env-file is not specified):
$WEBULL_CONFIG_DIR/.env — if WEBULL_CONFIG_DIR is set<project_root>/.env — default (sibling of webull_skill/)- Current working directory
.env — last resort
To keep credentials outside the project directory, set WEBULL_CONFIG_DIR as a system environment variable (e.g. in ~/.zshrc), then place your .env at $WEBULL_CONFIG_DIR/.env. Setting WEBULL_CONFIG_DIR inside a .env file has no effect — it must be set before the process starts.
Optional:
| Variable |
Default |
Description |
WEBULL_ENVIRONMENT |
uat |
uat (sandbox) or prod (live) |
WEBULL_REGION_ID |
us |
us, hk, jp, sg, th, my, uk, mx, br, eu, za, or au |
WEBULL_MAX_ORDER_NOTIONAL_USD |
10000 |
Max order value (USD) |
WEBULL_MAX_ORDER_NOTIONAL_HKD |
80000 |
Max order value for HK market (HKD) |
WEBULL_MAX_ORDER_NOTIONAL_CNH |
70000 |
Max order value for CN market (CNH) |
WEBULL_MAX_ORDER_NOTIONAL_JPY |
1500000 |
Max order value for JP market (JPY) |
WEBULL_MAX_ORDER_QUANTITY |
1000 |
Max shares per order |
WEBULL_SYMBOL_WHITELIST |
(none) |
Comma-separated allowed symbols |
WEBULL_CONFIG_DIR |
(none) |
System env var only (not in .env). Moves .env lookup and token storage to this directory |
WEBULL_TOKEN_DIR |
<project_root>/conf/ |
Token storage directory |
WEBULL_AUDIT_LOG_FILE |
(stderr) |
Audit log file path |
WEBULL_LOG_LEVEL |
WARNING |
SDK log level |
Region Support
| Feature |
US |
HK |
JP |
SG |
TH |
MY |
UK |
MX |
BR |
EU |
ZA |
AU |
| Stock trading |
✓ |
✓ (US/HK/CN) |
✓ (US/JP) |
✓ (US) |
✓ (US) |
✓ (US) |
✓ (US) |
✓ (US) |
✓ (US) |
✓ (US) |
✓ (US) |
✓ (US) |
| Options |
✓ |
✓ (US only) |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
| Futures |
✓ |
✓ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
| Crypto |
✓ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
| Event contracts |
✓ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
| Combo orders |
✓ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
| Option leg in/out |
✓ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
| Algo orders |
✓ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
| Trailing stop loss |
✓ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
| Fractional shares |
✓ (US market) |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
✗ |
| Company profile |
✓ |
✓ |
✓ |
✗ |
✓ |
✓ |
✓ |
✗ |
✗ |
✗ |
✗ |
✗ |
| Analyst rating / target price |
✓ |
✓ |
✓ |
✗ |
✓ |
✓ |
✓ |
✗ |
✗ |
✗ |
✗ |
✗ |
| NOII bars / snapshot |
✓ |
✓ |
✓ |
✗ |
✓ |
✓ |
✓ |
✗ |
✗ |
✗ |
✗ |
✗ |
| Screener |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
| Watchlist |
✓ |
✓ |
✓ |
✗ |
✓ |
✓ |
✓ |
✗ |
✗ |
✗ |
✗ |
✗ |
| Fundamentals |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
HK-Specific Notes
- HK stocks use order types:
ENHANCED_LIMIT, AT_AUCTION, AT_AUCTION_LIMIT
- CN A-shares (Stock Connect):
LIMIT only, disabled by default — contact Webull to enable
- Board lot sizes vary by HK stock
- No combo orders, algo orders, crypto, or event contracts in HK region
- HK stock orders (institutional/broker): require
sender_sub_id and no_party_ids (BCAN)
- HK US options (institutional/broker): support
sender_sub_id only, no BCAN needed
JP-Specific Notes
- Configure JP with
WEBULL_REGION_ID=jp; sandbox uses WEBULL_ENVIRONMENT=uat.
- JP supports stock/ETF market data and stock order management. Futures, crypto, event contracts, options, combo orders, and algo orders are not supported in JP.
- JP stock instrument categories are
US_STOCK and US_ETF.
- JP stock order markets are
US and JP.
- JP market orders support
LIMIT and MARKET; JP market time in force is DAY.
- US market orders in JP support
LIMIT, MARKET, STOP_LOSS, STOP_LOSS_LIMIT with DAY or GTC.
- JP stock accounts are identified by
account_type: CASH or US_MARGIN.
account_tax_type is required for JP stock place and preview; valid values are GENERAL and SPECIFIC.margin_type and position_intent are valid only for JP US_MARGIN accounts (for stock orders). For US option orders, position_intent is supported via option-place.close_contracts is JP-only and accepts up to 10 objects with contract_id and positive quantity.
SG-Specific Notes
- Configure SG with
WEBULL_REGION_ID=sg; sandbox uses WEBULL_ENVIRONMENT=uat.
- SG supports US stock/ETF trading for Singapore-based clients.
- Supported order types:
MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT.
- Time in force:
DAY, GTC.
- Trading sessions:
CORE, ALL, NIGHT, ALL_DAY.
- SG order market is
US only.
- No futures, crypto, options, event contracts, combo orders, or algo orders in SG region.
TH-Specific Notes
- Configure TH with
WEBULL_REGION_ID=th; sandbox uses WEBULL_ENVIRONMENT=uat.
- TH supports US stock/ETF trading for Thailand-based clients.
- Supported order types:
MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT.
- Time in force:
DAY, GTC.
- Trading sessions:
CORE, ALL, NIGHT, ALL_DAY.
- TH order market is
US only.
- No futures, crypto, options, event contracts, combo orders, or algo orders in TH region.
MY-Specific Notes
- Configure MY with
WEBULL_REGION_ID=my; sandbox uses WEBULL_ENVIRONMENT=uat.
- MY supports US stock/ETF trading for Malaysia-based clients.
- Supported order types:
MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT.
- Time in force:
DAY, GTC.
- Trading sessions:
CORE, ALL, NIGHT, ALL_DAY.
- MY order market is
US only.
- No futures, crypto, options, event contracts, combo orders, or algo orders in MY region.
UK-Specific Notes
- Configure UK with
WEBULL_REGION_ID=uk; sandbox uses WEBULL_ENVIRONMENT=uat.
- UK supports US stock/ETF trading for UK-based clients.
- Supported order types:
MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT.
- Time in force:
DAY, GTC.
- Trading sessions:
CORE, ALL, NIGHT, ALL_DAY.
- UK order market is
US only.
- No futures, crypto, options, event contracts, combo orders, or algo orders in UK region.
MX-Specific Notes
- Configure MX with
WEBULL_REGION_ID=mx; sandbox uses WEBULL_ENVIRONMENT=uat.
- MX supports US stock/ETF trading for Mexico-based clients.
- Supported order types:
MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT.
- Time in force:
DAY, GTC.
- Trading sessions:
CORE, ALL, NIGHT, ALL_DAY.
- MX order market is
US only.
- No futures, crypto, options, event contracts, combo orders, or algo orders in MX region.
BR-Specific Notes
- Configure BR with
WEBULL_REGION_ID=br; sandbox uses WEBULL_ENVIRONMENT=uat.
- BR supports US stock/ETF trading for Brazil-based clients.
- Supported order types:
MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT.
- Time in force:
DAY, GTC.
- Trading sessions:
CORE, ALL, NIGHT, ALL_DAY.
- BR order market is
US only.
- No futures, crypto, options, event contracts, combo orders, or algo orders in BR region.
EU-Specific Notes
- Configure EU with
WEBULL_REGION_ID=eu; sandbox uses WEBULL_ENVIRONMENT=uat.
- EU supports US stock/ETF trading for EU-based clients.
- Supported order types:
MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT.
- Time in force:
DAY, GTC.
- Trading sessions:
CORE, ALL, NIGHT, ALL_DAY.
- EU order market is
US only.
- No futures, crypto, options, event contracts, combo orders, or algo orders in EU region.
ZA-Specific Notes
- Configure ZA with
WEBULL_REGION_ID=za; sandbox uses WEBULL_ENVIRONMENT=uat.
- ZA supports US stock/ETF trading for South Africa-based clients.
- Supported order types:
MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT.
- Time in force:
DAY, GTC.
- Trading sessions:
CORE, ALL, NIGHT, ALL_DAY.
- ZA order market is
US only.
- No futures, crypto, options, event contracts, combo orders, or algo orders in ZA region.
AU-Specific Notes
- Configure AU with
WEBULL_REGION_ID=au; sandbox uses WEBULL_ENVIRONMENT=uat.
- AU supports US stock/ETF trading for Australia-based clients.
- Supported order types:
MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT.
- Time in force:
DAY, GTC.
- Trading sessions:
CORE, ALL, NIGHT, ALL_DAY.
- AU order market is
US only.
- No futures, crypto, options, event contracts, combo orders, or algo orders in AU region.
Rate Limits
US Region
- Market data: 600 req/min
- Order place/replace/cancel: 600 req/min
- Order query: 2 req/2s
- Auth: 10 req/30s
HK Region
- Market data: 60 req/60s
- Order place: 15 req/s (US stocks), 1 req/s (HK/A-share)
- Order preview: 40 req/10s
- Order query: 40 req/2s
JP Region
- Instrument lookup: 60 req/min per AppId
- Other endpoint limits follow the JP developer portal for the enabled account/API plan
SG Region
- Market data: 300 req/60s
- Order place/replace/cancel: 600 req/60s
- Order query: 2 req/2s
- Auth: 10 req/30s
TH Region
- Market data: 300 req/60s
- Order place/replace/cancel: 600 req/60s
- Order query: 2 req/2s
- Auth: 10 req/30s
MY Region
- Market data: 300 req/60s
- Order place/replace/cancel: 600 req/60s
- Order query: 2 req/2s
- Auth: 10 req/30s
UK Region
- Market data: 300 req/60s
- Order place/replace/cancel: 600 req/60s
- Order query: 2 req/2s
- Auth: 10 req/30s
MX Region
- Market data: 300 req/60s
- Order place/replace/cancel: 600 req/60s
- Order query: 2 req/2s
- Auth: 10 req/30s
BR Region
- Market data: 300 req/60s
- Order place/replace/cancel: 600 req/60s
- Order query: 2 req/2s
- Auth: 10 req/30s
EU Region
- Market data: 60 req/60s
- Order place/replace/cancel: 60 req/60s
- Order query: 2 req/2s
- Auth: 10 req/30s
ZA Region
- Market data: 60 req/60s
- Order place/replace/cancel: 60 req/60s
- Order query: 2 req/2s
- Auth: 10 req/30s
AU Region
- Market data: 60 req/60s
- Order place/replace/cancel: 60 req/60s
- Order query: 2 req/2s
- Auth: 10 req/30s
Detailed Module Documentation
- Trading Guide — Full order JSON formats, replace rules, order types, trading sessions
- Market Data Guide — All market data actions, screener, watchlist, category values
Official API Documentation
Disclaimer
The information provided by this tool is for reference only and does not constitute investment advice. Trading involves risk; please make decisions carefully.
1---2name: webull-openapi3description: Trade stocks, options, futures, crypto, and event contracts on Webull. Query real-time and historical market data. Manage accounts and positions. Supports US, HK, JP, SG, TH, MY, UK, MX, BR, EU, ZA, and AU regions with configurable risk controls.4---56# Webull OpenAPI Skill78This skill lets you interact with Webull's trading platform through natural language. You can place orders, check market data, query account info, and manage positions — all via the official Webull Python SDK.910## What You Can Do1112- **Trade**: Place, preview, modify, and cancel orders for stocks, options, futures, crypto, and event contracts. Each asset type has dedicated actions:13 - Stock/ETF → `place`, `preview`, `replace`14 - Option → `option-place`, `option-preview`, `option-replace`, `option-strategy-place`15 - Futures → `futures-place`, `futures-replace`16 - Crypto → `crypto-place`17 - Event → `event-place`, `event-replace`18- **Market Data**: Get real-time snapshots, historical bars, tick data, quotes, and order flow for all asset classes (stocks, options, futures, crypto, event contracts)19 - Option market data actions: `option-snapshot`, `option-bars`, `option-tick` (category: US_OPTION, supports US/HK/JP)20- **Accounts**: List accounts, check balances, view positions21- **Instruments**: Look up stock, crypto, futures, option, and event contract instruments; get company profile, analyst ratings, and target prices22 - Option contracts: `instrument-option-contracts` (query by underlying symbol, expiry, strike, etc.)23- **Screener**: Top gainers/losers, most active stocks, market sectors, high dividend, and 52-week high/low24- **Fundamentals**: Financial statements, capital flow, industry comparison, earnings/dividend calendar, forecast EPS, and fund/ETF data25- **Watchlist**: Create, manage, and query watchlists and their instruments2627## Safety Rules2829**All order-mutating operations require user confirmation before execution.**3031Mutating actions: `place`, `replace`, `cancel`, `batch-place`, `algo-place`, `option-place`, `option-replace`, `option-strategy-place`, `futures-place`, `futures-replace`, `crypto-place`, `event-place`, `event-replace`.3233Before executing any of these operations, the AI must:341. Display a clear summary of the operation to the user, including:35 - Action type (place / replace / cancel)36 - Symbol, side, order type, quantity, price37 - Account being used382. Explicitly ask the user to confirm (e.g., "Confirm this order? [Yes/No]")393. Only proceed after receiving explicit user approval4041Read-only operations (`account-list`, `balance`, `position`, `open`, `history`, `detail`, `instrument-*`, all `market-data` actions) do not require confirmation and can be executed immediately.4243---4445## Quick Examples4647> **CLI command:** After `pip install -e .`, use `webull-skill` on all platforms (macOS, Linux, Windows). This console entry point is bound to the Python that ran `pip`, so it works regardless of what `python3` or `python` points to on your system.4849> **Passing order JSON:** Prefer `--order-file <path>` (write JSON to a temp file first) over `--order-json '<inline>'`. Inline JSON with `--order-json` is fragile across shells — Windows bash, PowerShell, and some macOS terminals mangle quotes and escapes. Using `--order-file` avoids all shell quoting issues.5051```bash52# Check your accounts53webull-skill trading --action account-list5455# Get AAPL stock price56webull-skill market-data --action stock-snapshot --symbols AAPL5758# Get account balance59webull-skill trading --action balance --account-id <id>6061# Place a limit buy order (recommended: use --order-file)62# echo '{"symbol":"AAPL","side":"BUY","order_type":"LIMIT","limit_price":180,"quantity":10,"instrument_type":"EQUITY","market":"US","time_in_force":"DAY","entrust_type":"QTY","support_trading_session":"CORE","combo_type":"NORMAL"}' > /tmp/order.json63# webull-skill trading --action place --account-id <id> --order-file /tmp/order.json6465# Cancel an order66webull-skill trading --action cancel --account-id <id> --client-order-id <oid>67```6869## CLI Entry Point7071```72webull-skill [--env-file PATH] [--verbose-sdk-log] <module> --action <ACTION> [options]73```7475Three modules: `trading`, `market-data`, `auth`.7677---7879## Modules8081### trading8283Instrument queries, account/asset operations, and all order operations (stock, option, futures, crypto, event contracts).8485For full action list, order JSON formats, replace rules, and order type references, see [Trading Guide](references/skill_trading.md).8687### market-data8889Real-time and historical market data for all asset classes (stock, option, futures, crypto, event contracts), plus screener, fundamentals, and watchlist.9091For full action list, options, category values, and examples, see [Market Data Guide](references/skill_market_data.md).9293### auth9495```bash96webull-skill auth97```9899Interactive 2FA authentication. Run once before first use. The SDK waits up to 5 minutes for you to approve in the Webull mobile app. Token is cached and auto-refreshes.100101---102103## Output Format104105All operations output formatted text directly to stdout, with a region-aware disclaimer at the top:106107```108⚠️ Disclaimer: The information provided by this tool is for reference only ...109110=== Stock Snapshot: AAPL ===111 Symbol: AAPL112 Price: 255.92113 Pre Close: 255.63114 Change: 0.29115 ...116```117118- Success: disclaimer + formatted data to stdout, exit code 0119- Error: error message to stderr, exit code 1120- US/JP/SG/TH/MY/UK/MX/BR/EU/ZA/AU region: English disclaimer only121- HK region: English + Simplified Chinese + Traditional Chinese disclaimer122123---124125## Configuration126127Via `.env` file or environment variables. Required:128129```130WEBULL_APP_KEY=<your_app_key>131WEBULL_APP_SECRET=<your_app_secret>132```133134Region selection:135136```env137# Choose one region:138WEBULL_REGION_ID=us139# WEBULL_REGION_ID=hk140# WEBULL_REGION_ID=jp141# WEBULL_REGION_ID=sg142# WEBULL_REGION_ID=th143# WEBULL_REGION_ID=my144# WEBULL_REGION_ID=uk145# WEBULL_REGION_ID=mx146# WEBULL_REGION_ID=br147# WEBULL_REGION_ID=eu148# WEBULL_REGION_ID=za149# WEBULL_REGION_ID=au150151# Sandbox by default; set prod only for live trading.152WEBULL_ENVIRONMENT=uat153```154155**`.env` lookup order** (when `--env-file` is not specified):1561. `$WEBULL_CONFIG_DIR/.env` — if `WEBULL_CONFIG_DIR` is set1572. `<project_root>/.env` — default (sibling of `webull_skill/`)1583. Current working directory `.env` — last resort159160> To keep credentials outside the project directory, set `WEBULL_CONFIG_DIR` as a **system environment variable** (e.g. in `~/.zshrc`), then place your `.env` at `$WEBULL_CONFIG_DIR/.env`. Setting `WEBULL_CONFIG_DIR` inside a `.env` file has no effect — it must be set before the process starts.161162Optional:163164| Variable | Default | Description |165|----------|---------|-------------|166| `WEBULL_ENVIRONMENT` | `uat` | `uat` (sandbox) or `prod` (live) |167| `WEBULL_REGION_ID` | `us` | `us`, `hk`, `jp`, `sg`, `th`, `my`, `uk`, `mx`, `br`, `eu`, `za`, or `au` |168| `WEBULL_MAX_ORDER_NOTIONAL_USD` | `10000` | Max order value (USD) |169| `WEBULL_MAX_ORDER_NOTIONAL_HKD` | `80000` | Max order value for HK market (HKD) |170| `WEBULL_MAX_ORDER_NOTIONAL_CNH` | `70000` | Max order value for CN market (CNH) |171| `WEBULL_MAX_ORDER_NOTIONAL_JPY` | `1500000` | Max order value for JP market (JPY) |172| `WEBULL_MAX_ORDER_QUANTITY` | `1000` | Max shares per order |173| `WEBULL_SYMBOL_WHITELIST` | (none) | Comma-separated allowed symbols |174| `WEBULL_CONFIG_DIR` | (none) | **System env var only** (not in `.env`). Moves `.env` lookup and token storage to this directory |175| `WEBULL_TOKEN_DIR` | `<project_root>/conf/` | Token storage directory |176| `WEBULL_AUDIT_LOG_FILE` | (stderr) | Audit log file path |177| `WEBULL_LOG_LEVEL` | `WARNING` | SDK log level |178179---180181## Region Support182183| Feature | US | HK | JP | SG | TH | MY | UK | MX | BR | EU | ZA | AU |184|---------|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|185| Stock trading | ✓ | ✓ (US/HK/CN) | ✓ (US/JP) | ✓ (US) | ✓ (US) | ✓ (US) | ✓ (US) | ✓ (US) | ✓ (US) | ✓ (US) | ✓ (US) | ✓ (US) |186| Options | ✓ | ✓ (US only) | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |187| Futures | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |188| Crypto | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |189| Event contracts | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |190| Combo orders | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |191| Option leg in/out | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |192| Algo orders | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |193| Trailing stop loss | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |194| Fractional shares | ✓ (US market) | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |195| Company profile | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ |196| Analyst rating / target price | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ |197| NOII bars / snapshot | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ |198| Screener | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |199| Watchlist | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ |200| Fundamentals | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |201202203### HK-Specific Notes204205- HK stocks use order types: `ENHANCED_LIMIT`, `AT_AUCTION`, `AT_AUCTION_LIMIT`206- CN A-shares (Stock Connect): `LIMIT` only, disabled by default — contact Webull to enable207- Board lot sizes vary by HK stock208- No combo orders, algo orders, crypto, or event contracts in HK region209- HK stock orders (institutional/broker): require `sender_sub_id` and `no_party_ids` (BCAN)210- HK US options (institutional/broker): support `sender_sub_id` only, no BCAN needed211212### JP-Specific Notes213214- Configure JP with `WEBULL_REGION_ID=jp`; sandbox uses `WEBULL_ENVIRONMENT=uat`.215- JP supports stock/ETF market data and stock order management. Futures, crypto, event contracts, options, combo orders, and algo orders are not supported in JP.216- JP stock instrument categories are `US_STOCK` and `US_ETF`.217- JP stock order markets are `US` and `JP`.218- JP market orders support `LIMIT` and `MARKET`; JP market time in force is `DAY`.219- US market orders in JP support `LIMIT`, `MARKET`, `STOP_LOSS`, `STOP_LOSS_LIMIT` with `DAY` or `GTC`.220- JP stock accounts are identified by `account_type`: `CASH` or `US_MARGIN`.221- `account_tax_type` is required for JP stock `place` and `preview`; valid values are `GENERAL` and `SPECIFIC`.222- `margin_type` and `position_intent` are valid only for JP `US_MARGIN` accounts (for stock orders). For US option orders, `position_intent` is supported via `option-place`.223- `close_contracts` is JP-only and accepts up to 10 objects with `contract_id` and positive `quantity`.224225### SG-Specific Notes226227- Configure SG with `WEBULL_REGION_ID=sg`; sandbox uses `WEBULL_ENVIRONMENT=uat`.228- SG supports US stock/ETF trading for Singapore-based clients.229- Supported order types: `MARKET`, `LIMIT`, `STOP_LOSS`, `STOP_LOSS_LIMIT`.230- Time in force: `DAY`, `GTC`.231- Trading sessions: `CORE`, `ALL`, `NIGHT`, `ALL_DAY`.232- SG order market is `US` only.233- No futures, crypto, options, event contracts, combo orders, or algo orders in SG region.234235### TH-Specific Notes236237- Configure TH with `WEBULL_REGION_ID=th`; sandbox uses `WEBULL_ENVIRONMENT=uat`.238- TH supports US stock/ETF trading for Thailand-based clients.239- Supported order types: `MARKET`, `LIMIT`, `STOP_LOSS`, `STOP_LOSS_LIMIT`.240- Time in force: `DAY`, `GTC`.241- Trading sessions: `CORE`, `ALL`, `NIGHT`, `ALL_DAY`.242- TH order market is `US` only.243- No futures, crypto, options, event contracts, combo orders, or algo orders in TH region.244245### MY-Specific Notes246247- Configure MY with `WEBULL_REGION_ID=my`; sandbox uses `WEBULL_ENVIRONMENT=uat`.248- MY supports US stock/ETF trading for Malaysia-based clients.249- Supported order types: `MARKET`, `LIMIT`, `STOP_LOSS`, `STOP_LOSS_LIMIT`.250- Time in force: `DAY`, `GTC`.251- Trading sessions: `CORE`, `ALL`, `NIGHT`, `ALL_DAY`.252- MY order market is `US` only.253- No futures, crypto, options, event contracts, combo orders, or algo orders in MY region.254255### UK-Specific Notes256257- Configure UK with `WEBULL_REGION_ID=uk`; sandbox uses `WEBULL_ENVIRONMENT=uat`.258- UK supports US stock/ETF trading for UK-based clients.259- Supported order types: `MARKET`, `LIMIT`, `STOP_LOSS`, `STOP_LOSS_LIMIT`.260- Time in force: `DAY`, `GTC`.261- Trading sessions: `CORE`, `ALL`, `NIGHT`, `ALL_DAY`.262- UK order market is `US` only.263- No futures, crypto, options, event contracts, combo orders, or algo orders in UK region.264265### MX-Specific Notes266267- Configure MX with `WEBULL_REGION_ID=mx`; sandbox uses `WEBULL_ENVIRONMENT=uat`.268- MX supports US stock/ETF trading for Mexico-based clients.269- Supported order types: `MARKET`, `LIMIT`, `STOP_LOSS`, `STOP_LOSS_LIMIT`.270- Time in force: `DAY`, `GTC`.271- Trading sessions: `CORE`, `ALL`, `NIGHT`, `ALL_DAY`.272- MX order market is `US` only.273- No futures, crypto, options, event contracts, combo orders, or algo orders in MX region.274275### BR-Specific Notes276277- Configure BR with `WEBULL_REGION_ID=br`; sandbox uses `WEBULL_ENVIRONMENT=uat`.278- BR supports US stock/ETF trading for Brazil-based clients.279- Supported order types: `MARKET`, `LIMIT`, `STOP_LOSS`, `STOP_LOSS_LIMIT`.280- Time in force: `DAY`, `GTC`.281- Trading sessions: `CORE`, `ALL`, `NIGHT`, `ALL_DAY`.282- BR order market is `US` only.283- No futures, crypto, options, event contracts, combo orders, or algo orders in BR region.284285### EU-Specific Notes286287- Configure EU with `WEBULL_REGION_ID=eu`; sandbox uses `WEBULL_ENVIRONMENT=uat`.288- EU supports US stock/ETF trading for EU-based clients.289- Supported order types: `MARKET`, `LIMIT`, `STOP_LOSS`, `STOP_LOSS_LIMIT`.290- Time in force: `DAY`, `GTC`.291- Trading sessions: `CORE`, `ALL`, `NIGHT`, `ALL_DAY`.292- EU order market is `US` only.293- No futures, crypto, options, event contracts, combo orders, or algo orders in EU region.294295### ZA-Specific Notes296297- Configure ZA with `WEBULL_REGION_ID=za`; sandbox uses `WEBULL_ENVIRONMENT=uat`.298- ZA supports US stock/ETF trading for South Africa-based clients.299- Supported order types: `MARKET`, `LIMIT`, `STOP_LOSS`, `STOP_LOSS_LIMIT`.300- Time in force: `DAY`, `GTC`.301- Trading sessions: `CORE`, `ALL`, `NIGHT`, `ALL_DAY`.302- ZA order market is `US` only.303- No futures, crypto, options, event contracts, combo orders, or algo orders in ZA region.304305### AU-Specific Notes306307- Configure AU with `WEBULL_REGION_ID=au`; sandbox uses `WEBULL_ENVIRONMENT=uat`.308- AU supports US stock/ETF trading for Australia-based clients.309- Supported order types: `MARKET`, `LIMIT`, `STOP_LOSS`, `STOP_LOSS_LIMIT`.310- Time in force: `DAY`, `GTC`.311- Trading sessions: `CORE`, `ALL`, `NIGHT`, `ALL_DAY`.312- AU order market is `US` only.313- No futures, crypto, options, event contracts, combo orders, or algo orders in AU region.314315---316317## Rate Limits318319### US Region320- Market data: 600 req/min321- Order place/replace/cancel: 600 req/min322- Order query: 2 req/2s323- Auth: 10 req/30s324325### HK Region326- Market data: 60 req/60s327- Order place: 15 req/s (US stocks), 1 req/s (HK/A-share)328- Order preview: 40 req/10s329- Order query: 40 req/2s330331### JP Region332- Instrument lookup: 60 req/min per AppId333- Other endpoint limits follow the JP developer portal for the enabled account/API plan334335### SG Region336- Market data: 300 req/60s337- Order place/replace/cancel: 600 req/60s338- Order query: 2 req/2s339- Auth: 10 req/30s340341### TH Region342- Market data: 300 req/60s343- Order place/replace/cancel: 600 req/60s344- Order query: 2 req/2s345- Auth: 10 req/30s346347### MY Region348- Market data: 300 req/60s349- Order place/replace/cancel: 600 req/60s350- Order query: 2 req/2s351- Auth: 10 req/30s352353### UK Region354- Market data: 300 req/60s355- Order place/replace/cancel: 600 req/60s356- Order query: 2 req/2s357- Auth: 10 req/30s358359### MX Region360- Market data: 300 req/60s361- Order place/replace/cancel: 600 req/60s362- Order query: 2 req/2s363- Auth: 10 req/30s364365### BR Region366- Market data: 300 req/60s367- Order place/replace/cancel: 600 req/60s368- Order query: 2 req/2s369- Auth: 10 req/30s370371### EU Region372- Market data: 60 req/60s373- Order place/replace/cancel: 60 req/60s374- Order query: 2 req/2s375- Auth: 10 req/30s376377### ZA Region378- Market data: 60 req/60s379- Order place/replace/cancel: 60 req/60s380- Order query: 2 req/2s381- Auth: 10 req/30s382383### AU Region384- Market data: 60 req/60s385- Order place/replace/cancel: 60 req/60s386- Order query: 2 req/2s387- Auth: 10 req/30s388389---390391## Detailed Module Documentation392393- [Trading Guide](references/skill_trading.md) — Full order JSON formats, replace rules, order types, trading sessions394- [Market Data Guide](references/skill_market_data.md) — All market data actions, screener, watchlist, category values395396## Official API Documentation397398- US: https://developer.webull.com/apis/docs/webull-open-api-reference399- HK: https://developer.webull.hk/apis/docs/webull-open-api-reference400- JP: https://developer.webull.co.jp/apis/docs/webull-open-api-reference401- SG: https://developer.webull.com.sg/apis/docs/index.md402- TH: https://developer.webull.co.th/apis/docs/403- MY: https://developer.webull.com.my/apis/docs/404- UK: https://developer.webull-uk.com/apis/docs/405- MX: https://developer.webull.com.mx/apis/docs/406- BR: https://developer.webull.com.br/apis/docs/407- EU: https://developer.webull.eu/apis/docs/408- ZA: https://developer.webull.co.za/apis/docs/409- AU: https://developer.webull.com.au/apis/docs/410411---412413## Disclaimer414415The information provided by this tool is for reference only and does not constitute investment advice. Trading involves risk; please make decisions carefully.
webull-inc