Skip to main content

Test Order(TRADE)

API Description

Testing order request, this order will not be submitted to matching engine

HTTP Request

POST /fapi/v1/order/test

Request Parameters

NameTypeMandatoryDescription
symbolSTRINGYES
sideENUMYES
positionSideENUMNODefault BOTH for One-way Mode ; LONG or SHORT for Hedge Mode. It must be sent in Hedge Mode.
typeENUMYES
timeInForceENUMNO
quantityDECIMALNOCannot be sent with closePosition=true(Close-All)
reduceOnlySTRINGNO"true" or "false". default "false". Cannot be sent in Hedge Mode; cannot be sent with closePosition=true
priceDECIMALNO
newClientOrderIdSTRINGNOA unique id among open orders. Automatically generated if not sent. Can only be string following the rule: ^[\.A-Z\:/a-z0-9_-]{1,36}$
stopPriceDECIMALNOUsed with STOP/STOP_MARKET or TAKE_PROFIT/TAKE_PROFIT_MARKET orders.
closePositionSTRINGNOtrue, false;Close-All,used with STOP_MARKET or TAKE_PROFIT_MARKET.
activationPriceDECIMALNOUsed with TRAILING_STOP_MARKET orders, default as the latest price(supporting different workingType)
callbackRateDECIMALNOUsed with TRAILING_STOP_MARKET orders, min 0.1, max 5 where 1 for 1%
workingTypeENUMNOstopPrice triggered by: "MARK_PRICE", "CONTRACT_PRICE". Default "CONTRACT_PRICE"
priceProtectSTRINGNO"TRUE" or "FALSE", default "FALSE". Used with STOP/STOP_MARKET or TAKE_PROFIT/TAKE_PROFIT_MARKET orders.
newOrderRespTypeENUMNO"ACK", "RESULT", default "ACK"
priceMatchENUMNOonly avaliable for LIMIT/STOP/TAKE_PROFIT order; can be set to OPPONENT/ OPPONENT_5/ OPPONENT_10/ OPPONENT_20: /QUEUE/ QUEUE_5/ QUEUE_10/ QUEUE_20; Can't be passed together with price
selfTradePreventionModeENUMNONONE:No STP / EXPIRE_TAKER:expire taker order when STP triggers/ EXPIRE_MAKER:expire taker order when STP triggers/ EXPIRE_BOTH:expire both orders when STP triggers; default NONE
goodTillDateLONGNOorder cancel time for timeInForce GTD, mandatory when timeInforce set to GTD; order the timestamp only retains second-level precision, ms part will be ignored; The goodTillDate timestamp must be greater than the current time plus 600 seconds and smaller than 253402300799000
recvWindowLONGNO
timestampLONGYES

Additional mandatory parameters based on type:

TypeAdditional mandatory parameters
LIMITtimeInForce, quantity, price
MARKETquantity
STOP/TAKE_PROFITquantity, price, stopPrice
STOP_MARKET/TAKE_PROFIT_MARKETstopPrice
TRAILING_STOP_MARKETcallbackRate
  • Order with type STOP, parameter timeInForce can be sent ( default GTC).

  • Order with type TAKE_PROFIT, parameter timeInForce can be sent ( default GTC).

  • Condition orders will be triggered when:

    • If parameterpriceProtectis sent as true:
      • when price reaches the stopPrice ,the difference rate between "MARK_PRICE" and "CONTRACT_PRICE" cannot be larger than the "triggerProtect" of the symbol
      • "triggerProtect" of a symbol can be got from GET /fapi/v1/exchangeInfo
    • STOP, STOP_MARKET:
      • BUY: latest price ("MARK_PRICE" or "CONTRACT_PRICE") >= stopPrice
      • SELL: latest price ("MARK_PRICE" or "CONTRACT_PRICE") <= stopPrice
    • TAKE_PROFIT, TAKE_PROFIT_MARKET:
      • BUY: latest price ("MARK_PRICE" or "CONTRACT_PRICE") <= stopPrice
      • SELL: latest price ("MARK_PRICE" or "CONTRACT_PRICE") >= stopPrice
    • TRAILING_STOP_MARKET:
      • BUY: the lowest price after order placed <= activationPrice, and the latest price >= the lowest price * (1 + callbackRate)
      • SELL: the highest price after order placed >= activationPrice, and the latest price <= the highest price * (1 - callbackRate)
  • For TRAILING_STOP_MARKET, if you got such error code.
    {"code": -2021, "msg": "Order would immediately trigger."}
    means that the parameters you send do not meet the following requirements:

    • BUY: activationPrice should be smaller than latest price.
    • SELL: activationPrice should be larger than latest price.
  • If newOrderRespType is sent as RESULT :

    • MARKET order: the final FILLED result of the order will be return directly.
    • LIMIT order with special timeInForce: the final status result of the order(FILLED or EXPIRED) will be returned directly.
  • STOP_MARKET, TAKE_PROFIT_MARKET with closePosition=true:

    • Follow the same rules for condition orders.
    • If triggered,close all current long position( if SELL) or current short position( if BUY).
    • Cannot be used with quantity paremeter
    • Cannot be used with reduceOnly parameter
    • In Hedge Mode,cannot be used with BUY orders in LONG position side. and cannot be used with SELL orders in SHORT position side
  • selfTradePreventionMode is only effective when timeInForce set to IOC or GTC or GTD.

  • In extreme market conditions, timeInForce GTD order auto cancel time might be delayed comparing to goodTillDate

Response Example

{
"clientOrderId": "testOrder",
"cumQty": "0",
"cumQuote": "0",
"executedQty": "0",
"orderId": 22542179,
"avgPrice": "0.00000",
"origQty": "10",
"price": "0",
"reduceOnly": false,
"side": "BUY",
"positionSide": "SHORT",
"status": "NEW",
"stopPrice": "9300", // please ignore when order type is TRAILING_STOP_MARKET
"closePosition": false, // if Close-All
"symbol": "BTCUSDT",
"timeInForce": "GTD",
"type": "TRAILING_STOP_MARKET",
"origType": "TRAILING_STOP_MARKET",
"activatePrice": "9020", // activation price, only return with TRAILING_STOP_MARKET order
"priceRate": "0.3", // callback rate, only return with TRAILING_STOP_MARKET order
"updateTime": 1566818724722,
"workingType": "CONTRACT_PRICE",
"priceProtect": false, // if conditional order trigger is protected
"priceMatch": "NONE", //price match mode
"selfTradePreventionMode": "NONE", //self trading preventation mode
"goodTillDate": 1693207680000 //order pre-set auot cancel time for TIF GTD order
}