Introduction

Welcome to use MEXC API! This document provides you with REST API related information to help you obtain market information, manage account information, and conduct trading.

What is API？

API is an Application Programming Interface, abbreviated as API, which is a settlement interface. It defines the interaction between multiple applications, the types of calls or requests that can be made, how to make calls or requests, the data format that should be used, the conventions that should be followed, etc. The API document describes how the application interacts with our exchange.

Instructions

Step: if the developer needs to use the API, please first create APIKey and then carry out the development of trading according to the details of this document. If you have any problems or suggestions in the process of using it, please let us know in time.

• Please refer to this page to set the API Key.
• When setting API key, it is recommended to set IP access whitelist for security.
• Never tell anyone your API key/secret.

Interface type REST API

REST, the abbreviation of Representational State Transfer, is a popular communication mechanism based on HTTP. Its structure is clear, standard, easy to understand, easy to expand, and is being adopted by more and more websites. Its advantages are as follows:

• Each URL represents a resource in RESTful structure;
• Some presentation layer of the resource is passed between the client and the server;
• It is suggested that developers use Rest API for currency trading or asset withdrawal;
• The client uses four HTTP instructions to operate the server-side resources to achieve "Representational State Transfer";

API V1 or API V2

We recommend that all users build their applications on V2 of the API. Using V2 has the following advantages:

• Compared with API V1, the security and rationality of API V2 signature are better.
• Improved performance for particular endpoints / channels.
• Our official customer base provides a wider range of support.

Change log

Integration guide

Access URLs

Please make API requests with the following base urls:

• https://www.mexc.com

Request Format

The APIs accept GET, POST or DELETE request, as will be described in later sections

• For a GET or DELETE reqeust, all parameters are path paremeters (query string)
• For a POST reqeust, business parameters are to be put in request body and of JSON format(withcontent-typeset toapplication/json), they will not be used for signing of the request. To calculate signature, params api_key,req_time,recv_window(optional),sign need to be sent as path parameter

Response Format

Response is of JSON format for all APIs

Signature

Public APIs (for market data) and private APIs (for account and order operations) are provided.

Signature is not required for public APIs.

And for private APIs, signature is required and will be used for checking the validity of each request.

Please refer to Signature Method for detail

Time Security

 if (req_time > (server_time + 2 ) || req_time < (server_time - recv_window)) {
   // reject request     
 }else{
  // process request
 }

Parameter req_time is required for each private API, After API server receives a request, timestamp validation will be conducted to make sure the requesting time from client is valid.

The request is considered invalid if the received req_time is less or more than 10 seconds (the default value) (the time window can be adjusted by sending an optional header parameter recv-window with a maximum value of 60, recv_window of 30 seconds or more is not recommended)

Signature Parameters

Parameters related to request signature

Creating API key

API key can be created in the User Center of MEXC site. There are two parts of API key, Access key and Secret key,both of them will be used for calculating and validating a signature. Please grant appropriate permissions for the created API key, before using it.

Signature Method

java example

/**
 * Gets the get request parameter string
 *
 * @param param get/delete Request parameters map
 * @return
 */
public static String getRequestParamString(Map<String, String> param) {
    if (MapUtils.isEmpty(param)) {
        return "";
    }
    StringBuilder sb = new StringBuilder(1024);
    SortedMap<String, String> map = new TreeMap<>(param);
    for (Map.Entry<String, String> entry : map.entrySet()) {
        String key = entry.getKey();
        String value = StringUtils.isBlank(entry.getValue()) ? "" : entry.getValue();
        sb.append(key).append('=').append(urlEncode(value)).append('&');
    }
    sb.deleteCharAt(sb.length() - 1);
    return sb.toString();
}

public static String urlEncode(String s) {
    try {
        return URLEncoder.encode(s, "UTF-8").replaceAll("\\+", "%20");
    } catch (UnsupportedEncodingException e) {
        throw new IllegalArgumentException("UTF-8 encoding not supported!");
    }
}

