# 持仓
### 描述
实时推送用户持仓数据
以下事件发生时推送数据：
1. 首次订阅，推送，全量
2. 统一账户合约平仓委托单下单，推送，增量
3. 统一账户合约开仓委托成交，推送，增量
4. 统一账户合约平仓委托成交，推送，增量
5. 统一账户合约平仓委托单改单，推送，增量
6. 统一账户合约平仓委托单撤单，推送，增量
```json title="请求示例"
{
"op": "subscribe",
"args": [
{
"instType": "UTA",
"topic": "position"
}
]
}
```
### 请求参数
| 参数名 | 参数类型 | 是否必须 | 描述 |
|:--------------|:-------------------|-----|:-------------------------------------------------|
| op | String | 是 | 操作:
`subscribe` 订阅
`unsubscribe` 取消订阅 |
| args | List<Object> | 是 | 请求订阅的频道列表 |
| > instType | String | 是 | 产品类型
`UTA` 统一账户 |
| > topic | String | 是 | 频道名: `position` 仓位 |
```json title="订阅返回示例"
{
"event": "subscribe",
"arg": {
"instType": "UTA",
"topic": "position"
},
"code": "",
"msg": "",
"connId": "xxxxxxxxxx"
}
```
### 返回参数说明
| 返回字段 | 参数类型 | 字段说明 |
|:--------------|:---------|:----------------------------------------------------------------|
| event | String | 操作
`subscribe` 订阅
`unsubscribe` 退订
`error` 参数错误 |
| arg | Object | 订阅的频道 |
| > instType | String | 产品类型
`UTA` 统一账户 |
| > topic | String | 频道名
`position` 仓位 |
| code | String | 错误码 |
| msg | String | 错误消息 |
| connId | String | 连接ID |
```json title="推送示例"
{
"data": [
{
"symbol": "BTCUSDT",
"leverage": "20",
"openFeeTotal": "",
"mmr": "",
"breakEvenPrice": "",
"available": "0",
"liqPrice": "",
"marginMode": "crossed",
"unrealisedPnl": "0",
"markPrice": "94987.1",
"createdTime": "1736378720620",
"avgPrice": "0",
"totalFundingFee": "0",
"cashDividend": "0",
"updatedTime": "1736378720620",
"marginCoin": "USDT",
"frozen": "0",
"profitRate": "",
"closeFeeTotal": "",
"marginSize": "0",
"curRealisedPnl": "0",
"size": "0",
"positionStatus": "ended",
"posSide": "long",
"holdMode": "hedge_mode"
}
],
"arg": {
"instType": "UTA",
"topic": "position"
},
"action": "update",
"ts": 1736378720624
}
```
### 参数说明
| 参数 | 类型 | 描述 |
|---------------------|--------------------|------------------------------------------------------|
| arg | Object | 订阅成功频道 |
| > instType | String | 产品线类型
`UTA`统一账户 |
| > topic | String | 频道名
`position`仓位频道 |
| action | String | 推送数据动作
`snapshot`全量
`update` 增量 |
| data | List<Object> | 订阅的数据 |
| >symbol | String | 交易对名称 |
| >marginCoin | String | 保证金币种 |
| >marginSize | String | 保证金数量 |
| >marginMode | String | 保证金模式
`crossed` 全仓
`isolated` 逐仓 |
| >posSide | String | 持仓方向
`long` 多
`short`空 |
| >holdMode | String | 持仓模式
`one_way_mode`单向持仓
`hedge_mode`双向持仓 |
| >positionStatus | String | 仓位状态
`opening`进行中
`ended`完结 |
| >size | String | 持仓数量
`size` = `available` + `frozen` |
| >available | String | 可平仓数量 |
| >frozen | String | 冻结数量 |
| >avgPrice | String | 开仓平均价 |
| >leverage | String | 杠杆倍数 |
| >curRealisedPnl | String | 已实现盈亏 (不包含手续费和资金费用) |
| >unrealisedPnl | String | 未实现盈亏 |
| >liqPrice | String | 预估强平价 |
| >mmr | String | 维持保证金率 |
| >marginRate | String | 保证金率 |
| >markPrice | String | 标记价格 |
| >openFeeTotal | String | 开仓总计手续费 |
| >closeFeeTotal | String | 平仓总计手续费 |
| >breakEvenPrice | String | 仓位盈亏平衡价 |
| >profitRate | String | 收益率 |
| >totalFundingFee | String | 资金费用 仓位存续期间，资金费用的累加值，初始值为空，表示还没收取过资金费 |
| >cashDividend | String | 现金派息，单位：USDT |
| >createdTime | String | 持仓创建时间 Unix时间戳的毫秒数格式，如 1597026383085 |
| >updatedTime | String | 最近一次持仓更新时间 Unix时间戳的毫秒数格式，如 1597026383085 |
## 收益率计算公式
收益率的计算公式为：
回报率=未实现盈亏÷初始保证金，
初始保证金=开仓均价x持仓数量÷杠杆÷保证金币指数价格