Introduction

Welcome to the MCS trader and developer documentation.These documents outline exchange functionality, market details, and APIs. APIs are separated into two categories: Trading and Feed. Trading API : Requires authentication and provide access to placing orders and other account information. Feed API : Public API that provides market data.

MCS API Resources

  • Help Center - Learn about exchange mechanism here!

  • MCS API docs - Report issues here!

  • MCS Socket API Docs - Streaming API with the most up-to-date market and account order data. With this API, you can send messages to a server and receive event-driven responses without having to poll the server for a reply.

ChangeLog

General Info

General API Information

  • REST endpoint URL

  • All endpoints return a JSON object.

  • Data is returned in ascending order. Oldest first, newest last.

  • All time and timestamp related fields are in milliseconds.

  • For GET endpoints, parameters must be sent as a query string.

  • For POST, PUT, and DELETE endpoints, the query parameters need to be included in the request body with JSON. (e.g. {"symbol":"BTCUSDT","leverage":20}).

All requests made to private endpoints must be authenticated. Requests made to public endpoints do not require the additional parameters needed for authentication.

We also have sample codes for Python, Java and Node.js. (Not supported yet)

Creating a Request

All private REST requests must contain the following headers:

  • X-MCS-ACCESS-KEY : Your API key.

  • X-MCS-TIMESTAMP : Number of milliseconds since Unix epoch.

  • X-MCS-SIGNATURE : SHA256 HMAC of the following four strings, using your API secret as a hex string.

  • HTTP method in uppercase (e.g. GET or POST)

  • Use API-Secret to encrypt the prehash string {timestamp+method+endpoint+body} with SHA256 HMAC. The request body is a JSON string and needs to be the same with the parameters passed by the API. Do not include extra spaces in JSON strings.

    e.g.
    '1598236093000PUT/position/leverage{"symbol":"BTCUSDT","leverage":20}'
  • For GET requests, the endpoint needs to contain the query string.

    e.g.
    '1598236093000GET/order/fills?symbol=BTCUSDT&limit=20'

Selecting a Timestamp

The X-MCS-TIMESTAMP header MUST be a number in milliseconds since Unix Epoch in UTC. e.g. 1598236093000

Click here for how to create timestamp for each language.

The difference between your timestamp and the API service time must be less than 5 seconds , or your request will be considered expired and rejected.

HTTP Return Codes

  • HTTP 4XX return codes are used for malformed requests; the issue is on the sender’s side.

  • HTTP 403 return code is used when the WAF Limit (Web Application Firewall) has been violated.

  • HTTP 429 return code is used when breaking a request rate limit.

  • HTTP 418 return code is used when an IP has been auto-banned for continuing to send requests after receiving 429 codes.

  • HTTP 5XX return codes are used for internal errors; the issue is on MCS’s side.

  • HTTP 503 return code is used when the API successfully sent the message but did not get a response within the timeout period. It is important to NOT treat this as a failure operation; the execution status is UNKNOWN and could have been a success.

LIMITS

Rate Limits

  • Every request will contain X-MCS-USED-WEIGHT-(intervalNum)(intervalLetter) in the response headers which has the current used weight for the IP for all request rate limiters defined.

  • Each route has a weight which determines for the number of requests each endpoint counts for. Heavier endpoints and endpoints that do operations on multiple symbols will have a heavier weight.

  • When a 429 is received, it’s your obligation as an API to back off and not spam the API.

  • Repeatedly violating rate limits and/or failing to back off after receiving 429s will result in an automated IP ban (HTTP status 418).

  • IP bans are tracked and scale in duration for repeat offenders, from 2 minutes to 3 days.

  • The limits on the API are based on the IPs, not the API keys.

It is strongly recommended to use websocket stream for getting data as much as possible, which can not only ensure the timeliness of the message, but also reduce the access restriction pressure caused by the request.

Order Count Limits

To keep an orderly market, MCS imposes limits on the number of open orders per position. These limits are:

  1. Maximum 50 request orders (active orders + condition orders) per position;

  2. Maximum 10 conditional orders per position;

When placing a new order that causes these caps to be exceeded, it will be rejected with the message “Too many [active or conditional] orders”.

Public Resources

Market Data

