Webull CLI
Command-line trading tool for AI Agents, quant developers, and institutional clients. Coverage of Japan market: Japanese domestic stocks and US stocks traded from Japan accounts, with Japan-specific tax and margin configurations.
Source code: webull-inc/webull-openapi-cli
What is Webull CLI
Webull CLI (webull) is a single-binary Go tool that wraps the full Webull OpenAPI surface into a structured command-line interface. In the JP region, it provides access to Japanese domestic stocks and US stocks traded via Japan accounts, with mandatory Japan-specific parameters for tax account type, margin configuration, and position intent.
Architecture Overview
Prerequisites
API Credentials
- Production
- Test Environment
Apply at: Individual Application Guide
No application required. Use the publicly shared test credentials to get started immediately. See SDKs and Tools.
Other Requirements
- Go 1.21+ (for
go install) or download pre-built binary - Webull App (Japan) (if 2FA verification is required)
- Market Data Subscription (for JP real-time quotes): Subscription Guide
Setup Steps
Step 1: Install Go Environment
Check if Go is already installed:
go version
If not installed or version is below 1.21, install Go:
# macOS (Homebrew)
brew install go
# Linux
wget https://go.dev/dl/go1.22.5.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.22.5.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin
# Windows — download installer from https://go.dev/dl/
Verify Go installation:
go version
# Expected: go version go1.21+ or higher
Step 2: Install Webull CLI
go install github.com/webull-inc/webull-openapi-cli/cmd/webull@latest
Or download pre-built binary from GitHub Releases.
Ensure $GOPATH/bin is in your PATH:
export PATH=$PATH:$(go env GOPATH)/bin
Verify:
webull version
Step 3: Authenticate
webull auth login --region jp
Enter App Key: <your-app-key>
Enter App Secret: <hidden>
Checking 2FA configuration...
✓ Profile "default" created (region: jp, auth: ak_sk)
Step 4: Verify Connection
webull doctor
✓ Token valid, expires: 2026-07-11 10:00:00
✓ Region: JP Environment: prod
✓ API connectivity: api.webull.co.jp → 200 (60ms)
✓ Permissions: JP Stocks ✓ US Stocks (JP) ✓
Step 5: Verify Account Access
webull account list
Usage Examples
Just talk to your AI assistant in natural language, or use the CLI directly:
Market Data:
webull data stock snapshot --symbol AAPL
JP Stock Trading — Cash:
webull order stock submit --account-id ACC123 --symbol 7203.T \
--side BUY --qty 100 --type LIMIT --limit-price 2850 \
--account-tax-type SPECIFIC --market JP
JP Stock Trading — Margin:
# Open margin position
webull order stock submit --account-id ACC123 --symbol 7203.T \
--side BUY --qty 100 --type LIMIT --limit-price 2850 \
--account-tax-type SPECIFIC --margin-type ONE_DAY \
--position-intent BUY_TO_OPEN --market JP -y
# Close margin position
webull order stock submit --account-id ACC123 --symbol 7203.T \
--side SELL --qty 100 --type LIMIT --limit-price 2900 \
--account-tax-type SPECIFIC --margin-type ONE_DAY \
--position-intent SELL_TO_CLOSE \
--close-contracts '[{"contract_id":"CONTRACT_001","quantity":100}]' \
--market JP -y
US Stock Trading (from JP Account):
webull order stock submit --account-id ACC123 --symbol AAPL \
--side BUY --qty 10 --type LIMIT --limit-price 185.00 \
--account-tax-type SPECIFIC --market US -y
Order Management:
webull order open --account-id ACC123
webull order stock replace --account-id ACC123 \
--client-order-id cli_stock_123456 --limit-price 2880
webull order cancel --account-id ACC123 --client-order-id cli_stock_123456 -y
Account:
webull account balance --account-id ACC123
webull account positions --account-id ACC123
webull account position-detail --account-id ACC123
Available Commands
Orders
| Command | Description |
|---|---|
order stock submit | Place stock order (JP or US stocks, with tax type) |
order stock preview | Preview order cost |
order stock replace | Modify order (preserve close_contracts if present) |
order cancel | Cancel unfilled order |
order open | List open orders |
order detail | Order details |
order history | Historical orders |
Market Data
| Command | Description |
|---|---|
data stock snapshot | US stock snapshot |
data stock bars | OHLCV bars |
data stock batch-bars | Batch OHLCV bars |
data stock quotes | Order book depth |
data stock tick | Tick-by-tick |
data screener gainers-losers | Market movers |
data screener actives | Most active |
Account
| Command | Description |
|---|---|
account list | List all accounts |
account balance | Account balance (JPY/USD) |
account positions | Position list |
account position-detail | Position detail with contract_id (JP-specific) |
Configuration
Environment Endpoints
See API Environments for production and test endpoint details.
Flags
| Flag | Description |
|---|---|
--profile | Use a specific profile |
--region | Override region (jp) |
--env | Environment (prod / uat) |
--csv | CSV output |
-q, --quiet | Suppress non-data output |
--verbose | Show HTTP request summary |
--debug | Show full request/response |
--timeout | HTTP timeout in seconds (default 30) |
-y, --yes | Skip confirmation prompts |
Security Recommendations
- Never share App Key, App Secret, or Token in chat
- Use
order previewto estimate costs before live orders - In Live mode, orders require confirmation unless
-yis passed - Use test environment for testing before production
Disclosure
Trading in securities involves substantial risk of loss. All trading decisions are at your own discretion. Verify order details before execution. This software is provided "as is" without warranty.
Related Links
- GitHub: webull-inc/webull-openapi-cli