WebSocket API

WebSocket 是 HTML5 一种新的协议（Protocol）。它实现了客户端与服务器全双工通信，使得数据可以快速地双向传播。通过一次简单的握手就可以建立客户端和服务器连接，服务器根据业务规则可以主动推送信息给客户端。其优点如下：

客户端和服务器进行数据传输时，请求头信息比较小，大概 2 个字节。
客户端和服务器皆可以主动地发送数据给对方。
不需要多次创建 TCP 请求和销毁，节约宽带和服务器的资源。

原生 ws 连接地址

wss://contract.mexc.com/edge

数据交互命令详解

发送 ping 消息

{
  "method": "ping"
}

服务端返回

{
  "channel": "pong",
  "data": 1587453241453
}

订阅/取消订阅数据命令列表（除个人相关命令列表之外，其余都不需要做 ws 认证）

1 分钟以内未收到客户端 ping，将断开该客户端连接，建议 10~20 秒发送一次 ping

订阅过滤

取消默认推送示例

{
  "subscribe": false,
  "method": "login",
  "param": {
    "apiKey": "mxU1TzSmRDW1o5AsE",
    "signature": "8c957a757ea31672eca05cb652d26bab7f46a41364adb714dda5475264aff120",
    "reqTime": "1611038237237"
  }
}

只要资产

{
  "method": "personal.filter",
  "param": {
    "filters": [
      {
        "filter": "asset"
      }
    ]
  }
}

只要 ADL 等级

{
  "method": "personal.filter",
  "param": {
    "filters": [
      {
        "filter": "adl.level"
      }
    ]
  }
}

只要所有的成交单

{
  "method": "personal.filter",
  "param": {
    "filters": [
      {
        "filter": "order.deal",
        "rules": []
      }
    ]
  }
}

或者

{
  "method": "personal.filter",
  "param": {
    "filters": [
      {
        "filter": "order.deal"
      }
    ]
  }
}

只要单个合约的成交单

{
  "method": "personal.filter",
  "param": {
    "filters": [
      {
        "filter": "order.deal",
        "rules": ["BTC_USDT"]
      }
    ]
  }
}

混合使用

{
  "method": "personal.filter",
  "param": {
    "filters": [
      {
        "filter": "order",
        "rules": ["BTC_USDT"]
      },
      {
        "filter": "order.deal",
        "rules": ["EOS_USDT", "ETH_USDT", "BTC_USDT"]
      },
      {
        "filter": "position",
        "rules": ["EOS_USDT", "BTC_USDT"]
      },
      {
        "filter": "asset"
      }
    ]
  }
}

登录之后会推送所有私有数据：order 订单、order.deal 成交单、position 持仓、plan.order 计划委托单、stop.order 止盈止损单、stop.planorder 止盈止损计划委托单、risk.limit 风险限额、adl.level ADL 等级、asset 资产

1、如果要取消默认推送，登录时新加参数： "subscribe":false，默认为true;

2、登录之后通过发送 personal.filter 事件来过滤自己需要的数据，如果想要恢复推送所有数据，可发送： {"method":"personal.filter"} 或者 {"method":"personal.filter","param":{"filters":[]}}

3、filter 可用 key：order、order.deal、position、plan.order、stop.order、stop.planorder、risk.limit、adl.level、asset 固定值，不可更改，若有错误会提示

其中 asset 和 adl.level 不支持过滤单个币种或者单个合约，其他均可以过滤单个合约

后面发送的 filter 事件会覆盖前面的

公共频道

Tickers

订阅

{
  "method": "sub.tickers",
  "param": {}
}

如需返回明文(后面订阅一样):

{
  "method": "sub.tickers",
  "param": {},
  "gzip": false
}

取消订阅

{
  "method": "unsub.tickers",
  "param": {}
}

数据示例

{
  "channel": "push.tickers",
  "data": [
    {
      "fairPrice": 183.01,
      "lastPrice": 183,
      "riseFallRate": -0.0708,
      "symbol": "BSV_USDT",
      "volume24": 200,
      "maxBidPrice": 7073.42,
      "minAskPrice": 6661.37
    },
    {
      "fairPrice": 220.22,
      "lastPrice": 220.4,
      "riseFallRate": -0.0686,
      "symbol": "BCH_USDT",
      "volume24": 200,
      "maxBidPrice": 7073.42,
      "minAskPrice": 6661.37
    }
  ]
}

获取平台全部永续合约的最新成交价、买一价、卖一价和 24 交易量，无需用户登录，订阅后 1 秒发送一次。

响应参数：

参数名	类型	说明
symbol	string	合约名
timestamp	long	成交时间
lastPrice	decimal	最新价
volume24	decimal	24 小时成交量，按张数统计
amount24	decimal	24 小时成交额，按金额统计
riseFallRate	decimal	涨跌幅
fairPrice	decimal	合理价
indexPrice	decimal	指数价
maxBidPrice	decimal	最大买入价格
minAskPrice	decimal	最低卖出价格
lower24Price	decimal	24 小时最低价
high24Price	decimal	24 小时最高价

获取单个 ticker

订阅

{
  "method": "sub.ticker",
  "param": {
    "symbol": "BTC_USDT"
  }
}

取消订阅

{
  "method": "unsub.ticker",
  "param": {
    "symbol": "BTC_USDT"
  }
}

数据示例

