Webull Openapi

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
• Accounts: List accounts, check balances, view positions
• Instruments: Look up stock, crypto, futures, and event contract instruments; get company profile, analyst ratings, and target prices
• 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:

1. 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

1. Explicitly ask the user to confirm (e.g., "Confirm this order? [Yes/No]")
2. 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 (write JSON to a temp file first) over --order-json ''. 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 

# 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  --order-file /tmp/order.json

# Cancel an order
webull-skill trading --action cancel --account-id  --client-order-id 

CLI Entry Point

webull-skill [--env-file PATH] [--verbose-sdk-log]  --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](references/skill_trading.md).

market-data

Real-time and historical market data for all asset classes (stock, futures, crypto, event contracts), plus screener, fundamentals, and watchlist.

For full action list, options, category values, and examples, see [Market Data Guide](references/skillmarketdata.md).

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=
WEBULL_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):

1. $WEBULL_CONFIG_DIR/.env — if WEBULL_CONFIG_DIR is set
2. /.env — default (sibling of webull_skill/)
3. 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 | /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 | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | | Algo orders | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | | Trailing stop loss | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | | Fractional shares | ✓ (US market) | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | | Company profile | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | | Analyst rating / target price | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | | NOII bars / snapshot | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | | Screener (gainers/losers/active) | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | | Screener (stock-market-sectors/stock-market-sectors-detail/stock-high-dividend/stock-52-week-high-low) | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | | 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](references/skill_trading.md) — Full order JSON formats, replace rules, order types, trading sessions
• [Market Data Guide](references/skillmarketdata.md) — All market data actions, screener, watchlist, category values

Official API Documentation

• US: https://develop

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: webull-inc
• Source: webull-inc/webull-openapi-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.