WebSocket API

接入URL

mainnet: wss://ws.api3.loopring.io/v3/ws

testnet(goerli): wss://ws.uat2.loopring.io/v3/ws

订阅要求

在订阅websocket之前，需要先拿到wsApiKey，然后用该wsApiKey进行连接，步骤如下：

1. 访问REST API"/v3/ws/key"得到返回的{"key":"fx2xW5hoVFbcaanWS"}
2. 将fx2xW5hoVFbcaanWS拼接到url地址进行websocket连接, 即连接wss://ws.uat3.loopring.io/v3/ws?wsApiKey=fx2xW5hoVFbcaanWS.

订阅

客户端可以通过发送JSON数据订阅多个主题：

{
  "op": "sub",
  "sequence": 10000,
  "apiKey": ".....",
  "unsubscribeAll": true,
  "topics": [
    {
      "topic": "account"
    },
    {
      "topic": "order",
      "market": "LRC-ETH"
    },
    {
      "topic": "order",
      "market": "LRC-USDT"
    },
    {
      "topic": "orderbook",
      "market": "LRC-ETH",
      "level": 0
    },
    {
      "topic": "orderbook",
      "market": "LRC-USDT",
      "level": 0,
      "count": 20,
      "snapshot": true
    },
    {
      "topic": "ammpool",
      "poolAddress": "0x18920d6E6Fb7EbE057a4DD9260D6D95845c95036",
      "snapshot": true
    }
  ]
}

1. 在一次订阅中，如果topics中任何一个主题需要ApiKey，那么本次操作就必须包含ApiKey。
2. 在一次订阅中，相同的主题可以出现多次，但同一个主题的相同的配置只可以出现一次。
3. 在一次订阅中，如果有任何参数错误，则全部订阅都会失败。
4. 如果unsubscribeAll是true，订阅前会先退订之前订阅的所有主题。
5. 订阅时客户端可以指定一个sequence代表序列号，后台返回结果也会附带同样的序列号。
6. 最多可以订阅20个主题

退订

客户端可以通过发送JSON数据退订多个主题：

 {
    "op":"unSub",
    "sequence": 10000,
    "apiKey": ".....",
    "unsubscribeAll": false,
    "topics": [
        {
            "topic": "account",
        },
        {
            "topic": "order",
            "market": "LRC-ETH"
        },
        {
            "topic": "order",
            "market": "LRC-USDT"
        },
        {
            "topic": "orderbook",
            "unsubscribeAll":true
        }
    ]
  },

1. 在一次退订中，如果topics中任何一个主题需要ApiKey，那么本次操作就必须包含ApiKey。
2. 在一次退订中，相同的主题可以出现多次，但同一个主题的相同的配置只可以出现一次。
3. 在一次退订中，如果有任何参数错误，则全部订阅都会失败。
4. 如果unsubscribeAll是true，所有主题都会被退订；如果在某个主题内将unsubscribeAll设置为true，那么该主题的所有配置都会被退订。
5. 退订时客户端可以指定一个sequence代表序列号，后台返回结果也会附带同样的序列号。

心跳

WebSocket链接建立后，中继会每30秒会发送“ping”消息给客户端做心跳检测。如果客户端在最近2分钟内都没有任何“pong”消息，中继会断开WebSocket链接。如果客户端的“pong”消息数量超过服务端发送的“ping”消息数量，中继也会断开WebSocket链接。

返回值

Result结构

Error结构

状态码

示例

订阅成功示例：

{
  "op": "sub",
  "sequence": 10000,
  "topics": [
    {
      "topic": "orderbook",
      "market": "LRC-ETH",
      "level": 0
    }
  ],
  "result": {
    "status": "ok"
  }
}

订阅参数不合法的失败示例：

{
  "op": "sub",
  "sequence": 10000,
  "topics": [
    {
      "topic": "candlestick",
      "market": "LRC-ETH",
      "count": 10
    }
  ],
  "result": {
    "status": "failed",
    "error": {
      "code": 104106,
      "message": "receive illegal arg for candlestick:lrc-eth"
    }
  }
}

订阅参数无法解析的失败示例：

{
    "op": "sub",
    "topics":[],
    "result": {
        "status": "failed",
        "error": {
            "code": 104115,
            "message": "unexpected msg:xxx"
        }
    }
}