{
  "channel": "push.ticker",
  "data": {
    "ask1": 6866.5,
    "bid1": 6865,
    "contractId": 1,
    "fairPrice": 6867.4,
    "fundingRate": 0.0008,
    "high24Price": 7223.5,
    "indexPrice": 6861.6,
    "lastPrice": 6865.5,
    "lower24Price": 6756,
    "maxBidPrice": 7073.42,
    "minAskPrice": 6661.37,
    "riseFallRate": -0.0424,
    "riseFallValue": -304.5,
    "symbol": "BTC_USDT",
    "timestamp": 1587442022003,
    "holdVol": 2284742,
    "volume24": 164586129
  },
  "symbol": "BTC_USDT"
}

获取某个合约的最新成交价、买一价、卖一价和 24 交易量，无需用户登录，有成交数据就推送，订阅后 1 秒发送一次。

响应参数：

参数名	类型	说明
symbol	string	合约名
timestamp	long	成交时间
lastPrice	decimal	最新价
bid1	decimal	买一价
ask1	decimal	卖一价
holdVol	decimal	总持仓量
fundingRate	decimal	资金费率
riseFallRate	decimal	涨跌幅
riseFallValue	decimal	涨跌额
volume24	decimal	24 小时成交量，按张数统计
amount24	decimal	24 小时成交额，按金额统计
fairPrice	decimal	合理价
indexPrice	decimal	指数价
maxBidPrice	decimal	最大买入价格
minAskPrice	decimal	最低卖出价格
lower24Price	decimal	24 小时最低价
high24Price	decimal	24 小时最高价

成交

订阅

{
  "method": "sub.deal",
  "param": {
    "symbol": "BTC_USDT"
  }
}

取消订阅

{
  "method": "unsub.deal",
  "param": {
    "symbol": "BTC_USDT"
  }
}

数据示例

{
  "symbol": "BTC_USDT",
  "data": [
    {
      "p": 115309.8,
      "v": 55,
      "T": 2,
      "O": 3,
      "M": 1,
      "t": 1755487578276,
      "i": 13064218826
    },
    {
      "p": 115309.8,
      "v": 11,
      "T": 1,
      "O": 3,
      "M": 1,
      "t": 1755487578275,
      "i": 13064218827
    }
  ],
  "channel": "push.deal",
  "ts": 1755487578276
}

获取最近的成交数据，无需用户登录，有成交数据就推送。成交数据订阅，默认启用合并，如不需启用，订阅时请将 compress 设置为 false。

响应参数：

参数名	类型	说明
p	decimal	成交价
v	decimal	数量
T	int	成交方向,1:买,2:卖
O	int	是否是开仓，1:新增仓位,2:减少仓位,3:仓位不变。当 O 为 1 的时候, vol 是新增的持仓量
M	int	是否为自成交,1:是,2:否
i	int	成交 id
t	long	成交时间

深度

订阅

{
  "method": "sub.depth",
  "param": {
    "symbol": "BTC_USDT"
  }
}

取消订阅

{
  "method": "unsub.depth",
  "param": {
    "symbol": "BTC_USDT"
  }
}

数据示例

{
  "channel": "push.depth",
  "data": {
    "asks": [[6859.5, 3251, 1]],
    "bids": [],
    "version": 96801927
  },
  "symbol": "BTC_USDT",
  "ts": 1587442022003
}

获取某个合约的深度数据推送，订阅后 200ms 发送一次。

响应参数：

参数名	类型	说明
asks	`List<Numeric[]>`	卖方深度
bids	`List<Numeric[]>`	买方深度
version	long	版本号

备注: [411.8, 10, 1] 411.8 为价格，10 为此价格的合约张数,1 为订单数量

深度-指定最小金额单位

订阅

{ "method": "sub.depth.step", "param": { "symbol": "BTC_USDT", "step": "10" } }

备注： 10 表示以 10 为金额的最小比例单位，如 100010，100020，100030 拆分深度数据

取消订阅

{
  "method": "unsub.depth.step",
  "param": { "symbol": "BTC_USDT", "step": "10" }
}

数据示例

{
  "channel": "push.depth.step",
  "data": {
    "askMarketLevelPrice": 111089.4,
    "asks": [
      [111090, 398676, 26],
      [111100, 410175, 8]
    ],
    "bidMarketLevelPrice": 111085.5,
    "bids": [
      [111080, 461204, 35],
      [111070, 386809, 3]
    ],
    "ct": 1760950364388,
    "version": 27883254360
  },
  "symbol": "BTC_USDT"
}

获取指定最小金额单位合约的深度数据推送，订阅后 200ms 发送一次

响应参数：

参数名	类型	说明
asks	`List<Numeric[]>`	卖方深度
bids	`List<Numeric[]>`	买方深度
askMarketLevelPrice	decimal	愿意卖出的最高价
bidMarketLevelPrice	decimal	愿意买入的最高价
version	long	版本号

备注: [111090,398676,26] 111090 为价格，398676 为此价格的合约张数,26 为订单数量

K 线数据

订阅

{
  "method": "sub.kline",
  "param": {
    "symbol": "BTC_USDT",
    "interval": "Min60"
  },
  "gzip": false
}

取消订阅

{
  "method": "unsub.kline",
  "param": {
    "symbol": "BTC_USDT"
  }
}

数据示例

{
  "channel": "push.kline",
  "data": {
    "a": 233.740269343644737245,
    "c": 6885,
    "h": 6910.5,
    "interval": "Min60",
    "l": 6885,
    "o": 6894.5,
    "q": 1611754,
    "symbol": "BTC_USDT",
    "t": 1587448800
  },
  "symbol": "BTC_USDT"
}

获取合约的 K 线数据，有更新就推送。

interval 可选参数: Min1、Min5、Min15、Min30、Min60、Hour4、Hour8、Day1、Week1、Month1

响应参数：

