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.

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
View account balances and positions
Place, modify, and cancel stock orders
Query order history and order details
Authenticate via 2FA token flow

Architecture Overview

Prerequisites

API Credentials

Production
UAT (Test)

Apply at: Individual Application Guide

Other Requirements

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

Setup Steps

Step 1: Clone Repository

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

Step 2: Install

pip install -e .

Step 3: Configure Credentials

cp .env.example .env

Edit .env with your credentials:

Production
Sandbox

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

WEBULL_APP_KEY=your_app_key
WEBULL_APP_SECRET=your_app_secret
WEBULL_ENVIRONMENT=uat
WEBULL_REGION_ID=jp

Step 4: Authenticate

note

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

Complete a one-time 2FA 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 5: Verify Connection

webull-skill trading --action account-list

If account information is returned, the setup is successful.

Integration with Different AI Tools

Cursor
Claude Desktop
GitHub Copilot
Kiro

Create .cursor/rules/webull.mdc in your project root with script paths and usage instructions:

# Webull OpenAPI

When the user needs to query market data or execute trades, use the following commands:
- Trading: webull-skill trading --action <ACTION> [args...]
- Market data: webull-skill market-data --action <ACTION> [args...]
- Auth: webull-skill auth

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 real-time quotes for MSFT

Trading:

Show my account list

Check my account balance

Buy 10 shares of AAPL at limit price 180

Cancel my open order for TSLA

Show my open orders

Show my order history

Account:

What are my current positions?

Available Endpoints

Endpoint	Description
`stock_snapshot`	Get real-time stock/ETF snapshot
`stock_bars`	Get single stock OHLCV candlestick data
`stock_batch_bars`	Get OHLCV bars for multiple stocks
`stock_tick`	Get stock tick-by-tick trade data
`stock_quotes`	Get real-time bid/ask quotes with depth
`stock_footprint`	Get stock large order footprint (order flow)
`get_instruments`	Get stock/ETF instrument info
`get_account_list`	Get all linked accounts
`get_account_balance`	Get account balance, buying power, and cash details
`get_account_positions`	Get current positions and holdings
`get_position_detail`	Get position details by instrument
`place_stock_order`	Place a stock order
`preview_stock_order`	Preview a stock order without submitting
`replace_stock_order`	Modify an existing stock order
`cancel_order`	Cancel an unfilled order
`get_order_history`	Get historical orders
`get_open_orders`	Get all current open/pending orders
`get_order_detail`	Get single order details

JP-Specific Order Parameters

When placing orders in the JP region, the following additional parameters are available:

Parameter	Required	Values	Description
`account_tax_type`	Yes	`GENERAL`, `SPECIFIC`	Tax account type for the order
`margin_type`	No (margin accounts only)	`ONE_DAY`, `INDEFINITE`	Margin loan duration
`position_intent`	No (margin accounts only)	`BUY_TO_OPEN`, `BUY_TO_CLOSE`, `SELL_TO_OPEN`, `SELL_TO_CLOSE`	Position direction for margin trades
`close_contracts`	No	Array of contract objects	Specific contracts to close (for position closing)

Configuration

Via .env file or environment variables. Required:

WEBULL_APP_KEY=<your_app_key>
WEBULL_APP_SECRET=<your_app_secret>

Optional:

Variable	Default	Description
`WEBULL_ENVIRONMENT`	`uat`	`uat` (sandbox) or `prod` (live)
`WEBULL_REGION_ID`	`us`	Set to `jp` for JP region
`WEBULL_MAX_ORDER_NOTIONAL_JPY`	`1500000`	Max order value (JPY)
`WEBULL_MAX_ORDER_NOTIONAL_USD`	`10000`	Max order value for US market (USD)
`WEBULL_MAX_ORDER_QUANTITY`	`1000`	Max shares per order
`WEBULL_SYMBOL_WHITELIST`	(none)	Comma-separated allowed symbols
`WEBULL_TOKEN_DIR`	`conf/`	Token storage directory
`WEBULL_AUDIT_LOG_FILE`	(stderr)	Audit log file path
`WEBULL_LOG_LEVEL`	`WARNING`	SDK log level

Environment Endpoints

Environment	HTTP API
Production	`api.webull.co.jp`
Sandbox	`api.sandbox.webull.co.jp`

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

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_JPY and WEBULL_MAX_ORDER_QUANTITY to limit order size

Troubleshooting

Error Message	Cause	Solution
`Insufficient permission` / `subscribe to stock quotes`	Insufficient data permissions	Subscribe to market data
`HTTP Status: 401` / `UNAUTHORIZED`	Credential/environment mismatch	Check `.env` configuration
`HTTP Status: 417` / `INVALID_TOKEN`	Token expired or cache issue	Re-run `webull-skill auth`
`Failed to resolve` / `NameResolutionError`	DNS/network issue	Check network/proxy/firewall settings

Disclosure

The information provided by this tool is for reference only and does not constitute investment advice. Trading in securities 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.

Webull OpenAPI Docs: developer.webull.co.jp
Python SDK: pip install webull-openapi-python-sdk

What is Webull Agent Skills​

Architecture Overview​

Prerequisites​

API Credentials​

Other Requirements​

Setup Steps​

Step 1: Clone Repository​

Step 2: Install​

Step 3: Configure Credentials​

Step 4: Authenticate​

Step 5: Verify Connection​

Integration with Different AI Tools​

Usage Examples​

Available Endpoints​

JP-Specific Order Parameters​

Configuration​

Environment Endpoints​

Output Format​

Security Recommendations​

Troubleshooting​

Disclosure​

Related Links​