Get Order Information
API Description
This interface provides information for current unfilled orders. Users can specify a list of order IDs to query specific orders. If neither the instrument nor order IDs are specified, the response will include all unfilled orders under the specified order type. The response includes details such as the instrument, trade direction, quantity, quantity unit, margin, leverage, maker fee, taker fee, timestamp etc.
Note: Order information data is only available via RESTful API.
Precautions
- This API is only used to obtain information about unfulfilled orders. It does not support batch query of all order records by orderId. Please do not confuse usage scenarios.
- The request parameter "positionType" may return additional data beyond the specified type. For example: If set to execute (market orders), the response may also include plan orders (limit orders). For "planTrigger", the response will be returned only after the order is triggered and placed. For "moveStopProfitLoss", the response behaves as expected.
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 Policyolicy*, please refer to the "Frequency Limit" section at click here
Request Parameters
| Parameter | Mandatory | Type | Description |
|---|---|---|---|
| sourceIds | false | String | List of order IDs separated by commas (,). Example: "orderId1,orderId2,orderId3" Note: The number of order IDs cannot exceed 20. |
| positionType | true | String | Order type: execute/plan/moveStop/stopProfitLoss execute: market order, plan: plan order， moveStop: trailing stop loss and take profit， stopProfitLoss: stop loss and take profit |
| 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 |
|---|---|---|
| id | String | Order ID |
| baseSize | BigDecimal | Contract size in base currency |
| contractType | String | Contract type: 1: perpetual contract |
| userId | Long | Contract account user ID |
| fee | BigDecimal | Handling fee |
| createdDate | Long | Order creation timestamp |
| currentPiece | BigDecimal | Current number of contracts |
| direction | String | Trade direction:long/short |
| frozenFee | BigDecimal | Frozen handeling fee |
| indexPrice | BigDecimal | Index trigger price |
| instrument | String | Represents trading instrument. Example: BTC (for BTC/USDT), BTC_USDC (for BTC/USDC) |
| leverage | BigDecimal | Position leverage |
| liquidateBy | String | Opening and closing event types: Manual |
| makerFee | BigDecimal | Maker fee |
| takerFee | BigDecimal | Taker fee |
| margin | BigDecimal | Margin used by the position |
| orderPrice | BigDecimal | Order price specified by user |
| totalPiece | BigDecimal | Total number of contracts |
| 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 |
| 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) |
| status | String | Status:open/close |
| stopLossPrice | String | Stop loss price |
| stopLossRate | String | Stop loss rate |
| stopProfitPrice | String | Take profit price |
| stopProfitRate | String | Take profit rate |
| stopLossOrderPrice | String | Stop loss limit price |
| stopProfitOrderPrice | String | Take profit limit price |
| updatedDate | Long | Last order update timestamp |
| source | String | Source: web/api |
| thirdOrderId | String | Custom order ID assigned by the user |
Request Example
The following Python code shows how to get order information.
Note: For a complete code example, please refer to Introduction > Authentication & Code Snippet > Futures > Restful Private Interface.
params = {
"positionType" : "execute",
# "instrument" : "btc",
"sourceIds" : "33308753606524437,33308753605637070,33308753616147587" }
api_url = "/v1/perpum/order"
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': [{'baseSize': 0.002,
'contractType': 1,
'createdDate': 1740905644000,
'currentPiece': 2,
'direction': 'long',
'fee': '0',
'frozenFee': '0.0168',
'id': 33308753605637070,
'indexPrice': 85880.1,
'instrument': 'BTC',
'leverage': 2,
'liquidateBy': 'manual',
'makerFee': '0.0001',
'margin': 84,
'orderPrice': 84000,
'orderStatus': 'unFinish',
'originalType': 'plan',
'posType': 'plan',
'positionMargin': 84,
'positionModel': 0,
'quantity': 100,
'quantityUnit': 0,
'source': 'api',
'status': 'open',
'stopLossPrice': 83000,
'stopLossRate': 0.02380952,
'stopProfitPrice': 95000,
'stopProfitRate': 0.2619048,
'takerFee': '0.0006',
'thirdOrderId': '103-12-53',
'totalPiece': 2,
'triggerPrice': 84400,
'triggerType': 1,
'updatedDate': 1740905777000,
'userId': 1162061}, {..........},{.......}],
'msg': ''}