订阅持仓变更
API说明
此Websocket提供所有交易品种的持仓变更（已成交订单）的实时更新。此websocket还提供已实现净盈亏的更新。
注意：持仓变更数据只能通过 Websocket API 获取。
注意事项
- 用户必须先建立连接。一旦连接，所有交易品种的持仓变更将实时推送。
认证
这是一个私有接口，需要认证。有关使用Websocket API的详细信息，请参考简介 > 认证和代码示例 > 合约 > Websocket私有接口。
Websocket URL
频率限制
无
订阅参数
| 参数 | 必填 | 类型 | 描述 |
|---|---|---|---|
| event | true | String | 订阅或取消订阅：sub: 订阅; unsub: 取消订阅。注意：此参数区分大小写。 |
| params | true | Json | 包含以下字段的数据对象： |
| -type | true | String | 定义功能类型，例如，"position_change"。 |
| -biz | true | String | 指定频道，例如，"futures"。 |
响应参数
| 参数 | 类型 | 描述 |
|---|---|---|
| biz | String | 指定频道，例如，"futures"。 |
| type | String | 功能类型，例如，"position_change"。 |
| result | boolean | 指示订阅或取消订阅是否成功：true/false |
| channel | String | 指定执行的操作：subscribe或unsubscribe。 |
| pairCode | String | 交易品种的基础货币，即BTC |
| data | Json | 包含以下字段的数据对象： |
| -currentPiece | String | 当前合约数量 |
| -isProfession | Integer | 表示匹配服务器处理状态 |
| -leverage | String | 应用于持仓的杠杆率。 |
| -originalType | String | 订单的原始类型，例如，"execute"。 |
| -orderId | String | 订单ID。 |
| -contractType | Integer | 合约类型：1：永续合约。 |
| -openId | String | 开仓位置的唯一ID。 |
| -fee | String | 手续费 |
| -openPrice | String | 开仓价格（订单成交价格） |
| -orderStatus | String | 订单状态，例如，"finish"。 |
| -instrument | String | 交易品种的基础货币，例如，"BTC"。 |
| -quantityUnit | Integer | 用于指定订单数量的计量单位： 0：以计价货币计价（例如，BTC-USDT 合约中的 USDT）； 1：以合约张数计价； 2：以基础货币计价（例如，BTC-USDT 合约中的 BTC）。 |
| -source | String | 来源：api/web |
| -updatedDate | Long | 更新时间戳（毫秒）。 |
| -positionModel | Integer | 持仓持仓模式：0：逐仓，1：全仓 |
| -feeRate | String | 计算费用的费率。 |
| -netProfit | String | 已实现净盈亏。 |
| -baseSize | String | 基础货币计的订单大小 |
| -liquidateBy | String | 持仓平仓事件，例如，"manual"。 |
| -totalPiece | String | 合约总数量。 |
| -orderPrice | String | 用户指定的订单价格。 |
| -id | String | 交易条目的唯一标识符。 |
| -fundingSettle | String | 此持仓结算的资金费用金额。 |
| -direction | String | 交易方向：long/short |
| -margin | String | 用于持仓的保证金。 |
| -takerMaker | Integer | taker为1，maker为2。 |
| -indexPrice | String | 指数价格 |
| -quantity | String | 基于quantityUnit 指定订单数量： 当 quantityUnit = 0 时，数量以计价货币计量（例如，BTC-USDT 中的 USDT）； 当 quantityUnit = 1 时，数量以合约张数计量； 当 quantityUnit = 2 时，数量以基础货币计量（例如，BTC-USDT 中的 BTC）。 |
| -userId | String | 用户ID |
| -closedPiece | String | 已平仓的合约数量。 |
| -createdDate | Long | 创建时间戳 |
| -hedgeId | String | 对冲ID。 |
| -closePrice | String | 持仓平仓价格 |
| -positionMargin | String | 分配给持仓的保证金。 |
| -realPrice | String | 订单的执行价格。 |
| -status | String | 状态：0：开仓，1：平仓，2：取消 |
订阅示例
以下Python代码展示了如何订阅持仓变更。
注意：完整代码示例请参考简介 > 认证和代码示例 > 合约 > Websocket私有接口。
url = "wss://ws.futurescw.com/perpum"
subscription_payload = {"event": "sub",
"params": {"biz": "futures",
"type": "position_change"}}
api_key= "your_api_key"
sec_key = "your_sec_key"
FuturesWebsocketPrivate(url, api_key, sec_key, subscription_payload) # 函数FuturesWebsocketPrivate()在章节(简介 > 认证和代码示例 > 合约 > Websocket私有接口)中定义
注意：完整Java代码示例请参考简介 > 认证和代码示例 > 合约 > Websocket私有接口。
响应示例
Websocket将实时更新持仓变更。为简洁起见，以下仅显示上述Python订阅的一个持仓变更：
{'biz': 'futures',
'data': {'result': true},
'channel': 'subscribe',
'type': 'position_change'}
{'biz': 'futures',
'pairCode': 'BTC',
'data': [{'currentPiece': '1',
'isProfession': 0,
'leverage': '5',
'originalType': 'execute',
'orderId': '33308809187064313',
'contractType': 1,
'openId': '2435521222633466843',
'fee': '0.055707',
'openPrice': '92845',
'orderStatus': 'finish',
'instrument': 'BTC',
'quantityUnit': 1,
'source': 'api',
'updatedDate': 1745501769376,
'positionModel': 0,
'feeRate': '0.0006',
'netProfit': '0',
'baseSize': '0.001',
'liquidateBy': 'manual',
'totalPiece': '1',
'orderPrice': '2147483647',
'id': '21412625432427527',
'fundingSettle': '0',
'direction': 'long',
'margin': '18.513293',
'takerMaker': 1,
'indexPrice': '92844.9',
'quantity': '18.569',
'userId': '1162061',
'closedPiece': '0',
'createdDate': 1745501769376,
'hedgeId': '21412625432427528',
'closePrice': '0',
'positionMargin': '18.569',
'realPrice': '92845',
'status': 'open'}],
'type': 'position_change'},.....