订阅持仓变更

API说明

此Websocket提供所有交易品种的持仓变更（已成交订单）的实时更新。此websocket还提供已实现净盈亏的更新。

注意：持仓变更数据只能通过 Websocket API 获取。

注意事项

用户必须先建立连接。一旦连接，所有交易品种的持仓变更将实时推送。

认证

这是一个私有接口，需要认证。有关使用Websocket API的详细信息，请参考简介 > 认证和代码示例 > 合约 > Websocket私有接口。

Websocket URL

wss://ws.futurescw.com/perpum

频率限制

无

订阅参数

参数	必填	类型	描述
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（USDT 合约）或 BTC_USDC（USDC 合约）
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"（USDT 合约）或 "BTC_USDC"（USDC 合约）。
-quantityUnit	Integer	用于指定订单数量的计量单位： 0：以计价货币计价（例如，BTC-USDT 合约中的 USDT / BTC-USDC 合约中的 USDC）； 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 / BTC-USDC 中的 USDC）；当 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'},.....

API说明​

注意事项​

认证​

Websocket URL​

频率限制​

订阅参数​

响应参数​

订阅示例​

响应示例​