# 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-openapi-skills](https://github.com/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 (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

```mermaid
sequenceDiagram
    participant U as User
    participant AI as AI Coding Assistant
    participant S as Skills Scripts (Python)
    participant SDK as Webull Python SDK
    participant API as Webull OpenAPI

    U->>AI: Natural language command (e.g. Get 00700 quote)
    AI->>S: Execute Python script (shell command)
    S->>SDK: Invoke SDK method
    SDK->>API: REST API request (signed auth)
    API-->>SDK: Return data
    SDK-->>S: Parse result
    S-->>AI: Formatted text output
    AI-->>U: Readable reply
```

---

## Prerequisites

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

### API Credentials

<Tabs groupId="environment">
  <TabItem value="prod" label="Production" default>

Apply based on your account type:

Individual users: [Trading API Application Guide](../authentication/TradingAPIApplication.md)

Institutional users: [Broker API Application Guide](../authentication/BrokerAPIapplication.md)

  </TabItem>
  <TabItem value="sandbox" label="Sandbox (Test)">

No application required. Use the publicly shared test credentials to get started immediately. See [SDKs and Tools](../sdk.md).

  </TabItem>
</Tabs>

### Other Requirements

- **Python 3.10+**
- **Webull Python SDK**: `pip install webull-openapi-python-sdk`
- **Market Data Subscription** (if market data is needed): [webullapp.hk/quote](https://www.webullapp.hk/quote) | [Subscription Guide](../market-data-api/subscribe-quotes.md)
- **AI coding assistant with shell command support** — e.g. [Kiro](https://kiro.dev), [Cursor](https://cursor.com), [Claude Desktop](https://claude.ai/download)

---

## Demo Video
<video src="https://uat-static.webullbroker.com/inst-bo/Webull_Agent_Skills_demo_videoX2.mp4" controls width="80%"></video>


## Setup Steps

```mermaid
flowchart LR
    S1(Install Dependencies) --> S2(Configure Credentials) --> S3(Authenticate 2FA) --> S4(Verify Connection)
```

### Step 1: Install Dependencies

```bash
pip install webull-openapi-python-sdk
```

### Step 2: Configure Credentials

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

<Tabs groupId="environment">
  <TabItem value="prod" label="Production" default>

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

  </TabItem>
  <TabItem value="sandbox" label="Sandbox">

```env
WEBULL_APP_KEY=your_app_key
WEBULL_APP_SECRET=your_app_secret
WEBULL_ENVIRONMENT=uat
WEBULL_REGION_ID=hk
```

  </TabItem>
</Tabs>

### Step 3: Authenticate

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

```bash
python3 scripts/cli.py auth
```

Authentication flow:

```mermaid
sequenceDiagram
    participant CLI as Terminal
    participant API as Webull API
    participant App as Webull App (Mobile)

    CLI->>API: Request Token Creation
    API-->>CLI: Return PENDING Status
    CLI->>CLI: Waiting for 2FA Approval (up to 5 min)...
    App->>API: User Approves in App
    API-->>CLI: Token Status → NORMAL
    CLI->>CLI: Save Token Locally
    Note over CLI: Auth Complete, Token cached and auto-refreshes
```

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

### Step 4: Verify Connection

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

If account information is returned, the setup is successful.

---

## Integration with Different AI Tools

<Tabs groupId="ai-client">

  <TabItem value="cursor" label="Cursor">

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

```markdown
# Webull OpenAPI

When the user needs to query market data or execute trades, use the following commands:
- Trading: python3 scripts/cli.py trading --action <ACTION> [args...]
- Market data: python3 scripts/cli.py market-data --action <ACTION> [args...]
- Auth: python3 scripts/cli.py auth
```

  </TabItem>
  <TabItem value="claude" label="Claude Desktop">

Add the project as a working directory in Claude Desktop. Claude can execute shell commands directly in conversation to run the scripts.

  </TabItem>
  <TabItem value="copilot" label="GitHub Copilot">

In Agent Mode, directly request script command execution. Copilot will execute via terminal and return results.

  </TabItem>

  <TabItem value="kiro" label="Kiro" default>

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
```

  </TabItem>
</Tabs>

---

## 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

| Endpoint | Description |
|----------|-------------|
| `stock-noii-bars` | Get NOII (Net Order Imbalance Indicator) OHLCV bars for a stock |
| `stock-noii-snapshot` | Get NOII real-time snapshot |
| `stock-gainers-losers` | Top gainers or losers by price change |
| `stock-most-active` | Most actively traded stocks |
| `instrument-company-profile` | Get company profile (CEO, sector, employees, etc.) |
| `instrument-analyst-rating` | Get analyst buy/hold/sell rating counts |
| `instrument-analyst-target-price` | Get analyst target price (mean/high/low/median) |
| `instrument-futures-product-class` | Get futures product classification groups |
| `instrument-futures-products` | Get all futures product codes |
| `instrument-futures-list` | Get futures instruments by symbol |
| `watchlist-list` | Get all watchlists |
| `watchlist-create` | Create a new watchlist |
| `watchlist-delete` | Delete a watchlist |
| `watchlist-update` | Update watchlist name or sort |
| `watchlist-instruments-list` | Get instruments in a watchlist |
| `watchlist-instruments-add` | Add instruments to a watchlist |
| `watchlist-instruments-remove` | Remove instruments from a watchlist |
| `watchlist-instruments-update` | Update instrument sort order |
| `stock_snapshot` | Get real-time stock snapshot (HK, US, A-shares) |
| `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 |
| `place_stock_order` | Place a stock order |
| `preview_stock_order` | Preview a stock order without submitting |
| `replace_stock_order` | Modify an existing stock order |
| `place_option_single_order` | Place a single-leg option order |
| `preview_option_order` | Preview an option order without submitting |
| `replace_option_order` | Modify an existing option 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 |
| `fundamentals-capital-flow` | Get capital flow distribution for a stock, broken down by order-size tier. |  
| `fundamentals-sec-filings` | Get recent SEC filings for a US stock (last 3 years). |  
| `fundamentals-earnings-calendar` | Get a stock's earnings calendar around the current date. |  
| `fundamentals-dividend-calendar` | Get a stock's dividend calendar around the current date. |  
| `fundamentals-forecast-eps` | Get a stock's recent actual EPS plus the latest analyst consensus estimate. |  
| `fundamentals-industry-comparison` | Get industry peer comparison for a stock (up to 20 peers), with a selectable sort metric. |  
| `fundamentals-fund-rating` | Get rating history for a fund or ETF. |  
| `fundamentals-fund-performance` | Get fund performance returns over multiple horizons. |  
| `fundamentals-fund-allocation` | Get a fund's asset allocation breakdown. |  
| `fundamentals-fund-holdings` | Get a fund's top 10 holdings. |  
| `fundamentals-fund-brief` | Get brief profile information for a fund or ETF. |  
| `fundamentals-fund-dividends` | Get a fund's dividend distribution history. |  
| `fundamentals-fund-splits` | Get a fund's split history. |  
| `fundamentals-fund-net-value` | Get a fund's net asset value (NAV) history, paged by date. |  
| `fundamentals-fund-files` | Get documents and files published for a fund. |  
| `fundamentals-financials-alert` | Get a stock's earnings alert, comparing next-report estimates against the prior-year period. |  
| `fundamentals-financials-indicators` | Get key financial indicators and ratios for a stock, annual or quarterly. |  
| `fundamentals-financials-income` | Get a stock's income statement across reporting periods, annual or quarterly. |  
| `fundamentals-financials-balance-sheet` | Get a stock's balance sheet across reporting periods, annual or quarterly. |  
| `fundamentals-financials-cashflow` | Get a stock's cash flow statement across reporting periods, annual or quarterly. | 
| `stock-market-sectors` | Get a market-wide sector overview ranking with aggregate statistics by market value or volume. |  
| `stock-market-sectors-detail` | Get the constituent stock list and statistics for a specific market sector. |  
| `stock-high-dividend` | Get a ranking of high dividend yield stocks in a market. |  
| `stock-52-week-high-low` | Get a ranking of stocks at or near their 52-week highs or lows. |

---

## 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 `hk` for HK region |
| `WEBULL_MAX_ORDER_NOTIONAL_USD` | `10000` | Max order value (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 | Trade Events (gRPC) | Market Streaming (MQTT) |
|-------------|----------|---------------------|------------------------|
| Production | `api.webull.hk` | `events-api.webull.hk` | `data-api.webull.hk` |
| Sandbox | `api.sandbox.webull.hk` | `events-api.sandbox.webull.hk` | `data-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 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 `python3 scripts/cli.py 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, 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.

---

## Related Links

- Webull OpenAPI Docs: [developer.webull.hk](https://developer.webull.hk/apis)
- Webull MCP Server: [Webull MCP](mcp.md)
- Python SDK: `pip install webull-openapi-python-sdk`