Get Historical Orders (3 Months)

API Description

This interface provides historical orders' records from the past three months. Users can filter results using parameters such as page number, page size, order type, and trading instrument. The response provides comprehensive order details, including status, margin, leverage, and order size.

Note: Historical Orders data is only available via RESTful API.

Precautions

1. If no parameters are specified, this interface will return 10 most recent historical orders' records from the past three months by default.
2. This interface returns only the orders that have been executed (i.e., entered a trade).

Authentication

This is a private interface and requires authentication. For details on using the RESTful API, refer to Introduction > Authentication & Code Snippet > Futures > RESTful Private Interface.

Request Method

GET

Endpoint

/v1/perpum/orders/archive

Frequency Limit

The frequency limit for this interface is 5 requests/s per user ID and IP. In addition to this per-interface limit, a global rate limit is also enforced.

For detailed information on Global rate limits and API Rate Limiting Policyolicyolicyolicy*, please refer to the "Frequency Limit" section at click here

Request Parameters

Parameter	Mandatory	Type	Description
page	false	Integer	Current page number
pageSize	false	Integer	Number of results per page. Note: If not specified, the interface will return the information of 10 most recent orders from the past three months.
originType	false	String	Initial order type : plan/planTrigger/execute execute: market order, plan: for planning different orders including limit order, triggered limit order, limit order with SL/TP, triggered limit order with SL/TP, triggered market orders, triggered market orders with SL/TP, planTrigger: planned trigger order
instrument	false	String	The base currency of the instrument. (e.g., BTC or btc). This parameter is case-insensitive. Note: For instruments that start with numbers (e.g., 1000PEPE), both uppercase and lowercase formats are valid.

Response Parameters

Parameter	Type	Description
userId	Long	Contract account User ID
baseSize	BigDecimal	Order size in base currency
completeUsdt	BigDecimal	Transaction amount in USDT
createdDate	Long	Timestamp when the order was created.
currentPiece	BigDecimal	Number of contracts currently held.
direction	String	Trade direction: long/short
entrustUsdt	BigDecimal	Order size in USDT
havShortfall	Boolean	Indicates whether the user is at risk of liquidation.
hedgeId	Long	Associated hedge ID
indexPrice	BigDecimal	Index price/latest price
instrument	String	Base currency of the instrument e.g., BTC or ETH.
leverage	BigDecimal	Position leverage
liquidateBy	String	Opening and closing event types:Manual
margin	BigDecimal	Margin used for the postiion
openId	Long	Position ID
orderId	Long	ID ( user can ignore it)
orderPrice	BigDecimal	Order price set by the user. Note: Ignore in case of market order
orderStatus	String	Order status: unFinish: Unfulfilled part: Partially filled Finish: Fully filled Cancel: Cancelled
originalType	String	Original order type.
posType	String	Position type:plan/planTrigger/execute
positionModel	Integer	Margin mode: 0: Isolated margin 1: Cross position
quantity	BigDecimal	Specifies order size based on quantityUnit: If quantityUnit=0, the quantity is measured the quote currency (e.g., USDT in BTC-USDT), If quantityUnit=1, the quantity is measured in number of contracts, If quantityUnit=2, the quantity is measured in the base currency (e.g., BTC in BTC-USDT)
quantityUnit	Integer	Specifies the unit for order size: 0: Denominated in the quote currency (e.g., USDT in BTC-USDT), 1: Denominated in number of contracts, 2: Denominated in the base currency (e.g., BTC in BTC-USDT)
status	String	Status: open/close
totalPiece	String	Total number of contracts.
updatedDate	Date	Timestamp of the latest trade update.
thirdOrderId	String	Custom order ID
tradePiece	Integer	Contract to be traded
stepMarginVersion	Integer	(User can ignore it)
id	Long	Order ID
cancelPiece	Integer	Number of contracts canceled.
contractType	Integer	Contract Type: 1: Linear perpetuals
source	String	Source: web/api
avgPrice	String	Average executed price.
triggerPrice	String	Trigger price for perpetual contract plan orders.
triggerType	Integer	Specifies order type once triggerPrice is met: 0: Limit order 1: Market order
thirdOrderId	String	Custom order ID assigned by the user

Request Example

The following Python code shows how to get the historical orders' records for the past three months.

Note: For a complete code example, please refer to Introduction > Authentication & Code Snippet > Futures > RESTful Private Interface.

params = {
    "page" : 1,
    "pageSize" : 5,
    "originType" : "execute",
    "instrument" : "BTC",
    }
 
api_url = "/v1/perpum/orders/archive"
method = "GET"
response_code, response_data = FuturesRestfulPrivate(params, api_url, method, sec_key, api_key)   # function FuturesRestfulPrivate() is defined in section (Introduction > Authentication & Code Snippet > Futures > RESTful Private Interface)

Note: For a complete Java code example, please refer to Introduction > Authentication & Code Snippet > Futures > RESTful Private Interface.

Response Example

The following is an example response returned by the above Python request. The response contained up to 5 orders from the past three months. For brevity, only one order is shown below:

{'code': 0,
 'data': {'nextId': 0,
  'prevId': 0,
  'rows': [{'avgPrice': '86070',
    'baseSize': '0',
    'cancelPiece': 0,
    'completeUsdt': '86.07',
    'contractType': 1,
    'createdDate': 1740915577000,
    'currentPiece': '1',
    'direction': 'short',
    'entrustUsdt': '86.07',
    'havShortfall': False,
    'hedgeId': 20811504068180998,
    'id': '33308753751538235',
    'indexPrice': '86077.2',
    'instrument': 'BTC',
    'leverage': '1',
    'liquidateBy': 'manual',
    'margin': '13.8267076',
    'openId': 2435521222632111503,
    'orderId': 2882616995,
    'orderPrice': '0',
    'orderStatus': 'finish',
    'originalType': 'execute',
    'posType': 'execute',
    'positionModel': 0,
    'quantity': '100',
    'quantityUnit': 0,
    'source': 'api',
    'status': 'open',
    'stepMarginVersion': 0,
    'thirdOrderId': 'historyoforder',
    'totalPiece': '1',
    'tradePiece': 1,
    'triggerPrice': '84400',
    'triggerType': 0,
    'updatedDate': 1740915577000,
    'userId': 1162061},.........{....}],
  'total': 114},
 'msg': ''}