Get Batch Historical Orders (7 Days)
API Description
This API returns historical order records from the past seven days and supports batch queries through the "symbols" parameter. Users can filter results by page, size, and order type. The response includes key order details such as status, margin, leverage, and size etc.
Note: Batch Historical orders data is only available via RESTful API.
Precautions
- 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/batchInsHistory
Frequency Limit
The frequency limit for this interface is 1 request/second 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 Policy, 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: Maximum limit 500 orders |
| originType | true | String | Initial order type : plan/planTrigger/execute execute: market order plan: for plan 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 |
| symbols | true | String | Specify multiple instruments via a comma-separated string. Example: "BTC,ETH,1000PEPE" Note: Specify only base currency for USDT margined coins i.e., BTC for BTCUSDT. Note: Maximum of 20 instruments are allowed in a request. |
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 batch historical orders records for the past seven days. Note: For a complete code example, please refer to Introduction > Authentication & Code Snippet > Futures > Restful Private Interface.
params = {
"page" : 1,
"pageSize" : 12,
"originType" : "execute",
"symbols" : "BTC,ETH",
}
api_url = "/v1/perpum/orders/batchInsHistory"
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:
{'code': 0,
'data':
{'nextId': 0,
'prevId': 0,
'rows': [
{'avgPrice': '3027.94',
'base': 'eth',
'baseSize': '0',
'cancelPiece': 0,
'completeUsdt': '60.5588',
'contractType': 1,
'createdDate': 1763452322000,
'currentPiece': '2',
'direction': 'long',
'entrustUsdt': '60.5588',
'fee': 0.03633528,
'finalOrderStatus': 'finish',
'havShortfall': False,
'hedgeId': 23765440242368518,
'id': '33309107055452107',
'indexPrice': '3027.92',
'instrument': 'ETH',
'leverage': '3',
'liquidateBy': 'manual',
'margin': '0.030279400000002',
'openId': 2435521222639519743,
'orderId': 2776199686,
'orderPrice': '2147483647',
'orderStatus': 'finish',
'originalType': 'execute',
'posType': 'execute',
'positionModel': 0,
'quantity': '2',
'quantityUnit': 1,
'quote': 'usdt',
'source': 'web',
'status': 'open',
'stepMarginVersion': 0,
'thirdOrderId': '',
'totalPiece': '2',
'tradePiece': 2,
'updatedDate': 1763452322000,
'userId': 1162061},
{'avgPrice': '104427.5',
'base': 'btc',
'baseSize': '0',
'cancelPiece': 0,
'completeUsdt': '626.565',
'contractType': 1,
'createdDate': 1762867076000,
'currentPiece': '6',
'direction': 'short',
'entrustUsdt': '626.565',
'fee': 0.375939,
'finalOrderStatus': 'finish',
'havShortfall': False,
'hedgeId': 23688730875116550,
'id': '33309091808724570',
'indexPrice': '104409.6',
'instrument': 'BTC',
'leverage': '13',
'liquidateBy': 'manual',
'margin': '48.1899230769230624',
'openId': 2435521222639289274,
'orderId': 3060259431,
'orderPrice': '2147483647',
'orderStatus': 'finish',
'originalType': 'execute',
'posType': 'execute',
'positionModel': 0,
'quantity': '48.1899230769230624',
'quantityUnit': 1,
'quote': 'usdt',
'source': 'web',
'status': 'close',
'stepMarginVersion': 0,
'thirdOrderId': '',
'totalPiece': '6',
'tradePiece': 6,
'updatedDate': 1762867076000,
'userId': 1162061},
{'avgPrice': '104411.5',
'base': 'btc',
'baseSize': '0',
'cancelPiece': 0,
'completeUsdt': '626.469',
'contractType': 1,
'createdDate': 1762867068000,
'currentPiece': '6',
'direction': 'short',
'entrustUsdt': '626.469',
'fee': 0.3758814,
'finalOrderStatus': 'finish',
'havShortfall': False,
'hedgeId': 23688729854065670,
'id': '33309091808516140',
'indexPrice': '104410.3',
'instrument': 'BTC',
'leverage': '13',
'liquidateBy': 'manual',
'margin': '1.8100769230769376',
'openId': 2435521222639289274,
'orderId': 3060259335,
'orderPrice': '0',
'orderStatus': 'finish',
'originalType': 'execute',
'posType': 'execute',
'positionModel': 0,
'quantity': '50',
'quantityUnit': 0,
'quote': 'usdt',
'source': 'web',
'status': 'open',
'stepMarginVersion': 0,
'thirdOrderId': '',
'totalPiece': '6',
'tradePiece': 6,
'updatedDate': 1762867068000,
'userId': 1162061}],
'total': 3},
'msg': ''}