0
# Trading API
1

2
Order placement and management functions supporting stocks, futures, options, and bonds with various order types, position effects, and execution styles. All trading functions are available within strategy context and enforce proper execution phases.
3

4
## Capabilities
5

6
### Share-based Order Functions
7

8
Order placement functions that specify quantities in terms of shares or contracts.
9

10
```python { .api }
11
def order_shares(id_or_ins, amount, price_or_style=None):
12
    """
13
    Order by number of shares.
14

15
    Parameters:
16
    - id_or_ins (str|Instrument): Instrument ID or Instrument object
17
    - amount (int): Number of shares (positive=buy, negative=sell)
18
    - price_or_style (float|OrderStyle, optional): Limit price or order style
19

20
    Returns:
21
    Order: Order object or None if order failed
22
    """
23

24
def order(order_book_id, quantity, price_or_style=None):
25
    """
26
    Universal smart order function.
27

28
    Parameters:
29
    - order_book_id (str): Instrument identifier
30
    - quantity (float): Quantity to order (positive=buy, negative=sell)
31
    - price_or_style (float|OrderStyle, optional): Price or order style
32

33
    Returns:
34
    Order: Order object or None if order failed
35
    """
36
```
37

38
### Value-based Order Functions
39

40
Order placement functions that specify order size in terms of cash value.
41

42
```python { .api }
43
def order_value(id_or_ins, cash_amount, price_or_style=None):
44
    """
45
    Order by cash value.
46

47
    Parameters:
48
    - id_or_ins (str|Instrument): Instrument ID or Instrument object
49
    - cash_amount (float): Cash amount to invest (positive=buy, negative=sell)
50
    - price_or_style (float|OrderStyle, optional): Limit price or order style
51

52
    Returns:
53
    Order: Order object or None if order failed
54
    """
55

56
def order_percent(id_or_ins, percent, price_or_style=None):
57
    """
58
    Order by portfolio percentage.
59

60
    Parameters:
61
    - id_or_ins (str|Instrument): Instrument ID or Instrument object
62
    - percent (float): Percentage of portfolio to invest (0.0-1.0)
63
    - price_or_style (float|OrderStyle, optional): Limit price or order style
64

65
    Returns:
66
    Order: Order object or None if order failed
67
    """
68
```
69

70
### Target Position Functions
71

72
Order placement functions that target specific position sizes.
73

74
```python { .api }
75
def order_target_value(id_or_ins, cash_amount, price_or_style=None):
76
    """
77
    Target position by cash value.
78

79
    Parameters:
80
    - id_or_ins (str|Instrument): Instrument ID or Instrument object
81
    - cash_amount (float): Target position value
82
    - price_or_style (float|OrderStyle, optional): Limit price or order style
83

84
    Returns:
85
    Order: Order object or None if order failed
86
    """
87

88
def order_target_percent(id_or_ins, percent, price_or_style=None):
89
    """
90
    Target position by portfolio percentage.
91

92
    Parameters:
93
    - id_or_ins (str|Instrument): Instrument ID or Instrument object
94
    - percent (float): Target percentage of portfolio (0.0-1.0)
95
    - price_or_style (float|OrderStyle, optional): Limit price or order style
96

97
    Returns:
98
    Order: Order object or None if order failed
99
    """
100

101
def order_to(order_book_id, quantity, price_or_style=None):
102
    """
103
    Universal position targeting function.
104

105
    Parameters:
106
    - order_book_id (str): Instrument identifier
107
    - quantity (float): Target position quantity
108
    - price_or_style (float|OrderStyle, optional): Price or order style
109

110
    Returns:
111
    Order: Order object or None if order failed
112
    """
113
```
114

115
### Futures Trading Functions
116

117
Specialized order functions for futures trading with position effects.
118

119
```python { .api }
120
def buy_open(id_or_ins, amount, price_or_style=None):
121
    """
122
    Buy to open position (futures).
123

124
    Parameters:
125
    - id_or_ins (str|Instrument): Futures instrument ID or object
126
    - amount (int): Number of contracts to buy
127
    - price_or_style (float|OrderStyle, optional): Limit price or order style
128

129
    Returns:
130
    Order: Order object or None if order failed
131
    """
132

133
def buy_close(id_or_ins, amount, price_or_style=None, close_today=False):
134
    """
135
    Buy to close position (futures).
136

137
    Parameters:
138
    - id_or_ins (str|Instrument): Futures instrument ID or object
139
    - amount (int): Number of contracts to close
140
    - price_or_style (float|OrderStyle, optional): Limit price or order style
141
    - close_today (bool): Whether to close today's positions first
142

143
    Returns:
144
    Order: Order object or None if order failed
145
    """
146

147
def sell_open(id_or_ins, amount, price_or_style=None):
148
    """
149
    Sell to open position (futures).
150

151
    Parameters:
152
    - id_or_ins (str|Instrument): Futures instrument ID or object
153
    - amount (int): Number of contracts to sell
154
    - price_or_style (float|OrderStyle, optional): Limit price or order style
155

156
    Returns:
157
    Order: Order object or None if order failed
158
    """
159

160
def sell_close(id_or_ins, amount, price_or_style=None, close_today=False):
161
    """
162
    Sell to close position (futures).
163

164
    Parameters:
165
    - id_or_ins (str|Instrument): Futures instrument ID or object
166
    - amount (int): Number of contracts to close
167
    - price_or_style (float|OrderStyle, optional): Limit price or order style
168
    - close_today (bool): Whether to close today's positions first
169

170
    Returns:
171
    Order: Order object or None if order failed
172
    """
173
```
174

175
### Options and Convertible Bonds
176

177
Exercise functions for options and convertible bonds.
178

