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 Python command-line toolkit (webull-skill) built on the official Webull Python SDK. Any AI coding assistant that can execute shell commands can call it directly. With natural language, you can:

  • Query real-time and historical market data (stocks, options, futures, crypto, event contracts)
  • Look up instruments, fundamentals, financial statements, and institution/insider data
  • Search market news, use screeners, and manage watchlists
  • Browse and publish community posts and comments
  • 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 – 3.12
  • Git (to clone the Skills repository)
  • 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​

git clone https://github.com/webull-inc/webull-openapi-skills.git
cd webull-openapi-skills

# Create and activate a virtual environment (recommended)
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# Install the package (also installs the Webull Python SDK and the webull-skill command)
pip install -e .

Step 2: Configure Credentials​

Create a .env file in the project root (the webull-openapi-skills directory) 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​

Actions are invoked as webull-skill <module> --action <action> [options]. Run webull-skill <module> --help for all options.

trading module​

Instruments​

ActionDescription
instrument-stockGet stock/ETF instrument info.
instrument-cryptoGet cryptocurrency instrument info.
instrument-option-contractsList option contracts by underlying symbol, expiry, strike, etc.
instrument-futures-productsGet all futures products and codes.
instrument-futures-product-classGet futures product classification groups.
instrument-futures-listGet futures instruments by symbol.
instrument-futures-by-codeGet futures contracts by product code.
instrument-event-seriesGet event contract series.
instrument-event-listGet event contract instruments by series.
instrument-event-categoriesGet event contract categories.
instrument-event-eventsGet events within a series.
instrument-company-profileGet company profile (CEO, sector, employees, etc.).
instrument-analyst-ratingGet analyst buy/hold/sell rating counts.
instrument-analyst-target-priceGet analyst target price (mean/high/low/median).

Account​

ActionDescription
account-listGet all linked accounts.
balanceGet account balance, buying power, and cash details.
positionGet current positions and holdings.

Orders​

ActionDescription
placePlace a stock/ETF order.
previewPreview a stock order without submitting.
replaceModify an existing stock order.
batch-placePlace a combo stock order (OTO/OCO/OTOCO).
algo-placePlace an algorithmic order (TWAP/VWAP/POV).
option-placePlace a single-leg option order.
option-previewPreview an option order without submitting.
option-replaceModify an existing option order.
option-strategy-placePlace a multi-leg option strategy order.
futures-placePlace a futures order.
futures-previewPreview a futures order without submitting.
futures-replaceModify an existing futures order.
crypto-placePlace a cryptocurrency order.
event-placePlace an event contract order.
event-replaceModify an existing event contract order.
cancelCancel an unfilled order.
openGet all current open/pending orders.
historyGet historical orders.
detailGet single order details.
local-checkRun local risk checks on an order without sending a request.

market-data module​

Stock​

ActionDescription
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).
stock-noii-barsGet NOII OHLCV bars (auction imbalance).
stock-noii-snapshotGet NOII real-time snapshot.

Options​

ActionDescription
option-snapshotGet real-time option snapshot (requires option market data subscription).
option-barsGet option OHLCV bars.
option-tickGet option tick-by-tick trade data.

Futures, Crypto, and Event Contracts​

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

Screener​

ActionDescription
stock-gainers-losersTop gainers or losers by price change.
stock-most-activeMost actively traded stocks.
stock-market-sectorsGet a market-wide sector overview ranking with aggregate statistics by market value or volume.
stock-market-sectors-detailGet the constituent stock list and statistics for a specific market sector.
stock-high-dividendGet a ranking of high dividend yield stocks in a market.
stock-52-week-high-lowGet a ranking of stocks at or near their 52-week highs or lows.
market-sentimentGet the US market fear & greed sentiment index with historical comparison points.
stock-unusual-activitiesGet recent unusual activity alerts (volume surge, price spike) for US stocks.

Fundamentals​

ActionDescription
fundamentals-capital-flowGet capital flow distribution for a stock, broken down by order-size tier.
fundamentals-sec-filingsGet recent SEC filings for a US stock (last 3 years).
fundamentals-earnings-calendarGet a stock's earnings calendar around the current date.
fundamentals-dividend-calendarGet a stock's dividend calendar around the current date.
fundamentals-forecast-epsGet a stock's recent actual EPS plus the latest analyst consensus estimate.
fundamentals-industry-comparisonGet industry peer comparison for a stock (up to 20 peers), with a selectable sort metric.
fundamentals-fund-ratingGet rating history for a fund or ETF.
fundamentals-fund-performanceGet fund performance returns over multiple horizons.
fundamentals-fund-allocationGet a fund's asset allocation breakdown.
fundamentals-fund-holdingsGet a fund's top 10 holdings.
fundamentals-fund-briefGet brief profile information for a fund or ETF.
fundamentals-fund-dividendsGet a fund's dividend distribution history.
fundamentals-fund-splitsGet a fund's split history.
fundamentals-fund-net-valueGet a fund's net asset value (NAV) history, paged by date.
fundamentals-fund-filesGet documents and files published for a fund.
fundamentals-financials-alertGet a stock's earnings alert, comparing next-report estimates against the prior-year period.
fundamentals-financials-indicatorsGet key financial indicators and ratios for a stock, annual or quarterly.
fundamentals-financials-incomeGet a stock's income statement across reporting periods, annual or quarterly.
fundamentals-financials-balance-sheetGet a stock's balance sheet across reporting periods, annual or quarterly.
fundamentals-financials-cashflowGet a stock's cash flow statement across reporting periods, annual or quarterly.
institution-searchSearch US institutional investors by name or SEC CIK.
institution-holdingsGet a US institution's 13F holdings.
institution-holding-changesGet a US institution's holding changes by position type (OPEN/CLOSE/CHANGE).
insider-transactionsGet insider transaction records for a US stock (optional BUY/SELL filter).
insider-holdings-overviewGet insider ownership statistics overview for a US stock.
economic-calendarGet the US macroeconomic event calendar for a date range.

News​

ActionDescription
news-searchSearch US market news by keyword.
news-detailGet the full content of a news article by ID.
stock-newsGet news related to a US stock, with optional sentiment filter.

Watchlist​

ActionDescription
watchlist-listGet all watchlists.
watchlist-createCreate a new watchlist.
watchlist-deleteDelete a watchlist.
watchlist-updateUpdate watchlist name or sort.
watchlist-instruments-listGet instruments in a watchlist.
watchlist-instruments-addAdd instruments to a watchlist.
watchlist-instruments-removeRemove instruments from a watchlist.
watchlist-instruments-updateUpdate instrument sort order.

Community​

ActionDescription
community-create-postCreate a plain-text post, optionally tagged with a symbol (write operation, requires confirmation).
community-create-commentComment on a community post (write operation, requires confirmation).
community-hot-stocksList stocks ranked by community activity.
community-posts-by-symbolList community posts for a symbol, with optional keyword and pagination.
community-post-detailGet detailed information for a community post.
community-my-postsList the current user's posts.

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_CONFIG_DIR(none)System environment variable only (has no effect inside .env). Moves .env lookup and token storage to this directory
WEBULL_TOKEN_DIR<project_root>/conf/Token storage directory ($WEBULL_CONFIG_DIR/conf/ if WEBULL_CONFIG_DIR is set)
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
Sandbox (test)api.sandbox.webull.comevents-api.sandbox.webull.comdata-api.sandbox.webull.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, option-preview, or futures-preview before placing orders
  • community-create-post and community-create-comment publish content under your account; the AI must show the full text and get your confirmation first
  • 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.