0
# Enumerations and Constants
1

2
The enums module provides comprehensive constants and enumerations for all TD Ameritrade API parameters. These values ensure valid API requests and provide validation for order parameters, streaming field IDs, and endpoint arguments.
3

4
## Core Import
5

6
```python
7
from td.enums import *
8
```
9

10
## Capabilities
11

12
### Order Session Constants
13

14
Trading session specifications for when orders should be executed.
15

16
```python { .api }
17
class ORDER_SESSION:
18
    NORMAL: str = 'NORMAL'
19
    AM: str = 'AM'
20
    PM: str = 'PM'
21
    SEAMLESS: str = 'SEAMLESS'
22
```
23

24
**Values:**
25
- `NORMAL`: Regular trading hours (9:30 AM - 4:00 PM ET)
26
- `AM`: Pre-market session (4:00 AM - 9:30 AM ET)  
27
- `PM`: After-hours session (4:00 PM - 8:00 PM ET)
28
- `SEAMLESS`: Extended hours trading session
29

30
### Order Duration Constants
31

32
Time-in-force specifications for order validity periods.
33

34
```python { .api }
35
class DURATION:
36
    DAY: str = 'DAY'
37
    GOOD_TILL_CANCEL: str = 'GOOD_TILL_CANCEL'
38
    FILL_OR_KILL: str = 'FILL_OR_KILL'
39
```
40

41
**Values:**
42
- `DAY`: Order valid for current trading day only
43
- `GOOD_TILL_CANCEL`: Order remains active until filled or manually canceled
44
- `FILL_OR_KILL`: Order must be filled immediately and completely or canceled
45

46
### Order Strategy Types
47

48
Defines the strategy type for single orders versus complex order combinations.
49

50
```python { .api }
51
class ORDER_STRATEGY_TYPE:
52
    SINGLE: str = 'SINGLE'
53
    OCO: str = 'OCO'
54
    TRIGGER: str = 'TRIGGER'
55
```
56

57
**Values:**
58
- `SINGLE`: Individual standalone order
59
- `OCO`: One-Cancels-Other order pair
60
- `TRIGGER`: Conditional trigger order
61

62
### Quantity Types
63

64
Specifications for how order quantities are interpreted.
65

66
```python { .api }
67
class QUANTITY_TYPE:
68
    ALL_SHARES: str = 'ALL_SHARES'
69
    DOLLARS: str = 'DOLLARS'
70
    SHARES: str = 'SHARES'
71
```
72

73
**Values:**
74
- `ALL_SHARES`: All available shares in the position
75
- `DOLLARS`: Dollar amount rather than share count
76
- `SHARES`: Specific number of shares
77

78
### Asset Types
79

80
Asset classifications for different instrument types.
81

82
```python { .api }
83
class ORDER_ASSET_TYPE:
84
    EQUITY: str = 'EQUITY'
85
    OPTION: str = 'OPTION'
86
    INDEX: str = 'INDEX'
87
    MUTUAL_FUND: str = 'MUTUAL_FUND'
88
    CASH_EQUIVALENT: str = 'CASH_EQUIVALENT'
89
    FIXED_INCOME: str = 'FIXED_INCOME'
90
    CURRENCY: str = 'CURRENCY'
91
```
92

93
**Values:**
94
- `EQUITY`: Common stocks and ETFs
95
- `OPTION`: Options contracts
96
- `INDEX`: Index instruments
97
- `MUTUAL_FUND`: Mutual fund shares
98
- `CASH_EQUIVALENT`: Money market and cash equivalents
99
- `FIXED_INCOME`: Bonds and fixed income securities
100
- `CURRENCY`: Foreign exchange instruments
101

102
### Complex Order Strategy Types
103

104
Multi-leg options strategies and complex order combinations.
105