179
```python { .api }
180
def exercise(id_or_ins, amount, convert=False):
181
    """
182
    Exercise options or convertible bonds.
183

184
    Parameters:
185
    - id_or_ins (str|Instrument): Option or convertible bond ID/object
186
    - amount (int): Number of contracts/bonds to exercise
187
    - convert (bool): Whether to convert (for convertible bonds)
188

189
    Returns:
190
    Order: Exercise order object or None if failed
191
    """
192
```
193

194
### Order Management
195

196
Functions for managing active orders and order lifecycle.
197

198
```python { .api }
199
def get_open_orders():
200
    """
201
    Get all pending orders.
202

203
    Returns:
204
    list[Order]: List of pending Order objects
205
    """
206

207
def submit_order(id_or_ins, amount, side, price=None, position_effect=None):
208
    """
209
    Submit order manually with full control.
210

211
    Parameters:
212
    - id_or_ins (str|Instrument): Instrument ID or object
213
    - amount (float): Order amount/quantity
214
    - side (SIDE): Order side (BUY, SELL, etc.)
215
    - price (float, optional): Limit price
216
    - position_effect (POSITION_EFFECT, optional): Position effect
217

218
    Returns:
219
    Order: Order object or None if order failed
220
    """
221

222
def cancel_order(order):
223
    """
224
    Cancel pending order.
225

226
    Parameters:
227
    - order (Order): Order object to cancel
228

229
    Returns:
230
    bool: True if cancellation successful
231
    """
232
```
233

234
### Universe Management
235

236
Functions for managing the strategy's trading universe.
237

238
```python { .api }
239
def update_universe(id_or_symbols):
240
    """
241
    Update strategy universe.
242

243
    Parameters:
244
    - id_or_symbols (list[str]): List of instrument IDs to include in universe
245

246
    Returns:
247
    None
248
    """
249

250
def subscribe(id_or_symbols):
251
    """
252
    Subscribe to instruments for data.
253

254
    Parameters:
255
    - id_or_symbols (str|list[str]): Instrument ID(s) to subscribe to
256

257
    Returns:
258
    None
259
    """
260

261
def unsubscribe(id_or_symbols):
262
    """
263
    Unsubscribe from instruments.
264

265
    Parameters:
266
    - id_or_symbols (str|list[str]): Instrument ID(s) to unsubscribe from
267

268
    Returns:
269
    None
270
    """
271
```
272

273
## Order Styles
274

275
Order styles define how orders should be executed in the market.
276

277
### Market Orders
278

279
```python { .api }
280
class MarketOrder:
281
    """
282
    Market order style for immediate execution at current market price.
283
    
284
    Usage:
285
    order_shares("000001.XSHE", 100, MarketOrder())
286
    """
287
```
288

289
### Limit Orders
290

291
```python { .api }
292
class LimitOrder:
293
    """
294
    Limit order style with specified price.
295
    
296
    Parameters:
297
    - limit_price (float): Maximum price for buy orders, minimum for sell orders
298
    
299
    Usage:
300
    order_shares("000001.XSHE", 100, LimitOrder(10.50))
301
    """
302
```
303

304
### Algorithmic Orders
305

306
```python { .api }
307
class TWAPOrder:
308
    """
309
    Time-weighted average price order.
310
    
311
    Parameters:
312
    - start_time (str): Start time for execution
313
    - end_time (str): End time for execution
314
    
315
    Usage:
316
    order_shares("000001.XSHE", 1000, TWAPOrder("09:30", "15:00"))
317
    """
318

319
class VWAPOrder:
320
    """
321
    Volume-weighted average price order.
322
    
323
    Parameters:
324
    - start_time (str): Start time for execution
325
    - end_time (str): End time for execution
326
    
327
    Usage:
328
    order_shares("000001.XSHE", 1000, VWAPOrder("09:30", "15:00"))
329
    """
330
```
331

332
## Trading Examples
333

334
### Basic Stock Trading
335

336
```python
337
def handle_bar(context, bar_dict):
338
    # Buy 100 shares at market price
339
    order_shares("000001.XSHE", 100)
340
    
341
    # Buy with limit price
342
    order_shares("000002.XSHE", 100, LimitOrder(15.50))
343
    
344
    # Target 50% of portfolio in stock
345
    order_target_percent("000001.XSHE", 0.5)
346
    
347
    # Invest 10000 cash in stock
348
    order_value("000002.XSHE", 10000)
349
```
350

351
### Futures Trading
352

353
```python
354
def handle_bar(context, bar_dict):
355
    future = "RB2401"  # Steel rebar future
356
    
357
    # Open long position
358
    buy_open(future, 1)
359
    
360
    # Close long position
361
    sell_close(future, 1)
362
    
363
    # Open short position
364
    sell_open(future, 1)
365
    
366
    # Close short position
367
    buy_close(future, 1)
368
```
369

370
### Order Management
371

372
```python
373
def handle_bar(context, bar_dict):
374
    # Place a limit order
375
    order = order_shares("000001.XSHE", 100, LimitOrder(10.50))
376
    
377
    # Check pending orders
378
    open_orders = get_open_orders()
379
    for order in open_orders:
380
        if order.instrument.order_book_id == "000001.XSHE":
381
            # Cancel the order if conditions change
382
            cancel_order(order)
383
```
384

385
### Universe Management
386

387
```python
388
def init(context):
389
    # Set initial universe
390
    context.stocks = ["000001.XSHE", "000002.XSHE", "600000.XSHG"]
391
    update_universe(context.stocks)
392

393
def handle_bar(context, bar_dict):
394
    # Dynamically update universe based on conditions
395
    new_stocks = get_high_volume_stocks()  # Custom function
396
    update_universe(new_stocks)
397
    
398
    # Subscribe to additional data
399
    subscribe(["000858.XSHE", "002415.XSHE"])
400
```