Get Order History

Query order history. As order creation/cancellation is asynchronous, the data returned from this endpoint may delay. If you want to get real-time order information, you could query this endpoint or rely on the websocket stream (recommended).

Normal account covers: USDT perpetual / Inverse contract

info

• The orders in the last 7 days: supports querying all statuses
• The orders beyond 7 days: supports querying filled orders
• If no time is specified, the data from the last 7 days will be returned by default, You can query by symbol, baseCoin, orderId and orderLinkId, and if you pass multiple params, the system will process them according to this priority: orderId > orderLinkId > symbol.

HTTP Request

GET /cloud/trade/v3/order/history

Request Parameters

Parameter	Required	Type	Comments
category	true	string	Product type Normal account: linear, inverse, spot
symbol	false	string	Symbol name
orderId	false	string	Order ID
orderLinkId	false	string	User customised order ID
orderFilter	false	string	Order: active order, StopOrder: conditional order Others: all kinds of orders by default
orderStatus	false	string	Classic spot: not supported Others: return all status orders if not passed
startTime	false	integer	The start timestamp (ms) startTime and endTime must be passed together If not passed, query the past 7 days data by default For each request, startTime and endTime interval should be less then 7 days
endTime	false	integer	The end timestamp (ms) For each request, startTime and endTime interval should be less then 7 days
limit	false	integer	Limit for data size per page. [1, 50]. Default: 20
cursor	false	string	Cursor. Use the nextPageCursor token from the response to retrieve the next page of the result set

Response Parameters

Parameter	Type	Comments
category	string	Product type
list	array	Object
> orderId	string	Order ID
> orderLinkId	string	User customised order ID
> symbol	string	Symbol name
> price	string	Order price
> qty	string	Order qty
> side	string	Side. Buy,Sell
> positionIdx	integer	Position index. Used to identify positions in different position modes
> orderStatus	string	Order status
> cancelType	string	Cancel type
> rejectReason	string	Reject reason.
> avgPrice	string	Average filled price. If unfilled, it is ""
> leavesQty	string	The remaining qty not executed.
> leavesValue	string	The estimated value not executed.
> cumExecQty	string	Cumulative executed order qty
> cumExecValue	string	Cumulative executed order value.
> cumExecFee	string	Cumulative executed trading fee.
> timeInForce	string	Time in force
> orderType	string	Order type. Market,Limit. For TP/SL order, it means the order type after triggered
> stopOrderType	string	Stop order type
> orderIv	string	Implied volatility
> triggerPrice	string	Trigger price. If stopOrderType=TrailingStop, it is activate price. Otherwise, it is trigger price
> takeProfit	string	Take profit price
> stopLoss	string	Stop loss price
> tpslMode	string	TP/SL mode, Full: entire position for TP/SL. Partial: partial position tp/sl.
> tpLimitPrice	string	The limit order price when take profit price is triggered
> slLimitPrice	string	The limit order price when stop loss price is triggered
> tpTriggerBy	string	The price type to trigger take profit
> slTriggerBy	string	The price type to trigger stop loss
> triggerDirection	integer	Trigger direction. 1: rise, 2: fall
> triggerBy	string	The price type of trigger price
> lastPriceOnCreated	string	Last price when place the order
> reduceOnly	boolean	Reduce only. true means reduce position size
> closeOnTrigger	boolean	Close on trigger.
> placeType	string	Place type
> createdTime	string	Order created timestamp (ms)
> updatedTime	string	Order updated timestamp (ms)
nextPageCursor	string	Refer to the cursor request parameter

---

Request Example

GET /cloud/trade/v3/order/history?category=linear&limit=1 HTTP/1.1
Host: openapi-testnet.zoomex.com
X-BAPI-SIGN: XXXXX
X-BAPI-API-KEY: XXXXX
X-BAPI-TIMESTAMP: 1672221263407
X-BAPI-RECV-WINDOW: 5000

Response Example

{
    "retCode": 0,
    "retMsg": "OK",
    "result": {
        "list": [
            {
                "orderId": "14bad3a1-6454-43d8-bcf2-5345896cf74d",
                "orderLinkId": "YLxaWKMiHU",
                "symbol": "BTCUSDT",
                "price": "26864.40",
                "qty": "0.003",
                "side": "Buy",
                "isLeverage": "",
                "positionIdx": 1,
                "orderStatus": "Cancelled",
                "cancelType": "UNKNOWN",
                "rejectReason": "EC_PostOnlyWillTakeLiquidity",
                "avgPrice": "0",
                "leavesQty": "0.000",
                "leavesValue": "0",
                "cumExecQty": "0.000",
                "cumExecValue": "0",
                "cumExecFee": "0",
                "timeInForce": "PostOnly",
                "orderType": "Limit",
                "stopOrderType": "UNKNOWN",
                "orderIv": "",
                "triggerPrice": "0.00",
                "takeProfit": "0.00",
                "stopLoss": "0.00",
                "tpTriggerBy": "UNKNOWN",
                "slTriggerBy": "UNKNOWN",
                "triggerDirection": 0,
                "triggerBy": "UNKNOWN",
                "lastPriceOnCreated": "0.00",
                "reduceOnly": false,
                "closeOnTrigger": false,
                "tpslMode": "",
                "tpLimitPrice": "",
                "slLimitPrice": "",
                "placeType": "",
                "createdTime": "1684476068369",
                "updatedTime": "1684476068372"
            }
        ],
        "nextPageCursor": "page_token%3D39380%26",
        "category": "linear"
    },
    "retExtInfo": {},
    "time": 1684766282976
}