MAX Exchange RESTful API
URL: https://max-api.maicoin.com/api/v2
Introduction
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:
Type | Authentication | Rate Limits | Note |
---|---|---|---|
Public API | Not required | 1200 requests per IP address every 1 minutes | Ready to use |
Private API | authentication required | 1200 requests per person every 1 minutes | request for API token first |
Authentication
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:
Header Name | Value |
---|---|
X-MAX-ACCESSKEY | Your access key |
X-MAX-PAYLOAD | Payload generated according to your request body |
X-MAX-SIGNATURE | Signature generated according to your secret key and payload |
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}
Response Format
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
Change Log
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.
Tips/Caveats
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.