Get Order History

Description

Get previous futures orders. Orders that are completely canceled (no transaction has occurred) initiated through the API can only be queried for 4 hours.

HTTP Request

GET /v3/trade/order/history

Request Parameters

Parameter	Required	Type	Description
symbol	No	String	A trading pair, consisting of two currencies: base currency and quote currency
side	No	String	Trade Side, Enumerate BUY and SELL
ordId	No	String	Order ID
clOrdId	No	String	Client Order ID as assigned by the client
state	No	String	Order Status: Enumerate FILLED, PARTIALLY_CANCELED, CANCELED
type	No	String	Order type; various order types are supported.
sTime	No	String	Starting time of the history, Unix timestamp format in milliseconds. The default is the last 90 days
eTime	No	String	Ending time of the history, Unix timestamp format in milliseconds. The default is the last 90 days
from	No	Long	It is ordId. ID for the query starts at 0 by default.
limit	No	Integer	Pagination size defaults to 10, with a maximum limit of 100.
direct	No	String	Enumerate: PREV, NEXT, The default is NEXT

Response Parameters

Parameter	Type	Description
symbol	String	A trading pair, consisting of two currencies: base currency and quote currency
side	String	Enumerate: BUY and SELL
type	String	Order type; enumerate MARKET, LIMIT, and LIMIT_MAKER
ordId	String	Order ID
clOrdId	String	Client Order ID as assigned by the client
mgnMode	String	Margin Mode, Enumerate: ISOLATED, CROSS
posSide	String	Position side LONG SHORT BOTH
px	String	Price
sz	String	Order size, specifically in Cont
state	String	Order Status: Enumerate FILLED, PARTIALLY_CANCELED, CANCELED
cancelReason	String	USER_CANCEL_ORDER_ACTION, LIMIT_MAKER_ORDER_INCORRECT_PRICE_CONDITION, LIMIT_MATCH_IOC_OR_FOK_ORDER_PRICE_CANNOT_MATCH, LIMIT_MATCH_FOK_ORDER_MAKER_INSUFFICIENT_AVAILABLE_QUANTITY, LIMIT_MATCH_IOC_ORDER_CANNOT_FILLED, LIMIT_MATCH_ORDER_TAKER_SELF_TRADE,MARKET_ORDER_NO_OTHER_SIDE_ORDER, INVALID_PARAM_WHEN_PLACE_ORDER, INVALID_ORDER_TYPE_WHEN_PLACE_ORDER, INVALID_SEQUENCE_PLACE_ORDER_AFTER_CANCEL_SAME_ORDER, MATCH_SYMBOL_TRADE_LIMIT_NOT_EXIST, EXCEED_SLIPPAGE_TOLERANCE, OUT_OF_RANGE_LIMIT_PRICE,NO_MARGIN_QUANTITY_GREAT_THAN_POSITION, LIMIT_MATCH_ORDER_ONLY_SELF_TRADE, FL_CANCEL_ORDER_ACTION, RISK_CANCEL_ORDER_ACTION, SYS_CANCEL_ORDER_ACTION
source	String	Order Source: Enumerate WEB, APP, API, SMART, WEB_MARGIN, APP_IOS, APP_ANDROID, APP_IOS_MARGIN, APP_ANDROID_MARGIN, API_MARGIN, SMART_MARGIN, WS, WS_MARGIN, GRID, GRID_MARGIN, SYSTEM, COPY_TRADING, TRIGGER, LIQUIDATION, ADL, TRIAL, MARGIN_FL, MARGIN_FL_OFFLINE
reduceOnly	Boolean	Reduce only
timeInForce	String	Enumerate FOK, IOC, and GTC. It is an optional field with GTC by default.
avgPx	String	Average execution price
execQty	String	Cumulative execution amount
execAmt	String	Cumulative execution value
feeCcy	String	Name of the currency used for trading fees
feeAmt	String	Cumulative amount of trading fee
deductCcy	String	Name of the currency used to deduct trading fees
deductAmt	String	Cumulative amount of trading fee deducted
actType	String	Account type
qCcy	String	Quote currency
stpMode	String	Enumerate - EXPIRE_TAKER - EXPIRE_MAKER - EXPIRE_BOTH Default is NONE
cTime	String	Order creation time with a UTC timestamp (MS)
uTime	String	Order update time with a UTC timestamp (MS)

Request Example

{
  "symbol": "BTC_USDT_PERP",
  "direct": "NEXT",
  "From": "0",
  "limit": 100,
  "sTime": "1719971873000",
  "eTime": "1719973853000"
}

