Webull OpenAPI MCP Server

MCP Server for Webull OpenAPI — enables AI assistants (Cursor, Claude Desktop, Kiro, etc.) to securely access Webull trading and market data.

⚠️ Disclaimer

The information provided by this tool is for reference only and does not constitute investment advice. Trading involves risk; please make decisions carefully.

See DISCLAIMER.md for the full disclaimer.

Features

Multi-Region Support — US, HK, JP, SG, TH, MY, UK, MX, BR, EU, ZA, and AU regions with region-specific order types, trading sessions, and validation
Market Data — Real-time snapshots, tick data, quotes (depth), footprint, and OHLCV bars for stocks, options, futures, crypto, and event contracts
NOII Data — Net Order Imbalance Indicator bars and snapshots for US stock opening/closing auctions
Screener — Top gainers/losers, most active, market sectors, high dividend, and 52-week high/low rankings
Watchlist — Create, manage, and query user watchlists and instruments
Fundamental Data — Company profiles, analyst ratings, and target prices
Stock & Fund Fundamentals — Capital flow, SEC filings, earnings/dividend calendar, forecast EPS, industry comparison, and full fund data (rating, performance, allocation, holdings, brief, dividends, splits, net value, files)
Financial Statements — Financial alert, indicators, income statement, balance sheet, and cash flow
Trading — Place, modify, cancel orders for stocks, options, futures, crypto, and event contracts
Combo Orders — OTO, OCO, OTOCO combo orders (US only)
Option Strategies — Multi-leg option strategies: vertical, straddle, strangle, butterfly, condor, etc. (US only)
Algo Orders — TWAP, VWAP, POV algorithmic orders (US only)
Risk Controls — Market-specific notional limits (USD/HKD/CNH/JPY), quantity limits, symbol whitelist
Auto Account Resolution — Automatically selects the correct account based on asset type (stock, futures, crypto, event)
Audit Logging — All order operations are logged for compliance
2FA Support — Interactive authentication flow for accounts with Two-Factor Authentication

Example Prompts

Here are some prompts you can use with your AI assistant:

Market Data

Show me AAPL's daily bars for the last 5 days
Get a real-time snapshot for AAPL, MSFT, and GOOGL
What's the current bid/ask for TSLA?
Show me 1-minute tick data for NVDA
Show me the NOII data for AAPL before market open

Screener

What are today's top gainers?
Show me the biggest losers in pre-market
What are the most actively traded stocks right now?
Show me the market sectors overview
List high dividend stocks
Which stocks are making new 52-week highs?

Watchlist

Show me all my watchlists
Create a new watchlist called "Tech Stocks"
Add AAPL and MSFT to my watchlist
What stocks are in my watchlist?

Fundamental & Analyst

Tell me about NVDA's company profile
What do analysts rate AAPL?
What's the analyst target price for TSLA?
Show me the capital flow for AAPL
Get TSLA's earnings calendar
Show NVDA's industry comparison
What are QQQ's top holdings and fund performance?

Financial Statements

Show me AAPL's latest income statement
Get TSLA's balance sheet for the last 4 quarters
What's NVDA's cash flow statement?
Show me the financial indicators for MSFT

Account & Portfolio

What's my account balance and buying power?
Show me all my current positions
List all my linked accounts

Stock Trading

Place a limit order to buy 100 shares of AAPL at $250
Place a market order to sell 50 shares of TSLA
Preview a limit buy order for 200 shares of MSFT at $450 before placing it

Options Trading

Buy 1 AAPL call option, strike $250, expiring 2026-04-17, limit price $5.00
Buy 1 TSLA put option, strike $200, expiring 2026-05-15

Option Market Data

Get a snapshot for AAPL260522C00300000
Show me tick data for TSLA251219C00450000
Get daily bars for AAPL260522C00300000
List available option contracts for AAPL expiring after 2026-06-01

Order Management

Show me my order history for the last 7 days
What are my current open orders?
Cancel order with ID abc123

HK Market

Place an enhanced limit order to buy 100 shares of Tencent (00700) at HKD 500
Place an at-auction limit order for 200 shares of 00700 at HKD 510

Prerequisites

