获取当前持仓信息
API说明
此接口允许用户通过指定合约查询当前开仓持仓（已成交订单）的信息。用户还可以通过提供一个或多个持仓ID来检索特定持仓的详情。
注意：当前持仓信息数据只能通过 RESTful API 获取。
注意事项
- 此接口允许用户通过指定合约查询当前开仓持仓信息。如有需要，用户还可以通过提供一个或多个持仓ID来检索特定持仓的详情。
- 该接口与“市价平仓”接口在URL结构上较为相似，用户应仔细区分以确保采用正确的请求方法，避免因混淆导致非预期操作或数据异常。
认证
这是一个私有接口，需要认证。有关使用RESTful API的详细 信息，请参考简介 > 认证和代码示例 > 合约 > RESTful私有接口。
请求方法
GET
接口地址
频率限制
该接口的调用频率限制为：每个 IP 和用户 ID 每秒最多请求10次。
此外，该接口还受到全局频率限制的约束。
有关"全局速率限制"和"API限频策略"的详细信息，请参阅“频率限制”部分，跳转
请求参数
| 参数 | 必填 | 类型 | 描述 |
|---|---|---|---|
| instrument | true | String | 交易品种的基础货币（例如，BTC或btc）。此参数不区分大小写。注意：对于以数字开头的交易品种（例如1000PEPE），大写和小写格式都有效。 |
| openIds | false | String | 一个或多个以逗号(,)分隔的持仓ID。例如：'positionId1,positionId2,positionId3'注意：持仓ID数量不能超过20个。 |
响应参数
| 参数 | 类型 | 描述 |
|---|---|---|
| id | Long | 持仓ID |
| base | String | 交易品种基础货币，例如btc |
| baseSize | BigDecimal | 合约面值 |
| createdDate | Long | 持仓创建时间戳 |
| currentPiece | BigDecimal | 当前持仓张数 |
| direction | String | 交易方向：做多(long)/做空(short) |
| fee | BigDecimal | 资金费 |
| fundingSettle | BigDecimal | 已结算资金费 |
| indexPrice | BigDecimal | 触发时的指数价格 |
| instrument | String | 交易品种的基础货币，例如BTC或ETH |
| leverage | BigDecimal | 持仓杠杆率 |
| margin | BigDecimal | 持仓使用的保证金 |
| orderPrice | BigDecimal | 订单执行价格 |
| openPrice | BigDecimal | 持仓开仓价格 |
| originalType | String | 原始订单类型 |
| posType | String | 订单执行时的持仓类型：plan/planTrigger/execute |
| positionMargin | BigDecimal | 持仓保证金 |
| positionModel | Integer | 仓位模式：0：逐仓，1：全仓 |
| quantity | String | 基于quantityUnit 指定订单数量： 当 quantityUnit = 0 时，数量以计价货币计量（例如，BTC-USDT 中的 USDT）； 当 quantityUnit = 1 时，数量以合约张数计量； 当 quantityUnit = 2 时，数量以基础货币计量（例如，BTC-USDT 中的 BTC）。 |
| quantityUnit | BigDecimal | 用于指定订单数量的计量单位： 0：以计价货币计价（例如，BTC-USDT 合约中的 USDT）； 1：以合约张数计价； 2：以基础货币计价（例如，BTC-USDT 合约中的 BTC）。 |
| status | String | 状态：(open/close) |
| stopLossPrice | String | 止损价格 |
| stopLossRate | String | 止损率 |
| stopProfitPrice | String | 止盈价格 |
| stopProfitRate | String | 止盈率 |
| stopLossOrderPrice | String | 止损限价 |
| stopProfitOrderPrice | String | 止盈限价 |
| stopProfitType | String | 触发后的永续合约计划订单类型：plan：限价单，execute：市价单 |
| stopLossType | String | 触发后的永续合约计划订单类型：plan：限价单，execute：市价单 |
| totalPiece | BigDecimal | 合约总张数 |
| updatedDate | String | 最后更新时间戳 |
| userId | Long | 用户ID |
| autoDeleveragingScore | Integer | （用户可忽略） |
| profitUnreal | Float | 当前持仓的未实现盈亏 |
| liquidationPrice | Float | 强平价格 |
| triggerType | Integer | 指定"triggerPrice"满足时的订单类型：0：限价单，1：市价单 |
| triggerPrice | BigDecimal | 永续合约计划订单的触发价格 |
请求示例
以下Python代码展示了如何获取BTC的当前开仓持仓信息。
注意：完整代码示例请参考简介 > 认证和代码示例 > 合约 > RESTful私有接口。
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)
注意：完整Java代码示例请参考简介 > 认证和代码示例 > 合约 > RESTful私有接口。
响应示例
以下是上述Python请求返回的示例响应：
{'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': ''}