Response Example

{
  "code": 200,
  "data": [
    {
      "avgPx": "0.6272",
      "cTime": "1719973768748",
      "cancelReason": "",
      "clOrdId": "polo331380922769473536",
      "deductAmt": "0",
      "deductCcy": "0",
      "execAmt": "1.8816",
      "execQty": "3",
      "feeAmt": "0.00009408",
      "feeCcy": "USDT",
      "lever": "20",
      "mgnMode": "CROSS",
      "posSide": "BOTH",
      "ordId": "331380922769473536",
      "px": "60000",
      "reduceOnly": "false",
      "side": "BUY",
      "slPx": "",
      "slTrgPx": "",
      "slTrgPxType": "",
      "source": "WEB",
      "state": "FILLED",
      "stpMode": "NONE",
      "symbol": "BTC_USDT_PERP",
      "sz": "3",
      "timeInForce": "GTC",
      "tpPx": "",
      "tpTrgPx": "",
      "tpTrgPxType": "",
      "actType": "TRADING",
      "qCcy": "USDT",        
      "type": "LIMIT",
      "uTime": "1719973768764"
    },
    {
      "avgPx": "0.6272",
      "cTime": "1719973712694",
      "cancelReason": "",
      "clOrdId": "12345",
      "deductAmt": "0",
      "deductCcy": "0",
      "execAmt": "1.8816",
      "execQty": "3",
      "feeAmt": "0.00009408",
      "feeCcy": "USDT",
      "lever": "20",
      "mgnMode": "CROSS",
      "posSide": "BOTH",
      "ordId": "331380687661957120",
      "px": "0",
      "reduceOnly": "true",
      "side": "BUY",
      "slPx": "",
      "slTrgPx": "",
      "slTrgPxType": "",
      "source": "API",
      "state": "FILLED",
      "stpMode": "NONE",
      "symbol": "BTC_USDT_PERP",
      "sz": "3",
      "timeInForce": "GTC",
      "tpPx": "",
      "tpTrgPx": "",
      "tpTrgPxType": "",
      "actType": "TRADING",
      "qCcy": "USDT",  
      "type": "MARKET",
      "uTime": "1719973712703"
    },
    {
      "avgPx": "0",
      "cTime": "1719973298692",
      "cancelReason": "ORDER_SOURCE_API",
      "clOrdId": "4251fe5c-2b1e-4abd-b9b2-e7c713435653",
      "deductAmt": "0",
      "deductCcy": "0",
      "execAmt": "0",
      "execQty": "0",
      "feeAmt": "0",
      "feeCcy": "",
      "lever": "20",
      "mgnMode": "CROSS",
      "posSide": "BOTH",
      "ordId": "331378951211712512",
      "px": "60000",
      "reduceOnly": "false",
      "side": "SELL",
      "slPx": "",
      "slTrgPx": "",
      "slTrgPxType": "",
      "source": "API",
      "state": "CANCELED",
      "stpMode": "EXPIRE_TAKER",
      "symbol": "BTC_USDT_PERP",
      "sz": "2",
      "timeInForce": "GTC",
      "tpPx": "",
      "tpTrgPx": "",
      "tpTrgPxType": "",
      "actType": "TRADING",
      "qCcy": "USDT",  
      "type": "LIMIT",
      "uTime": "1719973526115"
    },
    {
      "avgPx": "0",
      "cTime": "1719973298689",
      "cancelReason": "ORDER_SOURCE_API",
      "clOrdId": "9e36e89c-6cab-45c6-9c8a-245b7547601a",
      "deductAmt": "0",
      "deductCcy": "0",
      "execAmt": "0",
      "execQty": "0",
      "feeAmt": "0",
      "feeCcy": "",
      "lever": "20",
      "mgnMode": "CROSS",
      "posSide": "BOTH",
      "ordId": "331378951199129601",
      "px": "60000",
      "reduceOnly": "false",
      "side": "SELL",
      "slPx": "",
      "slTrgPx": "",
      "slTrgPxType": "",
      "source": "API",
      "state": "CANCELED",
      "stpMode": "EXPIRE_TAKER",
      "symbol": "BTC_USDT_PERP",
      "sz": "2",
      "timeInForce": "GTC",
      "tpPx": "",
      "tpTrgPx": "",
      "tpTrgPxType": "",
      "actType": "TRADING",
      "qCcy": "USDT",  
      "type": "LIMIT",
      "uTime": "1719973454788"
    }
  ],
  "msg": "Success"
}