Get OrderBook

Get orderbook details.

Weight: 1

HTTP Request
GET /orderbook
Request Parameters
Parameter Required Description

symbol

true

Name of the market

depth

Max = 200. Default = 20

Response

The bids array is sorted by price in descending order. The best (highest) bid price is the first element and the worst (lowest) bid price is the last element. The asks array is sorted by price in ascending order. The best (lowest) ask price is the first element and the worst (highest) ask price is the last element. Bid/ask arrays can be empty if there are no corresponding orders in the order book.

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 200

{
  "result" : {
    "asks" : [ [ "8600.0", 240 ], [ "8400.0", 180 ], [ "8200.0", 150 ] ],
    "bids" : [ [ "9200.0", 150 ], [ "9000.0", 110 ], [ "8800.0", 100 ] ]
  },
  "timestamp" : 1599842375669
}
Response Content Fields
Path Type Description

asks

Array

asks[0]0] : price, asks[0][1] : quantity

bids

Array

bids[0][0] : price, bids[0][1] : quantity

Get Contracts

Get trading rules and symbol information

Weight
1 for a single symbol
2 when the symbol parameter is omitted

HTTP Request
GET /contract
Request Parameters
Parameter Required Description

symbol

true

Name of the market

Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 1089

{
  "result" : {
    "symbol" : "BTCUSDT",
    "baseCurrency" : "BTC",
    "quoteCurrency" : "USDT",
    "settlementCurrency" : "BTC",
    "contractStatus" : "OPEN",
    "productType" : "PERPETUAL",
    "contractType" : "INVERSE",
    "multiplier" : "1",
    "lotSize" : "1",
    "orderableMinPrice" : "1",
    "orderableMaxPrice" : "100000",
    "tickSize" : "0.05",
    "orderableMinQuantity" : 1,
    "orderableMaxQuantity" : 1000000,
    "baseInitialMarginRate" : "0.01",
    "incrementInitialMarginRate" : null,
    "baseMaintenanceMarginRate" : "0.005",
    "baseRiskLimit" : "200",
    "incrementRiskLimit" : "100",
    "riskLimitMaxLevel" : "10",
    "upsideOrderLimitRate" : "0.05",
    "downsideOrderLimitRate" : "0.05",
    "makerFeeRate" : "-0.00025",
    "takerFeeRate" : "0.00075",
    "hiddenFeeRate" : "0.00075",
    "settlementFeeRate" : null,
    "expiryAt" : null,
  },
  "timestamp" : 1599840917568
}
Response Content Fields
Path Type Description

symbol

String

contractStatus

String

contractType

String

productType

String

baseCurrency

String

quoteCurrency

String

settlementCurrency

String

expiryAt

Number

baseRiskLimit

String

incrementRiskLimit

String

riskLimitMaxLevel

String

baseInitialMarginRate

String

incrementInitialMarginRate

Number

baseMaintenanceMarginRate

String

incrementMaintenanceMarginRate

Number

multiplier

String

tickSize

String

lotSize

String

orderableMaxQuantity

Number

orderableMinQuantity

Number

orderableMaxPrice

String

orderableMinPrice

String

upsideOrderLimitRate

String

downsideOrderLimitRate

String

listingAt

Number

settlementFeeRate

Number

makerFeeRate

String

takerFeeRate

String

hiddenFeeRate

String

Get Tickers

Get the latest information for symbol.

Weight
1 for a single symbol
2 when the symbol parameter is omitted

HTTP Request
GET /tickers
Request Parameters
Parameter Required Description

symbol

true

Name of the market

Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 1044

