0
# Webull
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: webull
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install webull`
10
- **Requirements**: Python 3.6+
11
12
## Core Imports
13
14
```python
15
from webull import webull, paper_webull, StreamConn
16
```
17
18
Individual class imports:
19
20
```python
21
from webull import webull # Live trading client
22
from webull import paper_webull # Paper trading client
23
from webull import StreamConn # Real-time streaming
24
```
25
26
## Basic Usage
27
28
```python
29
from webull import webull
30
31
# Initialize client
32
wb = webull()
33
34
# Login with email/phone and password
35
wb.login('your_email@example.com', 'your_password')
36
37
# Handle MFA if required
38
mfa_code = input("Enter MFA code: ")
39
wb.check_mfa('your_email@example.com', mfa_code)
40
41
# Get trading token for placing orders
42
wb.get_trade_token('your_trading_password')
43
44
# Get account information
45
account_info = wb.get_account()
46
positions = wb.get_positions()
47
48
# Get real-time quote
49
quote = wb.get_quote(stock='AAPL')
50
print(f"AAPL Price: ${quote['close']}")
51
52
# Place a buy order
53
wb.place_order(
54
stock='AAPL',
55
price=150.00,
56
action='BUY',
57
orderType='LMT',
58
quant=10
59
)
60
61
# Get current orders
62
orders = wb.get_current_orders()
63
```
64
65
## Architecture
66
67
The webull package is built around three main components:
68
69
- **webull class**: Core API client for live trading operations, market data access, and account management
70
- **paper_webull class**: Specialized client for paper trading that inherits from webull with overridden methods for simulation
71
- **StreamConn class**: MQTT-based real-time streaming client for live quotes and order updates
72
- **endpoints module**: Internal URL management system providing API endpoint construction
73
74
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.
75
76
## Capabilities
77
78
### Authentication & Session Management
79
80
Complete user authentication system with email/phone login, Multi-Factor Authentication (MFA), security questions, and session management with token refresh capabilities.
81
82
```python { .api }
83
def login(self, username='', password='', device_name='', mfa='', question_id='', question_answer='', save_token=False, token_path=None): ...
84
def get_mfa(self, username=''): ...
85
def check_mfa(self, username='', mfa=''): ...
86
def get_security(self, username=''): ...
87
def check_security(self, username='', question_id='', question_answer=''): ...
88
def logout(self): ...
89
def get_trade_token(self, password=''): ...
90
def is_logged_in(self): ...
91
```
92
93
[Authentication](./authentication.md)
94
95
### Trading Operations
96
97
Comprehensive trading functionality including order placement, modification, and cancellation for stocks, options, and cryptocurrencies. Supports various order types and advanced order strategies.
98
99
```python { .api }
100
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'): ...
101
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): ...
102
def cancel_order(self, order_id=''): ...
103
def place_order_option(self, optionId=None, lmtPrice=None, stpPrice=None, action=None, orderType='LMT', enforce='DAY', quant=0): ...
104
def place_order_crypto(self, stock=None, tId=None, price=0, action='BUY', orderType='LMT', enforce='DAY', entrust_type='QTY', quant=0, outsideRegularTradingHour=False): ...
105
```
106
107
[Trading](./trading.md)
108
109
### Market Data & Research
110
111
Extensive market data access including real-time quotes, historical price data, news, analyst ratings, financial statements, and institutional holdings across stocks, options, and cryptocurrencies.
112
113
```python { .api }
114
def get_quote(self, stock=None, tId=None): ...
115
def get_bars(self, stock=None, tId=None, interval='m1', count=1, extendTrading=0, timeStamp=None): ...
116
def get_news(self, stock=None, tId=None, Id=0, items=20): ...
117
def get_analysis(self, stock=None): ...
118
def get_financials(self, stock=None): ...
119
def get_institutional_holding(self, stock=None, tId=None): ...
120
```
121
122
[Market Data](./market-data.md)
123
124
### Portfolio & Account Management
125
126
Complete portfolio management including positions tracking, account activities, order history, dividend information, and account details retrieval.
127
128
```python { .api }
129
def get_account(self): ...
130
def get_positions(self): ...
131
def get_portfolio(self): ...
132
def get_activities(self, index=1, size=500): ...
133
def get_current_orders(self): ...
134
def get_history_orders(self, status='All', count=20): ...
135
def get_dividends(self): ...
136
```
137
138
[Portfolio](./portfolio.md)
139
140
### Options Trading
141
142
Specialized options trading capabilities including options chain retrieval, expiration dates, strike price filtering, and options-specific order placement and management.
143
144
```python { .api }
145
def get_options(self, stock=None, count=-1, includeWeekly=1, direction='all', expireDate=None, queryAll=0): ...
146
def get_options_expiration_dates(self, stock=None, count=-1): ...
147
def get_option_quote(self, stock=None, tId=None, optionId=None): ...
148
def get_options_by_strike_and_expire_date(self, stock=None, expireDate=None, strike=None, direction='all'): ...
149
```
150
151
[Options](./options.md)
152
153
### Real-time Streaming
154
155
MQTT-based real-time data streaming for live price updates and order status changes with subscription management and callback handling.
156
157
```python { .api }
158
class StreamConn:
159
def __init__(self, debug_flg=False): ...
160
def connect(self, did, access_token=None): ...
161
def subscribe(self, tId=None, level=105): ...
162
def unsubscribe(self, tId=None, level=105): ...
163
def on_price_message(self, topic, data): ...
164
def on_order_message(self, topic, data): ...
165
```
166
167
[Streaming](./streaming.md)
168
169
### Paper Trading
170
171
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.
172
173
```python { .api }
174
class paper_webull(webull):
175
def __init__(self): ...
176
def get_account(self): ...
177
def place_order(self, stock=None, tId=None, price=0, action='BUY', orderType='LMT', enforce='GTC', quant=0, outsideRegularTradingHour=True): ...
178
```
179
180
[Paper Trading](./paper-trading.md)
181
182
### Alerts & Screening
183
184
Price alert management and stock screening capabilities for market discovery and automated monitoring of price movements and market conditions.
185
186
```python { .api }
187
def alerts_list(self): ...
188
def alerts_add(self, stock=None, frequency=1, interval=1, priceRules=[], smartRules=[]): ...
189
def alerts_remove(self, alert=None, priceAlert=True, smartAlert=True): ...
190
def run_screener(self, region=None, price_lte=None, price_gte=None, pct_chg_gte=None, pct_chg_lte=None, sort=None, ...): ...
191
def active_gainer_loser(self, direction='gainer', rank_type='afterMarket', count=50): ...
192
```
193
194
[Alerts & Screening](./alerts-screening.md)
195
196
## Error Handling
197
198
The webull package raises `ValueError` exceptions for:
199
- Missing required parameters (stock symbol, credentials)
200
- Invalid stock symbols that cannot be found
201
- Authentication failures and invalid credentials
202
- Invalid order parameters or insufficient permissions
203
204
Always wrap webull operations in try-catch blocks for production usage:
205
206
```python
207
try:
208
quote = wb.get_quote(stock='AAPL')
209
except ValueError as e:
210
print(f"Error getting quote: {e}")
211
```
212
213
## Common Types
214
215
```python { .api }
216
# Order actions
217
OrderAction = 'BUY' | 'SELL'
218
219
# Order types
220
OrderType = 'LMT' | 'MKT' | 'STP' | 'STP_LMT'
221
222
# Time in force
223
Enforce = 'GTC' | 'DAY' | 'IOC' | 'FOK'
224
225
# Options directions
226
OptionsDirection = 'all' | 'call' | 'put'
227
228
# Market intervals
229
Interval = 'm1' | 'm5' | 'm15' | 'm30' | 'h1' | 'h2' | 'h4' | 'd1' | 'w1'
230
```