Place Order

This endpoint supports to create the order for Spot, USDT perpetual and inverse futures.

Normal account covers: USDT perpetual / Inverse contract / Spot

info

• Supported order type (orderType):
  Limit order: orderType=Limit, it is necessary to specify order qty and price.
  

  Market order: orderType=Market, execute at the best price in the market until the transaction is completed. When selecting a market order, the `price` is empty. In the futures trading system, in order to protect the serious slippage of the market order, the trading system will convert the market order into a limit order for matching. will be cancelled. The slippage threshold refers to the percentage that the order price deviates from the latest transaction price. The current threshold is set to 3% for BTC contracts and 5% for other contracts.

• Supported timeInForce strategy:
  GTC
IOC
FOK
PostOnly: If the order would be filled immediately when submitted, it will be cancelled. The purpose of this is to protect your order during the submission process. If the matching system cannot entrust the order to the order book due to price changes on the market, it will be cancelled. For the PostOnly order type, the quantity that can be submitted in a single order is more than other types of orders, please refer to the parameter lotSizeFilter > postOnlyMaxOrderQty in the instruments-info endpoint.

• How to create conditional order:
  When submitting an order, if triggerPrice is set, the order will be automatically converted into a conditional order. In addition, the conditional order does not occupy the margin. If the margin is insufficient after the conditional order is triggered, the order will be cancelled.

• Take profit / Stop loss: You can set TP/SL while placing orders. Besides, you could modify the position's TP/SL.

• Order quantity: The quantity of perpetual contracts you are going to buy/sell. For the order quantity, only supports positive number at present.

• Order price: Place a limit order, this parameter is required. If you have position, the price should be higher than the liquidation price. For the minimum unit of the price change, please refer to the priceFilter > tickSize field in the instruments-info endpoint.

• orderLinkId: You can customize the active order ID. We can link this ID to the order ID in the system. Once the active order is successfully created, we will send the unique order ID in the system to you. Then, you can use this order ID to cancel active orders, and if both orderId and orderLinkId are entered in the parameter input, will prioritize the orderId to process the corresponding order. Meanwhile, your customized order ID should be no longer than 36 characters and should be unique.

• Open orders up limit:
  Future: Each account can hold a maximum of 500 active orders simultaneously. This is contract-specific, so the following situation is allowed: the same account can hold 300 BTCUSD active orders and 280 ETHUSD active orders at the same time. For conditional orders, each account can hold a maximum of 10 active orders simultaneously. When the upper limit of orders is reached, you can still place orders with parameters of reduceOnly or closeOnTrigger.
  *Spot: * Supports a total of 500 pending orders, including a maximum of 30 stop loss orders.

• Rate limit:
  Please refer to rate limit table.

rules for spot stop win and stop loss orders

Spot goods support stop loss orders, but the processing logic behind them is slightly different
After the profit stop loss is created, you will receive an order ID When it is triggered, you will receive a brand new order ID

HTTP Request

POST /cloud/trade/v3/order/create

Request Parameters