{
  "result" : [ {
    "symbol" : "BTCUSDT",
    "lastPrice" : "9100",
    "baseVolume24h" : "1351.8",
    "quoteVolume24h" : "13967537",
    "bestBid" : [ "9100", 1111 ],
    "bestAsk" : [ "9200", 1000 ],
    "highPrice24h" : "10600",
    "lowPrice24h" : "10000",
    "priceChange24h" : "-1009879",
    "openInterest" : 1018979,
    "indexPrice" : "9180.978766765",
    "markPrice" : "9181.71324387",
    "fundingRate" : "0.0001",
    "predictedFundingRate" : "0.0001",
    "nextFundingTime" : 1599116400000
  }, {
    "symbol" : "BTCUSDT",
    "lastPrice" : "9100",
    "baseVolume24h" : "1351.8",
    "quoteVolume24h" : "13967537",
    "bestBid" : [ "9100", 1111 ],
    "bestAsk" : [ "9200", 1000 ],
    "highPrice24h" : "10600",
    "lowPrice24h" : "10000",
    "priceChange24h" : "-1009879",
    "openInterest" : 1018979,
    "indexPrice" : "9180.978766765",
    "markPrice" : "9181.71324387",
    "fundingRate" : "0.0001",
    "predictedFundingRate" : "0.0001",
    "nextFundingTime" : 1599116400000
  } ],
  "timestamp" : 1599842372788
}
Response Content Fields
Path Type Description

symbol

String

lastPrice

String

baseVolume24h

String

quoteVolume24h

String

bestBid

Array

bestAsk

Array

highPrice24h

String

lowPrice24h

String

priceChange24h

String

openInterest

Number

indexPrice

String

markPrice

String

fundingRate

String

predictedFundingRate

String

nextFundingTime

Number

Get Klines

Kline/candlestick bars for a symbol. Klines are uniquely identified by their open time.

Weight: 1

HTTP Request
GET /klines
Request Parameters
Parameter Required Description

symbol

true

Name of the market

interval

true

Candle data recording period

startTime

Start timestamp in milliseconds

endTime

End timestamp in milliseconds

limit

Max = 200. Default = 20

Response

If {startTime} and {endTime} are not sent, the most recent {limit} data are returned.
If the number of data between {startTime} and {endTime} is larger than {limit}, return as {startTime} + {limit}.
The result array is sorted by timestamp in ascending order, oldest data first, most recent data last.

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 346

{
  "result" : [ {
    "open" : "9479.5",
    "high" : "9481",
    "low" : "9479.5",
    "close" : "9481",
    "volume" : 100,
    "openTime" : 1599842370753
  }, {
    "open" : "9495.5",
    "high" : "9495.5",
    "low" : "9491.5",
    "close" : "9491.5",
    "volume" : 196,
    "openTime" : 1599842370754
  } ],
  "timestamp" : 1599842370771
}
Response Content Fields
Path Type Description

openTime

Number

volume

Number

open

String

close

String

high

String

low

String

Get Trades

Get recent trades.

Weight: 1

HTTP Request
GET /trades
Request Parameters
Parameter Required Description

symbol

true

Name of the market

startTime

true

Start timestamp in milliseconds

endTime

true

End timestamp in milliseconds

limit

true

Max = 200. Default = 100

Response

If {startTime} and {endTime} are not sent, the most recent {limit} data are returned.
If the number of data between {startTime} and {endTime} is larger than {limit}, return as {startTime} + {limit}.
The result array is sorted by timestamp in ascending order, oldest data first, most recent data last.

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 316

{
  "result" : [ {
    "filledId" : 1597229688853004,
    "price" : "11500",
    "quantity" : 1,
    "side" : "SELL",
    "time" : 1597229688853
  }, {
    "filledId" : 1597280288671002,
    "price" : "12000",
    "quantity" : 1,
    "side" : "SELL",
    "time" : 1597280288671
  } ],
  "timestamp" : 1599842372121
}
Response Content Fields
Path Type Description

filledId

Number

price

String

quantity

Number

side

String

time

Number

Get Funding History

Get funding rate history.

Weight: 1

GET /funding/history
Request Parameters
Parameter Required Description

symbol

true

Name of the market

startTime

Start timestamp in milliseconds

endTime

End timestamp in milliseconds

limit

Max = 200. Default = 20

Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 198

{
  "result" : [ {
    "fundingRate" : "0.0000125",
    "fundingTime" : 1597370400000
  }, {
    "fundingRate" : "0.0000125",
    "fundingTime" : 1597374000000
  } ],
  "timestamp" : 1599842376340
}
Response Content Fields
Path Type Description

fundingRate

String

fundingTime

Number

Private Resources

Order

Create Order

Place a new order.

Weight: 1

HTTP Request
POST /order
Request Fields
Parameter Type Required Description

symbol

String

true