Webull Developer Account — Register at:
- US: developer.webull.com
- HK: developer.webull.hk
- JP: developer.webull.co.jp
- SG: developer.webull.com.sg
- TH: developer.webull.co.th
- MY: developer.webull.com.my
- UK: developer.webull-uk.com
- EU: developer.webull.eu
- ZA: developer.webull.co.za
- AU: developer.webull.com.au
- MX: developer.webull.com.mx
- BR: developer.webull.com.br
API Credentials — Obtain your App Key and App Secret
Market Data Subscription — Subscribe to quotes for market data access:
- US: webullapp.com/quote | Guide
- HK: webullapp.hk/quote | Guide
- JP: webull.co.jp/pricing | Guide
- SG: webull.com.sg/quote | Guide
- TH: webull.co.th/quote | Guide
- MY: webull.com.my/quote | Guide
- UK: webull-uk.com/quote | Guide
- EU: webullapp.eu/quote | Guide
- ZA: webullapp.co.za/quote | Guide
- AU: webullapp.com.au/quote | Guide
- MX: webull.com.mx/quote | Guide
- BR: webull.com.br/quote | Guide
Python 3.10+
uv (recommended) — Install guide

Quick Start

Step 1: Configure Credentials

Before running the server, you must configure your API credentials. Choose one of the following approaches:

Option A: MCP client configuration (recommended for production)

Add credentials via the env field in your MCP client config (Kiro, Cursor, Claude Desktop, etc.):

config.json

{
  "mcpServers": {
    "webull": {
      "command": "uvx",
      "args": ["webull-openapi-mcp", "serve"],
      "env": {
        "WEBULL_APP_KEY": "your_app_key",
        "WEBULL_APP_SECRET": "your_app_secret",
        "WEBULL_REGION_ID": "us",
        "WEBULL_ENVIRONMENT": "prod"
      }
    }
  }
}

Option B: .env file

bash

# Create a .env file interactively:
uvx webull-openapi-mcp init

# Or manually create .env with:
# WEBULL_APP_KEY=your_app_key
# WEBULL_APP_SECRET=your_app_secret

Step 2: Authenticate (2FA)

If your account requires Two-Factor Authentication, run the auth command and approve in your Webull mobile app:

bash

uvx webull-openapi-mcp auth

Token is valid for 15 days and auto-refreshes. You only need to do this once (or when the token expires).

Step 3: Start the Server

bash

uvx webull-openapi-mcp serve

That's it. Your AI assistant can now access Webull trading and market data.

Installation Options

Option 1: uvx (Recommended)

No installation needed. uvx downloads and runs the package directly from PyPI:

bash

uvx webull-openapi-mcp serve

Option 2: pip

Terminal

pip install webull-openapi-mcp
webull-openapi-mcp serve

Option 3: Local Development

bash

git clone https://github.com/webull-inc/webull-openapi-mcp.git
cd webull-openapi-mcp
uv sync
uv run python -m webull_openapi_mcp serve

Client Configuration

Kiro / Cursor / Claude Desktop / Claude Code

Add to your MCP configuration:

Using environment variables:

config.json

{
  "mcpServers": {
    "webull": {
      "command": "uvx",
      "args": ["webull-openapi-mcp", "serve"],
      "env": {
        "WEBULL_APP_KEY": "your_app_key",
        "WEBULL_APP_SECRET": "your_app_secret",
        "WEBULL_REGION_ID": "us",
        "WEBULL_ENVIRONMENT": "prod"
      }
    }
  }
}

Using .env file (local development):

config.json

{
  "mcpServers": {
    "webull": {
      "command": "uv",
      "args": [
        "run", "--directory", "/path/to/webull-openapi-mcp",
        "python", "-m", "webull_openapi_mcp", "serve",
        "--env-file", "/path/to/.env"
      ]
    }
  }
}

Configuration

Variable	Description	Default
`WEBULL_APP_KEY`	App Key (required)	—
`WEBULL_APP_SECRET`	App Secret (required)	—
`WEBULL_ENVIRONMENT`	`uat` (sandbox) or `prod`	`uat`
`WEBULL_REGION_ID`	`us`, `hk`, `jp`, `sg`, `th`, `my`, `uk`, `mx`, `br`, `eu`, `za`, or `au`	`us`
`WEBULL_TOOLSETS`	Enabled tool categories (comma-separated). Valid values: `account`, `market-data`, `trading`, `instrument`	(all enabled)
`WEBULL_MAX_ORDER_NOTIONAL_USD`	Max order value for US market (USD)	`10000`
`WEBULL_MAX_ORDER_NOTIONAL_HKD`	Max order value for HK market (HKD)	`80000`
`WEBULL_MAX_ORDER_NOTIONAL_CNH`	Max order value for CN market (CNH)	`70000`
`WEBULL_MAX_ORDER_NOTIONAL_JPY`	Max order value for JP market (JPY)	`1500000`
`WEBULL_MAX_ORDER_QUANTITY`	Max order quantity	`1000`
`WEBULL_SYMBOL_WHITELIST`	Allowed symbols (comma-separated)	(no restriction)
`WEBULL_TOKEN_DIR`	Token storage directory	`./conf/`
`WEBULL_AUDIT_LOG_FILE`	Audit log file path	stderr only
`WEBULL_LOG_LEVEL`	SDK log level	`WARNING`

