tessl/pypi-webull

The unofficial python interface for the WeBull API

Overview

Eval results

Files

Trading Operations

Name: tessl/pypi-webull
Author: tessl

Comprehensive trading functionality for placing, modifying, and cancelling orders across stocks, options, and cryptocurrencies. Supports various order types, time-in-force options, and advanced trading strategies.

Prerequisites

All trading operations require:

Successful login with valid session
Trading token obtained via get_trade_token()

Capabilities

Stock Order Placement

Place buy and sell orders for stocks with various order types and execution options.

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'):
    """
    Place a stock order.
    
    Parameters:
    - stock (str, optional): Stock symbol (e.g., 'AAPL')
    - tId (int, optional): Ticker ID (alternative to stock symbol)
    - price (float): Order price for limit orders
    - action (str): Order action - 'BUY' or 'SELL'
    - orderType (str): Order type - 'LMT', 'MKT', 'STP', 'STP_LMT'
    - enforce (str): Time in force - 'GTC', 'DAY', 'IOC', 'FOK'
    - quant (int): Quantity of shares to trade
    - outsideRegularTradingHour (bool): Allow extended hours trading
    - stpPrice (float, optional): Stop price for stop orders
    - trial_value (float, optional): Trial order value for testing
    - trial_type (str): Trial type - 'DOLLAR' or 'PERCENTAGE'
    
    Returns:
    dict: Order placement result with order ID and status
    
    Raises:
    ValueError: If required parameters are missing or invalid
    """

Usage examples:

# Market buy order
result = wb.place_order(
    stock='AAPL',
    action='BUY',
    orderType='MKT',
    quant=100
)

# Limit sell order
result = wb.place_order(
    stock='TSLA',
    price=250.00,
    action='SELL',
    orderType='LMT',
    enforce='DAY',
    quant=50
)

# Stop-loss order
result = wb.place_order(
    stock='MSFT',
    action='SELL',
    orderType='STP',
    stpPrice=300.00,
    quant=25
)

Order Modification

Modify existing orders by changing price, quantity, or other parameters.

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):
    """
    Modify an existing order.
    
    Parameters:
    - order (dict, optional): Complete order object to modify
    - order_id (int): Order ID to modify
    - stock (str, optional): Stock symbol
    - tId (int, optional): Ticker ID
    - price (float): New order price
    - action (str, optional): New order action if changing
    - orderType (str, optional): New order type if changing
    - enforce (str, optional): New time in force if changing
    - quant (int): New quantity
    - outsideRegularTradingHour (bool, optional): New extended hours setting
    
    Returns:
    dict: Modification result
    """

Usage example:

# Get current orders to find order to modify
orders = wb.get_current_orders()
order_to_modify = orders[0]  # First order

# Modify price and quantity
result = wb.modify_order(
    order_id=order_to_modify['orderId'],
    price=155.00,
    quant=75
)

Order Cancellation

Cancel individual orders or all pending orders.

def cancel_order(self, order_id=''):
    """
    Cancel a specific order.
    
    Parameters:
    - order_id (str): ID of order to cancel
    
    Returns:
    dict: Cancellation result
    """

def cancel_all_orders(self):
    """
    Cancel all pending orders.
    
    Returns:
    dict: Bulk cancellation result
    """

Usage examples:

# Cancel specific order
result = wb.cancel_order('12345678')

# Cancel all pending orders
result = wb.cancel_all_orders()

Advanced Order Types - OTOCO

One-Triggers-Other-Cancels orders for automated profit-taking and stop-loss strategies.

def place_order_otoco(self, stock='', price='', stop_loss_price='', limit_profit_price='', time_in_force='DAY', quant=0):
    """
    Place One-Triggers-Other-Cancels bracket order.
    
    Parameters:
    - stock (str): Stock symbol
    - price (str): Entry order price
    - stop_loss_price (str): Stop loss price
    - limit_profit_price (str): Take profit price
    - time_in_force (str): Time in force - 'DAY' or 'GTC'
    - quant (int): Order quantity
    
    Returns:
    dict: OTOCO order placement result with multiple order IDs
    """

def modify_order_otoco(self, order_id1='', order_id2='', order_id3='', stock='', price='', stop_loss_price='', limit_profit_price='', time_in_force='DAY', quant=0):
    """
    Modify existing OTOCO order.
    
    Parameters:
    - order_id1 (str): Primary order ID
    - order_id2 (str): Stop loss order ID
    - order_id3 (str): Take profit order ID
    - stock (str): Stock symbol
    - price (str): New entry price
    - stop_loss_price (str): New stop loss price
    - limit_profit_price (str): New take profit price
    - time_in_force (str): New time in force
    - quant (int): New quantity
    
    Returns:
    dict: Modification result
    """

def cancel_order_otoco(self, combo_id=''):
    """
    Cancel entire OTOCO order bracket.
    
    Parameters:
    - combo_id (str): OTOCO combination ID
    
    Returns:
    dict: Cancellation result
    """

Usage example:

# Place bracket order with stop loss and take profit
result = wb.place_order_otoco(
    stock='AAPL',
    price='150.00',
    stop_loss_price='145.00',
    limit_profit_price='160.00',
    time_in_force='GTC',
    quant=100
)

Cryptocurrency Trading

Trade cryptocurrencies with specialized order handling.