Name of thez market

orderSide

String

true

OrderSide

orderType

String

true

OrderType

orderQuantity

Number

true

orderPrice

Number

timeInForce

String

TimeInForce Default GOOD_TILL_CANCEL

fillCondition

String

FillConditionType Default NORMAL

postOnly

Boolean

Default false

displayQuantity

Number

Max = 200. Default = 20

triggerPrice

Null

Used with STOP_LIMIT, TAKE_PROFIT_LIMIT, STOP_MARKET, TAKE_PROFIT_MARKET orders

triggerType

String

TriggerType Default MARK

closeOnTrigger

Boolean

Default false

trailValue

Null

orderAlias

String

Agency customized order ID. Max length is 36 characters. Required if not passing orderId, and orderAlias under the same agency has to be unique

Request Body
{
  "symbol" : "BTCUSDT",
  "orderType" : "LIMIT",
  "orderSide" : "BUY",
  "orderQuantity" : 11,
  "orderPrice" : 9272,
  "timeInForce" : "GOOD_TILL_CANCEL",
  "fillCondition" : "NORMAL",
  "postOnly" : false,
  "displayQuantity" : 11,
  "triggerPrice" : null,
  "triggerType" : "MARK",
  "closeOnTrigger" : false,
  "orderAlias" : "[email protected]",
  "trailValue" : null
}
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 595

{
  "result" : {
    "symbol" : "BTCUSDT",
    "orderId" : "4675474c-dc43-4d45-be67-ddcfdc7022f8",
    "orderAlias" : "[email protected]",
    "orderStatus" : "NEW",
    "orderType" : "LIMIT",
    "orderSide" : "BUY",
    "orderQuantity" : 11,
    "displayQuantity" : 11,
    "orderPrice" : "9272",
    "timeInForce" : "GOOD_TILL_CANCEL",
    "fillCondition" : "NORMAL",
    "postOnly" : false,
    "triggerPrice" : "",
    "triggerType" : "",
    "createdAt" : 1599809967987,
    "accountId" : 1
  },
  "timestamp" : 1599842368037
}
Response Content Fields
Path Type Description

symbol

String

orderId

String

orderAlias

String

orderStatus

String

orderType

String

orderSide

String

orderQuantity

Number

displayQuantity

Number

orderPrice

String

timeInForce

String

fillCondition

String

postOnly

Boolean

triggerPrice

String

triggerType

String

createdAt

Number

accountId

Number

Cancel Order

Cancel an active order.

Weight: 1

HTTP Request
DELETE /order
Request Fields
Parameter Type Required Description

symbol

String

true

Name of the market

orderId

String

Order ID. Required if not passing clientOrderId

orderAlias

Null

Agency customized order ID. Max length is 36 characters. Required if not passing orderId, and orderAlias under the same agency has to be unique

Request Body
{
  "symbol" : "BTCUSDT",
  "orderId" : "653992b5-da7b-43b8-a1d6-f967c0e5a3d1",
  "orderAlias" : null
}
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 606

{
  "result" : {
    "symbol" : "BTCUSDT",
    "orderId" : "653992b5-da7b-43b8-a1d6-f967c0e5a3d1",
    "orderAlias" : "[email protected]",
    "orderStatus" : "CANCELED",
    "orderType" : "LIMIT",
    "orderSide" : "BUY",
    "orderQuantity" : 11,
    "displayQuantity" : 11,
    "orderPrice" : "9272",
    "timeInForce" : "GOOD_TILL_CANCEL",
    "fillCondition" : "NORMAL",
    "postOnly" : false,
    "triggerPrice" : null,
    "triggerType" : "MARK",
    "createdAt" : 1594615759344,
    "accountId" : 1
  },
  "timestamp" : 1599842367781
}
Response Content Fields
Path Type Description

symbol

String

orderId

String

orderAlias

String

orderStatus

String

orderType

String

orderSide

String

orderQuantity

Number

displayQuantity

Number

orderPrice

String

timeInForce

String

fillCondition

String

postOnly

Boolean

triggerPrice

String

triggerType

String

createdAt

Number

accountId

Number

Get Order

Retrieve order details by order ID.

Weight: 1

HTTP Request
GET /order
Request Parameters
Parameter Required Description