参数名	类型	说明
symbol	string	合约名
interval	string	间隔: Min1、Min5、Min15、Min30、Min60、Hour4、Hour8、Day1、Week1、Month1
a	decimal	总成交金额
q	decimal	总成交量
o	decimal	开盘价
c	decimal	收盘价
h	decimal	最高价
l	decimal	最低价
v	decimal	总成交量
ro	decimal	真实开盘价
rc	decimal	真实收盘价
rh	decimal	真实最高价
rl	decimal	真实最低价
t	long	交易时间，单位：秒（s），为窗口的开始时间（windowStart）

资金费率

订阅

{
  "method": "sub.funding.rate",
  "param": {
    "symbol": "BTC_USDT"
  },
  "gzip": false
}

取消订阅

{
  "method": "unsub.funding.rate",
  "param": {
    "symbol": "BTC_USDT"
  }
}

数据示例

{
  "channel": "push.funding.rate",
  "data": {
    "rate": 0.001,
    "symbol": "BTC_USDT"
  },
  "symbol": "BTC_USDT",
  "ts": 1587442022003
}

获取合约资金费率，有更新就推送。

响应参数：

参数名	类型	说明
symbol	string	合约名
fundingRate	decimal	资金费率
nextSettleTime	long	下一次结算时间

指数价格

订阅

正向及方向合约都使用同一个 symbol，例如 BTC_USD 反向合约，订阅指数价格时，使用 BTC_USDT

{
  "method": "sub.index.price",
  "param": {
    "symbol": "BTC_USDT"
  },
  "gzip": false
}

取消订阅

{
  "method": "unsub.index.price",
  "param": {
    "symbol": "BTC_USDT"
  }
}

数据示例

{
  "channel": "push.index.price",
  "data": {
    "price": 0.001,
    "symbol": "BTC_USDT"
  },
  "symbol": "BTC_USDT",
  "ts": 1587442022003
}

获取指数价格，指数价格有变化时就会推送一次数据。

响应参数：

参数名	类型	说明
symbol	string	合约名
price	decimal	价格

合理价格

订阅

{
  "method": "sub.fair.price",
  "param": {
    "symbol": "BTC_USDT"
  },
  "gzip": false
}

取消订阅

{
  "method": "unsub.fair.price",
  "param": {
    "symbol": "BTC_USDT"
  }
}

数据示例

{
  "channel": "push.fair.price",
  "data": {
    "price": 0.001,
    "symbol": "BTC_USDT"
  },
  "symbol": "BTC_USDT",
  "ts": 1587442022003
}

获取合约的合理价格，有更新就推送。

响应参数：

参数名	类型	说明
symbol	string	合约名
price	decimal	价格

合约数据

订阅

{ "method": "sub.contract" }

取消订阅

{ "method": "unsub.contract" }

数据示例

{
  "channel": "push.contract",
  "data": {
    "amountScale": 4,
    "askLimitPriceRate": 0.2,
    "baseCoin": "CLO",
    "baseCoinName": "CLO",
    "bidLimitPriceRate": 0.2,
    "conceptPlate": [],
    "conceptPlateId": [],
    "contractSize": 10,
    "depthStepList": ["0.0001", "0.001", "0.01", "0.1"],
    "displayName": "CLO_USDT永续",
    "displayNameEn": "CLO_USDT PERPETUAL",
    "feeRateMode": "NORMAL",
    "futureType": 1,
    "indexOrigin": ["MEXC_FUTURE", "MEXC", "KUCOIN"],
    "initialMarginRate": 0.02,
    "isHidden": false,
    "isHot": false,
    "isNew": false,
    "liquidationFeeRate": 0.0002,
    "limitMaxVol": 9000,
    "maintenanceMarginRate": 0.01,
    "makerFeeRate": 0,
    "maxLeverage": 50,
    "maxNumOrders": [200, 50],
    "maxVol": 9000,
    "minLeverage": 1,
    "minVol": 1,
    "openingCountdownOption": 1,
    "openingTime": 1760440200000,
    "positionOpenType": 3,
    "priceCoefficientVariation": 0.4,
    "priceScale": 4,
    "priceUnit": 0.0001,
    "quoteCoin": "USDT",
    "quoteCoinName": "USDT",
    "riskBaseVol": 9000,
    "riskIncrImr": 0.005,
    "riskIncrMmr": 0.005,
    "riskIncrVol": 9000,
    "riskLevelLimit": 1,
    "riskLimitMode": "INCREASE",
    "riskLimitType": "BY_VOLUME",
    "riskLongShortSwitch": 0,
    "settleCoin": "USDT",
    "state": 0,
    "symbol": "CLO_USDT",
    "takerFeeRate": 0.0002,
    "triggerProtect": 0.1,
    "volScale": 0,
    "volUnit": 1
  },
  "symbol": "CLO_USDT",
  "ts": 1760942212002
}

获取合约数据，有更新就推送。

响应参数：

