CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-webull

The unofficial python interface for the WeBull API

Overview
Eval results
Files

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'

Install with Tessl CLI

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