symbol

true

Name of the market

orderId

Order ID. Required if not passing clientOrderId

orderAlias

Agency customized order ID. Max length is 36 characters. Required if not passing orderId, and orderAlias under the same agency has to be unique

Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 638

{
  "result" : {
    "orderId" : "653992b5-da7b-43b8-a1d6-f967c0e5a3d1",
    "symbol" : "BTCUSDT",
    "orderType" : "LIMIT",
    "orderSide" : "BUY",
    "orderQuantity" : 11,
    "displayQuantity" : 11,
    "orderPrice" : "9272",
    "filledAvgPrice" : 0,
    "remainQuantity" : 11,
    "createdAt" : 1594615759344,
    "orderStatus" : "CANCELED",
    "orderAlias" : "[email protected]",
    "triggerPrice" : null,
    "triggerType" : "MARK",
    "timeInForce" : "GOOD_TILL_CANCEL",
    "postOnly" : false,
    "fillCondition" : "NORMAL"
  },
  "timestamp" : 1599842367934
}
Response Content Fields
Path Type Description

orderId

String

symbol

String

orderType

String

orderSide

String

orderQuantity

Number

displayQuantity

Number

orderPrice

String

filledAvgPrice

Number

remainQuantity

Number

createdAt

Number

orderStatus

String

orderAlias

String

triggerPrice

Null

triggerType

String

timeInForce

String

postOnly

Boolean

fillCondition

String

Get Filled Orders

Get recently filled transaction details.

Weight: 1

HTTP Request
GET /order/fills
Request Parameters
Parameter Required Description

symbol

true

Name of the market

startTime

Start timestamp in milliseconds

endTime

End timestamp in milliseconds

limit

Max = 200. Default = 100

Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 777

{
  "result" : [ {
    "filledId" : 6,
    "orderId" : "15937850-4144-42af-8289-a8367b77f07c",
    "orderStatus" : "PARTIALLY_FILLED",
    "ownerAccountId" : 1,
    "accountId" : 1,
    "positionId" : 8000,
    "symbol" : "BTCUSDT",
    "orderType" : "LIMIT",
    "orderSide" : "BUY",
    "filledType" : "MAKER",
    "orderQuantity" : 100,
    "displayQuantity" : 89,
    "executedQuantity" : 89,
    "remainQuantity" : 16,
    "orderPrice" : 9495.5,
    "filledPrice" : "9495.5",
    "feeRate" : "-0.00025",
    "fee" : "-0.000002343215207203",
    "filledAt" : 1599842368146,
    "isOpenOrder" : false,
    "orderAlias" : "[email protected]",
    "createdAt" : 1591969335285
  } ],
  "timestamp" : 1599842368167
}
Response Content Fields
Path Type Description

filledId

Number

orderId

String

orderStatus

String

ownerAccountId

Number

accountId

Number

positionId

Number

symbol

String

orderType

String

orderSide

String

filledType

String

orderQuantity

Number

displayQuantity

Number

executedQuantity

Number

remainQuantity

Number

orderPrice

Number

filledPrice

String

feeRate

String

fee

String

filledAt

Number

isOpenOrder

Boolean

orderAlias

String

createdAt

Number

Get All Orders

Get all open orders that are unfilled or partially filled. Fully filled orders cannot be cancelled.

Weight: 5

HTTP Request
GET /order/all
Request Parameters
Parameter Required Description

symbol

true

Name of the market

Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 588

{
  "result" : [ {
    "orderId" : "faf9543e-b483-4815-8c90-7b6608d3f300",
    "symbol" : "BTCUSDT",
    "orderType" : "MARKET",
    "orderSide" : "BUY",
    "orderQuantity" : 1,
    "displayQuantity" : 1,
    "orderPrice" : "10000",
    "filledAvgPrice" : 0,
    "remainQuantity" : 1,
    "createdAt" : 1597394983111,
    "orderStatus" : "NEW",
    "orderAlias" : null,
    "triggerPrice" : null,
    "triggerType" : null,
    "timeInForce" : "GOOD_TILL_CANCEL",
    "postOnly" : false,
    "fillCondition" : "NORMAL"
  } ],
  "timestamp" : 1599842367870
}
Response Content Fields
Path Type Description