106
```python { .api }
107
class COMPLEX_ORDER_STRATEGY_TYPE:
108
    NONE: str = 'NONE'
109
    COVERED: str = 'COVERED'
110
    VERTICAL: str = 'VERTICAL'
111
    BACK_RATIO: str = 'BACK_RATIO'
112
    CALENDAR: str = 'CALENDAR'
113
    DIAGONAL: str = 'DIAGONAL'
114
    STRADDLE: str = 'STRADDLE'
115
    STRANGLE: str = 'STRANGLE'
116
    COLLAR_SYNTHETIC: str = 'COLLAR_SYNTHETIC'
117
    BUTTERFLY: str = 'BUTTERFLY'
118
    CONDOR: str = 'CONDOR'
119
    IRON_CONDOR: str = 'IRON_CONDOR'
120
    VERTICAL_ROLL: str = 'VERTICAL_ROLL'
121
    COLLAR_WITH_STOCK: str = 'COLLAR_WITH_STOCK'
122
    DOUBLE_DIAGONAL: str = 'DOUBLE_DIAGONAL'
123
    UNBALANCED_BUTTERFLY: str = 'UNBALANCED_BUTTERFLY'
124
    UNBALANCED_CONDOR: str = 'UNBALANCED_CONDOR'
125
    UNBALANCED_IRON_CONDOR: str = 'UNBALANCED_IRON_CONDOR'
126
    UNBALANCED_VERTICAL_ROLL: str = 'UNBALANCED_VERTICAL_ROLL'
127
    CUSTOM: str = 'CUSTOM'
128
```
129

130
### Order Instructions
131

132
Trade instructions specifying buy/sell actions for different asset types.
133

134
```python { .api }
135
class ORDER_INSTRUCTIONS:
136
    BUY: str = 'BUY'
137
    SELL: str = 'SELL'
138
    BUY_TO_COVER: str = 'BUY_TO_COVER'
139
    SELL_SHORT: str = 'SELL_SHORT'
140
    BUY_TO_OPEN: str = 'BUY_TO_OPEN'
141
    BUY_TO_CLOSE: str = 'BUY_TO_CLOSE'
142
    SELL_TO_OPEN: str = 'SELL_TO_OPEN'
143
    SELL_TO_CLOSE: str = 'SELL_TO_CLOSE'
144
    EXCHANGE: str = 'EXCHANGE'
145
```
146

147
**Values:**
148
- `BUY`: Buy shares or long position
149
- `SELL`: Sell shares or close long position
150
- `BUY_TO_COVER`: Cover short position
151
- `SELL_SHORT`: Create short position
152
- `BUY_TO_OPEN`: Open long options position
153
- `BUY_TO_CLOSE`: Close short options position
154
- `SELL_TO_OPEN`: Open short options position
155
- `SELL_TO_CLOSE`: Close long options position
156
- `EXCHANGE`: Exchange or conversion transaction
157

158
### Order Types
159

160
Execution type specifications for trade orders.
161

162
```python { .api }
163
class ORDER_TYPE:
164
    MARKET: str = 'MARKET'
165
    LIMIT: str = 'LIMIT'
166
    STOP: str = 'STOP'
167
    STOP_LIMIT: str = 'STOP_LIMIT'
168
    TRAILING_STOP: str = 'TRAILING_STOP'
169
    MARKET_ON_CLOSE: str = 'MARKET_ON_CLOSE'
170
    EXERCISE: str = 'EXERCISE'
171
    TRAILING_STOP_LIMIT: str = 'TRAILING_STOP_LIMIT'
172
    NET_DEBIT: str = 'NET_DEBIT'
173
    NET_CREDIT: str = 'NET_CREDIT'
174
    NET_ZERO: str = 'NET_ZERO'
175
```
176

177
**Values:**
178
- `MARKET`: Execute at current market price
179
- `LIMIT`: Execute at specified price or better
180
- `STOP`: Stop loss order triggered at stop price
181
- `STOP_LIMIT`: Stop order with limit price execution
182
- `TRAILING_STOP`: Stop loss that trails the market price
183
- `MARKET_ON_CLOSE`: Execute at closing auction
184
- `EXERCISE`: Exercise options contract
185
- `TRAILING_STOP_LIMIT`: Trailing stop with limit price
186
- `NET_DEBIT`: Multi-leg order with net debit
187
- `NET_CREDIT`: Multi-leg order with net credit
188
- `NET_ZERO`: Multi-leg order with no net cost
189

