Skip to main content

Webull Agent Skills

Webull Agent Skills enable AI coding assistants (Cursor, Claude Desktop, Copilot, Kiro, etc.) to securely access Webull OpenAPI trading and market data capabilities via local Python scripts, with multi-environment (production/sandbox) routing for Hong Kong, US, and A-share markets.

Source code: webull-inc/webull-agent-skills

What is Webull Agent Skills​

Webull Agent Skills is a set of standalone Python scripts built on the official Webull Python SDK. Any AI coding assistant that can execute shell commands can call them directly. With natural language, you can:

  • Query real-time market data (HK stocks, US stocks, A-shares)
  • View account balances and positions
  • Place, modify, and cancel orders (stocks, ETFs, options)
  • Query order history and order details
  • Authenticate via 2FA token flow

Architecture Overview​

Prerequisites​

API Credentials​

Apply based on your account type:

Individual users: Trading API Application Guide

Institutional users: Broker API Application Guide

Other Requirements​

Demo Video​

Setup Steps​

Step 1: Install Dependencies​

pip install webull-openapi-python-sdk

Step 2: Configure Credentials​

Create a .env file in the project root with your credentials:

WEBULL_APP_KEY=your_app_key
WEBULL_APP_SECRET=your_app_secret
WEBULL_ENVIRONMENT=prod
WEBULL_REGION_ID=hk

Step 3: Authenticate​

Complete a one-time 2FA authentication before first use:

python3 scripts/cli.py auth

Authentication flow:

After approving the 2FA request in the Webull App, the token is cached locally and auto-refreshes on use.

Step 4: Verify Connection​

python3 scripts/cli.py trading --action account-list

If account information is returned, the setup is successful.

Integration with Different AI Tools​

Place scripts in the .kiro/skills/ directory. Kiro will automatically load SKILL.md and recognize all available operations. Just use natural language:

Get 00700 latest price

Usage Examples​

Just talk to your AI assistant in natural language:

Market Data:

Get 00700 latest price
Show me AAPL's daily bars for the last 5 days
Get real-time quotes for 09988

Trading:

Show my account list
Check my account balance
Buy 100 shares of 00700 at enhanced limit price 350
Cancel my open order for AAPL
Show my open orders
Show my order history

Account:

What are my current positions?

Available Endpoints​

EndpointDescription
stock_snapshotGet real-time stock snapshot (HK, US, A-shares)
stock_barsGet single stock OHLCV candlestick data
stock_batch_barsGet OHLCV bars for multiple stocks
stock_tickGet stock tick-by-tick trade data
stock_quotesGet real-time bid/ask quotes with depth
stock_footprintGet stock large order footprint (order flow)
get_instrumentsGet stock/ETF instrument info
get_account_listGet all linked accounts
get_account_balanceGet account balance, buying power, and cash details
get_account_positionsGet current positions and holdings
place_stock_orderPlace a stock order
preview_stock_orderPreview a stock order without submitting
replace_stock_orderModify an existing stock order
place_option_single_orderPlace a single-leg option order
preview_option_orderPreview an option order without submitting
replace_option_orderModify an existing option order
cancel_orderCancel an unfilled order
get_order_historyGet historical orders
get_open_ordersGet all current open/pending orders
get_order_detailGet single order details

Configuration​

Via .env file or environment variables. Required:

WEBULL_APP_KEY=<your_app_key>
WEBULL_APP_SECRET=<your_app_secret>

Optional:

VariableDefaultDescription
WEBULL_ENVIRONMENTuatuat (sandbox) or prod (live)
WEBULL_REGION_IDusSet to hk for HK region
WEBULL_MAX_ORDER_NOTIONAL_USD10000Max order value (USD)
WEBULL_MAX_ORDER_QUANTITY1000Max shares per order
WEBULL_SYMBOL_WHITELIST(none)Comma-separated allowed symbols
WEBULL_TOKEN_DIRconf/Token storage directory
WEBULL_AUDIT_LOG_FILE(stderr)Audit log file path
WEBULL_LOG_LEVELWARNINGSDK log level

Environment Endpoints​

EnvironmentHTTP APITrade Events (gRPC)Market Streaming (MQTT)
Productionapi.webull.hkevents-api.webull.hkdata-api.webull.hk
Sandboxapi.sandbox.webull.hkevents-api.sandbox.webull.hkdata-api.sandbox.webull.hk

Output Format​

All operations output formatted text directly to stdout, with a region-aware disclaimer:

⚠️ Disclaimer: The information provided by this tool is for reference only ...

=== Stock Snapshot: 00700 ===
  Symbol:          00700
  Price:           350.20
  Pre Close:       348.60
  Change:          1.60
  ...
  • Success: disclaimer + formatted data to stdout, exit code 0
  • Error: error message to stderr, exit code 1
  • HK region: English + Simplified Chinese + Traditional Chinese disclaimer

Security Recommendations​

  • Never share your App Key, App Secret, or Token in chat. Credentials should only be passed via .env file or environment variables
  • Use preview before placing orders
  • Use WEBULL_SYMBOL_WHITELIST to restrict tradeable symbols
  • Use WEBULL_MAX_ORDER_NOTIONAL_USD and WEBULL_MAX_ORDER_QUANTITY to limit order size
  • Use local-check to validate order parameters without sending requests

Troubleshooting​

Error MessageCauseSolution
Insufficient permission / subscribe to stock quotesInsufficient data permissionsSubscribe to market data
HTTP Status: 401 / UNAUTHORIZEDCredential/environment mismatchCheck .env configuration
HTTP Status: 417 / INVALID_TOKENToken expired or cache issueRe-run python3 scripts/cli.py auth
Failed to resolve / NameResolutionErrorDNS/network issueCheck network/proxy/firewall settings

Disclosure​

The information provided by this tool is for reference only and does not constitute investment advice. Trading in securities, options, and other financial instruments involves substantial risk of loss. All trading decisions are made at your own discretion and risk. You are solely responsible for verifying order details before execution. This software is provided "as is" without warranty of any kind.