or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

alerts-screening.mdauthentication.mdindex.mdmarket-data.mdoptions.mdpaper-trading.mdportfolio.mdstreaming.mdtrading.md
tile.json

tessl/pypi-webull

The unofficial python interface for the WeBull API

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/webull@0.6.x

To install, run

npx @tessl/cli install tessl/pypi-webull@0.6.0

index.mddocs/

Webull

The unofficial Python interface for the Webull API, providing comprehensive access to trading operations, market data, portfolio management, and real-time streaming capabilities. This library enables programmatic interaction with the Webull trading platform for both live and paper trading accounts.

Package Information

  • Package Name: webull
  • Package Type: pypi
  • Language: Python
  • Installation: pip install webull
  • Requirements: Python 3.6+

Core Imports

from webull import webull, paper_webull, StreamConn

Individual class imports:

from webull import webull        # Live trading client
from webull import paper_webull  # Paper trading client  
from webull import StreamConn    # Real-time streaming

Basic Usage

from webull import webull

# Initialize client
wb = webull()

# Login with email/phone and password
wb.login('your_email@example.com', 'your_password')

# Handle MFA if required
mfa_code = input("Enter MFA code: ")
wb.check_mfa('your_email@example.com', mfa_code)

# Get trading token for placing orders
wb.get_trade_token('your_trading_password')

# Get account information
account_info = wb.get_account()
positions = wb.get_positions()

# Get real-time quote
quote = wb.get_quote(stock='AAPL')
print(f"AAPL Price: ${quote['close']}")

# Place a buy order
wb.place_order(
    stock='AAPL',
    price=150.00,
    action='BUY',
    orderType='LMT',
    quant=10
)

# Get current orders
orders = wb.get_current_orders()

Architecture

The webull package is built around three main components:

  • webull class: Core API client for live trading operations, market data access, and account management
  • paper_webull class: Specialized client for paper trading that inherits from webull with overridden methods for simulation
  • StreamConn class: MQTT-based real-time streaming client for live quotes and order updates
  • endpoints module: Internal URL management system providing API endpoint construction

The library requires Multi-Factor Authentication (MFA) for all logins and supports both email and phone number authentication. Trading operations require an additional trade token for security.

Capabilities

Authentication & Session Management

Complete user authentication system with email/phone login, Multi-Factor Authentication (MFA), security questions, and session management with token refresh capabilities.

def login(self, username='', password='', device_name='', mfa='', question_id='', question_answer='', save_token=False, token_path=None): ...
def get_mfa(self, username=''): ...
def check_mfa(self, username='', mfa=''): ...
def get_security(self, username=''): ...
def check_security(self, username='', question_id='', question_answer=''): ...
def logout(self): ...
def get_trade_token(self, password=''): ...
def is_logged_in(self): ...

Authentication

Trading Operations

Comprehensive trading functionality including order placement, modification, and cancellation for stocks, options, and cryptocurrencies. Supports various order types and advanced order strategies.

def place_order(self, stock=None, tId=None, price=0, action='BUY', orderType='LMT', enforce='GTC', quant=0, outsideRegularTradingHour=True, stpPrice=None, trial_value=0, trial_type='DOLLAR'): ...
def modify_order(self, order=None, order_id=0, stock=None, tId=None, price=0, action=None, orderType=None, enforce=None, quant=0, outsideRegularTradingHour=None): ...
def cancel_order(self, order_id=''): ...
def place_order_option(self, optionId=None, lmtPrice=None, stpPrice=None, action=None, orderType='LMT', enforce='DAY', quant=0): ...
def place_order_crypto(self, stock=None, tId=None, price=0, action='BUY', orderType='LMT', enforce='DAY', entrust_type='QTY', quant=0, outsideRegularTradingHour=False): ...

Trading

Market Data & Research

Extensive market data access including real-time quotes, historical price data, news, analyst ratings, financial statements, and institutional holdings across stocks, options, and cryptocurrencies.

def get_quote(self, stock=None, tId=None): ...
def get_bars(self, stock=None, tId=None, interval='m1', count=1, extendTrading=0, timeStamp=None): ...
def get_news(self, stock=None, tId=None, Id=0, items=20): ...
def get_analysis(self, stock=None): ...
def get_financials(self, stock=None): ...
def get_institutional_holding(self, stock=None, tId=None): ...

Market Data

Portfolio & Account Management

Complete portfolio management including positions tracking, account activities, order history, dividend information, and account details retrieval.

def get_account(self): ...
def get_positions(self): ...
def get_portfolio(self): ...
def get_activities(self, index=1, size=500): ...
def get_current_orders(self): ...
def get_history_orders(self, status='All', count=20): ...
def get_dividends(self): ...

Portfolio

Options Trading

Specialized options trading capabilities including options chain retrieval, expiration dates, strike price filtering, and options-specific order placement and management.

def get_options(self, stock=None, count=-1, includeWeekly=1, direction='all', expireDate=None, queryAll=0): ...
def get_options_expiration_dates(self, stock=None, count=-1): ...
def get_option_quote(self, stock=None, tId=None, optionId=None): ...
def get_options_by_strike_and_expire_date(self, stock=None, expireDate=None, strike=None, direction='all'): ...

Options

Real-time Streaming

MQTT-based real-time data streaming for live price updates and order status changes with subscription management and callback handling.

class StreamConn:
    def __init__(self, debug_flg=False): ...
    def connect(self, did, access_token=None): ...
    def subscribe(self, tId=None, level=105): ...
    def unsubscribe(self, tId=None, level=105): ...
    def on_price_message(self, topic, data): ...
    def on_order_message(self, topic, data): ...

Streaming

Paper Trading

Complete paper trading simulation environment that mirrors live trading functionality for testing strategies without real money. Inherits from the main webull class with specialized methods.

class paper_webull(webull):
    def __init__(self): ...
    def get_account(self): ...
    def place_order(self, stock=None, tId=None, price=0, action='BUY', orderType='LMT', enforce='GTC', quant=0, outsideRegularTradingHour=True): ...

Paper Trading

Alerts & Screening

Price alert management and stock screening capabilities for market discovery and automated monitoring of price movements and market conditions.

def alerts_list(self): ...
def alerts_add(self, stock=None, frequency=1, interval=1, priceRules=[], smartRules=[]): ...
def alerts_remove(self, alert=None, priceAlert=True, smartAlert=True): ...
def run_screener(self, region=None, price_lte=None, price_gte=None, pct_chg_gte=None, pct_chg_lte=None, sort=None, ...): ...
def active_gainer_loser(self, direction='gainer', rank_type='afterMarket', count=50): ...

Alerts & Screening

Error Handling

The webull package raises ValueError exceptions for:

  • Missing required parameters (stock symbol, credentials)
  • Invalid stock symbols that cannot be found
  • Authentication failures and invalid credentials
  • Invalid order parameters or insufficient permissions

Always wrap webull operations in try-catch blocks for production usage:

try:
    quote = wb.get_quote(stock='AAPL')
except ValueError as e:
    print(f"Error getting quote: {e}")

Common Types

# Order actions
OrderAction = 'BUY' | 'SELL'

# Order types  
OrderType = 'LMT' | 'MKT' | 'STP' | 'STP_LMT'

# Time in force
Enforce = 'GTC' | 'DAY' | 'IOC' | 'FOK'

# Options directions
OptionsDirection = 'all' | 'call' | 'put'

# Market intervals
Interval = 'm1' | 'm5' | 'm15' | 'm30' | 'h1' | 'h2' | 'h4' | 'd1' | 'w1'