Note: WEBULL_REGION_ID=us represents Webull US (developer.webull.com), WEBULL_REGION_ID=hk represents Webull Hong Kong (developer.webull.hk), WEBULL_REGION_ID=jp represents Webull Japan (developer.webull.co.jp), WEBULL_REGION_ID=sg represents Webull Singapore (developer.webull.com.sg), WEBULL_REGION_ID=th represents Webull Thailand (developer.webull.co.th), WEBULL_REGION_ID=my represents Webull Malaysia (developer.webull.com.my), WEBULL_REGION_ID=uk represents Webull UK (developer.webull-uk.com), WEBULL_REGION_ID=mx represents Webull Mexico (developer.webull.com.mx), WEBULL_REGION_ID=br represents Webull Brazil (developer.webull.com.br), WEBULL_REGION_ID=eu represents Webull EU (developer.webull.eu), WEBULL_REGION_ID=za represents Webull South Africa (developer.webull.co.za), and WEBULL_REGION_ID=au represents Webull Australia (developer.webull.com.au).

See .env.example for full configuration template.

Available Tools

Market Data

Category	Tools	Region
Stock	`get_stock_tick`, `get_stock_snapshot`, `get_stock_quotes`, `get_stock_footprint`, `get_stock_bars`, `get_stock_bars_single`, `get_stock_noii_bars`, `get_stock_noii_snapshot`	All
Futures	`get_futures_tick`, `get_futures_snapshot`, `get_futures_depth`, `get_futures_bars`, `get_futures_footprint`	US, HK
Crypto	`get_crypto_snapshot`, `get_crypto_bars`	US
Option	`get_option_tick`, `get_option_snapshot`, `get_option_bars`	US, HK, JP
Event	`get_event_tick`, `get_event_snapshot`, `get_event_depth`, `get_event_bars`	US
Screener	`get_gainers_losers`, `get_most_active`, `get_market_sectors`, `get_market_sectors_detail`, `get_high_dividend`, `get_52_week_high_low`	All
Watchlist	`get_watchlists`, `create_watchlist`, `update_watchlist`, `delete_watchlist`, `get_watchlist_instruments`, `add_watchlist_instruments`, `remove_watchlist_instruments`, `update_watchlist_instruments`	All

Fundamental & Instrument

Category	Tools	Region
Instrument	`get_instruments`, `get_option_contracts`, `get_futures_instruments`, `get_futures_products`, `get_crypto_instruments`, `get_event_series`, `get_event_instruments`, `get_event_categories`, `get_event_events`	varies
Fundamental	`get_company_profile`, `get_analyst_rating`, `get_analyst_target_price`	All
Stock Fundamentals	`get_stock_capital_flow`, `get_stock_filings`, `get_stock_earnings_calendar`, `get_stock_dividend_calendar`, `get_stock_forecast_eps`, `get_stock_industry_comparison`	All
Fund Fundamentals	`get_fund_rating`, `get_fund_performance`, `get_fund_allocation`, `get_fund_holdings`, `get_fund_brief`, `get_fund_dividends`, `get_fund_splits`, `get_fund_net_value`, `get_fund_files`	All
Financial Statements	`get_financial_alert`, `get_financial_indicators`, `get_income_statement`, `get_balance_sheet`, `get_cash_flow`	All

Trading

Category	Tools	Region
Account	`get_account_list`	All
Assets	`get_account_balance`, `get_account_positions`, `get_account_position_details` (JP only)	All
Stock Order	`place_stock_order`, `preview_stock_order`, `replace_stock_order`	All
Combo Order	`place_stock_combo_order` (OTO/OCO/OTOCO)	US
Option Order	`place_option_single_order`, `preview_option_order`, `replace_option_order`	US, HK
Option Strategy	`place_option_strategy_order`	US
Algo Order	`place_algo_order` (TWAP/VWAP/POV)	US
Futures Order	`place_futures_order`, `replace_futures_order`	US, HK
Crypto Order	`place_crypto_order`	US
Event Order	`place_event_order`, `replace_event_order`	US
Order	`cancel_order`, `get_order_history`, `get_open_orders`, `get_order_detail`	All

Region Differences