参数名	类型	说明
symbol	string	合约名，如 BTC_USDT
displayName	string	展示合约名，如 BTC_USDT 永续
displayNameEn	string	展示合约英文名，如 BTC_USDT PERPETUAL
positionOpenType	int	开仓模式，1 表示全仓和逐仓； 2 表示全仓；3 表示逐仓
baseCoin	string	标的货币如 BTC
quoteCoin	string	标价货币如 USDT
baseCoinName	string	标的货币名称
quoteCoinName	string	标价货币名称
futureType	int	1 PERPETUAL ，2 DAILY
settleCoin	string	结算货币如 USDT
contractSize	decimal	合约面值
minLeverage	int	杠杆倍数下限
maxLeverage	int	杠杆倍数上限
priceScale	int	价格小数位数
volScale	int	交易量小数位数
amountScale	int	交易金额小数位数
priceUnit	decimal	价格的最小步进单位
volUnit	decimal	交易量的最小步进单位
minVol	decimal	订单张数下限
maxVol	decimal	订单张数上限
limitMaxVol	decimal	限价订单张数最大值
bidLimitPriceRate	decimal	合约下单价格限制-卖家
askLimitPriceRate	decimal	合约下单价格限制-买家
takerFeeRate	decimal	taker 费用
makerFeeRate	decimal	maker 费用
maintenanceMarginRate	decimal	维持保证金率
initialMarginRate	decimal	初始保证金率
riskBaseVol	decimal	基本张数
riskIncrVol	decimal	递增张数
riskIncrMmr	decimal	维持保证金率递增量
riskIncrImr	decimal	初始保证金率递增量
riskLevelLimit	decimal	风险限额档位数
priceCoefficientVariation	decimal	合理价格偏离指数价格系数
state	int	0：启用、1：交割、2：交割完成、3：下线、4：暂停
isNew	boolean	是否是新合约
isHot	boolean	是否是热门合约
isHidden	boolean	是否是隐藏合约
triggerProtect	decimal	价差保护阈值
riskLongShortSwitch	int	多空风险限额是否独立，0：关闭；1：启动
riskBaseVolLong	decimal	多方向订单基本张数
riskIncrVolLong	decimal	多方向订单递增张数
riskBaseVolShort	decimal	空方向订单基本张数
riskIncrVolShort	decimal	空方向订单递增张数
openingCountdownOption	int	开盘倒计时选项 1-显示开盘时间和倒计时, 2-仅显示开盘时间, 3-不显示开盘时间和倒计时
openingTime	long	开盘时间时间戳
liquidationFeeRate	decimal	强平手续费率
tieredDealAmount	decimal	交易金额
tieredEffectiveDay	int	有效天数
tieredExcludeZeroFee	boolean	false:不排除，true:排除；是否排除 0 费率交易额
tieredAppointContract	boolean	是否指定合约；false：不指定；true：指定
tieredExcludeContractId	boolean	是否包含合约； false:不包含，true:包含

事件合约

订阅

{ "method": "sub.event.contract" }

取消订阅

{ "method": "unsub.event.contract" }

获取事件合约，有更新就推送。

响应参数：

参数名	类型	说明
contractId	string	合约 id
symbol	string	合约名，如 BTC_USDT
baseCoin	string	标的货币，如 BTC
quoteCoin	string	标价货币，如 USDT
baseCoinName	string	标的货币名称
quoteCoinName	string	标价货币名称
settleCoin	string	结算货币
baseCoinIconUrl	string	标的货币
baseCoinName	string	标的货币图标配置
investMinAmount	decimal	最小投入金额
investMaxAmount	decimal	最大投入金额
amountScale	int	下单数量精度
payRateScale	int	支付率精度
indexPriceScale	int	指数价格精度
availableScale	int	可用精度精度

私有频道

签名方式：

api_key 和 req_time 拼接，将得到的参数字符串用 HMAC SHA256 进行加密。api_key 和 sec_key 分别为申请 api 时的 ACCESS KEY 和 SECRET KEY。

签名字符串

"mx0aBYs33eIilxBW5C1657186536762"

登录认证

示例

{
  "method": "login",
  "param": {
    "token": "token", // web和app需要传token进行完成认证
    "apiKey": "apiKey", // openapi需要传此参数，参数构造方式参照openapi文档
    "reqTime": "reqTime", // openapi需要传此参数，参数构造方式参照openapi文档
    "signature": "signature" // openapi需要传此参数，参数构造方式参照openapi文档
  }
}

响应参数：

示例

{
  "channel": "rs.login",
  "data": "success",
  "ts": "1587442022003"
}

成功: 无，失败:返回对应错误信息,channel = rs.error

登录成功(channel = rs.login)

订单

数据示例

{
  "channel": "push.personal.order",
  "data": {
    "orderId": 123456789,
    "symbol": "BTC_USDT",
    "positionId": 987654321,
    "price": 45000.5,
    "vol": 10,
    "leverage": 20,
    "side": 1,
    "category": 1,
    "orderType": 1,
    "dealAvgPrice": 45000.0,
    "dealVol": 5,
    "orderMargin": 2250.0,
    "usedMargin": 1125.0,
    "takerFee": 0.1125,
    "makerFee": 0.09,
    "profit": 0,
    "feeCurrency": "USDT",
    "openType": 1,
    "state": 2,
    "errorCode": 0,
    "externalOid": "ext_001",
    "createTime": 1760942212000,
    "updateTime": 1760942212000,
    "remainVol": 5,
    "positionMode": 1,
    "reduceOnly": false,
    "bboTypeNum": 0,
    "makerFeeRate": 0.0002,
    "takerFeeRate": 0.0004
  },
  "ts": 1760942212000
}

channel = push.personal.order

响应参数：