/**
 * signature
 */
public static String sign(SignVo signVo) {
    if (signVo.getRequestParam() == null) {
        signVo.setRequestParam("");
    }
    String str = signVo.getAccessKey() + signVo.getReqTime() + signVo.getRequestParam();
    return actualSignature(str, signVo.getSecretKey());
}

public static String actualSignature(String inputStr, String key) {
    Mac hmacSha256;
    try {
        hmacSha256 = Mac.getInstance("HmacSHA256");
        SecretKeySpec secKey =
                new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
        hmacSha256.init(secKey);
    } catch (NoSuchAlgorithmException e) {
        throw new RuntimeException("No such algorithm: " + e.getMessage());
    } catch (InvalidKeyException e) {
        throw new RuntimeException("Invalid key: " + e.getMessage());
    }
    byte[] hash = hmacSha256.doFinal(inputStr.getBytes(StandardCharsets.UTF_8));
    return Hex.encodeHexString(hash);
}

@Getter
@Setter
public static class SignVo {
    private String reqTime;
    private String accessKey;
    private String secretKey;
    private String requestParam; //get the request parameters are sorted in dictionary order, with & concatenated strings, POST should be a JSON string
}

1. Signature is not required for public endpoint.

2. For private endpoint, ApiKey, Request-Time(Timestamp string displayed in milliseconds ), Signature and Content-Type need to be passed into the header, must be specified as application / JSON, Recv-Window (optional) parameters, Signature is a signature string. The signature rules are as follows:

   1) When signing, you need to get the request parameter string first. It is "" if there is no parameter:

   For GET/DELETE requests, the service parameters are spliced in dictionary order with & interval, and finally the signature target string is obtained (in the API of batch operation, if there are special symbols such as comma in the parameter value, these symbols need to be URL encoded when signing).

   For POST requests, the signature parameter is a JSON string (dictionary sorting is not required).

   2) After obtaining the parameter string, the signature target string is spliced. The rule is: accessKey + timestamp + obtained parameter string.

   3) The HMAC SHA256 algorithm is used to sign the target string, and finally the signature is passed into the header as a parameter.

Note：

1) When the service parameter participating in the signature is null, it does not participate in the signature. For the path parameter, it does not participate in the signature; note that when get request stitches the parameter and pass it in the URL, if the parameter is null, it will be parsed into "" in the background parsing, fixed post request, when the parameter is null, do not pass the parameter, or set the value of the parameter to "" when signing, otherwise signature verification will fail.

2) When requesting, put the value of Request-Time used in signing into the Request-Time parameter of the header, put the obtained signature string into the signature parameter of the header, put the Access Key of APIKEY into the ApiKey parameter of the header, and pass the other service parameters.

3) The obtained signature string does not need to be base64 encoded.

Error Code

The following error information can be returend

Rate Limit

There is rate limit for API access frequency, upon exceed client will get code 429: Too many requests.

The account is used as the basic unit of speed limit for the endpoints that need to carry access keys. For endpoints that do not need to carry access keys, IP addresses are used as the basic unit of rate limiting.

The default rate limiting rule for an endpoint is 20 times per second.

ENUM Definition

Order State

Order Type

Trade Type

Time Interval

m -> minute; h -> hour; d -> day; M -> month

• 1m
• 5m
• 15m
• 30m
• 60m
• 4h
• 1M

General data

All symbols

Response example

{
  "code": 200,
  "data": [
    {
      "symbol": "QTUM_USDT",
      "state": "ENABLED",
      "price_scale": 4,
      "quantity_scale": 2,
      "min_amount": "5",
      "max_amount": "5000000",
      "maker_fee_rate": "0.002",
      "taker_fee_rate": "0.002",
      "limited": false,
      "etf_mark": 0,
      "symbol_partition": "MAIN",
      "tradeSideType":"1"
    }
  ]
}