orderId

String

symbol

String

orderType

String

orderSide

String

orderQuantity

Number

displayQuantity

Number

orderPrice

String

filledAvgPrice

Number

remainQuantity

Number

createdAt

Number

orderStatus

String

orderAlias

String

triggerPrice

String

triggerType

String

timeInForce

String

postOnly

Boolean

fillCondition

String

Bulk Order

Create Bulk Order

Place contract orders in a batch. Maximum 10 orders can be placed at a time for each contract.

Weight: 5

HTTP Request
POST /order/bulk
Request Fields
Parameter Type Required Description

symbol

String

true

orderAlias

String

true

orderType

String

true

orderSide

String

true

orderQuantity

Number

true

displayQuantity

Number

true

orderPrice

Number

true

timeInForce

String

true

fillCondition

String

true

postOnly

Boolean

true

triggerPrice

Null

true

triggerType

String

true

closeOnTrigger

Boolean

Default false

trailValue

Null

Request Body
{
  "orders" : [ {
    "symbol" : "BTCUSDT",
    "orderType" : "LIMIT",
    "orderSide" : "BUY",
    "orderQuantity" : 11,
    "orderPrice" : 9272,
    "timeInForce" : "GOOD_TILL_CANCEL",
    "fillCondition" : "NORMAL",
    "postOnly" : false,
    "displayQuantity" : 11,
    "triggerPrice" : null,
    "triggerType" : "MARK",
    "closeOnTrigger" : false,
    "orderAlias" : "[email protected]",
    "trailValue" : null
  } ]
}
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 599

{
  "result" : [ {
    "symbol" : "BTCUSDT",
    "orderId" : "d4ed8929-4841-45e2-82a5-2c5e817f4116",
    "orderAlias" : "[email protected]",
    "orderStatus" : "NEW",
    "orderType" : "LIMIT",
    "orderSide" : "BUY",
    "orderQuantity" : 11,
    "displayQuantity" : 11,
    "orderPrice" : "9272",
    "timeInForce" : "GOOD_TILL_CANCEL",
    "fillCondition" : "NORMAL",
    "postOnly" : false,
    "triggerPrice" : "",
    "triggerType" : "",
    "createdAt" : 1599809968073,
    "accountId" : 1
  } ],
  "timestamp" : 1599842368112
}
Response Content Fields
Path Type Description

symbol

String

orderId

String

orderAlias

String

orderStatus

String

orderType

String

orderSide

String

orderQuantity

Number

displayQuantity

Number

orderPrice

String

timeInForce

String

fillCondition

String

postOnly

Boolean

triggerPrice

String

triggerType

String

createdAt

Number

accountId

Number

Cancel Bulk Order

Cancel multiple open orders with orderId or orderAlias. Maximum 10 orders can be cancelled at a time for each contract.

Weight: 5

HTTP Request
DELETE /order
Request Fields
Parameter Type Required Description

symbol

String

true

Name of the market

orderIdList

Array

Order ID list. Required if not passing clientOrderIdList. Max 10 orders

orderAliasList

Null

Agency customized order ID list. Max 10 orders

Request Body
{
  "symbol" : "BTCUSDT",
  "orderIdList" : [ "653992b5-da7b-43b8-a1d6-f967c0e5a3d1" ],
  "orderAliasList" : null
}
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 610

{
  "result" : [ {
    "symbol" : "BTCUSDT",
    "orderId" : "653992b5-da7b-43b8-a1d6-f967c0e5a3d1",
    "orderAlias" : "[email protected]",
    "orderStatus" : "CANCELED",
    "orderType" : "LIMIT",
    "orderSide" : "BUY",
    "orderQuantity" : 11,
    "displayQuantity" : 11,
    "orderPrice" : "9272",
    "timeInForce" : "GOOD_TILL_CANCEL",
    "fillCondition" : "NORMAL",
    "postOnly" : false,
    "triggerPrice" : null,
    "triggerType" : "MARK",
    "createdAt" : 1594615759344,
    "accountId" : 1
  } ],
  "timestamp" : 1599842367830
}
Response Content Fields
Path Type Description

symbol

String

orderId

String

orderAlias

String

orderStatus