190
### Option Chain Enumerations
191

192
Constants for option chain API requests and filtering.
193

194
```python { .api }
195
class OPTION_CHAIN_STRATEGY:
196
    SINGLE: str = 'SINGLE'
197
    ANALYTICAL: str = 'ANALYTICAL'
198
    COVERED: str = 'COVERED'
199
    VERTICAL: str = 'VERTICAL'
200
    CALENDAR: str = 'CALENDAR'
201
    STRANGLE: str = 'STRANGLE'
202
    STRADDLE: str = 'STRADDLE'
203
    BUTTERFLY: str = 'BUTTERFLY'
204
    CONDOR: str = 'CONDOR'
205
    DIAGONAL: str = 'DIAGONAL'
206
    COLLAR: str = 'COLLAR'
207
    ROLL: str = 'ROLL'
208

209
class OPTION_CHAIN_RANGE:
210
    ITM: str = 'ITM'
211
    NTM: str = 'NTM'
212
    OTM: str = 'OTM'
213
    SAK: str = 'SAK'
214
    SBK: str = 'SBK'
215
    SNK: str = 'SNK'
216
    ALL: str = 'ALL'
217

218
class OPTION_CHAIN_EXP_MONTH:
219
    JAN: str = 'JAN'
220
    FEB: str = 'FEB'
221
    MAR: str = 'MAR'
222
    APR: str = 'APR'
223
    MAY: str = 'MAY'
224
    JUN: str = 'JUN'
225
    JUL: str = 'JUL'
226
    AUG: str = 'AUG'
227
    SEP: str = 'SEP'
228
    OCT: str = 'OCT'
229
    NOV: str = 'NOV'
230
    DEC: str = 'DEC'
231

232
class OPTION_CHAIN_OPTION_TYPE:
233
    S: str = 'S'
234
    NS: str = 'NS'
235
    ALL: str = 'ALL'
236
```
237

238
### API Endpoint Validation
239

240
Dictionary containing validation rules and parameter requirements for API endpoints.
241

242
```python { .api }
243
ENDPOINT_ARGUMENTS: Dict[str, Dict] = {
244
    # Comprehensive validation dictionary for all API endpoints
245
    # Contains required parameters, valid values, and constraints
246
}
247
```
248

249
### Chart Data Validation
250

251
Valid combinations of parameters for historical price data requests.
252

253
```python { .api }
254
VALID_CHART_VALUES: Dict[str, Dict] = {
255
    # Valid period types, frequencies, and their combinations
256
    # Used to validate get_price_history() parameters
257
}
258
```
259

260
### Streaming Field IDs
261

262
Field ID mappings for streaming data subscriptions.
263

264
```python { .api }
265
STREAM_FIELD_IDS: Dict[str, Dict] = {
266
    # Field ID mappings for different streaming services
267
    # Maps human-readable field names to numeric IDs
268
}
269
```
270

271
### CSV Field Mappings
272

273
Field mappings for CSV output formatting of streaming data.
274

275
```python { .api }
276
CSV_FIELD_KEYS: Dict[str, str] = {
277
    # Level 1 data field mappings for CSV output
278
}
279

280
CSV_FIELD_KEYS_LEVEL_2: Dict[str, str] = {
281
    # Level 2 data field mappings for CSV output
282
}
283
```
284

285
## Usage Examples
286

287
### Order Construction with Enums
288

289
```python
290
from td.orders import Order, OrderLeg
291
from td.enums import ORDER_TYPE, ORDER_SESSION, DURATION, ORDER_INSTRUCTIONS, ORDER_ASSET_TYPE
292

293
# Create a limit order using enums
294
order = Order()
295
order.order_type(ORDER_TYPE.LIMIT)
296
order.order_session(ORDER_SESSION.NORMAL)
297
order.order_duration(DURATION.DAY)
298
order.order_price(150.00)
299

300
# Create order leg using enums
301
leg = OrderLeg()
302
leg.order_leg_instruction(ORDER_INSTRUCTIONS.BUY)
303
leg.order_leg_asset(ORDER_ASSET_TYPE.EQUITY, 'AAPL')
304
leg.order_leg_quantity(100)
305

306
order.add_order_leg(leg)
307
```
308

