Get Current Orders

API Description

This interface allows querying the unfilled order details for a specified instrument and order type, including instrument, direction, quantity, quantity unit, margin, leverage, maker fee, taker fee and timestamp.

Note: Current orders data is available via both RESTful and Websocket APIs. This page describes the RESTful API. For information on the Websocket API, please click here

Precautions

1. This interface does not support retrieving unfilled orders for all instruments in a single request.

2. If there's no unfilled orders for the specified instrument, the following response will be returned:

{'code': 0, 'data': {'nextId': 0, 'prevId': 0, 'rows': [], 'total': 0}, 'msg': ''}

3. The request parameter "positionType" is required but may not always function as expected. For example, specifying "execute" may still return "plan" orders. However, "planTrigger" and "moveStopProfitLoss" are working 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

/v1/perpum/orders/open

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 Policyolicyolicyolicyolicyolicy*, please refer to the "Frequency Limit" section at click here

Request Parameters

Parameter	Mandatory	Type	Description
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.
positionType	true	String	Order type: plan/execute/planTrigger/moveStopProfitLoss plan: plan order， execute: market order， planTrigger: planned trigger order， moveStopProfitLoss: trailing SL/TP
page	false	Integer	Current page number
pageSize	false	Integer	Number of records per page

Response Parameters

Parameter	Type	Description
id	String	Order ID
userId	Long	Futures contract user ID
baseSize	BigDecimal	Order size in base currency
createdDate	timestamp	Order creation timestamp
currentPiece	BigDecimal	Order size in the number of contracts
direction	String	Order direction:long, short
frozenFee	BigDecimal	Frozen order fee
indexPrice	BigDecimal	Index trigger price
instrument	String	Base currrency of the instrument i.e., BTC, ETH
leverage	BigDecimal	Position leverage
liquidateBy	String	Opening and closing event types: planClose/manual
margin	BigDecimal	Margin used by the position
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
posType	String	Position type:plan/planTrigger/execute
positionMargin	BigDecimal	Position margin
positionModel	Integer	Position margin mode: 0: Isolated margin 1: Cross margin
quantity	String	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	BigDecimal	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
takerFee	BigDecimal	Taker fee
totalPiece	BigDecimal	Total number of contracts
updatedDate	String	Last order update timestamp
primaryId	Long	CoinW database ID(users can ignore it)
contractType	Integer	Contract Type: 1: Linear perpetuals
total	Integer	Total number of current orders
openId	Long	Position ID

Request Example

The following Python code shows how to check the current orders.

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

params = {
        "instrument" : "BTC",    
        "positionType" : "plan",     
        }
        
api_url = "/v1/perpum/orders/open"
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:

{'code': 0,
 'data': {'nextId': 0,
  'prevId': 0,
  'rows': [{'baseSize': 0.001,
    'contractType': 1,
    'createdDate': 1740053261000,
    'currentPiece': 1,
    'direction': 'long',
    'fee': 0,
    'frozenFee': 0.00954,
    'id': 33308741701971947,
    'indexPrice': 97299.7,
    'instrument': 'BTC',
    'leverage': 1,
    'liquidateBy': 'manual',
    'makerFee': 0.0001,
    'margin': 95.4,
    'orderPrice': 95400,
    'orderStatus': 'unFinish',
    'originalType': 'plan',
    'posType': 'plan',
    'positionMargin': 95.4,
    'positionModel': 0,
    'primaryId': 2874310689,
    'processStatus': 1,
    'quantity': 100,
    'quantityUnit': 0,
    'source': 'api',
    'status': 'open',
    'takerFee': 0.0006,
    'totalPiece': 1,
    'updatedDate': 1740053261000,
    'userId': 1162061}],
  'total': 1},
 'msg': ''}