• GET /open/api/v2/market/symbols

Request parameters：None

Response

Current System Time

Response example

{
    "code": 200,
    "data": 1573542414480
}

• GET /open/api/v2/common/timestamp

Request parameters：None

Response

Ping

Response example

{
    "code": 200
}

• GET /open/api/v2/common/ping

Request parameters：None

Response

Obtain the transaction pairs that supports API transactions on the platform.

Response example

{
  "code": 200,
  "data": [
    {
      "ALEPH_USDT",
      "XFI_USDT",
      "ETH3S_USDT",
      "OGN_USDT",
      "HC_USDT",
      "PAX_USDT",
      "BNU_USDT",
    }
  ]
}

Obtain the transaction pairs that supports API transactions on the platform.

• GET /open/api/v2/market/api_default_symbols

Request Parameters:

None

Response Parameters:

Market Data

Ticker Information

Response example

{
    "code": 200,
    "data": [
        {
          "symbol": "BTC_USDT",
          "volume": "47876.096755",
          "amount": "1161420469.76",
          "high": "24902.08",
          "low": "23494.28",
          "bid": "24684.48",
          "ask": "24685.6",
          "open": "24018.6",
          "last": "24681.71",
          "time": 1660226100000,
          "change_rate": "0.02760818"
        }
    ]
}

• GET /open/api/v2/market/ticker

Request parameters：

Response：

Market depth

Response example

{
    "code": 200,
    "data": {
        "asks": [
            {
                "price": "183.1683154",
                "quantity": "128.5"
            },
            {
                "price": "183.1983186",
                "quantity": "101.6"
            }
        ],
        "bids": [
            {
                "price": "182.4417544",
                "quantity": "115.5"
            },
            {
                "price": "182.4217568",
                "quantity": "135.7"
            }
        ]
    }
}

• GET /open/api/v2/market/depth

Request parameters：

Response：

Latest Deals

Response example

{
    "code": 200,
    "data": [
        {
            "trade_time": 1573267931530,
            "trade_price": "183.1683154",
            "trade_quantity": "5",
            "trade_type": "BID"
        },
        {
            "trade_time": 1573266717841,
            "trade_price": "183.1683154",
            "trade_quantity": "0.5",
            "trade_type": "ASK"
        },
        {
            "trade_time": 1573013871967,
            "trade_price": "183.1183105",
            "trade_quantity": "128.6",
            "trade_type": "BID"
        }
    ]
}

• GET /open/api/v2/market/deals

Request paramters：

Response：

Candlestick Data

Response example

{
    "code": 200,
    "data": [
        [
            1557728040,    //timestamp in seconds
            "7054.7",      //open
            "7056.26",     //close
            "7056.29",     //high
            "7054.16",     //low
            "9.817734",    //vol
            "6926.521"     //amount
        ],
        [
            1557728100,
            "7056.26",
            "7042.17",
            "7056.98",
            "7042.16",
            "23.69423",
            "1677.931"
        ]
    ]
}

• GET /open/api/v2/market/kline

Request parameters：

Response：

Get currency information

This endpoint returns a list of currency details.

• GET /open/api/v2/market/coin/list

API Permission: Read(for public )

Request Parameters:

Response Parameters:

Note:  the hidden currencies and off shelve currencies does not display; 

Account Information

Balance

Resposne example

{
    "code": 200,
    "data": {
        "BTC": {
            "frozen": "0",
            "available": "140"
        },
        "ETH": {
            "frozen": "8471.296525048",
            "available": "483280.9653659222035"
        },
        "USDT": {
            "frozen": "0",
            "available": "27.3629"
        },
        "MX": {
            "frozen": "30.9863",
            "available": "450.0137"
        }
    }
}

• GET /open/api/v2/account/info

Request parameters：None

Response：

Balance information of each currency

Obtain the trading pairs of the accounts that can trade through the API

Response example

