KuCoin期货WebSocket公共交易频道订阅及公共Token获取方法

直连固定wss端点返回401错误，核心原因是KuCoin所有WebSocket连接（包括无需用户授权的公共频道）都不支持直接连接固定地址，必须先通过公开HTTP接口申请临时公共接入凭证（包含专属服务器地址、临时token、有效期参数），再用返回的参数建立连接，整个凭证申请流程不需要传入任何用户API密钥。

接入流程 #

• 申请公共连接凭证
  向期货公开HTTP接口发送GET请求获取WS接入参数，接口路径为/api/v1/bullet-public，HTTP请求基础地址为https://api-futures.kucoin.com，完整请求无任何鉴权要求。
  接口返回核心字段结构如下：

  {
    "code": "200000",
    "data": {
      "token": "临时访问token字符串",
      "instanceServers": [
        {
          "endpoint": "WebSocket服务器连接地址",
          "encrypt": false,
          "protocol": "websocket",
          "pingInterval": 18000,
          "pingTimeout": 10000
        }
      ]
    }
  }
  

  提取返回值中的token字段，以及instanceServers数组内可用节点的endpoint、pingInterval字段备用。临时token有效期为24小时，过期后需要重新调用接口获取新参数重连。
• 拼接WebSocket连接地址
  最终合法连接地址格式为：{endpoint}?token={token}，直接使用未拼接token的固定endpoint连接就会返回401未授权错误。
• 连接建立后订阅成交频道
  连接成功后需要在超时时间内发送订阅请求，实时成交对应的公共频道主题格式为/contractMarket/execution:{交易对标识}，订阅消息结构如下：

  {
    "id": "自定义请求ID，服务端会原样返回用于匹配请求",
    "type": "subscribe",
    "topic": "/contractMarket/execution:XBTUSDTM",
    "response": true
  }
  

  注意KuCoin期货的交易对命名规则和其他平台存在差异，比如BTC USDT本位永续合约对应的标识为XBTUSDTM，订阅时需要替换为对应交易对的正确标识。
• 连接保活
  按照接口返回的pingInterval数值（单位毫秒）定时向服务端发送ping消息，避免连接被静默断开，ping消息结构如下：

  {
    "id": "自定义ping请求ID",
    "type": "ping"
  }
  

可直接运行的JavaScript实现代码 #

逻辑和常规交易所直连接入代码完全等价，可直接替换使用：

let kucoinMarketWs;
let pingTimer;

// 初始化连接
async function initKucoinTradeWS() {
  // 1. 获取公共接入凭证
  const res = await fetch("https://api-futures.kucoin.com/api/v1/bullet-public", { method: "GET" });
  const connInfo = await res.json();
  if (connInfo.code !== "200000") {
    setTimeout(initKucoinTradeWS, 3000);
    return;
  }

  const token = connInfo.data.token;
  const serverConfig = connInfo.data.instanceServers[0];
  const wsConnectUrl = `${serverConfig.endpoint}?token=${token}`;

  // 2. 建立WebSocket连接
  kucoinMarketWs = new WebSocket(wsConnectUrl);

  // 3. 绑定消息处理
  kucoinMarketWs.onmessage = event => handleKucoinMessage(event.data);

  // 4. 连接成功后发送订阅请求
  kucoinMarketWs.onopen = () => {
    // 订阅BTC USDT永续合约实时成交
    kucoinMarketWs.send(JSON.stringify({
      id: "sub_btc_trade",
      type: "subscribe",
      topic: "/contractMarket/execution:XBTUSDTM",
      response: true
    }));

    // 启动定时保活
    clearInterval(pingTimer);
    pingTimer = setInterval(() => {
      kucoinMarketWs.send(JSON.stringify({ id: "heartbeat", type: "ping" }));
    }, serverConfig.pingInterval);
  };

  // 5. 断线自动重连
  kucoinMarketWs.onclose = () => {
    clearInterval(pingTimer);
    setTimeout(initKucoinTradeWS, 3000);
  };
}

// 处理推送消息
function handleKucoinMessage(rawData) {
  const parsedData = JSON.parse(rawData);
  // 过滤出成交推送消息，忽略订阅响应、pong等其他类型消息
  if (parsedData.type === "message" && parsedData.topic.startsWith("/contractMarket/execution:")) {
    console.log(parsedData);
  }
}

// 启动连接
initKucoinTradeWS();

提示：如果需要订阅现货公共频道的实时成交，只需要把凭证申请接口替换为现货域名下的/api/v1/bullet-public，成交频道主题替换为/market/match:{交易对}即可，其余流程完全一致。

内容的提问来源于stack exchange，提问作者John R