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
 }, {
  "p": 115309.8,
  "v": 11,
  "T": 1,
  "O": 3,
  "M": 1,
  "t": 1755487578275
 }],
 "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:否
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.50,
    "vol": 10,
    "leverage": 20,
    "side": 1,
    "category": 1,
    "orderType": 1,
    "dealAvgPrice": 45000.00,
    "dealVol": 5,
    "orderMargin": 2250.00,
    "usedMargin": 1125.00,
    "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.0000,
    "frozenBalance": 1000.0000,
    "availableBalance": 9000.0000,
    "bonus": 100.0000
  },
  "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.50,
    "holdAvgPriceFullyScale": "45000.500000000000000000",
    "closeAvgPrice": 0,
    "openAvgPrice": 45000.50,
    "openAvgPriceFullyScale": "45000.500000000000000000",
    "liquidatePrice": 40000.00,
    "oim": 2250.025,
    "adlLevel": 1,
    "im": 2250.025,
    "holdFee": 0,
    "realised": 0,
    "leverage": 20,
    "autoAddIm": false,
    "pnl": 100.50,
    "marginRatio": 0.2,
    "newOpenAvgPrice": 45000.50,
    "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.00,
    "price": 45990.00,
    "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.00,
    "takeProfitPrice": 47000.00,
    "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.00,
        "takeProfitPrice": 48000.00,
        "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.00,
        "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.00,
    "markPrice": 44950.00,
    "backType": 1,
    "backValue": 0.5,
    "triggerPrice": 44750.00,
    "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.00,
    "takeProfitPrice": 48000.00
  },
  "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.50,
    "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.0000,
    "be": 1763539200000,
    "g": true,
    "ret": 1763539200000,
    "rea": 100.0000
  },
  "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.0000,
    "openPrice": 45000.50,
    "closePrice": 46250.75,
    "rewardAmount": 25.5000,
    "rewardAmountUsdt": 25.5000,
    "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	总盈亏

增量深度订单簿维护机制

通过 REST 接口获取全量深度访问接口：
GET https://contract.mexc.com/api/v1/contract/depth/{symbol}
示例：/BTC_USDT
获取当前完整深度快照，并记录返回的 version 作为初始版本号。
订阅 WebSocket 深度增量数据订阅深度更新事件。对于同一价格档位，若接收到多条更新，以 version 更高的数据覆盖 version 更低的数据。
获取深度 Commit 快照
定期或在初始化时，通过该接口获取最近 N 条深度快照（例如 1000 条）：
GET https://contract.mexc.com/api/v1/contract/depth_commits/{symbol}/{limit}
示例：/BTC_USDT/1000
移除过期的本地缓存数据
若本地缓存中某个价格档位的数据 version < Commit 快照中的同价格 version，则需将其丢弃。
合并 Commit 快照到本地缓存
将 Commit 快照内容应用到本地订单簿，然后从 WebSocket event 中继续按顺序更新。
确保 version 连续性
每条 WebSocket 增量事件的版本号需满足：
new_event.version == previous_event.version + 1
若发现 version 不连续（例如跳号），表示可能丢包，客户端需回到 步骤 3 重新加载 Commit 快照并重新同步。
当快照的 version 落在推送消息的 [fromVersion, toVersion] 范围内时，可将推送消息与快照数据整合，方法如下：
- 推送消息中的价位在快照中已存在，按照推送消息中的数量重新设置该价位的数量；
- 推送消息中的价位在快照中不存在，按照推送消息中的数量插入新的价位；
- 推送消息中存在数量为 0 的价位，则在快照中删除该价位。
挂单量为绝对值
event 中的数量表示该价格档位当前挂单量的绝对值，而不是相对变化。
挂单量为 0 的处理
当某个价格档位的数量为 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