Get Current Position Information
API Description
This interface allows users to query information on current open positions(filled orders) by specifying an instrument. Users can also retrieve details of specific positions by providing one or more Position IDs.
Note: This function is available via only RESTful API.
Precautions
- This interface allows users to query the current open positions information by specifying an instrument. If needed, users can also retrieve details of specific positions by providing one or more Position IDs.
- This interface closely resembles "closing postions at market price" endpoint. Users should carefully distinguish similar URLs and ensure the correct request method is used to avoid unintended actions.
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 |
|---|---|---|---|
| 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. |
| openIds | false | String | One or more position IDs separated by comma (,). Example: 'positionId1,positionId2,positionId3' Note: The number of positions IDs cannot exceed 20. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| id | Long | Position ID |
| base | String | Contract base currency, such as BTC |
| baseSize | BigDecimal | Contract face value |
| createdDate | Long | Position creation timestamp |
| currentPiece | BigDecimal | Current number of contracts |
| direction | String | Trade direction:long/short |
| fee | BigDecimal | Funding fee |
| fundingSettle | BigDecimal | Settled funding fee |
| indexPrice | BigDecimal | Index price at trigger |
| instrument | String | Base currency of the instrument e.g., BTC or ETH. |
| leverage | BigDecimal | Position leverage |
| margin | BigDecimal | Margin used by position |
| orderPrice | BigDecimal | Order execution price |
| openPrice | BigDecimal | Position opening price |
| originalType | String | Original order type |
| posType | String | Position type upon order execution: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) |
| 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 |
| stopProfitType | String | The type of perpetual contract plan order after triggering: plan: limit order, execute: market order. |
| stopLossType | String | The type of perpetual contract plan order after triggering: plan: limit order, execute: market order. |
| totalPiece | BigDecimal | Total number of contracts |
| updatedDate | String | Last update timestamp |
| userId | Long | User ID |
| autoDeleveragingScore | Integer | (user can ignore it) |
| profitUnreal | Float | Current unrealized profit or loss of the open position |
| liquidationPrice | Float | Liquidation price |
| triggerType | Integer | Specifies type of order once "triggerPrice" is met: 0: Limit order 1 : Market order |
| triggerPrice | BigDecimal | Trigger price for perpetual contract plan order |
Request Example
The following Python code shows how to get the current open position information for BTC.
Note: For a complete code example, please refer to Introduction > Authentication & Code Snippet > Futures > RESTful Private Interface.
params = {
"instrument": "BTC",
}
api_url = "/v1/perpum/positions"
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': [{'autoDeleveragingScore': 1,
'base': 'btc',
'baseSize': 0.001,
'closedPiece': 0,
'createdDate': 1740572391000,
'currentPiece': 1,
'direction': 'short',
'fee': '0.0529',
'fundingFee': '0',
'fundingSettle': 0,
'id': 2435521222631982507,
'indexPrice': 88230.6,
'instrument': 'BTC',
'leverage': 1,
'margin': 88.2305,
'openPrice': 88230.5,
'orderPrice': 0,
'originalType': 'execute',
'posType': 'execute',
'positionMargin': 88.2305,
'positionModel': 0,
'profitReal': 0,
'profitUnreal': 0.0086,
'quantity': 88.2305,
'quantityUnit': 0,
'source': 'api',
'status': 'open',
'totalPiece': 1,
'updatedDate': 1740572391000,
'userId': 1162061}],
'msg': ''}