Parameter	Required	Type	Comments
category	true	string	Product type Trading account: spot, linear, inverse Normal account: spot, linear, inverse
symbol	true	string	Symbol name
side	true	string	Buy, Sell
orderType	true	string	Market, Limit
qty	true	string	Order quantity. Trading account Spot: set marketUnit for market order qty unit, quoteCoin for market buy by default, baseCoin for market sell by default Futures: always use base coin as unit Classic account Spot: the unit of qty is quote coin for market buy order, for others, it is base coin Futures: always use base coin as unit
marketUnit	false	string	The unit for qty when create Spot market orders for Trading account. Currently, TP/SL and conditional orders are not supported. baseCoin: for example, buy BTCUSDT, then "qty" unit is BTC quoteCoin: for example, sell BTCUSDT, then "qty" unit is USDT
slippageToleranceType	false	string	Slippage tolerance Type for market order, TickSize, Percent Support linear, inverse, spot trading, but take profit, stoploss, conditional orders are not supported TickSize: the highest price of Buy order = ask1 + slippageTolerance x tickSize; the lowest price of Sell order = bid1 - slippageTolerance x tickSize Percent: the highest price of Buy order = ask1 x (1 + slippageTolerance x 0.01); the lowest price of Sell order = bid1 x (1 - slippageTolerance x 0.01)
slippageTolerance	false	string	Slippage tolerance value TickSize: range is [1, 10000], integer only Percent: range is [0.01, 10], up to 2 decimals
price	false	string	Order price. If you have net position, price needs to be greater than liquidation price
triggerDirection	false	integer	Conditional order param. Used to identify the expected direction of the conditional order. 1: triggered when market price rises to triggerPrice 2: triggered when market price falls to triggerPrice Only valid for linear and inverse
orderFilter	false	string	If it is not passed, Order by default. Order tpslOrder: Spot TP/SL order, the assets are occupied even before the order is triggered StopOrder: Spot conditional order, the assets will not be occupied until the price of the underlying asset reaches the trigger price, and the required assets will be occupied after the Conditional order is triggered Valid for spot only
triggerPrice	false	string	For futures, it is the conditional order trigger price. If you expect the price to rise to trigger your conditional order, make sure: triggerPrice > market price Else, triggerPrice < market price For spot, it is the TP/SL trigger price
triggerBy	false	string	Conditional order param. Trigger price type. LastPrice, IndexPrice, MarkPrice Only valid for linear and inverse
timeInForce	false	string	Time in force Market order will use IOC directly If not passed, GTC is used by default
positionIdx	false	integer	Used to identify positions in different position modes. Under hedge-mode, this param is required 0: one-way mode 1: hedge-mode Buy side 2: hedge-mode Sell side Only valid for linear and inverse
orderLinkId	false	string	User customised order ID. A max of 36 characters. Combinations of numbers, letters (upper and lower cases), dashes, and underscores are supported. future orderLinkId rules: optional param
takeProfit	false	string	Take profit price
stopLoss	false	string	Stop loss price
tpTriggerBy	false	string	The price type to trigger take profit. MarkPrice, IndexPrice, default: LastPrice Only valid for linear and inverse
slTriggerBy	false	string	The price type to trigger stop loss. MarkPrice, IndexPrice, default: LastPrice Only valid for linear and inverse
reduceOnly	false	boolean	What is a reduce-only order? true means your position can only reduce in size if this order is triggered. You must specify it as true when you are about to close/reduce the position When reduceOnly is true, take profit/stop loss cannot be set _Only valid for linear and inverse
closeOnTrigger	false	boolean	For a closing order. It can only reduce your position, not increase it. If the account has insufficient available balance when the closing order is triggered, then other active orders of similar contracts will be cancelled or reduced. It can be used to ensure your stop loss reduces your position regardless of current available margin. _Only valid for linear and inverse
smpType	false	string	Smp execution type.
tpslMode	false	string	TP/SL mode Full: entire position for TP/SL. Then, tpOrderType or slOrderType must be Market Partial: partial position tp/sl. Limit TP/SL order are supported. Note: When create limit tp/sl, tpslMode is required and it must be Partial Only valid for linear and inverse
tpLimitPrice	false	string	The limit order price when take profit price is triggered. Only works when tpslMode=Partial and tpOrderType=Limit
slLimitPrice	false	string	The limit order price when stop loss price is triggered. Only works when tpslMode=Partial and slOrderType=Limit
tpOrderType	false	string	The order type when take profit is triggered. Market(default), Limit. For tpslMode=Full, it only supports tpOrderType=Market
slOrderType	false	string	The order type when stop loss is triggered. Market(default), Limit. For tpslMode=Full, it only supports slOrderType=Market

Response Parameters

Parameter	Type	Comments
orderId	string	Order ID
orderLinkId	string	User customised order ID

---

Request Example

POST /cloud/trade/v3/order/create HTTP/1.1
Host: openapi-testnet.zoomex.com
X-BAPI-SIGN: XXXXX
X-BAPI-API-KEY: XXXXX
X-BAPI-TIMESTAMP: 1672211928338
X-BAPI-RECV-WINDOW: 5000
Content-Type: application/json


// USDT Perp open long position (one-way mode)
{"category":"linear","symbol":"BTCUSDT","side":"Buy","orderType":"Limit","qty":"1","price":"25000","timeInForce":"GTC","positionIdx":0,"orderLinkId":"usdt-test-01","reduceOnly":false,"takeProfit":"28000","stopLoss":"20000","tpslMode":"Partial","tpOrderType":"Limit","slOrderType":"Limit","tpLimitPrice":"27500","slLimitPrice":"20500"}

// USDT Perp close long position (one-way mode)
{"category": "linear", "symbol": "BTCUSDT", "side": "Sell", "orderType": "Limit", "qty": "1", "price": "30000", "timeInForce": "GTC", "positionIdx": 0, "orderLinkId": "usdt-test-02", "reduceOnly": true}

Response Example

{
    "retCode": 0,
    "retMsg": "OK",
    "result": {
        "orderId": "1321003749386327552",
        "orderLinkId": "test-postonly"
    },
    "retExtInfo": {},
    "time": 1672211918471
}