String

orderType

String

orderSide

String

orderQuantity

Number

displayQuantity

Number

orderPrice

String

timeInForce

String

fillCondition

String

postOnly

Boolean

triggerPrice

String

triggerType

String

createdAt

Number

accountId

Number

Position

Get Position

Get current position information.

Weight: 1

HTTP Request
GET /position
Request Parameters
Parameter Required Description

symbol

true

Name of the market

Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 473

{
  "result" : [ {
    "accountId" : 1,
    "symbol" : "BTCUSDT",
    "marginType" : "ISOLATED",
    "positionQuantity" : 1,
    "positionSide" : "NONE",
    "positionValue" : null,
    "entryPrice" : "11100.5",
    "liquidationPrice" : "10137.44292237446",
    "leverage" : "10",
    "orderMargin" : "0",
    "positionEntryMargin" : "0.000009082924192604",
    "upnl" : "0.0008",
    "markPrice" : 8900
  } ],
  "timestamp" : 1599842374354
}
Response Content Fields
Path Type Description

accountId

Number

symbol

String

marginType

String

positionQuantity

Number

positionSide

String

positionValue

String

entryPrice

String

liquidationPrice

String

leverage

String

orderMargin

String

positionEntryMargin

String

upnl

String

markPrice

Number

Change Position Leverage

Change position leverage

Weight: 1

HTTP Request
PUT /position/leverage
Request Fields
Parameter Type Required Description

symbol

String

true

Name of the market

leverage

Number

true

New leverage from 1 ~ max level of this position

targetValue

Number

Request Body
{
  "symbol" : "BTCUSDT",
  "targetValue" : 10,
  "leverage" : 10,
}
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 132

{
  "result" : {
    "symbol" : "BTCUSDT",
    "leverage" : "10"
  },
  "timestamp" : 1599842374309
}
Response Content Fields
Path Type Description

symbol

String

String

leverage

String

TradeFee

Get User Trade Fee

Fetch trade fee.

Weight
1 for a single symbol
2 when the symbol parameter is omitted

HTTP Request
GET /tradeFee
Request Parameters
Parameter Required Description

symbol

true

Name of the market

Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 150

{
  "result" : [ {
    "symbol" : "BTCUSDT",
    "maker" : -2.5E-4,
    "taker" : 7.5E-4,
    "hidden" : 7.5E-4
  } ],
  "timestamp" : 1599842372090
}
Response Content Fields
Path Type Description

symbol

String

maker

Number

taker

Number

hidden

Number

Wallet

Get Wallet Balances

Get wallet balance information.

Weight: 1

HTTP Request
GET /wallet/balances
Request Parameters
Parameter Required Description

asset

Returns all wallet balances if not passed

Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 246

{
  "result" : {
    "asset" : "BTC",
    "walletBalance" : "1.367036940158093",
    "bonusBalance" : "0",
    "availableBalance" : "1.367036940158093",
    "orderMargin" : "0",
    "positionEntryMargin" : "0"
  },
  "timestamp" : 1599842375071
}
Response Content Fields
Path Type Description

asset

String

walletBalance

String

bonusBalance

String

availableBalance

String

orderMargin

String

positionEntryMargin

String

Get Wallet Incomes

Get income history.

Weight: 1

HTTP Request
GET /wallet/incomes
Request Parameters
Parameter Required Description

asset

true

incomeType

BalanceIncomeType

symbol

Name of the market

startTime

Start timestamp in milliseconds

endTime

End timestamp in milliseconds

limit

Max = 200. Default = 100

Response

If {startTime} and {endTime} are not sent, the most recent {limit} data are returned.
If the number of data between {startTime} and {endTime} is larger than {limit}, return as {startTime} + {limit}.
The result array is sorted by timestamp in ascending order, oldest data first, most recent data last.

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 453

{
  "result" : [ {
    "incomeType" : "TRADE_FEE",
    "contractCode" : "BTCUSDT",
    "symbol" : "BTCUSDT",
    "currency" : "BTC",
    "asset" : "BTC",
    "amount" : "0.00001492380451918",
    "accountBalance" : "9.99992767273101",
    "walletBalance" : "9.99992767273101",
    "bonusType" : "NONE",
    "bonusBalance" : "0",
    "createdAt" : "2020-09-11T16:39:35.088Z",
    "time" : "2020-09-11T16:39:35.088Z"
  } ],
  "timestamp" : 1599842375097
}
Response Content Fields
Path Type Description

