MAX 交易所 RESTful API
查看 API 列表
基本介紹
為豐富使用者的交易體驗,MAX 交易所發佈了與平台相關的 RESTful API 接口,提供開發者去程式化及自動化操作交易的途徑。發佈的 API 包含了公開及私人兩種類型,下表列出中兩者的主要區別:
類別
身分驗證
流量限制
使用須知
公開 API
不需驗證
每個 IP 地址 1 分鐘內最多 1200 個請求
立即可用
私人 API
每人 1 分鐘內最多 1200 個請求
所有透過 API 的請求及回覆,需透過 JSON 格式表示。關於不同 API 間可以發送的請求內容,請參考 API 列表;而關於回覆的內容,請參考 回覆內容
如何驗證
在使用私人 API 前,需要先準備好您的 API 密鑰,請在註冊並通過認證後,訪問 API 密鑰 頁面申請您的密鑰並妥善保管,當完成申請後,您將會得到對應的 Access Key 及 Secret Key。
當您的 API 密鑰準備好後,在取用私人 API 時,將所需資訊依循下述指示填入封包的標頭檔,便可通過驗證:
標頭名稱
身分驗證
X-MAX-ACCESSKEY
您的 Access Key
X-MAX-PAYLOAD
根據您的請求內容生成的負載 (payload)
X-MAX-SIGNATURE
依據您的 Secret Key 跟負載內容生成的簽名 (signature)
負載是根據請求內容產生的字串,簽名則是根據負載所產生的雜湊值,以 JavaScript 為例
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 是請求路徑,例如/api/v3/info
 // nonce 是以正整數表示的時間戳記,代表了從 Unix epoch 到當前時間所經過的毫秒數(ms)。
 // nonce 與伺服器的時間差不得超過正負30秒,每個 nonce 只能使用一次。
 // body 中其餘的參數請依據您的請求內容自行調整
 const params = { 
   nonce: Date.now(),
   // <Other parameters if needed...>
 };
 const paramsToBeSigned = {
   ...params,
   path: '/api/v3/info',
 };
 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/v3/info?${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(),
   market: 'btcusdt',
 };
 const paramsToBeSigned = {
   ...params,
   path: '/api/v3/wallet/spot/orders',
 };
 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/v3/wallet/spot/orders', {
   method: 'DELETE',
   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/v3/info'
 parameters: {}

Request:
GET /api/v3/info?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: 'DELETE'
 path: '/api/v3/wallet/spot/orders'
 parameters: {}

Request:
DELETE /api/v3/wallet/spot/orders HTTP/1.1
content-type: application/json
x-max-accesskey: example-access-key
x-max-payload: eyJub25jZSI6MTYzMjM3NTg4MTkyMCwibWFya2V0IjoiYnRjdXNkdCIsInBhdGgiOiIvYXBpL3YzL3dhbGxldC9zcG90L29yZGVycyJ9=
x-max-signature: cb9938ab4b22b920fd312f5832af6dd3161e03f0a060b584f3766b738e7c192a
Host: max-api.maicoin.com

{"nonce":1632375881920}
回覆內容
當 API 調用失敗,會回覆對應的 HTTP 狀態碼,同時回傳包含詳細錯誤訊息的 JSON 數據,例如:
{"error":{"code":1001,"message":"market does not have a valid value"}}
所有錯誤都遵循上例的格式,只是引用的錯誤碼和錯誤訊息有所不同。錯誤是由 MAX 交易所自行定義,錯誤訊息則是具體的出錯內容。
對於成功的 API 請求,MAX 交易所會回傳 200 做為 HTTP 狀態碼,同時回傳請求的 JSON 數據,詳細的回傳內容可參考 API 列表
變更歷程
2024-08-30
2024-03-14
  • GET /api/v2/members/me 將 name, identity_number, arc_number, birthday, phone_number 欄位調整為隱碼格式。
  • GET /api/v2/members/profile 將 name, identity_number, arc_number, birthday, phone_number 欄位調整為隱碼格式。
  • POST /api/v2/withdrawal/twd 將 bank.name 欄位調整為隱碼格式。
2024-02-19
  • GET /api/v2/withdrawals & GET /api/v2/withdrawal 未上鏈之虛幣提領 txid 會為空值。
  • GET /api/v2/withdrawals & GET /api/v2/withdrawal 新增「label」(提幣地址標籤)欄位。
2024-01-15
  • 2024/01/18 後,GET /api/v2/trades/my 的 rate limit 調整為每分鐘 20 次。
2024-01-10
  • GET /api/v2/trades/my 即將啟用分頁最大限制,無法查詢到第 10,000 筆之後的資料,請改用 from, to 或是 timestamp 參數來取代。
2023-04-27
  • POST /api/v2/orders/multi/onebyone 將於 2023-5-31 後棄用,請改用 POST /api/v2/orders 取代。
2023-03-07
  • GET /api/v2/orders 的 states 參數預設值從 ['wait', 'convert'] 變更至 ['wait']。
注意事項
由於進入與離開掛單簿是一個非同步的操作,因此在接收到下單與取消單之 RESTful API 回傳結果時,僅代表該請求已被成功接受,並不保證對應之操作已全數完成。特別是在進行「取消掛單」的操作時,待取消的掛單可能有尚未處理完成的成交,或取消掛單的隊列有較多處理中的請求,此時,回傳結果中的訂單並不一定已處於「取消」狀態,必須透過 "GET /api/v3/order" 或是 WebSocket 來得到最新的資訊。