Authentication & Session Management

def login(self, username='', password='', device_name='', mfa='', question_id='', question_answer='', save_token=False, token_path=None):
    """
    Log in to Webull account with email/phone and password.
    
    Parameters:
    - username (str): Email address or phone number in format +[country_code]-[number]
    - password (str): Account password
    - device_name (str, optional): Device identifier for login
    - mfa (str, optional): Multi-factor authentication code
    - question_id (str, optional): Security question ID if required
    - question_answer (str, optional): Answer to security question
    - save_token (bool, optional): Whether to save authentication token to file
    - token_path (str, optional): Custom path for saving token file
    
    Returns:
    dict: Login response containing access tokens and session info
    
    Raises:
    ValueError: If username or password is missing
    """

from webull import webull

wb = webull()

# Email login
response = wb.login('user@example.com', 'password123')

# Phone login (must include country code)
response = wb.login('+1-5551234567', 'password123')

# Login with token saving
response = wb.login('user@example.com', 'password123', save_token=True)

def get_mfa(self, username=''):
    """
    Request MFA code to be sent to user's registered method.
    
    Parameters:
    - username (str): Email or phone number used for login
    
    Returns:
    dict: Response indicating MFA code delivery status
    """

def check_mfa(self, username='', mfa=''):
    """
    Verify MFA code received by user.
    
    Parameters:
    - username (str): Email or phone number used for login  
    - mfa (str): Multi-factor authentication code
    
    Returns:
    dict: Verification result
    """

# Request MFA code
wb.get_mfa('user@example.com')

# User receives code via SMS/email
mfa_code = input("Enter MFA code: ")

# Verify MFA code
result = wb.check_mfa('user@example.com', mfa_code)

def get_security(self, username=''):
    """
    Get security question for additional verification.
    
    Parameters:
    - username (str): Email or phone number used for login
    
    Returns:
    dict: Security question details including question_id and question text
    """

def next_security(self, username=''):
    """
    Get next security question if multiple are available.
    
    Parameters:
    - username (str): Email or phone number used for login
    
    Returns:
    dict: Next security question details
    """

def check_security(self, username='', question_id='', question_answer=''):
    """
    Submit answer to security question.
    
    Parameters:
    - username (str): Email or phone number used for login
    - question_id (str): ID of the security question being answered
    - question_answer (str): Answer to the security question
    
    Returns:
    dict: Verification result
    """

def login_prompt(self):
    """
    Interactive login with prompts for username, password, MFA, and security questions.
    
    Returns:
    dict: Login response after successful authentication
    """

wb = webull()
# Prompts user for all required login information
wb.login_prompt()

def get_trade_token(self, password=''):
    """
    Get trading token required for order operations.
    
    Parameters:
    - password (str): Trading password (may be same as login password)
    
    Returns:
    bool: True if trade token obtained successfully, False otherwise
    """

# Get trade token for order operations
success = wb.get_trade_token('trading_password')
if success:
    print("Trade token obtained successfully")
else:
    print("Failed to get trade token")

def api_login(self, access_token='', refresh_token='', token_expire='', uuid='', mfa=''):
    """
    Authenticate using existing tokens instead of username/password.
    
    Parameters:
    - access_token (str): Valid access token
    - refresh_token (str): Refresh token for token renewal
    - token_expire (str): Token expiration timestamp
    - uuid (str): User UUID associated with tokens
    - mfa (str, optional): MFA code if required
    
    Returns:
    dict: Authentication result
    """

def refresh_login(self, save_token=False, token_path=None):
    """
    Refresh authentication using stored refresh token.
    
    Parameters:
    - save_token (bool, optional): Whether to save refreshed tokens
    - token_path (str, optional): Custom path for token file
    
    Returns:
    dict: Refresh result with new tokens
    """

def logout(self):
    """
    Log out from Webull and invalidate session.
    
    Returns:
    int: HTTP status code (200 for success)
    """

def is_logged_in(self):
    """
    Check if user is currently logged in with valid session.
    
    Returns:
    bool: True if logged in, False otherwise
    """

# Check login status
if wb.is_logged_in():
    print("User is logged in")
else:
    print("User needs to log in")

# Refresh tokens
wb.refresh_login(save_token=True)

# Logout
wb.logout()

def get_account_type(self, username=''):
    """
    Get account type information for user.
    
    Parameters:
    - username (str, optional): Username to check account type for
    
    Returns:
    dict: Account type and capabilities information
    """

from webull import webull

wb = webull()

try:
    # Initial login attempt
    response = wb.login('user@example.com', 'password123')
    
    # Handle MFA if required
    if 'mfa_required' in response:
        wb.get_mfa('user@example.com')
        mfa_code = input("Enter MFA code: ")
        wb.check_mfa('user@example.com', mfa_code)
    
    # Handle security question if required
    if 'security_required' in response:
        security = wb.get_security('user@example.com')
        print(f"Security question: {security['question']}")
        answer = input("Answer: ")
        wb.check_security('user@example.com', security['question_id'], answer)
    
    # Get trading token for order operations
    trade_success = wb.get_trade_token('trading_password')
    
    if wb.is_logged_in() and trade_success:
        print("Successfully authenticated and ready for trading")
    
except ValueError as e:
    print(f"Authentication failed: {e}")