incomeType

String

contractCode

String

symbol

String

currency

String

asset

String

amount

String

accountBalance

String

walletBalance

String

bonusType

String

bonusBalance

String

createdAt

String

time

String

Error Codes

Errors consist of two parts: an error code and a message.
Codes are universal,but messages can vary.

Error Codes and Messages

ErrorCode Message

NVALID_API_KEY

Invalid api-key

INVALID_SIGNATURE

Invalid signature

API_KEY_NOT_FOUND

Api-key not found

ORDERBOOK_NOT_FOUND

%s orderbook not found

CHART_NOT_FOUND

%s klines not found

TRADES_NOT_FOUND

%s recent trades not found

FUNDING_HISTORY_NOT_FOUND

%s funding rate history not found

LIQUIDATION_ORDERS_NOT_FOUND

%s liquidation active orders not found

INTERVAL_NOT_A_NUMBER

Interval is not a number.

MISSING_PARAM

Missing parameter '%s'

MISSING_PRICE

Missing parameter price

MISSING_SYMBOL

Missing parameter symbol

MISSING_ASSET

Missing parameter asset

INVALID_DATA

Invalid data

INVALID_PARAM

Invalid parameter '%s'

INVALID_ASSET

Invalid parameter asset %s

INVALID_POSITION_TYPE

Invalid parameter position type

INVALID_SYMBOL

Invalid parameter symbol

POST_ONLY_REJECT

Post-only rule not satisfied

REDUCE_ONLY_REJECT

reduce-only rule not satisfied

CLOSE_BY_REJECT

close-by rule not satisfied

OPTIONAL_PARAMS_BAD_COMBO

Combination of optional parameters invalid

QUANTITY_LESS_THAN_MIN_QUANTITY

Quantity less than min quantity

QUANTITY_GREATER_THAN_MAX_QUANTITY

Quantity greater than max quantity

PRICE_LESS_THAN_MIN_PRICE

Price less than min price

PRICE_GREATER_THAN_MAX_PRICE

Price greater than max price

EXCEED_MIN_TAKER_PRICE

Buy price cannot be higher than max taker order price

EXCEED_MAX_TAKER_PRICE

Sell price cannot be lower than min taker order price

PRICE_UNSUITABLE

Price Adjust Tick Size

EXCEED_ACTIVE_ORDER_COUNT

Too many active orders

EXCEED_CONDITIONAL_ORDER_COUNT

Too many conditional orders

WRONG_SIDE

Wrong parameter side

IOC_CANCEL

Orders that cannot be immediately filled has been canceled

UNKNOWN_ORDER_COMPOSITION

Unsupported order combination

DUPLICATE_ORDER_ID_SENT

The orderAlias is already in use

MISSING_ORDER_ID_OR_ORDER_ALIAS

Missing orderId or orderAlias

ORDER_ALREADY_DECLINED

The order is rejected or expired

ORDER_ALREADY_CANCELLED

Order already cancelled

UNKNOWN_ORDER_ID_SENT

The order (by either orderId, orderAlias) could not be found

ORDER_ALREADY_FILLED

Order already filled

HTTP_MESSAGE_NOT_READABLE

%s

REQUEST_REJECT

%s

METHOD_ARGUMENT_TYPE_MISMATCH

%s

RESOURCE_NOT_FOUND

%s

ILLEGAL_ARGUMENT

%s

TYPE_MISMATCH

%s

CONSTRAINT_VIOLATION

%s

VALIDATION_FAILED

%s

BIND_FAILED

%s

HTTP_REQUEST_METHOD_NOT_SUPPORTED

%s

METHOD_ARGUMENT_NOT_VALID

%s

NON_NUMERIC_FIELD

%s

EXCEPTION

%s

Changelog

2020-08-26

REST API

  • Check server time [new]

  • Order Validation [enhancement]

  • Place Order [new]

  • Cancel Order [new]

  • Place Multiple Orders [new]

  • Cancel Multiple Orders [new]