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/test) routing for US markets — stocks, options, futures, crypto, and event contracts.

Source code: webull-inc/webull-openapi-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 (stocks, futures, crypto, event contracts)
  • View account balances and positions
  • Place, modify, and cancel orders (stocks, ETFs, options, futures, crypto, event contracts)
  • Execute combo orders (OTO/OCO/OTOCO) and algo orders (TWAP/VWAP/POV)
  • Query order history and order details
  • Authenticate via 2FA token flow

Architecture Overview​

Prerequisites​

API Credentials​

Apply based on your account type:

Individual users: Individual Application Process

Institutional users: Institution Application Process

Other Requirements​

  • Python 3.10+
  • Webull Python SDK: pip install webull-openapi-python-sdk
  • Market Data Subscription (if market data is needed): Subscription Guide
  • AI coding assistant with shell command support — e.g. Kiro, Cursor, Claude Desktop

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=us

Step 3: Authenticate (Optional)​

note

This step is only required if your account has Two-Factor Authentication enabled.

If your account has 2FA enabled, complete a one-time authentication before first use:

webull-skill 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​

webull-skill 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 AAPL latest price

Usage Examples​

Just talk to your AI assistant in natural language:

Market Data:

Get AAPL latest price
Show me TSLA's daily bars for the last 5 days
Get Bitcoin real-time price
Show ES futures snapshot

Trading:

Show my account list
Check my account balance
Buy 10 shares of AAPL at limit price 180
Buy 1 AAPL call option, strike 220, expiring June 2026
Buy 1 ES futures contract at limit 4500
Cancel my open order for TSLA
Show my open orders

Account:

What are my current positions?

Available Endpoints​

EndpointDescription
stock_snapshotGet real-time stock/ETF snapshot
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)
futures_snapshotGet futures real-time snapshot
futures_barsGet futures OHLCV candlestick data
futures_tickGet futures tick-by-tick trade data
futures_depthGet futures order book depth
futures_footprintGet futures large order footprint
crypto_snapshotGet cryptocurrency real-time snapshot
crypto_barsGet cryptocurrency OHLCV bars
event_snapshotGet event contract real-time snapshot
event_depthGet event contract order book depth
event_barsGet event contract OHLCV bars
event_tickGet event contract tick-by-tick data
get_instrumentsGet stock/ETF instrument info
get_crypto_instrumentsGet cryptocurrency instrument info
get_futures_instrumentsGet futures instrument info
get_futures_instruments_by_codeGet futures contracts by product code
get_futures_productsGet all futures products and codes
get_event_seriesGet event contract series
get_event_instrumentsGet event contract instruments by series
get_event_categoriesGet event contract categories
get_event_eventsGet events within a series
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_stock_combo_orderPlace a combo stock order (OTO/OCO/OTOCO)
place_algo_orderPlace an algorithmic order (TWAP/VWAP/POV)
place_option_single_orderPlace a single-leg option order
preview_option_orderPreview an option order without submitting
replace_option_orderModify an existing option order
place_option_strategy_orderPlace a multi-leg option strategy order
place_futures_orderPlace a futures order
replace_futures_orderModify an existing futures order
place_crypto_orderPlace a cryptocurrency order
place_event_orderPlace an event contract order
replace_event_orderModify an existing event contract 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 (test) or prod (live)
WEBULL_REGION_IDusus for US 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.comevents-api.webull.comdata-api.webull.com
Testus-openapi-alb.uat.webullbroker.comus-openapi-events.uat.webullbroker.com—

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: 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 region: English disclaimer only

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 webull-skill 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, futures, crypto, 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.