Currently, WebSocket API is in BETA, we will have minor changes without prior announcement.

URL: wss://max-ws.maicoin.com


MAX Exchange WebSocket API provides a realtime updates for developers to monitor order books, trades, and their accounts changes information.

To use WebSocket API, one can simply follows the steps:

  1. 1. Connect to WebSocket server
  2. 2. Subscribe to interested channels
  3. 3. Authenticate the connection using API tokens and get private information
  4. 4. Dealing with the data

WebSocket is a protocol that supported on many languages. Take JavaScript for example here:

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

let web_socket = new WebSocket(url);
web_socket.onopen = function() {
  // deal with connection success, start the subscription
}

web_socket.onmessage = function(msg) {
  // deal with different message, like challenge and authentication
  console.log(msg.data);
}

// listen to events like 'onclose' and 'onerror' depends on your needs
......

MAX Exchange provides a few public channels. For details, please refer to Channel List.

Below shows an example to subscribe to your interested channel in JavaScript:

// subscribe
web_socket.send(JSON.stringify({
  cmd: 'subscribe',
  channel: 'ticker',
  params: { market: 'btctwd' } // parameters can be different between channels
}));
// unsubscribe
web_socket.send(JSON.stringify({
  cmd: 'unsubscribe',
  channel: 'ticker',
  params: { market: 'btctwd' } // parameters can be different between channels
}));

Before you subscribe to private channel, you need to get your access/secret keys first. After signed up and verified, please visit API Tokens page to get your keys.

When your access/secret keys are ready, you can connect to MAX Exchange WebSocket server and get a challenge message from it:

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

A challenge message will include a random generated string. Client should sign the string with its secret key. Then send the signature to the server. Server will verify the signature, if pass, start pushing account information; if fail, send the error message back.

Let's demonstrate the process in JavaScript:

const crypto = require('crypto');

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

// Take the string above for example
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));

Note that, authentication is not required if you don't need your account information. You can choose to not authenticate or unauthenticate your connection if you don't need to monitor your account information:

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

Public channels

  • Ticker

    Ticker provides realtime price information.

    requestresponsemessage format
    {
      cmd: 'subscribe',
      channel: 'ticker',
      params: {
        // using https://max-api.maicoin.com/api/v2/markets to get available 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 provides realtime changes on order books.

    requestresponsemessage format
    {
      cmd: 'subscribe',
      channel: 'orderbook',
      params: {
        // using https://max-api.maicoin.com/api/v2/markets to get available 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 provides realtime trades information.

    requestresponsemessage format
    {
      cmd: 'subscribe',
      channel: 'trade',
      params: {
        // using https://max-api.maicoin.com/api/v2/markets to get available markets
        market: < Target Market >
      }
    }
    {
      info: 'subscribed',
      channel: 'trade',
      params: {
        market: < Target Market >
      }
    }
    {
      info: 'trade',
      at: < UNIX Epoch timestamp >,
      market: < Market >,
      price: < Price >,
      volume: < Volume >
    }

Private channel

  • Account

    Account provides accounts changes for an user.

    requestresponsemessage format
    {
      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: { // Or ask, depends on the user's striked order
          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 >
        }
      }
    }