订阅持仓
API说明
此Websocket提供所有交易品种所有当前持仓（已成交订单）的实时信息。
注意：当前持仓数据可通过RESTful和Websocket接口获取。本页是Websocket接口的描述。如需了解RESTful接口，请参见 跳转
注意事项
- 此Websocket连接提供所有交易品种持仓实时更新。
- 用户必须首先建立连接。连接后，所有交易品种所有新开仓和平仓持仓将实时流式传输。
认证
这是一个私有接口，需要认证。有关使用Websocket API的详细信息，请参考简介 > 认证和代码示例 > 合约 > Websocket私有接口。
Websocket URL
频率限制
此订阅的频率限制为每IP每2秒10个请求。
订阅参数
| 参数 | 必填 | 类型 | 描述 |
|---|---|---|---|
| event | true | String | 订阅或取消订阅。sub：订阅；unsub：取消订阅。注意：此参数区分大小写。 |
| params | true | Json | 包含以下字段的数据对象： |
| -type | true | String | 定义功能类型，例如"position"。 |
| -biz | true | String | 指定频道，例如"futures"。 |
响应参数
| 参数 | 类型 | 描述 |
|---|---|---|
| biz | String | 指定频道，例如"futures"。 |
| type | String | 功能类型，例如"position"。 |
| result | boolean | 表示订阅或取消订阅是否成功：true/false |
| channel | String | 指定执行的操作：subscribe或unsubscribe。 |
| pairCode | String | 交易品种基础货币，即BTC |
| data | Json | 包含以下字段的数据对象： |
| -baseSize | String | 合约中的手数 |
| -closedPiece | String | 已平仓合约数量 |
| -closedQuantity | String | 已平仓数量 |
| -contractType | String | 合约类型：1：永续合约 |
| -createdDate | Long | 创建时间戳 |
| -currentPiece | String | 当前合约数量 |
| -direction | String | 交易方向：做多(long)/做空(short) |
| -distId | String | 分销商ID |
| -fee | String | 费用 |
| -fundingSettle | String | 资金费率结算金额 |
| -hedgeId | String | 对冲订单ID |
| -id | String | 持仓ID |
| -indexPrice | String | 触发时的指数价格 |
| -instrument | String | 交易品种的基础货币，例如BTC |
| -isProfession | Integer | 专业订单：0-否，1-是 |
| -leaderId | String | 交易员ID |
| -leverage | Integer | 持仓杠杆率 |
| -margin | String | 持仓保证金 |
| -openPrice | String | 开仓价格（订单成交时的价格） |
| -orderPrice | String | 用户指定的订单价格 |
| -originalType | String | 订单的原始类型：例如，plan/planTrigger/execute |
| -parentId | String | 注册用户（被邀请者）ID：0：活跃注册用户，1：未注册用户 |
| -partnerId | String | 合作伙伴ID |
| -posType | String | 持仓类型，例如plan/planTrigger/execute |
| -positionMargin | String | 持仓保证金 |
| -positionModel | Integer | 持仓持仓模式：0：逐仓，1：全仓 |
| -processStatus | Integer | 处理状态：0：正常状态，1：处理中 |
| -quantity | String | 基于quantityUnit 指定订单数量： 当 quantityUnit = 0 时，数量以计价货币计量（例如，BTC-USDT 中的 USDT）； 当 quantityUnit = 1 时，数量以合约张数计量； 当 quantityUnit = 2 时，数量以基础货币计量（例如，BTC-USDT 中的 BTC）。 |
| -quantityUnit | Integer | 用于指定订单数量的计量单位： 0：以计价货币计价（例如，BTC-USDT 合约中的 USDT）； 1：以合约张数计价； 2：以基础货币计价（例如，BTC-USDT 合约中的 BTC）。 |
| -remainCurrentPiece | String | 剩余合约数量 |
| -salesId | String | 销售ID |
| -settlementId | String | 结算ID |
| -source | String | 来源：api/web |
| -status | Integer | 状态：0：开仓，1：平仓，2：取消 |
| -totalPiece | String | 合约总数量 |
| -updatedDate | Long | 更新时间戳 |
| -userId | String | 用户ID |
订阅示例
以下Python代码展示了如何使用Websocket订阅当前持仓（已成交订单）信息。
注意：完整代码示例请参考简介 > 认证和代码示例 > 合约 > Websocket私有接口。
url = "wss://ws.futurescw.com/perpum"
subscription_payload = {"event": "sub",
"params": {"biz": "futures",
"type": "position"}}
api_key= "your_api_key"
sec_key = "your_sec_key"
FuturesWebsocketPrivate(url, api_key, sec_key, subscription_payload) # function FuturesWebsocketPrivate() is defined in section (Introduction > Authentication & Code Snippet > Futures > Websocket Private Interface)
注意：完整Java代码示例请参考简介 > 认证和代码示例 > 合约 > Websocket私有接口。
响应示例
Websocket将实时更新当前持仓数据。为简洁起见，以下仅显示上述Python订阅的一个持仓信息：
{'biz': 'futures',
'data': {'result': True},
'channel': 'subscribe',
'type': 'position'}
{'biz': 'futures',
'pairCode': 'BTC',
'data': [{'currentPiece': '1',
'isProfession': 0,
'leverage': '1',
'distId': '0',
'originalType': 'execute',
'processStatus': 0,
'contractType': 1,
'fee': '0.05328162',
'openPrice': '88802.7',
'instrument': 'BTC',
'quantityUnit': 0,
'source': 'api',
'updatedDate': 1740569719634,
'positionModel': 0,
'posType': 'execute',
'leaderId': '1162061',
'baseSize': '0.001',
'closedQuantity': '0',
'salesId': '0',
'totalPiece': '1',
'orderPrice': '0',
'id': '2435521222631981320',
'fundingSettle': '0',
'direction': 'short',
'margin': '88.8027',
'indexPrice': '88802.8',
'quantity': '88.8027',
'userId': '1162061',
'parentId': '0',
'closedPiece': '0',
'createdDate': 1740569719634,
'hedgeId': '20766171808644102',
'partnerId': '0',
'positionMargin': '88.8027',
'remainCurrentPiece': '1',
'status': 'open'}],
'type': 'position'},.......