{
  "code": 200,
  "data": [
    {
      "ALEPH_USDT",
      "XFI_USDT",
      "ETH3S_USDT",
      "OGN_USDT",
      "HC_USDT",
      "PAX_USDT",
      "BNU_USDT",
    }
  ]
}

Obtain the transaction pairs where the API transactions and private endpoint are enabled by the account.

• POST /open/api/v2/market/api_symbols

Request Parameters:

None

Response Parameters:

Spot Trading

Place Order

Response example

{
    "code": 200,
    "data": "c8663a12a2fc457fbfdd55307b463495"
}

• POST /open/api/v2/order/place

Request parameters：

Response：

Cancel Order

Response example

{
    "code": 200,
    "data": {
        "504feca6ba6349e39c82262caf0be3f4": "success"
    }
}

• DELETE /open/api/v2/order/cancel

Request parameters：

Response：

Place Order In Batch

Response example:

response when requesting with client_order_id

{
    "code": 200,
    "data": {
        "1572936": "c8663a12a2fc457fbfdd55307b463495",
        "1572937": "ec42569b4f4349f7aabe26f78b0f8bd2",
        "1572938": "70669675cac2414c90493be2dcfaf7e3"
    }
}

response when requesting without client_order_id

{
    "code": 200,
    "data": [
        "e3e1ee06916c462eb8cd0349ff9ab242",
        "4d1f8c13f4cc40bcbfbac4da2a26d3a5"
    ]
}

• POST /open/api/v2/order/place_batch

Request parameters：

Response：

Open Orders

Response example

{
    "code": 200,
    "data": [
        {
            "id": "e5bb6963250146edb2f8677fcfcc97aa",
            "symbol": "MX_ETH",
            "price": "0.000907",
            "quantity": "300000",
            "state": "NEW",
            "type": "BID",
            "remain_quantity": "300000",
            "remain_amount": "272.1",
            "create_time": 1574338341797,
            "client_order_id": "",
            "order_type": "LIMIT_ORDER"
        }
    ]
}

• GET /open/api/v2/order/open_orders

Request parameters：

Response：

All Orders

Response example

{
    "code": 200,
    "data": [
        {
            "id": "70669675cac2414c90493be2dcfaf7e3",
            "symbol": "MX_ETH",
            "price": "0.000901",
            "quantity": "300000",
            "state": "NEW",
            "type": "BID",
            "deal_quantity": "0",
            "deal_amount": "0",
            "create_time": 1573217964000
        },
        {
            "id": "ec42569b4f4349f7aabe26f78b0f8bd2",
            "symbol": "MX_ETH",
            "price": "0.000907",
            "quantity": "300000",
            "state": "NEW",
            "type": "ASK",
            "deal_quantity": "0",
            "deal_amount": "0",
            "create_time": 1573217963000
        }
    ]
}

• GET /open/api/v2/order/list

Request parameters：

Response：

Query Orders

Response example

{
    "code": 200,
    "data": [
        {
            "id": "504feca6ba6349e39c82262caf0be3f4",
            "symbol": "MX_ETH",
            "price": "0.000901",
            "quantity": "300000",
            "state": "NEW",
            "type": "BID",
            "deal_quantity": "0",
            "deal_amount": "0",
            "create_time": 1573117266000
        },
        {
            "id": "72872b6ae721480ca4fe0f265d29dfee",
            "symbol": "MX_ETH",
            "price": "0.000907",
            "quantity": "300000",
            "state": "NEW",
            "type": "ASK",
            "deal_quantity": "0",
            "deal_amount": "0",
            "create_time": 1573117267000
        }
    ]
}

• GET /open/api/v2/order/query

Request parameters：

Response：

Deals History

Response example

{
    "code": 200,
    "data": [
        {
          "id": "4ab9700a077d403f8c144c981ff3464b",
          "symbol": "MX_USDT",
          "quantity": "5",
          "price": "1.328",
          "amount": "6.64",
          "fee": "0.01328",
          "trade_type": "ASK",
          "order_id": "d4991cd4296f4138a5b02b2aea8bde8d",
          "is_taker": true,
          "fee_currency": "USDT",
          "create_time": 1657173950000
        }
    ]
}