def place_order_crypto(self, stock=None, tId=None, price=0, action='BUY', orderType='LMT', enforce='DAY', entrust_type='QTY', quant=0, outsideRegularTradingHour=False):
    """
    Place cryptocurrency order.
    
    Parameters:
    - stock (str, optional): Crypto symbol (e.g., 'BTCUSD')
    - tId (int, optional): Ticker ID for cryptocurrency
    - price (float): Order price
    - action (str): 'BUY' or 'SELL'
    - orderType (str): Order type - 'LMT', 'MKT'
    - enforce (str): Time in force - 'DAY', 'GTC', 'IOC', 'FOK'
    - entrust_type (str): 'QTY' for quantity-based or 'AMT' for amount-based
    - quant (float): Quantity or amount to trade
    - outsideRegularTradingHour (bool): Extended hours (always available for crypto)
    
    Returns:
    dict: Crypto order placement result
    """

Usage example:

# Buy Bitcoin with limit order
result = wb.place_order_crypto(
    stock='BTCUSD',
    price=45000.00,
    action='BUY',
    orderType='LMT',
    entrust_type='QTY',
    quant=0.1
)

Options Trading

Place, modify, and cancel options orders with specialized options handling.

def place_order_option(self, optionId=None, lmtPrice=None, stpPrice=None, action=None, orderType='LMT', enforce='DAY', quant=0):
    """
    Place options order.
    
    Parameters:
    - optionId (int): Options contract ID
    - lmtPrice (float, optional): Limit price for limit orders
    - stpPrice (float, optional): Stop price for stop orders
    - action (str): 'BUY' or 'SELL'
    - orderType (str): 'LMT', 'MKT', 'STP', 'STP_LMT'
    - enforce (str): Time in force - 'DAY', 'GTC', 'IOC', 'FOK'
    - quant (int): Number of option contracts
    
    Returns:
    dict: Options order placement result
    """

def modify_order_option(self, order=None, lmtPrice=None, stpPrice=None, enforce=None, quant=0):
    """
    Modify existing options order.
    
    Parameters:
    - order (dict): Existing options order to modify
    - lmtPrice (float, optional): New limit price
    - stpPrice (float, optional): New stop price
    - enforce (str, optional): New time in force
    - quant (int): New quantity
    
    Returns:
    dict: Modification result
    """

Usage example:

# First get options chain to find option ID
options = wb.get_options(stock='AAPL', expireDate='2024-12-20')
call_option = options[0]  # First call option

# Buy call option
result = wb.place_order_option(
    optionId=call_option['derivativeId'],
    lmtPrice=5.50,
    action='BUY',
    orderType='LMT',
    quant=1
)

Trading Validation

Check if a stock is tradable before placing orders.

def get_tradable(self, stock=''):
    """
    Check if a stock is tradable on Webull.
    
    Parameters:
    - stock (str): Stock symbol to check
    
    Returns:
    dict: Trading availability information
    """

Usage example:

# Check if stock is tradable
tradable_info = wb.get_tradable('AAPL')
if tradable_info['tradable']:
    # Proceed with order placement
    wb.place_order(stock='AAPL', price=150.00, action='BUY', quant=10)

Order Types Reference

Supported Order Types

LMT (Limit): Order executes at specified price or better
MKT (Market): Order executes immediately at current market price
STP (Stop): Stop order becomes market order when stop price reached
STP_LMT (Stop Limit): Stop order becomes limit order when stop price reached

Time in Force Options

GTC (Good Till Cancelled): Order remains active until executed or cancelled
DAY: Order expires at end of trading day
IOC (Immediate or Cancel): Execute immediately, cancel unfilled portion
FOK (Fill or Kill): Execute entire order immediately or cancel

Trading Actions

BUY: Purchase securities
SELL: Sell securities (must own shares or have approved short selling)

Error Handling

Common trading errors and handling:

try:
    result = wb.place_order(
        stock='AAPL',
        price=150.00,
        action='BUY',
        quant=100
    )
    print(f"Order placed successfully: {result['orderId']}")
    
except ValueError as e:
    if "trade token" in str(e).lower():
        print("Need to get trade token first")
        wb.get_trade_token('your_trading_password')
    elif "insufficient" in str(e).lower():
        print("Insufficient buying power")
    else:
        print(f"Order failed: {e}")

Complete Trading Example

from webull import webull

wb = webull()

# Login and authenticate
wb.login('your_email@example.com', 'your_password')
wb.get_trade_token('your_trading_password')

try:
    # Check if stock is tradable
    tradable = wb.get_tradable('AAPL')
    if not tradable['tradable']:
        print("AAPL is not tradable")
        exit()
    
    # Place initial buy order
    buy_result = wb.place_order(
        stock='AAPL',
        price=150.00,
        action='BUY',
        orderType='LMT',
        enforce='GTC',
        quant=100
    )
    
    print(f"Buy order placed: {buy_result['orderId']}")
    
    # Check order status
    orders = wb.get_current_orders()
    for order in orders:
        if order['orderId'] == buy_result['orderId']:
            print(f"Order status: {order['status']}")
    
    # Place bracket order for risk management
    bracket_result = wb.place_order_otoco(
        stock='TSLA',
        price='250.00',
        stop_loss_price='240.00',
        limit_profit_price='270.00',
        quant=50
    )
    
    print(f"Bracket order placed: {bracket_result}")
    
except ValueError as e:
    print(f"Trading error: {e}")

Install with Tessl CLI