309
### Complex Options Strategy
310

311
```python
312
from td.enums import COMPLEX_ORDER_STRATEGY_TYPE, ORDER_INSTRUCTIONS, ORDER_ASSET_TYPE
313

314
# Vertical spread using enums
315
vertical = Order()
316
vertical.order_type(ORDER_TYPE.NET_DEBIT)
317
vertical.complex_order_type(COMPLEX_ORDER_STRATEGY_TYPE.VERTICAL)
318
vertical.order_session(ORDER_SESSION.NORMAL)
319
vertical.order_duration(DURATION.DAY)
320

321
# Buy leg
322
buy_leg = OrderLeg()
323
buy_leg.order_leg_instruction(ORDER_INSTRUCTIONS.BUY_TO_OPEN)
324
buy_leg.order_leg_asset(ORDER_ASSET_TYPE.OPTION, 'AAPL_030724C150')
325
buy_leg.order_leg_quantity(1)
326

327
# Sell leg
328
sell_leg = OrderLeg()
329
sell_leg.order_leg_instruction(ORDER_INSTRUCTIONS.SELL_TO_OPEN)
330
sell_leg.order_leg_asset(ORDER_ASSET_TYPE.OPTION, 'AAPL_030724C155')
331
sell_leg.order_leg_quantity(1)
332

333
vertical.add_order_leg(buy_leg)
334
vertical.add_order_leg(sell_leg)
335
```
336

337
### Option Chain Filtering
338

339
```python
340
from td.option_chain import OptionChain
341
from td.enums import OPTION_CHAIN_STRATEGY, OPTION_CHAIN_RANGE, OPTION_CHAIN_OPTION_TYPE
342

343
# Build option chain request with enum filters
344
chain = OptionChain()
345
chain.add_chain_key('symbol', 'AAPL')
346
chain.add_chain_key('strategy', OPTION_CHAIN_STRATEGY.SINGLE)
347
chain.add_chain_key('range', OPTION_CHAIN_RANGE.ITM)
348
chain.add_chain_key('optionType', OPTION_CHAIN_OPTION_TYPE.ALL)
349

350
# Get option chain data
351
option_data = client.get_options_chain(chain)
352
```
353

354
### Streaming Field Selection
355

356
```python
357
from td.enums import STREAM_FIELD_IDS
358

359
# Subscribe to specific Level 1 fields
360
streaming_client.level_one_quotes(
361
    symbols=['AAPL', 'MSFT'],
362
    fields=['0', '1', '2', '3', '8', '9']  # Symbol, bid, ask, last, volume, last size
363
)
364

365
# Use field mappings for readable code (if available)
366
level1_fields = ['0', '1', '2', '3']  # Common Level 1 fields
367
streaming_client.level_one_quotes(['GOOGL'], fields=level1_fields)
368
```
369

370
### Validation Usage
371

372
```python
373
from td.enums import ENDPOINT_ARGUMENTS, VALID_CHART_VALUES
374

375
# Validate price history parameters
376
period_type = 'day'
377
frequency_type = 'minute'
378

379
if period_type in VALID_CHART_VALUES:
380
    valid_frequencies = VALID_CHART_VALUES[period_type].get(frequency_type, [])
381
    if 1 in valid_frequencies:
382
        history = client.get_price_history(
383
            symbol='AAPL',
384
            period_type=period_type,
385
            frequency_type=frequency_type,
386
            frequency=1
387
        )
388
```
389

390
## Important Notes
391

392
- Always use enum values instead of hardcoded strings to prevent API errors
393
- Field IDs for streaming are numeric strings (e.g., '0', '1', '2')
394
- Complex order strategies may have specific requirements for legs and prices
395
- Validation dictionaries help ensure API requests meet TD Ameritrade requirements
396
- Some enum values may be restricted based on account permissions or market conditions