参数名	类型	说明
orderId	long	订单 ID
symbol	string	合约名
positionId	long	持仓 id
price	decimal	委托价格
vol	decimal	委托数量
leverage	long	杠杆倍数
side	int	订单方向 1:开多,2:平空,3:开空,4:平多
category	int	订单类别 1:限价委托,2:强平代管委托,3:代管平仓委托,4:ADL 减仓
orderType	int	订单类型 1:限价单,2:Post Only 只做 Maker,3:立即成交或立即取消,4:全部成交或者全部取消,5:市价单,6:市价转限价单
dealAvgPrice	decimal	成交均价
dealVol	decimal	成交数量
orderMargin	decimal	委托保证金
usedMargin	decimal	已经使用的保证金
takerFee	decimal	买单手续费
makerFee	decimal	卖单手续费
profit	decimal	平仓盈亏
feeCurrency	string	手续费币种
openType	int	开仓类型,1 逐仓,2 全仓
state	int	订单状态,1:等待接收,2 未完成,3 已完成,4 已撤销,5 无效
errorCode	int	详见枚举定义:errorCode
externalOid	string	外部订单号
createTime	long	创建时间
updateTime	long	修改时间
remainVol	decimal	剩余数量
positionMode	int	持仓模式
reduceOnly	boolean	只减仓
bboTypeNum	int	限价订单类型-BBO 类型订单
makerFeeRate	decimal	maker 手续费率
takerFeeRate	decimal	taker 手续费率

资产

数据示例

{
  "channel": "push.personal.asset",
  "data": {
    "currency": "USDT",
    "positionMargin": 5000.0,
    "frozenBalance": 1000.0,
    "availableBalance": 9000.0,
    "bonus": 100.0
  },
  "ts": 1760942212000
}

channel = push.personal.asset

响应参数：

参数名	类型	说明
currency	string	币种
positionMargin	decimal	仓位保证金
frozenBalance	decimal	冻结余额
availableBalance	decimal	当前可用余额
bonus	decimal	体验金

仓位

数据示例

{
  "channel": "push.personal.position",
  "data": {
    "positionId": 123456789,
    "symbol": "BTC_USDT",
    "holdVol": 10,
    "positionType": 1,
    "openType": 1,
    "state": 1,
    "frozenVol": 0,
    "closeVol": 0,
    "holdAvgPrice": 45000.5,
    "holdAvgPriceFullyScale": "45000.500000000000000000",
    "closeAvgPrice": 0,
    "openAvgPrice": 45000.5,
    "openAvgPriceFullyScale": "45000.500000000000000000",
    "liquidatePrice": 40000.0,
    "oim": 2250.025,
    "adlLevel": 1,
    "im": 2250.025,
    "holdFee": 0,
    "realised": 0,
    "leverage": 20,
    "autoAddIm": false,
    "pnl": 100.5,
    "marginRatio": 0.2,
    "newOpenAvgPrice": 45000.5,
    "newCloseAvgPrice": 0,
    "closeProfitLoss": 0,
    "fee": 0,
    "deductFeeList": [
      {
        "currency": "USDT",
        "deductFee": 0.1125,
        "convertSettleFee": 0.1125
      }
    ],
    "makerFeeRate": 0.0002,
    "takerFeeRate": 0.0004,
    "createTime": 1760942212000,
    "updateTime": 1760942212000,
    "version": 1
  },
  "ts": 1760942212000
}

channel = push.personal.position

响应参数：

参数名	类型	说明
positionId	long	持仓 id
symbol	string	合约名
holdVol	decimal	持仓数量
positionType	int	仓位类型， 1 多 2 空
openType	int	开仓类型， 1 逐仓 2 全仓
state	int	仓位状态,1 持仓中 2 系统代持 3 已平仓
frozenVol	decimal	冻结量
closeVol	decimal	平仓量
holdAvgPrice	decimal	持仓均价
holdAvgPriceFullyScale	string	全精度持仓均价
closeAvgPrice	decimal	平仓均价
openAvgPrice	decimal	开仓均价
openAvgPriceFullyScale	string	全精度开仓均价
liquidatePrice	decimal	逐仓时的爆仓价
oim	decimal	原始初始保证金
adlLevel	int	adl 减仓等级
im	decimal	初始保证金，逐仓时可以加减此项以调节爆仓价
holdFee	decimal	资金费, 正数表示得到，负数表示支出
realised	decimal	已实现盈亏
leverage	int	杠杆倍数
autoAddIm	boolean	是否自动追加保证金
pnl	decimal	浮动盈亏
marginRatio	decimal	保证金率
newOpenAvgPrice	decimal	开仓均价
newCloseAvgPrice	decimal	平仓均价
closeProfitLoss	decimal	平仓盈亏
fee	decimal	手续费
deductFeeList	array	抵扣信息
makerFeeRate	decimal	maker 手续费率
takerFeeRate	decimal	taker 手续费率
createTime	long	创建时间
updateTime	long	修改时间
version	long	版本号

抵扣信息

数据示例

{
  "channel": "push.personal.plan.order",
  "data": {
    "currency": "USDT",
    "deductFee": 0.1125,
    "convertSettleFee": 0.1125
  },
  "ts": 1760942212000
}

channel = push.personal.position

响应参数：

参数名	类型	说明
currency	string	抵扣币种
deductFee	decimal	抵扣币种手续费
convertSettleFee	decimal	折算成结算币种手续费

计划委托订单

数据示例

{
  "channel": "push.personal.plan.order",
  "data": {
    "id": 987654321,
    "symbol": "BTC_USDT",
    "leverage": 20,
    "side": 1,
    "triggerPrice": 46000.0,
    "price": 45990.0,
    "vol": 5,
    "openType": 1,
    "triggerType": 1,
    "state": 1,
    "executeCycle": 24,
    "trend": 1,
    "errorCode": 0,
    "orderId": 0,
    "orderType": 1,
    "marketOrderLevel": 0,
    "positionMode": 1,
    "lossTrend": 1,
    "profitTrend": 1,
    "stopLossPrice": 44000.0,
    "takeProfitPrice": 47000.0,
    "reduceOnly": false,
    "createTime": 1760942212000,
    "updateTime": 1760942212000
  },
  "ts": 1760942212000
}

channel = push.personal.plan.order

响应参数：

