Place Order
place_order Place Order
TradeClient.place_order():
Description
Trading order placement interface. For guidance on selecting instruments, order types, direction, quantities, etc., please see the explanations below.
Before running your program, please review the User and Account Types and Order and Trading Rules sections of this documentation to verify that your account supports the requested order type and that trading rules permit placing orders for the specific instrument during your program's runtime. If order placement fails, first consult the Error Codes section for troubleshooting.
After a successful place_order call, the order ID in the order object parameter is populated (order.id) and can be used for subsequent queries or cancellations. At this point, this method returns the order ID, but this only indicates successful order submission, not successful order execution. Order execution is asynchronous. After submitting an order, it will proceed to the next state based on circumstances, such as being filled, rejected, etc. Therefore, it's recommended to use the get_order or get_orders methods to check the order status before performing any subsequent operations on the order.
CAUTION
- Market orders (MKT) and stop orders (STP) do not support pre-market and after-hours trading. When calling the order placement interface, set outside_rth to false
- For shortable instruments, position locking is currently not supported, so you cannot simultaneously hold long and short positions in the same instrument
- Market orders (MKT) and paper trading accounts do not support setting the time_in_force parameter to GTC
Order Status Description
-
How to determine partial fill status for prime and paper trading accounts?
When the order status is not FILLED (it could be NEW, CANCELLED, EXPIRED, or REJECTED), there's still a possibility of partial fill status, which can be determined by checking if the filled quantity is greater than 0
Order Status Flow:
Other Notes
- For index options, except IWM/SPY/QQQ, only contracts with Friday expiration dates are supported for trading.
- Direct opening of reverse positions is prohibited. For example, when currently holding 100 long shares, directly selling 200 shares (intending to establish a net short position of 100 shares) will be rejected. You must first close the existing 100 long shares, then perform a new sell operation.
Parameters
Order object (tigeropen.trade.domain.order.Order)
You can use utility functions from tigeropen.common.util.order_utils, such as limit_order(), market_order(), to generate order objects locally based on your specific order type and parameter requirements. For creation methods, see the Order Object - Construction Methods section, or use TradeClient.create_order() to request an order number from the server and then generate the order object (not recommended).
Parameters
| Parameter | Type | Description | Market Order | Limit Order | Stop Order | Stop-Limit Order |
|---|---|---|---|---|---|---|
| account | str | User authorized account: 402901 | Required | Required | Required | Required |
| order_id | int | Order number, used to prevent duplicate orders. Can be obtained through the order number interface. If 0 is passed, the server will automatically generate an order number. When passing 0, duplicate order prevention is not possible, please choose carefully | Optional | Optional | Optional | Optional |
| symbol | str | Stock symbol (For callable bull bear contracts when sec_type, use the 5-digit number below the name in the app bull bear contract list) | Required | Required | Required | Required |
| sec_type | str | Contract type (STK Stock, OPT US Stock Options) | Required | Required | Required | Required |
| action | str | Trading direction BUY/SELL | Required | Required | Required | Required |
| order_type | str | Order type. MKT (Market Order), LMT (Limit Order), STP (Stop Order), STP_LMT (Stop-Limit Order) | MKT | LMT | STP | STP_LMT |
| quantity | int | Order quantity (callable bull/bear contracts have minimum quantity restrictions) | Required | Required | Required | Required |
| quantity_scale | int | Order quantity offset, default is 0. For fractional shares, quantity and quantity_scale combine to represent the actual order quantity. E.g., quantity=111, quantity_scale=2, then actual quantity=111*10^(-2)=1.11 | Not Required | Not Required | Not Required | Not Required |
| total_cash_amount | float | Total order amount, only needed for dollar-based orders. Not needed for quantity-based orders | Not Required | Not Required | Not Required | Not Required |
| limit_price | float | Limit price, required when order_type is LMT or STP_LMT | Not Required | Required | Not Required | Required |
| aux_price | float | Stock order stop trigger price. Meaning is price difference. When both trailing_percent exist, overridden by trailing_percent. Required when order_type is STP or STP_LMT. | Not Required | Not Required | Required | Required |
| outside_rth | bool | true: Allow pre-market and after-hours trading (US stocks only), false: Don't allow, default is allow. (Market orders and stop orders are only valid during market hours and will ignore the outside_rth parameter) | Not Required | Optional | Optional | Not Required |
| adjust_limit | float | Price micro-adjustment range (default 0 means no adjustment, positive for upward adjustment, negative for downward adjustment), automatically adjusts the input price to a valid price level. E.g., 0.001 means upward adjustment not exceeding 0.1%; -0.001 means downward adjustment not exceeding 0.1%. Default 0 means no adjustment | Not Required | Optional | Optional | Optional |
| market | str | Market (US stocks: US) | Optional | Optional | Optional | Optional |
| currency | str | Currency (US stocks: USD) | Optional | Optional | Optional | Optional |
| time_in_force | str | Order validity period, can only be DAY (valid for the day), GTC (valid until canceled, maximum validity 180 days), default is DAY | Optional | Optional | Optional | Optional |
| exchange | str | Exchange (US stocks: SMART) | Optional | Optional | Optional | Optional |
| expiry | str | Expiration date (options, callable bull/bear contracts only) | Optional | Optional | Optional | Optional |
| strike | str | Strike price (options, callable bull/bear contracts only) | Optional | Optional | Optional | Optional |
| right | str | Option direction PUT/CALL (options, callable bull/bear contracts only) | Optional | Optional | Optional | Optional |
| multiplier | float | Multiplier, quantity per lot (options, callable bull/bear contracts only) | Optional | Optional | Optional | Optional |
| local_symbol | str | For callable bull bear contracts, this field is required - the 5-digit number below the name in the app bull bear contract list | Optional | Optional | Optional | Optional |
| secret_key | str | Trader key, for institutional users only | Optional | Optional | Optional | Optional |
| user_mark | str | Order note information, cannot be modified after placing order, returns userMark information when querying orders | Optional | Optional | Optional | Optional |
Return
Returns order ID if successful, throws exception if failed. If order is placed successfully, the Order object's id will be populated with the actual order number.
Contract Object Examples
from tigeropen.common.util.contract_utils import stock_contract, option_contract, option_contract_by_symbol
# US stocks
contract = stock_contract(symbol='XYZX', currency='USD')
# Options
contract = option_contract(identifier='XYZX 190118P00160000')
contract = option_contract_by_symbol('JD', expiry='20211015', strike=45.0, put_call='PUT', currency='USD')Limit Order (LMT)
from tigeropen.common.util.contract_utils import stock_contract
from tigeropen.common.util.order_utils import limit_order
from tigeropen.trade.trade_client import TradeClient
from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='/path/to/your/properties/file/')
trade_client = TradeClient(client_config)
# Generate stock contract
contract = stock_contract(symbol='XYZX', currency='USD')
# Generate order object
order = limit_order(account=client_config.account, contract=contract, action='BUY', limit_price=0.1, quantity=1)
# Place order
oid = trade_client.place_order(order)
print(order)
# >>> Order({'account': '111111', 'id': 2498911111111111111, 'order_id': None, 'parent_id': None, 'order_time': None, 'reason': None, 'trade_time': None, 'action': 'BUY', 'quantity': 1, 'filled': 0, 'avg_fill_price': 0, 'commission': None, 'realized_pnl': None, 'trail_stop_price': None, 'limit_price': 0.1, 'aux_price': None, 'trailing_percent': None, 'percent_offset': None, 'order_type': 'LMT', 'time_in_force': None, 'outside_rth': None, 'order_legs': None, 'algo_params': None, 'secret_key': None, 'contract': XYZX/STK/USD, 'status': 'NEW', 'remaining': 1})
print(order.status) # Order status
print(order.reason) # If order fails, reason contains the failure reason
# If order is successful, order.id contains the order ID, which can be used for querying or canceling the order
my_order = trade_client.get_order(id=order.id)
oid = trade_client.cancel_order(id=order.id)
# Or modify the order object
trade_client.modify_order(order, limit_price=190.5)Market Order (MKT)
from tigeropen.common.util.contract_utils import stock_contract
from tigeropen.common.util.order_utils import market_order
from tigeropen.trade.trade_client import TradeClient
from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='/path/to/your/properties/file/')
trade_client = TradeClient(client_config)
# Generate stock contract
contract = stock_contract(symbol='XYZX', currency='USD')
# Generate order object
order = market_order(account=client_config.account, contract=contract, action='BUY', quantity=1)
# Place order
oid = trade_client.place_order(order)Market Order by Amount (MKT)
from tigeropen.common.util.contract_utils import stock_contract
from tigeropen.common.util.order_utils import market_order_by_amount
from tigeropen.trade.trade_client import TradeClient
from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='/path/to/your/properties/file/')
trade_client = TradeClient(client_config)
# Generate stock contract
contract = stock_contract(symbol='XYZX', currency='USD')
# Generate order object
order = market_order_by_amount(account=client_config.account, contract=contract, action='BUY', amount=100)
# Place order
oid = trade_client.place_order(order)Stop Order (STP)
from tigeropen.common.util.contract_utils import stock_contract
from tigeropen.common.util.order_utils import stop_order
from tigeropen.trade.trade_client import TradeClient
from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='/path/to/your/properties/file/')
trade_client = TradeClient(client_config)
# Generate stock contract
contract = stock_contract(symbol='XYZX', currency='USD')
# Generate order object
order = stop_order(account=client_config.account, contract=contract, action='SELL', aux_price=1, quantity=1)
# Place order
oid = trade_client.place_order(order)Stop Limit Order (STP_LMT)
from tigeropen.common.util.contract_utils import stock_contract
from tigeropen.common.util.order_utils import stop_limit_order
from tigeropen.trade.trade_client import TradeClient
from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='/path/to/your/properties/file/')
trade_client = TradeClient(client_config)
# Generate stock contract
contract = stock_contract(symbol='XYZX', currency='USD')
# Generate order object
order = stop_limit_order(account=client_config.account, contract=contract, action='SELL', limit_price=200.0, aux_price=180.0, quantity=1)
# Place order
oid = trade_client.place_order(order)Overnight Order
Only supports US stocks
from tigeropen.common.util.contract_utils import stock_contract
from tigeropen.common.consts import TradingSessionType
from tigeropen.common.util.order_utils import limit_order
from tigeropen.trade.trade_client import TradeClient
from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='/path/to/your/properties/file/')
trade_client = TradeClient(client_config)
# Generate stock contract
contract = stock_contract(symbol='XYZX', currency='USD')
# Generate order object
order = limit_order(account=client_config.account, contract=contract, action='BUY', limit_price=120, quantity=1)
# Overnight trading
order.trading_session_type = TradingSessionType.OVERNIGHT
# Place order
trade_client.place_order(order)
my_order = trade_client.get_order(id=order.id)
print(my_order.user_mark)Other Examples
Placing Options Orders
from tigeropen.common.util.contract_utils import option_contract, option_contract_by_symbol
from tigeropen.common.util.order_utils import limit_order
from tigeropen.trade.trade_client import TradeClient
from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='/path/to/your/properties/file/')
trade_client = TradeClient(client_config)
# Generate options contract
contract = option_contract(identifier='XYZX 190118P00160000')
# Or
contract = option_contract_by_symbol('XYZX', '20200110', strike=280.0, put_call='PUT', currency='USD')
# Generate order object
order = limit_order(account=client_config.account, contract=contract, action='BUY', limit_price=0.1, quantity=1)
# Place order
oid = trade_client.place_order(order)Placing Option Combo Orders
from tigeropen.common.consts import ComboType
from tigeropen.common.util.contract_utils import option_contract, option_contract_by_symbol
from tigeropen.common.util.order_utils import combo_order, contract_leg
from tigeropen.trade.trade_client import TradeClient
from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='/path/to/your/properties/file/')
trade_client = TradeClient(client_config)
contract_leg1 = contract_leg(symbol='XYZX', sec_type='OPT', expiry='20230616', strike=220, put_call='CALL',
action='BUY', ratio=1)
contract_leg2 = contract_leg(symbol='XYZX', sec_type='OPT', expiry='20230616', strike=225, put_call='CALL',
action='SELL', ratio=1)
order = combo_order(client_config.account, [contract_leg1, contract_leg2], combo_type=ComboType.VERTICAL,
action='BUY', quantity=1, order_type='LMT', limit_price=1.0)
res = trade_client.place_order(order)
print(res)Query Contract and Place Order
from tigeropen.common.util.contract_utils import stock_contract
from tigeropen.trade.trade_client import TradeClient
from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='/path/to/your/properties/file/')
trade_client = TradeClient(client_config)
# Get stock contract (not recommended)
contract = trade_client.get_contract('XYZX', sec_type=SecurityType.STK)
# Get order object (not recommended)
order = trade_client.create_order(account=client_config.account, contract=contract, action='SELL', order_type='LMT', quantity=1, limit_price=200.0)
# Place order
oid = trade_client.place_order(order)
Setting Order Attributes
Examples of using uncommon order attributes, such as user_mark
from tigeropen.common.util.contract_utils import stock_contract
from tigeropen.common.consts import TradingSessionType
from tigeropen.common.util.order_utils import limit_order
from tigeropen.trade.trade_client import TradeClient
from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='/path/to/your/properties/file/')
trade_client = TradeClient(client_config)
# Generate stock contract
contract = stock_contract(symbol='XYZX', currency='USD')
# Generate order object
order = limit_order(account=client_config.account, contract=contract, action='BUY', limit_price=0.1, quantity=1)
# Set custom order remark
order.user_mark = 'my-custom-remark'
# Set order validity to GTC
# order.time_in_force = 'GTC'
# Extended hours trading
# order.trading_session_type = TradingSessionType.OVERNIGHT
# Full session trading
# order.trading_session_type = TradingSessionType.FULL
# Set order to GTD (good till date, valid until specified date)
#order.time_in_force = 'GTD'
#order.expire_time = 1700496000000 # Must specify expiration time
# If using time string
#from tigeropen.common.util.common_utils import date_str_to_timestamp
#order.expire_time = date_str_to_timestamp('2023-07-01 11:00:00', 'US/Eastern')
# Place order
trade_client.place_order(order)
my_order = trade_client.get_order(id=order.id)
print(my_order.user_mark)Price Adjustment for Orders
Use contract information and PriceUtil to adjust order prices. When contracts are at different price levels, they have different precision requirements. When an inappropriate precision price is specified as the order price, it will return an error.
Here we use the queried contract tick specification data and tools to correct the price.
from tigeropen.common.util.contract_utils import stock_contract
from tigeropen.common.util.price_util import PriceUtil
from tigeropen.common.consts import SecurityType
from tigeropen.trade.trade_client import TradeClient
from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='/path/to/your/properties/file/')
trade_client = TradeClient(client_config)
# Get stock contract
contract = trade_client.get_contract(symbol='XYZX', sec_type=SecurityType.STK)
limit_price = 150.173
# Check if price matches contract tick specifications
is_price_ok = PriceUtil.match_tick_size(price, contract.tick_sizes)
# Adjust price (if is_up parameter is set to True, price adjusts upward. Default False, price adjusts downward)
# If contract price is between 1~1000 with tick size of 0.01, then 150.173 adjusts to 150.17; upward adjustment would be 150.18
limit_price = PriceUtil.fix_price_by_tick_size(price, contract.tick_sizes)
# Generate order object
order = limit_order(account=client_config.account, contract=contract, action='BUY', limit_price=limit_price, quantity=1)
# Place order
trade_client.place_order(order)Placing Fractional Share Orders
from tigeropen.common.util.contract_utils import stock_contract
from tigeropen.common.util.order_utils import limit_order
from tigeropen.trade.trade_client import TradeClient
from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='/path/to/your/properties/file/')
trade_client = TradeClient(client_config)
# Generate stock contract
contract = stock_contract(symbol='XYZX', currency='USD')
# Generate order object
order = limit_order(account=client_config.account, contract=contract, action='BUY', limit_price=170, quantity=5)
# quantity_scale set to 1, actual order quantity is 5 * 10^-1 = 0.5 shares; if quantity_scale is set to 2, actual order quantity is 5 * 10^-2 = 0.05 shares
order.quantity_scale = 1
# Place order
oid = trade_client.place_order(order)
print(order)create_order Request to Create Order
TradeClient.create_order():
Description
Request order ID and create order object (not recommended). It's recommended to use utility functions under tigeropen.common.util.order_utils to create orders locally, such as limit_order, market_order.
Parameters
| Parameter | Type | Description | Market Order | Limit Order | Stop Order | Stop Limit Order |
|---|---|---|---|---|---|---|
| account | str | Account ID, if not provided, returns all associated accounts | Optional | Optional | Optional | Optional |
| contract | Contract | Contract object | Required | Required | Required | Required |
| action | str | Buy/Sell direction, 'BUY': Buy, 'SELL': Sell | Required | Required | Required | Required |
| order_type | str | Order type, 'MKT' Market / 'LMT' Limit / 'STP' Stop / 'STP_LMT' Stop Limit | MKT | LMT | STP | STP_LMT |
| quantity | int | Order quantity, must be positive integer | Required | Required | Required | Required |
| limit_price | float | Limit order price, required when order type is LMT or STP_LMT | Required | Required | ||
| aux_price | float | For stop orders: stop price | N/A | N/A | Required | Required |
| adjust_limit | float | Price adjustment range (default 0 means no adjustment, positive for upward, negative for downward), automatically adjusts input price to legal price levels. E.g., 0.001 means upward adjustment within 0.1%; -0.001 means downward adjustment within 0.1%. Default 0 means no adjustment | N/A | Optional | Optional | Optional |
| time_in_force | str | Order validity period, can only be DAY (day order) or GTC (good till canceled), default is DAY | Optional | Optional | Optional | Optional |
| outside_rth | bool | True: Allow pre/post market trading (US stocks only), False: Don't allow, default True. (Market orders only valid during market hours, will ignore outside_rth parameter) | N/A | Optional | Optional | N/A |
| secret_key | str | For institutional users only, trader key | Optional | Optional | Optional | Optional |
| user_mark | str | Order remark information, cannot be modified after placing order, returns userMark info when querying orders | Optional | Optional | Optional | Optional |
Example
from tigeropen.common.util.contract_utils import stock_contract
from tigeropen.trade.trade_client import TradeClient
from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='/path/to/your/properties/file/')
trade_client = TradeClient(client_config)
contract = stock_contract(symbol='XYZX', currency='USD')
order = openapi_client.create_order(account, contract, 'BUY', 'LMT', 100, limit_price=5.0)
trade_client.place_order(order)
Updated 7 days ago