To provide programmable methods for users to trade automatically, MAX Exchange has published a RESTful API. Published API includes both a public and private one. The main differences between are listed below:

Every request and response through the API is communicated in JSON format. For details on requests that you can make for different API’s, please refer to API List. For response details, please refer to Response Format.

To use our private API, you will need to create an account, pass verification, and then get access/secret keys first. After signing up please visit API Tokens page to get your keys.

When your access/secret keys are ready, please enter in the following information into request headers to pass authentication:

Payload is a string encoded from request body; while signature is a hash of your payload, generated using your secret key. Take JavaScript for example:

import { createHmac } from 'crypto';
import fetch from 'node-fetch';
import * as qs from 'qs';

const accessKey = '<Your Access Key>';
const secretKey = '<Your Secret Key>';

(async () => {
  // path is request path like /api/v2/members/me
  // nonce is a timestamp in positive integer, stands for milliseconds elapsed since Unix epoch.
  // nonce must be within 30 seconds difference of server time, each nonce can be used only once
  // other parameters needed in body depends on your request content
  const params = {
    nonce: Date.now(),
    // <Other parameters if needed...>
  };
  const paramsToBeSigned = {
    ...params,
    path: '/api/v2/members/me',
  };
  const payload = Buffer.from(JSON.stringify(paramsToBeSigned)).toString('base64');
  const signature = createHmac('sha256', secretKey).update(payload).digest('hex');

  const response = await fetch(`https://max-api.maicoin.com/api/v2/members/me?${qs.stringify(params, {arrayFormat: 'brackets'})}`, {
    method: 'GET',
    headers: {
      'X-MAX-ACCESSKEY': accessKey,
      'X-MAX-PAYLOAD': payload,
      'X-MAX-SIGNATURE': signature,
      'Content-Type': 'application/json',
    },
  });
  const data = await response.json();
  console.log(data);
})();

(async () => {
  const params = {
    nonce: Date.now(),
  };
  const paramsToBeSigned = {
    ...params,
    path: '/api/v2/orders/clear',
  };
  const payload = Buffer.from(JSON.stringify(paramsToBeSigned)).toString('base64');
  const signature = createHmac('sha256', secretKey).update(payload).digest('hex');

  const response = await fetch('https://max-api.maicoin.com/api/v2/orders/clear', {
    method: 'POST',
    body: JSON.stringify(params),
    headers: {
      'X-MAX-ACCESSKEY': accessKey,
      'X-MAX-PAYLOAD': payload,
      'X-MAX-SIGNATURE': signature,
      'Content-Type': 'application/json',
    },
  });
  const data = await response.json();
  console.log(data);
})();

Example:
  accessKey: 'example-access-key'
  secretKey: 'example-secret-key'
  nonce: 1632375881920
  method: 'GET'
  path: '/api/v2/members/me'
  parameters: {}

Request:
GET /api/v2/members/me?nonce=1632375881920 HTTP/1.1
content-type: application/json
x-max-accesskey: example-access-key
x-max-payload: eyJub25jZSI6MTYzMjM3NTg4MTkyMCwicGF0aCI6Ii9hcGkvdjIvbWVtYmVycy9tZSJ9
x-max-signature: 5502091e27e06a2e85ade34360f19287431341676b596e84f5625f3c808631ce
Host: max-api.maicoin.com

--
Example:
  accessKey: 'example-access-key'
  secretKey: 'example-secret-key'
  nonce: 1632375881920
  method: 'POST'
  path: '/api/v2/orders/clear'
  parameters: {}

Request:
POST /api/v2/orders/clear HTTP/1.1
content-type: application/json
x-max-accesskey: example-access-key
x-max-payload: eyJub25jZSI6MTYzMjM3NTg4MTkyMCwicGF0aCI6Ii9hcGkvdjIvb3JkZXJzL2NsZWFyIn0=
x-max-signature: bc3e1c7b9d1e2bd66b404b595617738745b86e2f06a157ab1a4e1f1b8b36bf4c
Host: max-api.maicoin.com

{"nonce":1632375881920}

Corresponding HTTP status code will be used in API response. MAX Exchange will also return a JSON structure including error details on failed request, for example:

{"error":{"code":1001,"message":"market does not have a valid value"}}

All errors follow the message format above. “Code” is a MAX Exchange defined error code which indicates the error's category. ”Message” is the error details in human-readable format.

MAX Exchange returns HTTP 200 response on a successful request, with requested data in JSON format. For details, please refer to API List

2023-03-07

• GET /api/v2/orders default states from ['wait', 'convert'] to ['wait'].

2023-04-27

• POST /api/v2/orders/multi/onebyone will be deprecated after 2023-5-31. Please use POST /api/v2/orders instead.

Getting on and getting off the order book are asynchronous operations. Getting a response back from RESTful APIs for placing and cancelling orders only means requests have been accepted, not the operation has completed. Please keep this in mind especially for "cancel order" operations. Orders requested to cancel may have unfinished trades or there may be many cancel requests in the queue waiting to be processed. To get the latest status or an order, please check with the endpoint "GET /api/v2/order" or use the WebSocket.