参数名	类型	说明
id	long	订单 id
symbol	string	合约名
leverage	int	杠杆倍数
side	int	订单方向 1 开多,2 平空,3 开空,4 平多
triggerPrice	decimal	触发价
price	decimal	执行价格
vol	decimal	下单数量
openType	int	开仓类型,1:逐仓,2:全仓
triggerType	int	触发类型,1:大于等于，2:小于等于
state	int	状态,1:未触发,2:已取消,3:已执行,4:已失效,5:执行失败
executeCycle	int	执行周期,单位:小时
trend	int	触发价格类型,1:最新价，2:合理价，3:指数价
errorCode	int	详见枚举定义:errorCode
orderId	long	订单 id,执行成功时返回
orderType	int	订单类型,1:限价单,2:Post Only 只做 Maker,3:立即成交或立即取消,4:全部成交或者全部取消,5:市价单
marketOrderLevel	int	市价订单的自定义档位
positionMode	int	用户设置持仓类型默认 0：历史订单无记录 2：单向 1：双向
lossTrend	int	止损参考价格类型 1 最新价 2 合理价 3 指数价
profitTrend	int	止盈参考价格类型 1 最新价 2 合理价 3 指数价
stopLossPrice	decimal	止损价
takeProfitPrice	decimal	止盈价
reduceOnly	boolean	只减仓
createTime	long	创建时间
updateTime	long	修改时间

风险限额

数据示例

{
  "channel": "push.personal.risk.limit",
  "data": {
    "symbol": "BTC_USDT",
    "positionType": 1,
    "riskSource": 1,
    "level": 2,
    "maxVol": 500,
    "maxLeverage": 50,
    "mmr": 0.02,
    "imr": 0.04,
    "leverage": 20,
    "openType": 1,
    "limitBySys": true,
    "maxVolView": 1000
  },
  "ts": 1760942212000
}

channel = push.personal.risk.limit

响应参数：

参数名	类型	说明
symbol	string	合约名
positionType	int	持仓类型 1:多仓，2:空仓
riskSource	int	风险限制来源 0:其它 1:爆仓服务
level	int	当前风险等级
maxVol	decimal	最大可持仓数量
maxLeverage	int	最大杠杆倍数
mmr	decimal	维持保证金率
imr	decimal	初始保证金率
leverage	int	当前杠杆倍数
openType	int	保证金模式,默认逐仓
limitBySys	boolean	限额标识
maxVolView	decimal	用于前端滑动杠杆计算最大风险限额，不依赖杠杆倍数

止盈止损委托

数据示例

{
  "channel": "push.personal.stop.planorder",
  "data": {
    "id": 987654321,
    "orderId": 123456789,
    "symbol": "BTC_USDT",
    "positionId": 456789123,
    "lossTrend": 1,
    "profitTrend": 2,
    "stopLossPrice": 42000.0,
    "takeProfitPrice": 48000.0,
    "state": 1,
    "triggerSide": 1,
    "positionType": 1,
    "vol": 10,
    "takeProfitVol": 10,
    "stopLossVol": 10,
    "realityVol": 10,
    "placeOrderId": 987654321,
    "version": 1,
    "isFinished": 0,
    "profitLossVolType": "SAME",
    "volType": 1,
    "takeProfitReverse": 2,
    "stopLossReverse": 2,
    "closeTryTimes": 0,
    "reverseTryTimes": 0,
    "reverseErrorCode": 0,
    "stopLossType": 1,
    "stopLossOrderPrice": 41990.0,
    "createTime": 1760942212000,
    "updateTime": 1760942212000
  },
  "ts": 1760942212000
}

channel = push.personal.stop.planorder

响应参数：

参数名	类型	说明
id	long	主键 id
orderId	long	订单 ID
symbol	string	合约名
positionId	long	仓位 ID
lossTrend	int	止损参考价格类型
profitTrend	int	止盈参考价格类型
stopLossPrice	decimal	止损价
takeProfitPrice	decimal	止盈价
state	int	状态
triggerSide	int	触发方向，1:止盈，2:止损
positionType	int	仓位类型
vol	decimal	委托数量
takeProfitVol	decimal	止盈数量
stopLossVol	decimal	止损数量
realityVol	decimal	实际下单数量
placeOrderId	long	实际下单订单 id
version	int	版本号
isFinished	int	是否完成
profitLossVolType	string	止盈止损数量类型(SAME: 数量相同；SEPARATE：数量不同)
volType	int	数量类型 1、分批止盈止损 2、仓位止盈止损
takeProfitReverse	int	止盈反手：1 是 2 否
stopLossReverse	int	止损反手：1 是 2 否
closeTryTimes	int	平仓重试次数
reverseTryTimes	int	反手重试次数
reverseErrorCode	int	反手开仓失败原因默认值 0
stopLossType	int	止损类型 0-市价止损 1-限价止损
stopLossOrderPrice	decimal	限价止损委托价格
createTime	long	创建时间
updateTime	long	更新时间

跟踪委托

数据示例

{
  "channel": "push.personal.track.order",
  "data": {
    "id": 987654321,
    "symbol": "BTC_USDT",
    "leverage": 20,
    "side": 1,
    "vol": 50,
    "openType": 1,
    "trend": 1,
    "activePrice": 45000.0,
    "markPrice": 44950.0,
    "backType": 1,
    "backValue": 0.5,
    "triggerPrice": 44750.0,
    "triggerType": 2,
    "orderId": 123456789,
    "errorCode": 0,
    "state": 1,
    "positionMode": 2,
    "reduceOnly": false,
    "createTime": 1760942212000,
    "updateTime": 1760942212000
  },
  "ts": 1760942212000
}