Feature	US	HK	JP	SG	TH	MY	UK	MX	BR	EU	ZA	AU
Stock Trading	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
Option Trading	Yes	Yes	No	No	No	No	No	No	No	No	No	No
Futures Trading	Yes	Yes	No	No	No	No	No	No	No	No	No	No
Crypto Trading	Yes	No	No	No	No	No	No	No	No	No	No	No
Event Contracts	Yes	No	No	No	No	No	No	No	No	No	No	No
Combo Orders	Yes	No	No	No	No	No	No	No	No	No	No	No
Option Strategies	Yes	No	No	No	No	No	No	No	No	No	No	No
Algo Orders	Yes	No	No	No	No	No	No	No	No	No	No	No
Screener	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
Watchlist	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
Fundamental (Company/Analyst)	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
Stock/Fund Fundamentals	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
Financial Statements	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
NOII (Auction Imbalance)	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
Markets	US	US, HK, CN	US, JP	US	US	US	US	US	US	US	US	US
Instrument Categories	US_STOCK, US_ETF	US_STOCK, US_ETF, HK_STOCK, CN_STOCK	US_STOCK, US_ETF	US_STOCK, US_ETF	US_STOCK, US_ETF	US_STOCK, US_ETF	US_STOCK, US_ETF	US_STOCK, US_ETF	US_STOCK, US_ETF	US_STOCK, US_ETF	US_STOCK, US_ETF	US_STOCK, US_ETF
Order Types	LIMIT, MARKET, STOP_LOSS, STOP_LOSS_LIMIT, TRAILING_STOP_LOSS, etc.	LIMIT, MARKET, ENHANCED_LIMIT, AT_AUCTION, AT_AUCTION_LIMIT, etc.	JP market: LIMIT, MARKET — US market: LIMIT, MARKET, STOP_LOSS, STOP_LOSS_LIMIT	MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT	MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT	MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT	MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT	MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT	MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT	MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT	MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT	MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT
Time-in-Force	DAY, GTC	US market: DAY, GTC, GTD — HK market: DAY, GTC — CN market: DAY	JP market: DAY — US market: DAY, GTC, GTD	DAY, GTC	DAY, GTC	DAY, GTC	DAY, GTC	DAY, GTC	DAY, GTC	DAY, GTC	DAY, GTC	DAY, GTC
Trading Sessions	ALL, CORE, NIGHT	CORE, ALL_DAY, NIGHT, ALL	CORE, ALL, NIGHT, ALL_DAY	NIGHT, ALL, CORE, ALL_DAY	NIGHT, ALL, CORE, ALL_DAY	NIGHT, ALL, CORE, ALL_DAY	NIGHT, ALL, CORE, ALL_DAY	NIGHT, ALL, CORE, ALL_DAY	NIGHT, ALL, CORE, ALL_DAY	NIGHT, ALL, CORE, ALL_DAY	NIGHT, ALL, CORE, ALL_DAY	NIGHT, ALL, CORE, ALL_DAY
JP Order Fields	—	—	`account_tax_type` required (GENERAL or SPECIFIC); `margin_type` (ONE_DAY or INDEFINITE) and `position_intent` optional margin-account-only fields; `close_contracts` optional	—	—	—	—	—	—	—	—	—

Note: Screener (Gainers/Losers/Active), Fundamental (Company/Analyst), and NOII currently only support querying US stock data (US_STOCK category). Stock/Fund Fundamentals, Financial Statements, and the extended Screener (Sectors/Dividend/52W) are available in all regions; supported category values vary by endpoint (commonly US_STOCK, HK_STOCK, CN_STOCK, JP_STOCK). Watchlist supports US stocks and HK stocks.

CLI Commands

If installed via pip:

bash

webull-openapi-mcp --version                        # Show version
webull-openapi-mcp init [--env-file PATH]           # Initialize .env configuration
webull-openapi-mcp init --app-key KEY --app-secret SECRET --environment prod
webull-openapi-mcp auth [--env-file PATH]           # Authenticate (2FA accounts)
webull-openapi-mcp serve [--env-file PATH]          # Start MCP server
webull-openapi-mcp status [--env-file PATH]         # Show configuration status
webull-openapi-mcp tools [--env-file PATH]          # List available tools

If using uvx (prefix with uvx):

bash

uvx webull-openapi-mcp auth
uvx webull-openapi-mcp serve
uvx webull-openapi-mcp status

If local development (prefix with uv run python -m webull_openapi_mcp):

bash

uv run python -m webull_openapi_mcp auth
uv run python -m webull_openapi_mcp serve

All commands accept --env-file PATH to specify a custom .env file location (default: .env in the current directory).

Security

Never share your AK/SK with AI models — Do not paste your App Key or App Secret into chat prompts, AI assistants, or any LLM conversation. These credentials should only be configured via environment variables or .env files, never exposed in plain text to the model.
Prefer env over .env files — Pass credentials via the MCP client's env field (in mcp.json) rather than a .env file in your workspace. The env field injects credentials as process environment variables, which the AI model cannot access. A .env file in your workspace could be read by the AI assistant through IDE file access.
Credential isolation — AK/SK are used only inside the MCP server process for SDK initialization and request signing. They never appear in tool outputs, logs, or error messages.
Review before trading — Always review order details proposed by the AI before confirming. Use preview_stock_order / preview_option_order before placing orders.
Use toolset filtering — Set WEBULL_TOOLSETS=account,market-data to disable trading tools entirely if you only need read-only access. Valid toolsets: account, market-data, trading, instrument.
Default sandbox — The server defaults to UAT (sandbox) environment. You must explicitly set WEBULL_ENVIRONMENT=prod for live trading.
Dependency security — fastmcp is pinned to version 3.0.2 and webull-openapi-python-sdk is pinned to 2.0.16. Users are responsible for monitoring and updating third-party dependencies for security patches. Review release notes before upgrading.

Troubleshooting

2FA Authentication Required

bash

# If installed via pip:
webull-openapi-mcp auth

# If using uvx:
uvx webull-openapi-mcp auth

# If local development:
uv run python -m webull_openapi_mcp auth

Approve the request in your Webull app, then start the server.

Device Not Registered

Open Webull mobile app, log in with your API account, complete device registration
Then authenticate:

bash

# If installed via pip:
webull-openapi-mcp auth

# If using uvx:
uvx webull-openapi-mcp auth

Market Data 401/403

Subscribe to quotes:

Token Expired

bash

rm -rf ./conf/token.txt

# Then re-authenticate:
webull-openapi-mcp auth       # pip
uvx webull-openapi-mcp auth   # uvx

Windows: Garbled Characters in Error Messages

On Windows, authentication error messages may display garbled characters if the console encoding is not UTF-8. The server automatically detects the console encoding and falls back to ASCII-only output on non-UTF-8 terminals. If you still see garbled text, run:

cmd

chcp 65001

This switches the Windows console to UTF-8 before starting the server.

Project Structure

Code

webull-openapi-mcp/
├── webull_openapi_mcp/
│   ├── __init__.py         # Package version
│   ├── __main__.py         # python -m entry point
│   ├── cli.py              # CLI commands (init, auth, serve, status, tools)
│   ├── server.py           # MCP server setup and tool registration
│   ├── sdk_client.py       # Webull SDK adapter (ApiClient, TradeClient, DataClient)
│   ├── config.py           # Configuration loading and validation
│   ├── region_config.py    # Region-specific settings (US, HK, JP, SG, TH, MY, UK, MX, BR)
│   ├── guards.py           # Order validation (price, quantity, notional, region rules)
│   ├── audit.py            # Audit logging for order operations
│   ├── errors.py           # Exception definitions and SDK error handling
│   ├── formatters.py       # Response formatting with disclaimer
│   ├── constants.py        # Enum constants (sides, order types, strategies)
│   └── tools/
│       ├── __init__.py     # Tool registration exports
│       ├── market_data/
│       │   ├── stock.py    # Stock market data (snapshot, quotes, bars, tick, footprint, NOII)
│       │   ├── option.py   # Option market data (tick, snapshot, bars)
│       │   ├── futures.py  # Futures market data
│       │   ├── crypto.py   # Crypto market data
│       │   ├── event.py    # Event contract market data
│       │   ├── screener.py # Gainers/losers, most active, market sectors, high dividend, 52-week high/low
│       │   ├── watchlist.py# Watchlist CRUD and instrument management
│       │   ├── fundamental.py # Company profile, analyst data; stock & fund fundamentals (US/HK/JP)
│       │   └── financial.py   # Financial statements: alert, indicators, income, balance sheet, cash flow (US/HK/JP)
│       └── trading/
│           ├── account.py       # Account list
│           ├── assets.py        # Balance, positions
│           ├── instrument.py    # Instrument lookup
│           ├── order.py         # Order query, cancel (shared across asset types)
│           ├── stock_order.py   # Stock order place, preview, replace
│           ├── option_order.py  # Option single-leg and strategy orders
│           ├── futures_order.py # Futures order place, replace
│           ├── crypto_order.py  # Crypto order place
│           └── event_order.py   # Event contract order place, replace
├── tests/                  # Unit and property-based tests
├── conf/                   # Token storage (auto-generated)
├── .env.example            # Configuration template
├── DISCLAIMER.md           # Full disclaimer
├── pyproject.toml          # Package configuration
└── LICENSE                 # Apache 2.0

License

Apache License 2.0 — see LICENSE for details.