{
  "markdown": "<!-- mcp-name: io.github.webull-inc/webull-openapi-mcp -->\n\n# Webull OpenAPI MCP Server\n\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)\n\nMCP Server for Webull OpenAPI — enables AI assistants (Cursor, Claude Desktop, Kiro, etc.) to securely access Webull trading and market data.\n\n---\n\n## ⚠️ Disclaimer\n\nThe information provided by this tool is for reference only and does not constitute investment advice. Trading involves risk; please make decisions carefully.\n\nSee [DISCLAIMER.md](DISCLAIMER.md) for the full disclaimer.\n\n---\n\n## Features\n\n- **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\n- **Market Data** — Real-time snapshots, tick data, quotes (depth), footprint, and OHLCV bars for stocks, options, futures, crypto, and event contracts\n- **NOII Data** — Net Order Imbalance Indicator bars and snapshots for US stock opening/closing auctions\n- **Screener** — Top gainers/losers, most active, market sectors, high dividend, and 52-week high/low rankings\n- **Watchlist** — Create, manage, and query user watchlists and instruments\n- **Fundamental Data** — Company profiles, analyst ratings, and target prices\n- **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)\n- **Financial Statements** — Financial alert, indicators, income statement, balance sheet, and cash flow\n- **Trading** — Place, modify, cancel orders for stocks, options, futures, crypto, and event contracts\n- **Combo Orders** — OTO, OCO, OTOCO combo orders (US only)\n- **Option Strategies** — Multi-leg option strategies: vertical, straddle, strangle, butterfly, condor, etc. (US only)\n- **Algo Orders** — TWAP, VWAP, POV algorithmic orders (US only)\n- **Risk Controls** — Market-specific notional limits (USD/HKD/CNH/JPY), quantity limits, symbol whitelist\n- **Auto Account Resolution** — Automatically selects the correct account based on asset type (stock, futures, crypto, event)\n- **Audit Logging** — All order operations are logged for compliance\n- **2FA Support** — Interactive authentication flow for accounts with Two-Factor Authentication\n\n---\n\n## Example Prompts\n\nHere are some prompts you can use with your AI assistant:\n\n**Market Data**\n- Show me AAPL's daily bars for the last 5 days\n- Get a real-time snapshot for AAPL, MSFT, and GOOGL\n- What's the current bid/ask for TSLA?\n- Show me 1-minute tick data for NVDA\n- Show me the NOII data for AAPL before market open\n\n**Screener**\n- What are today's top gainers?\n- Show me the biggest losers in pre-market\n- What are the most actively traded stocks right now?\n- Show me the market sectors overview\n- List high dividend stocks\n- Which stocks are making new 52-week highs?\n\n**Watchlist**\n- Show me all my watchlists\n- Create a new watchlist called \"Tech Stocks\"\n- Add AAPL and MSFT to my watchlist\n- What stocks are in my watchlist?\n\n**Fundamental & Analyst**\n- Tell me about NVDA's company profile\n- What do analysts rate AAPL?\n- What's the analyst target price for TSLA?\n- Show me the capital flow for AAPL\n- Get TSLA's earnings calendar\n- Show NVDA's industry comparison\n- What are QQQ's top holdings and fund performance?\n\n**Financial Statements**\n- Show me AAPL's latest income statement\n- Get TSLA's balance sheet for the last 4 quarters\n- What's NVDA's cash flow statement?\n- Show me the financial indicators for MSFT\n\n**Account & Portfolio**\n- What's my account balance and buying power?\n- Show me all my current positions\n- List all my linked accounts\n\n**Stock Trading**\n- Place a limit order to buy 100 shares of AAPL at $250\n- Place a market order to sell 50 shares of TSLA\n- Preview a limit buy order for 200 shares of MSFT at $450 before placing it\n\n**Options Trading**\n- Buy 1 AAPL call option, strike $250, expiring 2026-04-17, limit price $5.00\n- Buy 1 TSLA put option, strike $200, expiring 2026-05-15\n\n**Option Market Data**\n- Get a snapshot for AAPL260522C00300000\n- Show me tick data for TSLA251219C00450000\n- Get daily bars for AAPL260522C00300000\n- List available option contracts for AAPL expiring after 2026-06-01\n\n**Order Management**\n- Show me my order history for the last 7 days\n- What are my current open orders?\n- Cancel order with ID abc123\n\n**HK Market**\n- Place an enhanced limit order to buy 100 shares of Tencent (00700) at HKD 500\n- Place an at-auction limit order for 200 shares of 00700 at HKD 510\n\n---\n\n## Prerequisites\n\n1. **Webull Developer Account** — Register at:\n   - US: [developer.webull.com](https://developer.webull.com/apis/home)\n   - HK: [developer.webull.hk](https://developer.webull.hk/apis/home)\n   - JP: [developer.webull.co.jp](https://developer.webull.co.jp/)\n   - SG: [developer.webull.com.sg](https://developer.webull.com.sg/apis/home)\n   - TH: [developer.webull.co.th](https://developer.webull.co.th/apis/home)\n   - MY: [developer.webull.com.my](https://developer.webull.com.my/apis/home)\n   - UK: [developer.webull-uk.com](https://developer.webull-uk.com/apis/home)\n   - EU: [developer.webull.eu](https://developer.webull.eu/apis/home)\n   - ZA: [developer.webull.co.za](https://developer.webull.co.za/apis/home)\n   - AU: [developer.webull.com.au](https://developer.webull.com.au/apis/home)\n   - MX: [developer.webull.com.mx](https://developer.webull.com.mx/apis/home)\n   - BR: [developer.webull.com.br](https://developer.webull.com.br/apis/home)\n2. **API Credentials** — Obtain your `App Key` and `App Secret`\n3. **Market Data Subscription** — Subscribe to quotes for market data access:\n   - US: [webullapp.com/quote](https://www.webullapp.com/quote) | [Guide](https://developer.webull.com/apis/docs/market-data-api/subscribe-quotes)\n   - HK: [webullapp.hk/quote](https://www.webullapp.hk/quote) | [Guide](https://developer.webull.hk/apis/docs/market-data-api/subscribe-quotes)\n   - JP: [webull.co.jp/pricing](https://www.webull.co.jp/pricing) | [Guide](https://developer.webull.co.jp/api-doc/market-data/subscribe-quotes/)\n   - SG: [webull.com.sg/quote](https://www.webull.com.sg/quote) | [Guide](https://developer.webull.com.sg/apis/docs/market-data-api/subscribe-quotes)\n   - TH: [webull.co.th/quote](https://www.webull.co.th/quote) | [Guide](https://developer.webull.co.th/apis/docs/market-data-api/subscribe-quotes)\n   - MY: [webull.com.my/quote](https://www.webull.com.my/quote) | [Guide](https://developer.webull.com.my/apis/docs/market-data-api/subscribe-quotes)\n   - UK: [webull-uk.com/quote](https://www.webull-uk.com/quote) | [Guide](https://developer.webull-uk.com/apis/docs/market-data-api/subscribe-quotes)\n   - EU: [webullapp.eu/quote](https://www.webullapp.eu/quote) | [Guide](https://developer.webull.eu/apis/docs/market-data-api/subscribe-quotes)\n   - ZA: [webullapp.co.za/quote](https://www.webullapp.co.za/quote) | [Guide](https://developer.webull.co.za/apis/docs/market-data-api/subscribe-quotes)\n   - AU: [webullapp.com.au/quote](https://www.webullapp.com.au/quote) | [Guide](https://developer.webull.com.au/apis/docs/market-data-api/subscribe-quotes)\n   - MX: [webull.com.mx/quote](https://www.webull.com.mx/quote) | [Guide](https://developer.webull.com.mx/apis/docs/market-data-api/subscribe-quotes)\n   - BR: [webull.com.br/quote](https://www.webull.com.br/quote) | [Guide](https://developer.webull.com.br/apis/docs/market-data-api/subscribe-quotes)\n4. **Python 3.10+**\n5. **uv** (recommended) — [Install guide](https://docs.astral.sh/uv/getting-started/installation/)\n\n---\n\n## Quick Start\n\n### Step 1: Configure Credentials\n\nBefore running the server, you must configure your API credentials. Choose one of the following approaches:\n\n**Option A: MCP client configuration (recommended for production)**\n\nAdd credentials via the `env` field in your MCP client config (Kiro, Cursor, Claude Desktop, etc.):\n\n```json\n{\n  \"mcpServers\": {\n    \"webull\": {\n      \"command\": \"uvx\",\n      \"args\": [\"webull-openapi-mcp\", \"serve\"],\n      \"env\": {\n        \"WEBULL_APP_KEY\": \"your_app_key\",\n        \"WEBULL_APP_SECRET\": \"your_app_secret\",\n        \"WEBULL_REGION_ID\": \"us\",\n        \"WEBULL_ENVIRONMENT\": \"prod\"\n      }\n    }\n  }\n}\n```\n\n**Option B: .env file**\n\n```bash\n# Create a .env file interactively:\nuvx webull-openapi-mcp init\n\n# Or manually create .env with:\n# WEBULL_APP_KEY=your_app_key\n# WEBULL_APP_SECRET=your_app_secret\n```\n\n### Step 2: Authenticate (2FA)\n\nIf your account requires Two-Factor Authentication, run the auth command and approve in your Webull mobile app:\n\n```bash\nuvx webull-openapi-mcp auth\n```\n\nToken is valid for 15 days and auto-refreshes. You only need to do this once (or when the token expires).\n\n### Step 3: Start the Server\n\n```bash\nuvx webull-openapi-mcp serve\n```\n\nThat's it. Your AI assistant can now access Webull trading and market data.\n\n---\n\n## Installation Options\n\n### Option 1: uvx (Recommended)\n\nNo installation needed. `uvx` downloads and runs the package directly from PyPI:\n\n```bash\nuvx webull-openapi-mcp serve\n```\n\n### Option 2: pip\n\n```bash\npip install webull-openapi-mcp\nwebull-openapi-mcp serve\n```\n\n### Option 3: Local Development\n\n```bash\ngit clone https://github.com/webull-inc/webull-openapi-mcp.git\ncd webull-openapi-mcp\nuv sync\nuv run python -m webull_openapi_mcp serve\n```\n\n---\n\n## Client Configuration\n\n### Kiro / Cursor / Claude Desktop / Claude Code\n\nAdd to your MCP configuration:\n\n**Using environment variables:**\n\n```json\n{\n  \"mcpServers\": {\n    \"webull\": {\n      \"command\": \"uvx\",\n      \"args\": [\"webull-openapi-mcp\", \"serve\"],\n      \"env\": {\n        \"WEBULL_APP_KEY\": \"your_app_key\",\n        \"WEBULL_APP_SECRET\": \"your_app_secret\",\n        \"WEBULL_REGION_ID\": \"us\",\n        \"WEBULL_ENVIRONMENT\": \"prod\"\n      }\n    }\n  }\n}\n```\n\n**Using .env file (local development):**\n\n```json\n{\n  \"mcpServers\": {\n    \"webull\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\", \"--directory\", \"/path/to/webull-openapi-mcp\",\n        \"python\", \"-m\", \"webull_openapi_mcp\", \"serve\",\n        \"--env-file\", \"/path/to/.env\"\n      ]\n    }\n  }\n}\n```\n\n---\n\n## Configuration\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `WEBULL_APP_KEY` | App Key (required) | — |\n| `WEBULL_APP_SECRET` | App Secret (required) | — |\n| `WEBULL_ENVIRONMENT` | `uat` (sandbox) or `prod` | `uat` |\n| `WEBULL_REGION_ID` | `us`, `hk`, `jp`, `sg`, `th`, `my`, `uk`, `mx`, `br`, `eu`, `za`, or `au` | `us` |\n| `WEBULL_TOOLSETS` | Enabled tool categories (comma-separated). Valid values: `account`, `market-data`, `trading`, `instrument` | (all enabled) |\n| `WEBULL_MAX_ORDER_NOTIONAL_USD` | Max order value for US market (USD) | `10000` |\n| `WEBULL_MAX_ORDER_NOTIONAL_HKD` | Max order value for HK market (HKD) | `80000` |\n| `WEBULL_MAX_ORDER_NOTIONAL_CNH` | Max order value for CN market (CNH) | `70000` |\n| `WEBULL_MAX_ORDER_NOTIONAL_JPY` | Max order value for JP market (JPY) | `1500000` |\n| `WEBULL_MAX_ORDER_QUANTITY` | Max order quantity | `1000` |\n| `WEBULL_SYMBOL_WHITELIST` | Allowed symbols (comma-separated) | (no restriction) |\n| `WEBULL_TOKEN_DIR` | Token storage directory | `./conf/` |\n| `WEBULL_AUDIT_LOG_FILE` | Audit log file path | stderr only |\n| `WEBULL_LOG_LEVEL` | SDK log level | `WARNING` |\n\n> **Note:** `WEBULL_REGION_ID=us` represents **Webull US** ([developer.webull.com](https://developer.webull.com/apis/home)), `WEBULL_REGION_ID=hk` represents **Webull Hong Kong** ([developer.webull.hk](https://developer.webull.hk/apis/home)), `WEBULL_REGION_ID=jp` represents **Webull Japan** ([developer.webull.co.jp](https://developer.webull.co.jp/)), `WEBULL_REGION_ID=sg` represents **Webull Singapore** ([developer.webull.com.sg](https://developer.webull.com.sg/apis/home)), `WEBULL_REGION_ID=th` represents **Webull Thailand** ([developer.webull.co.th](https://developer.webull.co.th/apis/home)), `WEBULL_REGION_ID=my` represents **Webull Malaysia** ([developer.webull.com.my](https://developer.webull.com.my/apis/home)), `WEBULL_REGION_ID=uk` represents **Webull UK** ([developer.webull-uk.com](https://developer.webull-uk.com/apis/home)), `WEBULL_REGION_ID=mx` represents **Webull Mexico** ([developer.webull.com.mx](https://developer.webull.com.mx/apis/home)), `WEBULL_REGION_ID=br` represents **Webull Brazil** ([developer.webull.com.br](https://developer.webull.com.br/apis/home)), `WEBULL_REGION_ID=eu` represents **Webull EU** ([developer.webull.eu](https://developer.webull.eu/apis/home)), `WEBULL_REGION_ID=za` represents **Webull South Africa** ([developer.webull.co.za](https://developer.webull.co.za/apis/home)), and `WEBULL_REGION_ID=au` represents **Webull Australia** ([developer.webull.com.au](https://developer.webull.com.au/apis/home)).\n\nSee [.env.example](.env.example) for full configuration template.\n\n---\n\n## Available Tools\n\n### Market Data\n\n| Category | Tools                                                                                                                                                                                                  | Region |\n|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------|\n| **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 |\n| **Futures** | `get_futures_tick`, `get_futures_snapshot`, `get_futures_depth`, `get_futures_bars`, `get_futures_footprint`                                                                                           | US, HK |\n| **Crypto** | `get_crypto_snapshot`, `get_crypto_bars`                                                                                                                                                               | US |\n| **Option** | `get_option_tick`, `get_option_snapshot`, `get_option_bars`                                                                                                                                            | US, HK, JP |\n| **Event** | `get_event_tick`, `get_event_snapshot`, `get_event_depth`, `get_event_bars`                                                                                                                            | US |\n| **Screener** | `get_gainers_losers`, `get_most_active`, `get_market_sectors`, `get_market_sectors_detail`, `get_high_dividend`, `get_52_week_high_low`                                                                                                                                                              | All |\n| **Watchlist** | `get_watchlists`, `create_watchlist`, `update_watchlist`, `delete_watchlist`, `get_watchlist_instruments`, `add_watchlist_instruments`, `remove_watchlist_instruments`, `update_watchlist_instruments` | All |\n\n### Fundamental & Instrument\n\n| Category | Tools | Region |\n|----------|-------|--------|\n| **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 |\n| **Fundamental** | `get_company_profile`, `get_analyst_rating`, `get_analyst_target_price` | All |\n| **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 |\n| **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 |\n| **Financial Statements** | `get_financial_alert`, `get_financial_indicators`, `get_income_statement`, `get_balance_sheet`, `get_cash_flow` | All |\n\n### Trading\n\n| Category | Tools | Region |\n|----------|-------|--------|\n| **Account** | `get_account_list` | All |\n| **Assets** | `get_account_balance`, `get_account_positions`, `get_account_position_details` (JP only) | All |\n| **Stock Order** | `place_stock_order`, `preview_stock_order`, `replace_stock_order` | All |\n| **Combo Order** | `place_stock_combo_order` (OTO/OCO/OTOCO) | US |\n| **Option Order** | `place_option_single_order`, `preview_option_order`, `replace_option_order` | US, HK |\n| **Option Strategy** | `place_option_strategy_order` | US |\n| **Algo Order** | `place_algo_order` (TWAP/VWAP/POV) | US |\n| **Futures Order** | `place_futures_order`, `replace_futures_order` | US, HK |\n| **Crypto Order** | `place_crypto_order` | US |\n| **Event Order** | `place_event_order`, `replace_event_order` | US |\n| **Order** | `cancel_order`, `get_order_history`, `get_open_orders`, `get_order_detail` | All |\n\n### Region Differences\n\n| Feature                     | US | HK | JP | SG | TH | MY | UK | MX | BR | EU | ZA | AU |\n|-----------------------------|----|----|----|----|----|----|-----|----|----|----|----|-----|\n| Stock Trading               | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |\n| Option Trading              | Yes | Yes | No | No | No | No | No | No | No | No | No | No |\n| Futures Trading             | Yes | Yes | No | No | No | No | No | No | No | No | No | No |\n| Crypto Trading              | Yes | No | No | No | No | No | No | No | No | No | No | No |\n| Event Contracts             | Yes | No | No | No | No | No | No | No | No | No | No | No |\n| Combo Orders                | Yes | No | No | No | No | No | No | No | No | No | No | No |\n| Option Strategies           | Yes | No | No | No | No | No | No | No | No | No | No | No |\n| Algo Orders                 | Yes | No | No | No | No | No | No | No | No | No | No | No |\n| Screener                    | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |\n| Watchlist                   | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |\n| Fundamental (Company/Analyst) | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |\n| Stock/Fund Fundamentals     | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |\n| Financial Statements        | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |\n| NOII (Auction Imbalance)    | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |\n| Markets                     | US | US, HK, CN | US, JP | US | US | US | US | US | US | US | US | US |\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n| 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 | — | — | — | — | — | — | — | — | — |\n\n> **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.\n\n---\n\n## CLI Commands\n\n**If installed via pip:**\n\n```bash\nwebull-openapi-mcp --version                        # Show version\nwebull-openapi-mcp init [--env-file PATH]           # Initialize .env configuration\nwebull-openapi-mcp init --app-key KEY --app-secret SECRET --environment prod\nwebull-openapi-mcp auth [--env-file PATH]           # Authenticate (2FA accounts)\nwebull-openapi-mcp serve [--env-file PATH]          # Start MCP server\nwebull-openapi-mcp status [--env-file PATH]         # Show configuration status\nwebull-openapi-mcp tools [--env-file PATH]          # List available tools\n```\n\n**If using uvx** (prefix with `uvx`):\n\n```bash\nuvx webull-openapi-mcp auth\nuvx webull-openapi-mcp serve\nuvx webull-openapi-mcp status\n```\n\n**If local development** (prefix with `uv run python -m webull_openapi_mcp`):\n\n```bash\nuv run python -m webull_openapi_mcp auth\nuv run python -m webull_openapi_mcp serve\n```\n\nAll commands accept `--env-file PATH` to specify a custom `.env` file location (default: `.env` in the current directory).\n\n---\n\n## Security\n\n- **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.\n- **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.\n- **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.\n- **Review before trading** — Always review order details proposed by the AI before confirming. Use `preview_stock_order` / `preview_option_order` before placing orders.\n- **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`.\n- **Default sandbox** — The server defaults to UAT (sandbox) environment. You must explicitly set `WEBULL_ENVIRONMENT=prod` for live trading.\n- **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.\n\n---\n\n## Troubleshooting\n\n### 2FA Authentication Required\n\n```bash\n# If installed via pip:\nwebull-openapi-mcp auth\n\n# If using uvx:\nuvx webull-openapi-mcp auth\n\n# If local development:\nuv run python -m webull_openapi_mcp auth\n```\n\nApprove the request in your Webull app, then start the server.\n\n### Device Not Registered\n\n1. Open Webull mobile app, log in with your API account, complete device registration\n2. Then authenticate:\n\n```bash\n# If installed via pip:\nwebull-openapi-mcp auth\n\n# If using uvx:\nuvx webull-openapi-mcp auth\n```\n\n### Market Data 401/403\n\nSubscribe to quotes:\n- US: [webullapp.com/quote](https://www.webullapp.com/quote) | [Guide](https://developer.webull.com/apis/docs/market-data-api/subscribe-quotes)\n- HK: [webullapp.hk/quote](https://www.webullapp.hk/quote) | [Guide](https://developer.webull.hk/apis/docs/market-data-api/subscribe-quotes)\n- JP: [webull.co.jp/pricing](https://www.webull.co.jp/pricing) | [Guide](https://developer.webull.co.jp/api-doc/market-data/subscribe-quotes/)\n- SG: [webull.com.sg/quote](https://www.webull.com.sg/quote) | [Guide](https://developer.webull.com.sg/apis/docs/market-data-api/subscribe-quotes)\n- TH: [webull.co.th/quote](https://www.webull.co.th/quote) | [Guide](https://developer.webull.co.th/apis/docs/market-data-api/subscribe-quotes)\n- MY: [webull.com.my/quote](https://www.webull.com.my/quote) | [Guide](https://developer.webull.com.my/apis/docs/market-data-api/subscribe-quotes)\n- UK: [webull-uk.com/quote](https://www.webull-uk.com/quote) | [Guide](https://developer.webull-uk.com/apis/docs/market-data-api/subscribe-quotes)\n- EU: [webullapp.eu/quote](https://www.webullapp.eu/quote) | [Guide](https://developer.webull.eu/apis/docs/market-data-api/subscribe-quotes)\n- ZA: [webullapp.co.za/quote](https://www.webullapp.co.za/quote) | [Guide](https://developer.webull.co.za/apis/docs/market-data-api/subscribe-quotes)\n- AU: [webullapp.com.au/quote](https://www.webullapp.com.au/quote) | [Guide](https://developer.webull.com.au/apis/docs/market-data-api/subscribe-quotes)\n- MX: [webull.com.mx/quote](https://www.webull.com.mx/quote) | [Guide](https://developer.webull.com.mx/apis/docs/market-data-api/subscribe-quotes)\n- BR: [webull.com.br/quote](https://www.webull.com.br/quote) | [Guide](https://developer.webull.com.br/apis/docs/market-data-api/subscribe-quotes)\n\n### Token Expired\n\n```bash\nrm -rf ./conf/token.txt\n\n# Then re-authenticate:\nwebull-openapi-mcp auth       # pip\nuvx webull-openapi-mcp auth   # uvx\n```\n\n### Windows: Garbled Characters in Error Messages\n\nOn 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:\n\n```cmd\nchcp 65001\n```\n\nThis switches the Windows console to UTF-8 before starting the server.\n\n---\n\n## Project Structure\n\n```\nwebull-openapi-mcp/\n├── webull_openapi_mcp/\n│   ├── __init__.py         # Package version\n│   ├── __main__.py         # python -m entry point\n│   ├── cli.py              # CLI commands (init, auth, serve, status, tools)\n│   ├── server.py           # MCP server setup and tool registration\n│   ├── sdk_client.py       # Webull SDK adapter (ApiClient, TradeClient, DataClient)\n│   ├── config.py           # Configuration loading and validation\n│   ├── region_config.py    # Region-specific settings (US, HK, JP, SG, TH, MY, UK, MX, BR)\n│   ├── guards.py           # Order validation (price, quantity, notional, region rules)\n│   ├── audit.py            # Audit logging for order operations\n│   ├── errors.py           # Exception definitions and SDK error handling\n│   ├── formatters.py       # Response formatting with disclaimer\n│   ├── constants.py        # Enum constants (sides, order types, strategies)\n│   └── tools/\n│       ├── __init__.py     # Tool registration exports\n│       ├── market_data/\n│       │   ├── stock.py    # Stock market data (snapshot, quotes, bars, tick, footprint, NOII)\n│       │   ├── option.py   # Option market data (tick, snapshot, bars)\n│       │   ├── futures.py  # Futures market data\n│       │   ├── crypto.py   # Crypto market data\n│       │   ├── event.py    # Event contract market data\n│       │   ├── screener.py # Gainers/losers, most active, market sectors, high dividend, 52-week high/low\n│       │   ├── watchlist.py# Watchlist CRUD and instrument management\n│       │   ├── fundamental.py # Company profile, analyst data; stock & fund fundamentals (US/HK/JP)\n│       │   └── financial.py   # Financial statements: alert, indicators, income, balance sheet, cash flow (US/HK/JP)\n│       └── trading/\n│           ├── account.py       # Account list\n│           ├── assets.py        # Balance, positions\n│           ├── instrument.py    # Instrument lookup\n│           ├── order.py         # Order query, cancel (shared across asset types)\n│           ├── stock_order.py   # Stock order place, preview, replace\n│           ├── option_order.py  # Option single-leg and strategy orders\n│           ├── futures_order.py # Futures order place, replace\n│           ├── crypto_order.py  # Crypto order place\n│           └── event_order.py   # Event contract order place, replace\n├── tests/                  # Unit and property-based tests\n├── conf/                   # Token storage (auto-generated)\n├── .env.example            # Configuration template\n├── DISCLAIMER.md           # Full disclaimer\n├── pyproject.toml          # Package configuration\n└── LICENSE                 # Apache 2.0\n```\n\n---\n\n## License\n\nApache License 2.0 — see [LICENSE](LICENSE) for details.\n",
  "bytes": 29224,
  "sha": "cd56123aec95b33e6d8cc2fca41728ece244944a67316113d7d4397d65fb73b2",
  "repo_slug": "webull-inc/webull-openapi-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_webull_inc_webull_openapi_mcp_6dae35f6/readme"
}