订阅持仓变动数据

positions.$contract_code

是否验签: 是

接口权限: 读取

限频: WebSocket私有订单成交推送接口(需要API KEY验签) 一个UID最多同时建立30个私有订单成交推送WS链接。该用户在一个品种(包含该品种的所有周期的合约)上，仅需要维持一个订单推送WS链接即可。 单个链接为50次/秒的请求，单个IP链接为100次/秒的请求。 注意: 订单推送WS的限频，跟用户RESTFUL私有接口的限频是分开的，相互不影响。

接口描述: 当持仓信息发生变更时，例如形成仓位、加仓、平仓、逐仓增加/减少保证金等事件时,推送如下信息

订阅地址

环境	地址
线上环境	wss://api.sunx.io/ws/v1/notification
线上环境（aws客户首选）	wss://api.sunx.io/ws/v1/notification

请求参数

字段名称	类型	说明
op	string	必填;操作名称，sub 或 unsub;
cid	string	选填;Client 请求唯一 ID
topic	string	必填; 固定 ： positions
contract_code	string	必填; contract_code * 或者 BTC-USDT 或者 BTC-USDT-240909

规则说明

订阅(sub)	取消订阅(unsub)	规则
*	*	允许
*	contract_code	不允许
contract_code	*	允许

订阅参数

参数	数据类型	是否必填	描述	取值范围	默认值
contract_code	string	true	合约代码，支持大小写	全部：*（交割和永续）， 永续:“BTC-USDT：... ，交割："BTC-USDT-210625"...

数据更新

参数	数据类型	是否必填	描述	取值范围
op	string	true	操作名称，推送固定值为 notify;--可不可以去掉
topic	string	true	推送的主题	例如： positions
contract_code	string	true	订阅的contract_code	* 或者 BTC-USDT 或者 BTC-USDT-240909
ts	long	true	服务端应答时间戳
event	string	true	持仓变化通知相关事件说明	事件类型 snapshot：首推快照 create_order: 订单下单 cancel_order: 订单撤单 delivered：交割 transferred：划转 filled：成交 liquidation：强平 adl：ADL自动减仓 funding_fee：资金费 set_leverage：设置杠杆 price_update ：价格更新 （api 用户不要）
uid	string	true	用户uid
<data>		false
contract_code	string	true	合约代码
position_side	string	true	仓位方向	持仓方向 买卖模式下默认值both， 开平仓模式下： long：多 ，short：空
direction	string	true	订单方向	"buy":买， "sell":卖
margin_mode	string	true	保证金模式	cross：全仓
open_avg_price	string	true	开仓均价
volume	string	true	持仓量（张）
available	string	true	可平仓数量（张）
fee	string	true	平仓手续费
lever_rate	Long	true	杠杠倍数
adl_risk_percent	string	true	自动减仓指示	(1、2、3、4、5)，1档风险最低，5档风险最高
liquidation_price	string	true	预估强平价
initial_margin	string	true	初始保证金，仅适用于全仓
maintenance_margin	string	true	维持保证金
profit_unreal	string	true	未实现盈亏
profit	string	true	平仓盈亏
profit_rate	string	true	未实现收益率
margin_rate	string	true	保证金率
state	string	true	仓位状态	normal, liq, adl
funding_fee	string	true	累计资金费用
last_price	string	true	最新价格
mark_price	string	true	标记价格
contract_type	string	true	业务类型	swap（永续）、this_week（当周）、next_week（次周）、quarter（当季）、next_quarter（次季）
created_time	string	true	创建时间
updated_time	string	true	更新时间
version	int	true	版本号
<data>		false

订阅示例

{
  "op": "sub",
  "cid": "NuAWMqWKSI",
  "topic": "positions",
  "contract_code": "EOS-USDT"
}

订阅成功示例

{
  "op": "sub",
  "cid": "NuAWMqWKSI",
  "topic": "positions",
  "ts": 1734683308615,
  "err-code": 0,
  "contract_code": "EOS-USDT"
}

数据更新示例

{
  "op": "notify",
  "topic": "positions",
  "contract_code": "EOS-USDT",
  "ts": 1734683308618,
  "uid": "413120795",
  "event": "snapshot",
  "data": [
    {
      "contract_code": "EOS-USDT",
      "symbol": "EOS",
      "position_mode": "dual_side",
      "position_side": "short",
      "direction": "sell",
      "margin_mode": "cross",
      "open_avg_price": "0.492",
      "volume": "1",
      "available": "1",
      "fee": "0.8856",
      "lever_rate": 9,
      "adl_risk_percent": null,
      "liquidation_price": "11.408717810946043845",
      "initial_margin": "55.87624909281424",
      "maintenance_margin": "2.5144312091766408",
      "profit_unreal": "-10.88624183532816",
      "profit": "-21",
      "profit_rate": "-0.1948",
      "margin_rate": "0.000229358737821968",
      "state": "normal",
      "funding_fee": "-3.749999999225936542",
      "mark_price": "0.50289749455688544",
      "contract_type": "swap",
      "version": 21,
      "created_time": 1734675591497,
      "updated_time": 1734682810399
    }
  ]
}