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
发送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
},
{
"fairPrice": 220.22,
"lastPrice": 220.4,
"riseFallRate": -0.0686,
"symbol": "BCH_USDT",
"volume24": 200
}
],
"ts": 1587442022003
}
获取平台全部永续合约的最新成交价、买一价、卖一价和24交易量，无需用户登录，订阅后1秒发送一次。
订阅、取消订阅、数据示例见右侧。
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| symbol | string | 合约名 |
| lastPrice | decimal | 最新价 |
| volume24 | decimal | 24小时成交量，按张数统计 |
| riseFallRate | decimal | 涨跌幅 |
| fairPrice | decimal | 合理价 |
获取单个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",
"ts":1587442022003
}
获取某个合约的最新成交价、买一价、卖一价和24交易量，无需用户登录，有成交数据就推送，订阅后1秒发送一次。
订阅、取消订阅、数据示例见右侧。
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| symbol | string | 合约名 |
| lastPrice | decimal | 最新价 |
| bid1 | decimal | 买一价 |
| ask1 | decimal | 卖一价 |
| volume24 | decimal | 24小时成交量，按张数统计 |
| holdVol | decimal | 总持仓量 |
| lower24Price | decimal | 24小时最低价 |
| high24Price | decimal | 24小时内最高价 |
| riseFallRate | decimal | 涨跌幅 |
| riseFallValue | decimal | 涨跌额 |
| indexPrice | decimal | 指数价格 |
| fairPrice | decimal | 合理价 |
| fundingRate | decimal | 资金费率 |
| timestamp | long | 系统时间戳 |
成交
订阅
{
"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":"sub.depth",
"param":{
"symbol":"BTC_USDT",
"compress":true
}
}
订阅全量（limit可取值:5、10、20，不传默认为20档，只能订阅一个档位的全量）
{
"method":"sub.depth.full",
"param":{
"symbol":"BTC_USDT",
"limit":5
}
}
取消订阅（增量的都以该事件取消订阅）
{
"method":"unsub.depth",
"param":{
"symbol":"BTC_USDT"
}
}
取消订阅（取消订阅全量，limit可传可不传）
{
"method":"usub.depth.full",
"param":{
"symbol":"BTC_USDT"
}
}
数据示例
{
"channel":"push.depth",
"data":{
"asks":[
[
6859.5,
3251,
1
]
],
"bids":[
],
"version":96801927
},
"symbol":"BTC_USDT",
"ts":1587442022003
}
订阅、取消订阅、数据示例见右侧。 增量深度订阅，默认启用合并，如不需启用，订阅时请将compress设置为false
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| asks | List<Numeric[]> | 卖方深度 |
| bids | List<Numeric[]> | 买方深度 |
| version | long | 版本号 |
备注: [411.8, 10, 1] 411.8为价格，10为此价格的合约张数,1为订单数量
K线数据
订阅
{
"method":"sub.kline",
"param":{
"symbol":"BTC_USDT",
"interval":"Min60"
}
}
取消订阅
{
"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",
"ts":1587442022003
}
获取合约的K线数据，有更新就推送。
订阅、取消订阅、数据示例见右侧。
interval可选参数: Min1、Min5、Min15、Min30、Min60、Hour4、Hour8、Day1、Week1、Month1
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| symbol | string | 合约名 |
| a | decimal | 总成交金额 |
| c | decimal | 收盘价 |
| interval | string | 间隔: Min1、Min5、Min15、Min30、Min60、Hour4、Hour8、Day1、Week1、Month1 |
| l | decimal | 最低价 |
| o | decimal | 开盘价 |
| q | decimal | 总成交量 |
| h | decimal | 最高价 |
| t | long | 交易时间，单位：秒（s），为窗口的开始时间（windowStart） |
资金费率
订阅
{
"method":"sub.funding.rate",
"param":{
"symbol":"BTC_USDT"
}
}
取消订阅
{
"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 | 下一次结算时间 |
指数价格
订阅
{
"method":"sub.index.price",
"param":{
"symbol":"BTC_USDT"
}
}
取消订阅
{
"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"
}
}
取消订阅
{
"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 | 价格 |
私有频道
签名方式：
api_key和req_time拼接，将得到的参数字符串用HMAC SHA256进行加密。api_key和sec_key分别为申请api时的ACCESS KEY 和SECRET KEY。
签名字符串
"mx0aBYs33eIilxBW5C1657186536762"
登录认证
示例
{"channel":"rs.login",
"data":"success",
"ts":"1587442022003"
}
{
"method":"login",
"param":{
"apiKey":"apiKey", // openapi需要传此参数，参数构造方式参照openapi文档
"reqTime":"reqTime", // openapi需要传此参数，参数构造方式参照openapi文档
"signature":"signature" // openapi需要传此参数，参数构造方式参照openapi文档
}
}
响应参数：
成功: 无，失败:返回对应错误信息,channel = rs.error
登录成功(channel = rs.login)
订单
数据示例
{
"channel":"push.personal.order",
"data":{
"category":1,
"createTime":1610005069976,
"dealAvgPrice":0.731,
"dealVol":1,
"errorCode":0,
"externalOid":"_m_95bc2b72d3784bce8f9efecbdef9fe35",
"feeCurrency":"USDT",
"leverage":0,
"makerFee":0,
"openType":1,
"orderId":"102067003631907840",
"orderMargin":0,
"orderType":5,
"positionId":1397818,
"price":0.707,
"profit":-0.0005,
"remainVol":0,
"side":4,
"state":3,
"symbol":"CRV_USDT",
"takerFee":0.00004386,
"updateTime":1610005069983,
"usedMargin":0,
"version":2,
"vol":1
},
"ts":1610005069989
}
请求参数： 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强平代管委托,4ADL减仓 |
| orderType | int | 1:限价单,2:Post Only只做Maker,3:立即成交或立即取消,4:全部成交或者全部取消 |
| 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 | 错误code,0:正常，1：参数错误，2：账户余额不足，3：仓位不存在，4：仓位可用持仓不足，5：多仓时， 委托价小于了强平价，空仓时， 委托价大于了强平价，6：开多时， 强平价大于了合理价，开空时， 强平价小于了合理价 ,7:超过风险限额限制，8:系统撤销 |
| externalOid | string | 外部订单号 |
| createTime | date | 创建时间 |
| updateTime | date | 修改时间 |
资产
数据示例
{
"channel":"push.personal.asset",
"data":{
"availableBalance":0.7514236,
"bonus":0,
"currency":"USDT",
"frozenBalance":0,
"positionMargin":0
},
"ts":1610005070083
}
请求参数： channel = push.personal.asset
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| currency | string | 币种 |
| positionMargin | decimal | 仓位保证金 |
| frozenBalance | decimal | 冻结余额 |
| availableBalance | decimal | 当前可用余额 |
| cashBalance | decimal | 可提现余 额 |
仓位
数据示例
{
"channel":"push.personal.position",
"data":{
"autoAddIm":false,
"closeAvgPrice":0.731,
"closeVol":1,
"frozenVol":0,
"holdAvgPrice":0.736,
"holdFee":0,
"holdVol":0,
"im":0,
"leverage":15,
"liquidatePrice":0,
"oim":0,
"openAvgPrice":0.736,
"openType":1,
"positionId":1397818,
"positionType":1,
"realised":-0.0005,
"state":3,
"symbol":"CRV_USDT"
},
"ts":1610005070157
}
请求参数： 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 | 持仓均价 |
| closeAvgPrice | decimal | 平仓均价 |
| openAvgPrice | decimal | 开仓均价 |
| liquidatePrice | decimal | 逐仓时的爆仓价 |
| oim | decimal | 原始初始保证金 |
| adlLevel | int | adl减仓等级,取值为 1-5，为空时需等待刷新 |
| im | decimal | 初始保证金， 逐仓时可以加减此项以调节爆仓价 |
| holdFee | decimal | 资金费, 正数表示得到，负数表示支出 |
| realised | decimal | 已实现盈亏 |
| createTime | date | 创建时间 |
| updateTime | date | 修改时间 |
风险限额
请求参数： 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 | 初始保证金率 |
adl自动减仓等级
数据示例
{
"channel":"push.personal.adl.level",
"data":{
"adlLevel":0,
"positionId":1397818
},
"ts":1610005032231
}
请求参数： channel = push.personal.adl.level
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| adlLevel | int | 当前adl等级 ：1-5 |
| positionId | long | 仓位id |
如何维护深度信息
例如订阅成交信息
{"method":"sub.deal",
"param":{
"symbol":"BTC_USDT"
}
}
订阅成功响应
{"channel":"rs.sub.deal",
"data":"success",
"ts":"1587442022003"
}
订阅失败响应
{"channel":"rs.error",
"data":"合约不存在!",
"ts":"1587442022003"
}
仓位模式
数据示例
{
"channel":"push.personal.position.mode",
"data":{
positionMode: 1
},
"ts":1610005070157
}
请求参数： channel = push.personal.position.mode
响应参数：
| 参数名 | 类型 | 说明 |
|---|---|---|
| positionMode | int | 仓位模式,1:双向，2:单向 |
如何维护增量深度信息:
- 通过接口 https://contract.mexc.com/api/v1/contract/depth/BTC_USDT获取全量深度信息，保存当前version
- 订阅ws深度信息，收到更新后，如果收到的数据
version>当前version,同一个价位，后收到的更新覆盖前面的。 - 通过接口 https://contract.mexc.com/api/v1/contract/depth_commits/BTC_USDT/1000获取最新1000条深度快照
- 将目前缓存的深度信息中同一价格，
version<步骤3获取到的快照中的version的数据丢弃 - 将深度快照中的内容更新至本地缓存，并从ws接收到的event开始继续更新
- 每一个新event的version应该恰好等于上一个event的version+1，否则可能出现了丢包，如出现丢包或者获取到的event的version不连续,请从步骤3重新进行初始化。
- 每一个event中的挂单量代表这个价格目前的挂单量绝对值，而不是相对变化。
- 如果某个价格对应的挂单量为0，表示该价位的挂单已经撤单或者被吃，应该移除这个价位。
订阅类事件，订阅成功响应:
channel 为 rs. + 订阅的method， data为 "success"