channel = push.personal.track.order

响应参数：

参数名	类型	说明
id	long	主键 id
symbol	string	合约名
leverage	int	杠杆倍数
side	int	订单方向（1 开多 2 平空 3 开空 4 平多）
vol	decimal	委托数量
openType	int	持仓类型（1 逐仓 2 全仓）
trend	int	参考价格（1 最新价 2 合理价 3 指数价）
activePrice	decimal	激活价格
markPrice	decimal	对标价格（激活后的最高价或者最低价）
backType	int	价格回调类型（1 回调百分比 2 回调跨度值）
backValue	decimal	回调值
triggerPrice	decimal	触发价格（随对标价格更新而更新）
triggerType	int	触发类型
orderId	long	触发成功后的委托单 id
errorCode	int	详见枚举定义:errorCode
state	int	当前跟踪委托单状态（0 未激活 1 已激活 2 执行成功 3 执行失败 4 已取消）
positionMode	int	用户设置持仓类型
reduceOnly	boolean	只减仓
createTime	long	创建时间
updateTime	long	更新时间

止盈止损价格

数据示例

{
  "channel": "push.personal.stop.order",
  "data": {
    "symbol": "BTC_USDT",
    "orderId": 123456789,
    "lossTrend": 1,
    "profitTrend": 2,
    "stopLossPrice": 42000.0,
    "takeProfitPrice": 48000.0
  },
  "ts": 1760942212000
}

channel = push.personal.stop.order

响应参数：

参数名	类型	说明
symbol	string	合约名
orderId	long	订单 ID
lossTrend	int	止损参考价格类型
profitTrend	int	止盈参考价格类型
stopLossPrice	decimal	止损价
takeProfitPrice	decimal	止盈价

成交明细

数据示例

{
  "channel": "push.personal.order.deal",
  "data": {
    "id": 987654321,
    "symbol": "BTC_USDT",
    "side": 1,
    "vol": 10,
    "price": 45000.5,
    "feeCurrency": "USDT",
    "fee": 0.225,
    "timestamp": 1760942212000,
    "profit": 0,
    "isTaker": true,
    "category": 1,
    "orderId": 123456789,
    "isSelf": false,
    "externalOid": "ext_001",
    "positionMode": 1,
    "reduceOnly": false,
    "opponentUid": 987654321
  },
  "ts": 1760942212000
}

channel = push.personal.order.deal

响应参数：

参数名	类型	说明
id	long	成交 ID
symbol	string	合约名
side	int	订单方向：1 开多,2 平空,3 开空,4 平多
vol	decimal	数量
price	decimal	价格
feeCurrency	string	手续费币种
fee	decimal	单边产生的手续费，正数表示用户付出，负数表示用户获得
timestamp	long	成交时间
profit	decimal	盈亏
isTaker	boolean	是否为 taker
category	int	订单类别
orderId	long	订单 ID
isSelf	boolean	是否为自成交
externalOid	string	外部订单号
positionMode	int	持仓模式
reduceOnly	boolean	只减仓
opponentUid	long	对手方 uid

追单失败

数据示例

{
  "channel": "push.personal.order.chase",
  "data": {
    "ec": 1001,
    "s": "BTC_USDT"
  },
  "ts": 1760942212000
}

channel = push.personal.order.chase

响应参数：

参数名	类型	说明
ec	int	错误码
s	string	合约名

强平风险变更

数据示例

{
  "channel": "push.personal.liquidate.risk",
  "data": {
    "symbol": "BTC_USDT",
    "positionId": 123456789,
    "liquidatePrice": 35000.0,
    "marginRatio": 0.1,
    "adlLevel": 3
  },
  "ts": 1760942212000
}

channel = push.personal.liquidate.risk

响应参数：

参数名	类型	说明
symbol	string	合约名
positionId	long	仓位 ID
liquidatePrice	decimal	强平价
marginRatio	decimal	保证金率
adlLevel	int	adl 等级

杠杆模式变更

数据示例

{
  "channel": "push.personal.leverage.mode",
  "data": {
    "lm": 1
  },
  "ts": 1760942212000
}

channel = push.personal.leverage.mode

响应参数：

参数名	类型	说明
lm	int	杠杆模式

持仓模式变更

数据示例

{
  "channel": "push.personal.position.mode",
  "data": {
    "positionMode": 2
  },
  "ts": 1760942212000
}

channel = push.personal.position.mode

响应参数：

参数名	类型	说明
positionMode	int	持仓模式

全平仓失败

channel = push.personal.position.closeall.fail

响应参数：

无数据体，仅推送频道消息

反手仓位

数据示例

{
  "channel": "push.personal.reverse.position",
  "data": {
    "contractId": 1,
    "positionId": 123456789,
    "state": 2,
    "errorCode": 0
  },
  "ts": 1760942212000
}

channel = push.personal.reverse.position

响应参数：

参数名	类型	说明
contractId	int	合约 ID
positionId	long	仓位 ID
state	int	状态
errorCode	int	详见枚举定义:errorCode

体验金通知

数据示例

{
  "channel": "push.personal.bonus",
  "data": {
    "c": "USDT",
    "b": 100.0,
    "be": 1763539200000,
    "g": true,
    "ret": 1763539200000,
    "rea": 100.0
  },
  "ts": 1760942212000
}

channel = push.personal.bonus

响应参数：

参数名	类型	说明
c	string	币种
b	decimal	体验金金额
be	long	体验金过期时间
g	boolean	是否发放体验金
ret	long	最近一笔到期时间
rea	decimal	最近一笔到期金额

用户通知-强平预警/强平通知

数据示例

