目前 WebSocket API 為 BETA 版本,有任何更動系統不會事先公告。

網域名稱: wss://max-ws.maicoin.com


MAX 交易所 WebSocket API 為開發者提供了數據更新更加即時的管道。透過 WebSocket,MAX 交易所將即時地推送交易所最新的掛單簿變化、成交資訊及用戶帳戶資訊給使用者。

使用 WebSocket API 可以簡單拆分為下列幾步:

  1. 1. 建立 WebSocket 連接
  2. 2. 訂閱感興趣的資訊
  3. 3. 根據需求使用 API 密鑰驗證身分並獲取帳戶資訊
  4. 4. 接收並處理數據

WebSocket 是一個在許多語言上都有支持的通訊協定,在此我們以 JavaScript 為例:

const WebSocket = require('ws');
const url = 'wss://max-ws.maicoin.com';

let web_socket = new WebSocket(url);
web_socket.onopen = function() {
  // 進行連結成功後的處理,例如開始訂閱資料
}

web_socket.onmessage = function(msg) {
  // 依據訊息內容進行相應處理,例如挑戰驗證
  console.log(msg.data);
}

// 根據需求監聽其他事件,例如 onclose 與 onerror
......

MAX 交易所提供了數個可以公開訂閱的頻道,詳細列表與推送的訊息內容可以參考頻道列表

若您對特定的頻道資訊感興趣,以 JavaScript 為例,您可以透過如下的方式來訂閱或取消訂閱:

// 訂閱
web_socket.send(JSON.stringify({
  cmd: 'subscribe',
  channel: 'ticker',
  params: { market: 'btctwd' } // 參數內容依不同頻道可能有所差異
}));
// 取消訂閱
web_socket.send(JSON.stringify({
  cmd: 'unsubscribe',
  channel: 'ticker',
  params: { market: 'btctwd' } // 參數內容依不同頻道可能有所差異
}));

在訂閱私人頻道之前,需要準備好您的 API 密鑰,請在註冊並通過認證後,訪問 API 密鑰 頁面申請您的密鑰並妥善保管,當完成申請後,您將會得到對應的 Access Key 及 Secret Key。

準備好您的 API 密鑰,依照上述步驟與 MAX 交易所的 WebSocket 伺服器建立連結後,MAX 交易所伺服器會回傳格式如下的一個挑戰訊息:

{ "info": "challenge", "msg": "d45sSFIZZdYzRgwi-zDqA8HFP2MfVoWqXlHX-2LbB_37q9_3pkZ8og" }

挑戰訊息包含一個隨機生成的字串,客戶端需要用 Access Key 及 Secret Key 對這個字串進行簽名,並且將簽名依據格式回傳給伺服器。伺服器將對簽名進行驗證,若通過則開始推送使用者的帳戶資訊給客戶端;失敗的情況下將會回傳錯誤訊息。

以下以 JavaScript 為例,演示如何生成簽名並回傳對應的訊息:

const crypto = require('crypto');

const access_key = < Your Access Key >
const secret_key = < Your Secret Key >

// 使用上述的字串為例
let payload = access_key + 'd45sSFIZZdYzRgwi-zDqA8HFP2MfVoWqXlHX-2LbB_37q9_3pkZ8og';
let signature = crypto.createHmac('sha256', secret_key).update(payload).digest('hex');

let message = {
  cmd: 'auth',
  access_key: access_key,
  answer: signature
};
web_socket.send(JSON.stringify(message));

請注意,身份驗證並非必要的步驟,若您不需要訂閱私人頻道,您可以選擇不進行身份證證;或是當您不再需要訂閱私人頻道後,也可以發送如下的訊息來停止訂閱:

web_socket.send(JSON.stringify({ cmd: 'unauth' }));

公開頻道

  • Ticker

    Ticker 提供了市場即時價格的資訊。

    要求回覆訊息格式
    {
      cmd: 'subscribe',
      channel: 'ticker',
      params: {
        // 可以使用 https://max-api.maicoin.com/api/v2/markets 來獲取上線的市場資訊
        market: < Target Market >
      }
    }
    {
      info: 'subscribed',
      channel: 'ticker',
      params: {
        market: < Target Market >
      }
    }
    {
      info: 'ticker',
      at: < UNIX Epoch timesatamp >,
      market: < Market >,
      buy: < Best buy price on orderbook >,
      sell: < Best sell price on orderbook; >,
      open: < Price before 24 hours >,
      low: < Lowest price within 24 hours >,
      high: < Highest price within 24 hours; >,
      last: < Last price >,
      vol: < Total volume within 24 hours >
    }
  • Order Book

    Order Book 提供了關於掛單簿的變化資訊。

    要求回覆訊息格式
    {
      cmd: 'subscribe',
      channel: 'orderbook',
      params: {
        // 可以使用 https://max-api.maicoin.com/api/v2/markets 來獲取上線的市場資訊
        market: < Target Market >
      }
    }
    {
      info: 'subscribed',
      channel: 'orderbook',
      params: {
        market: < Target Market >
      }
    }
    {
      info: 'orderbook',
      timestamp: < UNIX Epoch timestamp >,
      action: < 'add'|'remove'|'update' >,
      market: < Market >,
      id: < Order ID >,
      side: < 'buy'|'sell' >,
      volume: < Volume >,
      price: < Price >,
      ord_type: < 'limit'|'market' >
    }
  • Trade

    Trade 提供了即時的成交資訊。

    要求回覆訊息格式
    {
      cmd: 'subscribe',
      channel: 'trade',
      params: {
        // 可以使用 https://max-api.maicoin.com/api/v2/markets 來獲取上線的市場資訊
        market: < Target Market >
      }
    }
    {
      info: 'subscribed',
      channel: 'trade',
      params: {
        market: < Target Market >
      }
    }
    {
      info: 'trade',
      at: < UNIX Epoch timestamp >,
      market: < Market >,
      price: < Price >,
      volume: < Volume >
    }

私人頻道

  • Account

    Account 提供了使用者帳戶的即時變化資訊。

    要求回覆訊息格式
    {
      cmd: 'auth',
      access_key: < Access Key >,
      answer: < Answer of the signature >
    }
    {
      info: 'authenticated'
    }
    {
      info: 'account',
      reason: < 'deposit'|'deposit & refund_lock'|'withdraw'|'withdraw_lock'|'withdraw_unlock'|'trade' >,
      // only changed accounts
      accounts: [
        { currency: < Currency >, balance: < Balance >, locked: < Locked > },
        ...
      ],
      // for deposit
      deposit: {
        txid: < Transaction ID >, amount: < Amount >
      },
      // for withdraw
      withdrawal: {
        uuid: < UUID >, amount: < Amount >, fee: < Fee >
      },
      // for trade
      trade: {
        id: < Trade ID >,
        price: < Price >,
        volume: < Volume >,
        funds: < Price * Volume >,
        market: < Market >,
        created_at: < ISO 8601 format >,
        side: < 'bid'|'ask' >,
        bid: { // 或 ask,根據使用者的成交單來決定
          id: < Order ID >,
          side: < 'buy' >, // 'sell' for ask
          price: < Your order price >,
          avg_price: < Funds / Executed volume >,
          state: 'done',
          market: < Market >,
          created_at: < ISO 8601 format >,
          volume: < Origin volume >,
          remaining_volume: < Remaining volume >,
          executed_volume: < Executed volume >
        }
      }
    }