# Webull Openapi

> Trade stocks, options, futures, crypto, and event contracts on Webull. Query real-time and historical market data. Manage accounts and positions. Supports US, HK, JP, SG, TH, MY, UK, MX, BR, EU, ZA, and AU regions with configurable risk controls.

- **Type:** Skill
- **Install:** `agentstack add skill-webull-inc-webull-openapi-skills-webull-openapi-skills`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [webull-inc](https://agentstack.voostack.com/s/webull-inc)
- **Installs:** 0
- **Category:** [Finance & Payments](https://agentstack.voostack.com/c/finance-and-payments)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [webull-inc](https://github.com/webull-inc)
- **Source:** https://github.com/webull-inc/webull-openapi-skills

## Install

```sh
agentstack add skill-webull-inc-webull-openapi-skills-webull-openapi-skills
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Webull OpenAPI Skill

This skill lets you interact with Webull's trading platform through natural language. You can place orders, check market data, query account info, and manage positions — all via the official Webull Python SDK.

## What You Can Do

- **Trade**: Place, preview, modify, and cancel orders for stocks, options, futures, crypto, and event contracts. Each asset type has dedicated actions:
  - Stock/ETF → `place`, `preview`, `replace`
  - Option → `option-place`, `option-preview`, `option-replace`, `option-strategy-place`
  - Futures → `futures-place`, `futures-replace`
  - Crypto → `crypto-place`
  - Event → `event-place`, `event-replace`
- **Market Data**: Get real-time snapshots, historical bars, tick data, quotes, and order flow for all asset classes
- **Accounts**: List accounts, check balances, view positions
- **Instruments**: Look up stock, crypto, futures, and event contract instruments; get company profile, analyst ratings, and target prices
- **Screener**: Top gainers/losers, most active stocks, market sectors, high dividend, and 52-week high/low
- **Fundamentals**: Financial statements, capital flow, industry comparison, earnings/dividend calendar, forecast EPS, and fund/ETF data
- **Watchlist**: Create, manage, and query watchlists and their instruments

## Safety Rules

**All order-mutating operations require user confirmation before execution.**

Mutating actions: `place`, `replace`, `cancel`, `batch-place`, `algo-place`, `option-place`, `option-replace`, `option-strategy-place`, `futures-place`, `futures-replace`, `crypto-place`, `event-place`, `event-replace`.

Before executing any of these operations, the AI must:
1. Display a clear summary of the operation to the user, including:
   - Action type (place / replace / cancel)
   - Symbol, side, order type, quantity, price
   - Account being used
2. Explicitly ask the user to confirm (e.g., "Confirm this order? [Yes/No]")
3. Only proceed after receiving explicit user approval

Read-only operations (`account-list`, `balance`, `position`, `open`, `history`, `detail`, `instrument-*`, all `market-data` actions) do not require confirmation and can be executed immediately.

---

## Quick Examples

> **CLI command:** After `pip install -e .`, use `webull-skill` on all platforms (macOS, Linux, Windows). This console entry point is bound to the Python that ran `pip`, so it works regardless of what `python3` or `python` points to on your system.

> **Passing order JSON:** Prefer `--order-file ` (write JSON to a temp file first) over `--order-json ''`. Inline JSON with `--order-json` is fragile across shells — Windows bash, PowerShell, and some macOS terminals mangle quotes and escapes. Using `--order-file` avoids all shell quoting issues.

```bash
# Check your accounts
webull-skill trading --action account-list

# Get AAPL stock price
webull-skill market-data --action stock-snapshot --symbols AAPL

# Get account balance
webull-skill trading --action balance --account-id 

# Place a limit buy order (recommended: use --order-file)
#   echo '{"symbol":"AAPL","side":"BUY","order_type":"LIMIT","limit_price":180,"quantity":10,"instrument_type":"EQUITY","market":"US","time_in_force":"DAY","entrust_type":"QTY","support_trading_session":"CORE","combo_type":"NORMAL"}' > /tmp/order.json
#   webull-skill trading --action place --account-id  --order-file /tmp/order.json

# Cancel an order
webull-skill trading --action cancel --account-id  --client-order-id 
```

## CLI Entry Point

```
webull-skill [--env-file PATH] [--verbose-sdk-log]  --action  [options]
```

Three modules: `trading`, `market-data`, `auth`.

---

## Modules

### trading

Instrument queries, account/asset operations, and all order operations (stock, option, futures, crypto, event contracts).

For full action list, order JSON formats, replace rules, and order type references, see [Trading Guide](references/skill_trading.md).

### market-data

Real-time and historical market data for all asset classes (stock, futures, crypto, event contracts), plus screener, fundamentals, and watchlist.

For full action list, options, category values, and examples, see [Market Data Guide](references/skill_market_data.md).

### auth

```bash
webull-skill auth
```

Interactive 2FA authentication. Run once before first use. The SDK waits up to 5 minutes for you to approve in the Webull mobile app. Token is cached and auto-refreshes.

---

## Output Format

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

```
⚠️ 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/JP/SG/TH/MY/UK/MX/BR/EU/ZA/AU region: English disclaimer only
- HK region: English + Simplified Chinese + Traditional Chinese disclaimer

---

## Configuration

Via `.env` file or environment variables. Required:

```
WEBULL_APP_KEY=
WEBULL_APP_SECRET=
```

Region selection:

```env
# Choose one region:
WEBULL_REGION_ID=us
# WEBULL_REGION_ID=hk
# WEBULL_REGION_ID=jp
# WEBULL_REGION_ID=sg
# WEBULL_REGION_ID=th
# WEBULL_REGION_ID=my
# WEBULL_REGION_ID=uk
# WEBULL_REGION_ID=mx
# WEBULL_REGION_ID=br
# WEBULL_REGION_ID=eu
# WEBULL_REGION_ID=za
# WEBULL_REGION_ID=au

# Sandbox by default; set prod only for live trading.
WEBULL_ENVIRONMENT=uat
```

**`.env` lookup order** (when `--env-file` is not specified):
1. `$WEBULL_CONFIG_DIR/.env` — if `WEBULL_CONFIG_DIR` is set
2. `/.env` — default (sibling of `webull_skill/`)
3. Current working directory `.env` — last resort

> To keep credentials outside the project directory, set `WEBULL_CONFIG_DIR` as a **system environment variable** (e.g. in `~/.zshrc`), then place your `.env` at `$WEBULL_CONFIG_DIR/.env`. Setting `WEBULL_CONFIG_DIR` inside a `.env` file has no effect — it must be set before the process starts.

Optional:

| Variable | Default | Description |
|----------|---------|-------------|
| `WEBULL_ENVIRONMENT` | `uat` | `uat` (sandbox) or `prod` (live) |
| `WEBULL_REGION_ID` | `us` | `us`, `hk`, `jp`, `sg`, `th`, `my`, `uk`, `mx`, `br`, `eu`, `za`, or `au` |
| `WEBULL_MAX_ORDER_NOTIONAL_USD` | `10000` | Max order value (USD) |
| `WEBULL_MAX_ORDER_NOTIONAL_HKD` | `80000` | Max order value for HK market (HKD) |
| `WEBULL_MAX_ORDER_NOTIONAL_CNH` | `70000` | Max order value for CN market (CNH) |
| `WEBULL_MAX_ORDER_NOTIONAL_JPY` | `1500000` | Max order value for JP market (JPY) |
| `WEBULL_MAX_ORDER_QUANTITY` | `1000` | Max shares per order |
| `WEBULL_SYMBOL_WHITELIST` | (none) | Comma-separated allowed symbols |
| `WEBULL_CONFIG_DIR` | (none) | **System env var only** (not in `.env`). Moves `.env` lookup and token storage to this directory |
| `WEBULL_TOKEN_DIR` | `/conf/` | Token storage directory |
| `WEBULL_AUDIT_LOG_FILE` | (stderr) | Audit log file path |
| `WEBULL_LOG_LEVEL` | `WARNING` | SDK log level |

---

## Region Support

| Feature | US | HK | JP | SG | TH | MY | UK | MX | BR | EU | ZA | AU |
|---------|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|
| Stock trading | ✓ | ✓ (US/HK/CN) | ✓ (US/JP) | ✓ (US) | ✓ (US) | ✓ (US) | ✓ (US) | ✓ (US) | ✓ (US) | ✓ (US) | ✓ (US) | ✓ (US) |
| Options | ✓ | ✓ (US only) | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| Futures | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| Crypto | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| Event contracts | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| Combo orders | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| Algo orders | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| Trailing stop loss | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| Fractional shares | ✓ (US market) | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| Company profile | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ |
| Analyst rating / target price | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ |
| NOII bars / snapshot | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ |
| Screener (gainers/losers/active) | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ |
| Screener (stock-market-sectors/stock-market-sectors-detail/stock-high-dividend/stock-52-week-high-low) | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| Watchlist | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ |
| Fundamentals | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |

### HK-Specific Notes

- HK stocks use order types: `ENHANCED_LIMIT`, `AT_AUCTION`, `AT_AUCTION_LIMIT`
- CN A-shares (Stock Connect): `LIMIT` only, disabled by default — contact Webull to enable
- Board lot sizes vary by HK stock
- No combo orders, algo orders, crypto, or event contracts in HK region
- HK stock orders (institutional/broker): require `sender_sub_id` and `no_party_ids` (BCAN)
- HK US options (institutional/broker): support `sender_sub_id` only, no BCAN needed

### JP-Specific Notes

- Configure JP with `WEBULL_REGION_ID=jp`; sandbox uses `WEBULL_ENVIRONMENT=uat`.
- JP supports stock/ETF market data and stock order management. Futures, crypto, event contracts, options, combo orders, and algo orders are not supported in JP.
- JP stock instrument categories are `US_STOCK` and `US_ETF`.
- JP stock order markets are `US` and `JP`.
- JP market orders support `LIMIT` and `MARKET`; JP market time in force is `DAY`.
- US market orders in JP support `LIMIT`, `MARKET`, `STOP_LOSS`, `STOP_LOSS_LIMIT` with `DAY` or `GTC`.
- JP stock accounts are identified by `account_type`: `CASH` or `US_MARGIN`.
- `account_tax_type` is required for JP stock `place` and `preview`; valid values are `GENERAL` and `SPECIFIC`.
- `margin_type` and `position_intent` are valid only for JP `US_MARGIN` accounts (for stock orders). For US option orders, `position_intent` is supported via `option-place`.
- `close_contracts` is JP-only and accepts up to 10 objects with `contract_id` and positive `quantity`.

### SG-Specific Notes

- Configure SG with `WEBULL_REGION_ID=sg`; sandbox uses `WEBULL_ENVIRONMENT=uat`.
- SG supports US stock/ETF trading for Singapore-based clients.
- Supported order types: `MARKET`, `LIMIT`, `STOP_LOSS`, `STOP_LOSS_LIMIT`.
- Time in force: `DAY`, `GTC`.
- Trading sessions: `CORE`, `ALL`, `NIGHT`, `ALL_DAY`.
- SG order market is `US` only.
- No futures, crypto, options, event contracts, combo orders, or algo orders in SG region.

### TH-Specific Notes

- Configure TH with `WEBULL_REGION_ID=th`; sandbox uses `WEBULL_ENVIRONMENT=uat`.
- TH supports US stock/ETF trading for Thailand-based clients.
- Supported order types: `MARKET`, `LIMIT`, `STOP_LOSS`, `STOP_LOSS_LIMIT`.
- Time in force: `DAY`, `GTC`.
- Trading sessions: `CORE`, `ALL`, `NIGHT`, `ALL_DAY`.
- TH order market is `US` only.
- No futures, crypto, options, event contracts, combo orders, or algo orders in TH region.

### MY-Specific Notes

- Configure MY with `WEBULL_REGION_ID=my`; sandbox uses `WEBULL_ENVIRONMENT=uat`.
- MY supports US stock/ETF trading for Malaysia-based clients.
- Supported order types: `MARKET`, `LIMIT`, `STOP_LOSS`, `STOP_LOSS_LIMIT`.
- Time in force: `DAY`, `GTC`.
- Trading sessions: `CORE`, `ALL`, `NIGHT`, `ALL_DAY`.
- MY order market is `US` only.
- No futures, crypto, options, event contracts, combo orders, or algo orders in MY region.

### UK-Specific Notes

- Configure UK with `WEBULL_REGION_ID=uk`; sandbox uses `WEBULL_ENVIRONMENT=uat`.
- UK supports US stock/ETF trading for UK-based clients.
- Supported order types: `MARKET`, `LIMIT`, `STOP_LOSS`, `STOP_LOSS_LIMIT`.
- Time in force: `DAY`, `GTC`.
- Trading sessions: `CORE`, `ALL`, `NIGHT`, `ALL_DAY`.
- UK order market is `US` only.
- No futures, crypto, options, event contracts, combo orders, or algo orders in UK region.

### MX-Specific Notes

- Configure MX with `WEBULL_REGION_ID=mx`; sandbox uses `WEBULL_ENVIRONMENT=uat`.
- MX supports US stock/ETF trading for Mexico-based clients.
- Supported order types: `MARKET`, `LIMIT`, `STOP_LOSS`, `STOP_LOSS_LIMIT`.
- Time in force: `DAY`, `GTC`.
- Trading sessions: `CORE`, `ALL`, `NIGHT`, `ALL_DAY`.
- MX order market is `US` only.
- No futures, crypto, options, event contracts, combo orders, or algo orders in MX region.

### BR-Specific Notes

- Configure BR with `WEBULL_REGION_ID=br`; sandbox uses `WEBULL_ENVIRONMENT=uat`.
- BR supports US stock/ETF trading for Brazil-based clients.
- Supported order types: `MARKET`, `LIMIT`, `STOP_LOSS`, `STOP_LOSS_LIMIT`.
- Time in force: `DAY`, `GTC`.
- Trading sessions: `CORE`, `ALL`, `NIGHT`, `ALL_DAY`.
- BR order market is `US` only.
- No futures, crypto, options, event contracts, combo orders, or algo orders in BR region.

### EU-Specific Notes

- Configure EU with `WEBULL_REGION_ID=eu`; sandbox uses `WEBULL_ENVIRONMENT=uat`.
- EU supports US stock/ETF trading for EU-based clients.
- Supported order types: `MARKET`, `LIMIT`, `STOP_LOSS`, `STOP_LOSS_LIMIT`.
- Time in force: `DAY`, `GTC`.
- Trading sessions: `CORE`, `ALL`, `NIGHT`, `ALL_DAY`.
- EU order market is `US` only.
- No futures, crypto, options, event contracts, combo orders, or algo orders in EU region.

### ZA-Specific Notes

- Configure ZA with `WEBULL_REGION_ID=za`; sandbox uses `WEBULL_ENVIRONMENT=uat`.
- ZA supports US stock/ETF trading for South Africa-based clients.
- Supported order types: `MARKET`, `LIMIT`, `STOP_LOSS`, `STOP_LOSS_LIMIT`.
- Time in force: `DAY`, `GTC`.
- Trading sessions: `CORE`, `ALL`, `NIGHT`, `ALL_DAY`.
- ZA order market is `US` only.
- No futures, crypto, options, event contracts, combo orders, or algo orders in ZA region.

### AU-Specific Notes

- Configure AU with `WEBULL_REGION_ID=au`; sandbox uses `WEBULL_ENVIRONMENT=uat`.
- AU supports US stock/ETF trading for Australia-based clients.
- Supported order types: `MARKET`, `LIMIT`, `STOP_LOSS`, `STOP_LOSS_LIMIT`.
- Time in force: `DAY`, `GTC`.
- Trading sessions: `CORE`, `ALL`, `NIGHT`, `ALL_DAY`.
- AU order market is `US` only.
- No futures, crypto, options, event contracts, combo orders, or algo orders in AU region.

---

## Rate Limits

### US Region
- Market data: 600 req/min
- Order place/replace/cancel: 600 req/min
- Order query: 2 req/2s
- Auth: 10 req/30s

### HK Region
- Market data: 60 req/60s
- Order place: 15 req/s (US stocks), 1 req/s (HK/A-share)
- Order preview: 40 req/10s
- Order query: 40 req/2s

### JP Region
- Instrument lookup: 60 req/min per AppId
- Other endpoint limits follow the JP developer portal for the enabled account/API plan

### SG Region
- Market data: 300 req/60s
- Order place/replace/cancel: 600 req/60s
- Order query: 2 req/2s
- Auth: 10 req/30s

### TH Region
- Market data: 300 req/60s
- Order place/replace/cancel: 600 req/60s
- Order query: 2 req/2s
- Auth: 10 req/30s

### MY Region
- Market data: 300 req/60s
- Order place/replace/cancel: 600 req/60s
- Order query: 2 req/2s
- Auth: 10 req/30s

### UK Region
- Market data: 300 req/60s
- Order place/replace/cancel: 600 req/60s
- Order query: 2 req/2s
- Auth: 10 req/30s

### MX Region
- Market data: 300 req/60s
- Order place/replace/cancel: 600 req/60s
- Order query: 2 req/2s
- Auth: 10 req/30s

### BR Region
- Market data: 300 req/60s
- Order place/replace/cancel: 600 req/60s
- Order query: 2 req/2s
- Auth: 10 req/30s

### EU Region
- Market data: 60 req/60s
- Order place/replace/cancel: 60 req/60s
- Order query: 2 req/2s
- Auth: 10 req/30s

### ZA Region
- Market data: 60 req/60s
- Order place/replace/cancel: 60 req/60s
- Order query: 2 req/2s
- Auth: 10 req/30s

### AU Region
- Market data: 60 req/60s
- Order place/replace/cancel: 60 req/60s
- Order query: 2 req/2s
- Auth: 10 req/30s

---

## Detailed Module Documentation

- [Trading Guide](references/skill_trading.md) — Full order JSON formats, replace rules, order types, trading sessions
- [Market Data Guide](references/skill_market_data.md) — All market data actions, screener, watchlist, category values

## Official API Documentation

- US: https://develop

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [webull-inc](https://github.com/webull-inc)
- **Source:** [webull-inc/webull-openapi-skills](https://github.com/webull-inc/webull-openapi-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-webull-inc-webull-openapi-skills-webull-openapi-skills
- Seller: https://agentstack.voostack.com/s/webull-inc
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.