Get Transaction Details (3 Days)
API Description
This interface allows querying a comprehensive summary of transaction details from the past three days, including key trading metrics such as order status, position details, fees, profit/loss, leverage, margin, etc.
Note: Transaction details data is only available via RESTful API.
Precautions
- In case certain order gets filled, request parameter "originalType" may be misleading, as the interface returns same response even if a specified type (plan or execute) is requested. Users should not rely solely on this parameter to determine the nature of the order and should verify additional order details (Order Status, Position ID, Order ID) for accuracy.
- The response parameter "total" may also be misleading as both execute and plan orders are included even if a specific type is specified in case of filled order. It is recommended not to rely solely on this parameter.
- Unfilled orders are not displayed in this interface. However, if an unfilled order is cancelled, the cancellation will be reflected through this interface.
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
Frequency Limit
The frequency limit for this interface is 10 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 Policy, please refer to the "Frequency Limit" section at click here
Request Parameters
| Parameter | Mandatory | Type | Description |
|---|---|---|---|
| page | false | Integer | Current page |
| pageSize | false | Integer | Number of responses per page |
| originType | false | String | Initial order type : 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 |
| instrument | true | 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. |
| positionModel | false | Integer | Position margin mode: 0: Isolated margin 1: Cross margin |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| closePrice | BigDecimal | Price at which the position was closed. |
| userId | Long | Contract account user ID |
| closedPiece | BigDecimal | Closed contracts |
| createdDate | Long | Timestamp when the order was created. |
| currentPiece | BigDecimal | Current number of contracts |
| direction | String | Trade direction: long/short |
| fee | BigDecimal | Fee |
| feeRate | BigDecimal | Handling fee rate |
| fundingSettle | BigDecimal | Funding rate settlement amount |
| hedgeId | Long | 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 | Closing or opening event type |
| margin | BigDecimal | Margin allocated for this position. |
| netProfit | BigDecimal | Net profit |
| openId | Long | Position ID |
| openPrice | BigDecimal | Opening price at which order actually gets filled |
| orderId | Long | Order ID |
| orderPrice | BigDecimal | Order price specified by user |
| orderStatus | String | Order status: unFinish: Unfulfilled part: Partially filled Finish: Fully filled Cancel: Cancelled |
| originalType | String | Original order type |
| positionMargin | BigDecimal | Position margin |
| positionModel | Integer | Position margin mode: 0: Isolated margin, 1: Cross margin |
| 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) |
| settlementId | Long | Counterparty ID |
| status | String | The status of the trade: open: Active position close: Position closed cancel: Order canceled |
| takerMaker | Integer | Identifies whether the trade was a taker or maker trade: 1-taker, 2-maker |
| totalPiece | BigDecimal | The total number of contracts |
| updatedDate | Long | Timestamp of the latest trade update |
| thirdOrderId | String | A custom order ID assigned by the user |
| id | Long | ID |
| contractType | Integer | Contract type: 1: perpetual contract |
| baseSize | Integer | Contract size |
| isProfession | Integer | (user can ignore it) |
| processStatus | Integer | Match server processing status: 0: waiting 1: processing 2: success, 3: failure |
| source | String | Source: web/api |
| total | Integer | Total number of transactions. |
Request Example
The following Python code shows how to get the transaction details for BTC for the past three days.
Note: For a complete code example, please refer to Introduction > Authentication & Code Snippet > Futures > RESTful Private Interface.
params = {
"instrument" : "btc",
"positionModel" : 0,
"originType" : "plan",
"page" : 1,
# "pageSize" : 1,
}
api_url = "/v1/perpum/orders/deals"
request_url = f'{base_url}{api_url}'
method = "GET"
response_code, response_data = FuturesRestfulPrivate(params, api_url, method, sec_key, api_key) # the 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 actual response included 73 transection histories. For brevity, only one transection history is shown below:
{'code': 0,
'data': {'nextId': 0,
'prevId': 0,
'rows': [{'baseSize': 0.001,
'closePrice': 0,
'closedPiece': 0,
'contractType': 1,
'createdDate': 1741325037000,
'currentPiece': 0,
'direction': 'long',
'fee': '0',
'feeRate': '0',
'fundingFee': '0',
'fundingSettle': 0,
'id': 20865618454160389,
'instrument': 'BTC',
'isProfession': 0,
'leverage': 1,
'liquidateBy': 'moveStopProfitAndLoss',
'margin': 87.90975,
'netProfit': 0,
'openId': 2435521222632288678,
'openPrice': 87909.75,
'orderId': 20865172723909637,
'orderPrice': 0,
'orderStatus': 'cancel',
'originalType': 'moveStopProfitLoss',
'positionMargin': 0.0,
'positionModel': 0,
'processStatus': 1,
'quantity': 1,
'quantityUnit': 1,
'source': 'api',
'status': 'close',
'takerMaker': 1,
'thirdOrderId': '07-9-16',
'totalPiece': 1,
'triggerPrice': 0,
'triggerType': 1,
'updatedDate': 1741328437000,
'userId': 1162061}......],
'total': 73},
'msg': ''}