{
  "channel": "push.personal.generic.notify",
  "data": {
    "type": 1,
    "param": {
      "notifyType": 2,
      "openType": 1,
      "dn": "BTC_USDT永续",
      "dne": "BTC_USDT PERPETUAL",
      "multiAssets": false,
      "marginRate": 0.085
    }
  },
  "ts": 1760942212000
}

channel = push.personal.generic.notify

响应参数：

参数名	类型	说明
type	int	通知类型 1-强平通知
param	object	通知参数

通知参数（type 为强平相关时）

参数名	类型	说明
notifyType	int	通知类型:1-强平通知, 2-强平预警
openType	int	开仓类型:1-逐仓, 2-全仓
dn	string	显示名称
dne	string	显示名称(英文)
multiAssets	boolean	是否开启联保模式
marginRate	decimal	保证金率

事件合约仓位

数据示例

{
  "channel": "push.personal.event.contract.position",
  "data": {
    "positionId": 123456789,
    "symbol": "BTC_USDT",
    "side": "1",
    "payRate": 0.15,
    "amount": 1000.0,
    "openPrice": 45000.5,
    "closePrice": 46250.75,
    "rewardAmount": 25.5,
    "rewardAmountUsdt": 25.5,
    "state": "3",
    "closeResult": "PROFIT",
    "createTime": 1760942212000,
    "closeTime": 1760945812000,
    "pnlAmount": 125.25
  },
  "ts": 1760945812000
}

channel = push.personal.event.contract.position

响应参数：

参数名	类型	说明
positionId	long	仓位 id
symbol	string	合约名
side	string	方向
payRate	decimal	奖金支付率
amount	decimal	下单金额
openPrice	decimal	开仓价格
closePrice	decimal	平仓价格
rewardAmount	decimal	奖励金额
rewardAmountUsdt	decimal	奖励金额折 U
state	string	状态
closeResult	string	平仓结果
createTime	long	创建时间
closeTime	long	平仓时间
pnlAmount	decimal	总盈亏

增量深度订单簿维护机制

获取全量深度快照（初始化）接口：GET https://api.mexc.com/api/v1/contract/depth/{symbol}?limit=1000 保存 version = localLastVersion
订阅 WebSocket 深度信息
订阅 push.depth 收到 push.depth 更新：

如果消息 version > localLastVersion，同一个价位用后收到的更新覆盖前面的（可先缓存）
正常情况下若 version == localLastVersion + 1，直接应用更新

丢包恢复：获取最新深度 commits 接口：GET https://api.mexc.com/api/v1/contract/depth_commits/{symbol}/1000

获取最新 1000 条深度增量快照（按 version 升序）

应用 commits 并清理缓存

遍历 commits：跳过 version <= localLastVersion的
从 version == localLastVersion + 1 开始，依次应用每个 commit 的更新（quantity > 0 更新/插入；==0 删除价位）
更新 localLastVersion 为最后一个应用的 version
若缓存中有 WS 更新，可一并覆盖应用（更高 version 优先）

继续实时更新

从 WS 接收的 event 继续更新本地订单簿
每个新 event 的 version 应恰好等于上一个 version + 1
若不连续（跳号或乱序）：可能丢包 → 重新从步骤 4 开始恢复（或回步骤 1 全量初始化）

更新规则

event 中的挂单量为绝对值（当前总量，非相对变化）
如果 quantity == 0：表示该价位已撤单或被吃，应移除该价位

枚举定义

errorCode

0 正常状态
1 参数错误
2 账户余额不足
3 仓位不存在
4 仓位可用持仓不足
5 多仓时委托价小于强平价 / 空仓时委托价大于强平价
6 开多时强平价小于合理价 / 开空时强平价大于合理价
7 超过风险限额限制
8 系统撤销
9 仓位模式不匹配
10 因存在其他价格更优订单被撤销
11 合约未启用
12 交割撤单
13 仓位将被强平撤单
14 ADL 撤单
15 黑名单用户下单撤销
16 单向持仓资金费用结算余额不足撤单
17 划出保证金撤单
18 IOC 订单撤销剩余
19 FOK 订单撤销
20 只做 Maker 撤销
21 市价吃不到任何订单
22 order id 重复
23 externalOid 重复
999 其他通用情况

原生 ws 连接地址​

数据交互命令详解​

订阅过滤​

公共频道​

Tickers​

获取单个 ticker​

成交​

深度​

深度-指定最小金额单位​

K 线数据​

资金费率​

指数价格​

合理价格​

合约数据​

事件合约​

私有频道​

签名字符串​

登录认证​

订单​

资产​

仓位​

抵扣信息​

计划委托订单​

风险限额​

止盈止损委托​

跟踪委托​

止盈止损价格​

成交明细​

追单失败​

强平风险变更​

杠杆模式变更​

持仓模式变更​

全平仓失败​

反手仓位​

体验金通知​

用户通知-强平预警/强平通知​

事件合约仓位​

增量深度订单簿维护机制​

枚举定义​

errorCode​

原生 ws 连接地址

数据交互命令详解

订阅过滤

公共频道

Tickers

获取单个 ticker

成交

深度

深度-指定最小金额单位

K 线数据

资金费率

指数价格

合理价格

合约数据

事件合约

私有频道

签名字符串

登录认证

订单

资产

仓位

抵扣信息

计划委托订单

风险限额

止盈止损委托

跟踪委托

止盈止损价格

成交明细

追单失败

强平风险变更

杠杆模式变更

持仓模式变更

全平仓失败

反手仓位

体验金通知

用户通知-强平预警/强平通知

事件合约仓位

增量深度订单簿维护机制

枚举定义

errorCode