• GET /open/api/v2/order/deals

Request parameters：

Response：

Deals Detail

Response example

{
    "code": 200,
    "data": [
        {
          "id": "4ab9700a077d403f8c144c981ff3464b",
          "symbol": "MX_USDT",
          "quantity": "5",
          "price": "1.328",
          "amount": "6.64",
          "fee": "0.01328",
          "trade_type": "ASK",
          "order_id": "d4991cd4296f4138a5b02b2aea8bde8d",
          "is_taker": true,
          "fee_currency": "USDT",
          "create_time": 1657173950000
        }
    ]
}

• GET /open/api/v2/order/deal_detail

Request parameters：

Response：

Cancel Orders By Symbol

Response example

{
    "code": 200,
    "data": [
        {
            "msg": "success",
            "order_id": "75ecf99feef04538b78e4622beaba6eb",
            "client_order_id": "a9329e86f2094b0d8b58e92c25029554"
        },
        {
            "msg": "success",
            "order_id": "139413c48f8b4c018f452ce796586bcf"
        },
        {
            "msg": "success",
            "order_id": "b58ef34c570e4917981f276d44091484"
        }
    ]
}

• DELETE /open/api/v2/order/cancel_by_symbol

Request parameters：

Response：

Asset

Only the endpoint handling the reading of deposit and withdrawal information is open currently, the withdrawal endpoint will be made available soon (Please contact the online customer service if you wish to access it now).

Get Deposit Address

This endpoint is used to query the address of a specific currency in its block chain, which is available for both parent-account and  sub-account .

• GET /open/api/v2/asset/deposit/address/list

API Permission: Read

Request Parameters:

Response Parameters:

Note:  1, Signature certification is required for the private endpoint ;  2. Only return the generated address;

Query Deposit Records

• GET /open/api/v2/asset/deposit/list

API Permission: Read

Request Parameters:

Response Parameters:

Note: A single query can retrieve a maximum range of 10 days, and maximum retrieve records is the last 180 days.

Query Withdraw Address List

• GET /open/api/v2/asset/address/list

API Permission:Read

Request Parameters:

Response Parameters:

Query Withdraw Records

• GET /open/api/v2/asset/withdraw/list

API Permission:Read

Request Parameters:

Response Parameters:

Note: A single query can retrieve a maximum range of 10 days, and maximum retrieve records is the last 180 days.

Withdraw

• POST /open/api/v2/asset/withdraw

API Permission: Write 

Request Parameters:

Response Parameters:

Cancel a withdraw request

• DELETE /open/api/v2/asset/withdraw

API Permission: Write

Request Parameters:

Response Parameters:

Internal assets transfer

Support the transfer between Spot and Contract accounts in parent-account.

Support the transfer between Spot and Contract accounts in sub-account.

• POST /open/api/v2/asset/internal/transfer

API Permission: Write

Request Parameters:

Response Parameters:

Note：

1.Transfer is not available for isolated-margin account.

1. Successful submission does not mean successful transfer. You can check whether the transfer is successful through the transfer order query endpoint.

Get internal assets transfer records

It supports the query of internal asset transfer records, and up to 10 days through a single query, and records of the past 180 days can be inquired.

• GET /open/api/v2/asset/internal/transfer/record

API Permission: Read

Request Parameters:

Response Parameters:

Get transferable assets

This endpoint can obtain transferable assets in a specified account and currency.

• GET /open/api/v2/account/balance

API Permission: Read

Request Parameters:

Response Parameters:

Internal assets transfer order inquiry

Through transfer ID query internal asset transfer order details.

• GET /open/api/v2/asset/internal/transfer/info

API Permission: Read

Request Parameters:

Response Parameters: