Webull OpenAPI

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, MY, UK, MX, BR, and ZA 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
• Community (US only) — Create posts and comments, list hot stocks, browse posts by symbol, view post details, and list your own posts
• 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?

Community

• What are the community hot stocks right now?
• Show me recent community posts about NVDA
• Post "Great earnings report!" tagged with AAPL
• List my community posts

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

1. Webull Developer Account — Register at:

• US: developer.webull.com
• HK: developer.webull.hk
• JP: developer.webull.co.jp
• SG: developer.webull.com.sg
• MY: developer.webull.com.my
• UK: developer.webull-uk.com
• ZA: developer.webull.co.za
• MX: developer.webull.com.mx
• BR: developer.webull.com.br

1. API Credentials — Obtain your App Key and App Secret
2. 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
• MY: webull.com.my/quote | Guide
• UK: webull-uk.com/quote | Guide
• ZA: webullapp.co.za/quote | Guide
• MX: webull.com.mx/quote | Guide
• BR: webull.com.br/quote | Guide

1. Python 3.10+
2. 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.):

{

"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

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

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

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:

uvx webull-openapi-mcp serve

Option 2: pip

pip install webull-openapi-mcp

webull-openapi-mcp serve

Option 3: Local Development

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:

{

"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):

{

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

---

Configuration

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=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](https://develope