Change log:

2024-10-11: Added the /openapi/v1/sub-account/wallet/deposit/address,/openapi/v1/sub-account/wallet/deposit/history endpoint.

Public Rest API for Coins (2024-05-17)

General API Information

• The base endpoint is: https://api.coins.xyz
• All endpoints return data in either a JSON object or array format.
• Data is returned in ascending order, with the oldest records appearing first and the newest records appearing last.
• All time and timestamp related fields are expressed in milliseconds.

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 exchange’s side. It is important to NOT treat this as a failure operation; the execution status is UNKNOWN and could have been a success.

Error Codes

• Any endpoint can return an ERROR; the error payload is as follows:

{
  "code": -1000,
  "msg": "An unknown error occurred while processing the request."
}

• Specific error codes and messages are defined in another document.

General Information on Endpoints

• For GET endpoints, parameters must be sent as a query string.
• For POST, PUT, and DELETE endpoints, the parameters may be sent as a query string or in the request body with content type application/x-www-form-urlencoded. It is also possible to use a combination of parameters in both the query string and the request body if desired.
• Parameters can be sent in any order.
• If a parameter is included in both the query string and the request body, the value of the parameter from the query string will take precedence and be used.

LIMITS

General Info on Limits

• intervalNum describes the amount of the interval. For example, intervalNum 5 with intervalLetter M means “Every 5 minutes”.

• A HTTP status code 429 will be returned when the rate limit is violated.

IP Limits

• Each route has a weight which determines the number of requests each endpoint counts for. Endpoints with heavier operations or those that involve multiple symbols will have a higher weight.
• When a 429 response code is received, it is mandatory for the API user to back off and refrain from making further requests.
• Repeated failure to comply with rate limits and a disregard for backing off after receiving 429 responses can result in an automated IP ban. The HTTP status code 418 is used for IP bans.
• IP bans are tracked and their duration increases for repeat offenders, ranging from 2 minutes to 3 days.
• A Retry-After header iis included in 418 or 429 responses, indicating the number of seconds that need to be waited in order to prevent a ban (for 429) or until the ban is lifted (for 418).
• The limits imposed by the API are based on IP addresses rather than API keys

Order Rate Limits

• When the order count exceeds the limit, you will receive a 429 error without the Retry-After header.

• The order rate limit is counted against each IP and UID.

Websocket Limits

• A single connection can listen to a maximum of 1024 streams.

/api/ Limit Introduction

• For endpoints related to /api/*:

  • There are two modes of limit enforcement: IP limit and UID limit. Each mode operates independently.

  • The IP limit allows a maximum of 1200 requests per minute across all endpoints within the /api/* namespace.

Endpoint Security Type

• Each endpoint is associated with a security type, which indicates how you should interact with it. The security type is specified next to the name of the endpoint.
  • If no security type is mentioned, assume that the security type is NONE.
• API keys are passed to the Rest API via the X-COINS-APIKEYheader.
• Both API keys and secret keys are case sensitive.
• API keys can be configured to have access only to specific types of secure endpoints. For example, one API key may be restricted to TRADE routes only, while another API key can have access to all routes except TRADE.
• By default, API keys have access to all secure routes.

• TRADE and USER_DATA endpoints are SIGNED endpoints.

SIGNED (TRADE and USER_DATA) Endpoint Security

• SIGNED endpoints require an additional parameter, signature, to be sent in the query string or request body.
• Endpoints use HMAC SHA256 signatures. The HMAC SHA256 signature is a keyed HMAC SHA256 operation. Use your secretKey as the key and totalParams as the value for the HMAC operation.
• The signature is not case sensitive.
• totalParams is defined as the query string concatenated with the request body.
• We recommend the use of query string for GET request and request body for POST request. However, for Spot Trading APIs, we recommend using query string.

Timing Security

• A SIGNED endpoint requires an additional parameter, timestamp, to be included in the request. The timestamp should be the millisecond timestamp indicating when the request was created and sent.
• An optional parameter, recvWindow, can be included to specify the validity duration of the request in milliseconds after the timestamp. If recvWindow is not provided, it will default to 5000 milliseconds.

• The logic is as follows:

  if (timestamp < (serverTime + 1000) && (serverTime - timestamp) <= recvWindow) {
    // process request
  } else {
    // reject request
  }
  

Serious trading is about timing. Networks can be unstable and unreliable, which can lead to requests taking varying amounts of time to reach the servers. With recvWindow, you can specify that the request must be processed within a certain number of milliseconds or be rejected by the server.

To ensure optimal performance, it is recommended to use a recvWindow value of 5000 milliseconds or less. The maximum value allowed for recvWindowis 60,000 milliseconds and should not exceed this limit.

SIGNED Endpoint Examples for POST /openapi/v1/order

Here is a step-by-step example of how to send a valid signed payload from the Linux command line using echo, openssl, and curl:

Example 1: As a query string

• queryString: symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000
• HMAC SHA256 signature:

[linux]$ echo -n "symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000" | openssl dgst -sha256 -hmac "lH3ELTNiFxCQTmi9pPcWWikhsjO04Yoqw3euoHUuOLC3GYBW64ZqzQsiOEHXQS76"
(stdin)= 5f2750ad7589d1d40757a55342e621a44037dad23b5128cc70e18ec1d1c3f4c6

• curl command:

(HMAC SHA256)
[linux]$ curl -H "X-COINS-APIKEY: tAQfOrPIZAhym0qHISRt8EFvxPemdBm5j5WMlkm3Ke9aFp0EGWC2CGM8GHV4kCYW" -X POST 'https://$HOST/openapi/v1/order?symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000&signature=5f2750ad7589d1d40757a55342e621a44037dad23b5128cc70e18ec1d1c3f4c6'

Example 2: As a request body

• requestBody: symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000
• HMAC SHA256 signature:

[linux]$ echo -n "symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000" | openssl dgst -sha256 -hmac "lH3ELTNiFxCQTmi9pPcWWikhsjO04Yoqw3euoHUuOLC3GYBW64ZqzQsiOEHXQS76"
(stdin)= 5f2750ad7589d1d40757a55342e621a44037dad23b5128cc70e18ec1d1c3f4c6

• curl command:

(HMAC SHA256)
[linux]$ curl -H "X-COINS-APIKEY: tAQfOrPIZAhym0qHISRt8EFvxPemdBm5j5WMlkm3Ke9aFp0EGWC2CGM8GHV4kCYW" -X POST 'https://$HOST/openapi/v1/order' -d 'symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000&signature=5f2750ad7589d1d40757a55342e621a44037dad23b5128cc70e18ec1d1c3f4c6'

Example 3: Mixed query string and request body

• queryString: symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC
• requestBody: quantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000
• HMAC SHA256 signature:

[linux]$ echo -n "symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTCquantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000" | openssl dgst -sha256 -hmac "lH3ELTNiFxCQTmi9pPcWWikhsjO04Yoqw3euoHUuOLC3GYBW64ZqzQsiOEHXQS76"
(stdin)= 885c9e3dd89ccd13408b25e6d54c2330703759d7494bea6dd5a3d1fd16ba3afa

• curl command:

(HMAC SHA256)
[linux]$ curl -H "X-COINS-APIKEY: tAQfOrPIZAhym0qHISRt8EFvxPemdBm5j5WMlkm3Ke9aFp0EGWC2CGM8GHV4kCYW" -X POST 'https://$HOST/openapi/v1/order?symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC' -d 'quantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000&signature=885c9e3dd89ccd13408b25e6d54c2330703759d7494bea6dd5a3d1fd16ba3afa'

Note that in Example 3, the signature is different from the previous examples. Specifically, there is be no & character between GTC and quantity=1.

Public API Endpoints

Terminology

These terms will be used throughout the documentation, so it is recommended especially for new users to read to help their understanding of the API.

• base asset refers to the asset that is the quantity of a symbol. For the symbol BTCUSDT, BTC would be the base asset.
• quote asset refers to the asset that is the price of a symbol. For the symbol BTCUSDT, USDT would be the quote asset.

ENUM definitions

Symbol status:

• TRADING
• BREAK (ongoing)
• CANCEL_ONLY (ongoing)

Order status:

Order types:

• LIMIT
• MARKET
• LIMIT_MAKER
• STOP_LOSS
• STOP_LOSS_LIMIT
• TAKE_PROFIT
• TAKE_PROFIT_LIMIT

Order Response Type (newOrderRespType):

• ACK

• RESULT

• FULL

Order side:

• BUY
• SELL

Anti self-trading behaviour(stpFlag):

Time in force (timeInForce):

This sets how long an order will be active before expiration.

Kline/Candlestick chart intervals:

m -> minutes; h -> hours; d -> days; w -> weeks; M -> months

• 1m
• 3m
• 5m
• 15m
• 30m
• 1h
• 2h
• 4h
• 6h
• 8h
• 12h
• 1d
• 3d
• 1w
• 1M

General endpoints

Test connectivity

GET /openapi/v1/ping

Test connectivity to the Rest API.

Weight: 1

Parameters: NONE

Response:

{}

Check server time

GET /openapi/v1/time

Test connectivity to the Rest API and get the current server time.

Weight: 1

Parameters: NONE

Response:

{
  "serverTime": 1538323200000
}

Get user ip

GET /openapi/v1/user/ip

Get the user ip.

Weight: 1

Parameters: NONE

Response:

{
  "ip": "57.181.16.43"
}

Exchange information

GET /openapi/v1/exchangeInfo

Current exchange trading rules and symbol information

Weight: 1

Parameters:

Response:

{
  "timezone": "UTC",
  "serverTime": 1538323200000,
  "exchangeFilters": [],
  "symbols": [
    {
      "symbol": "ETHBTC",
      "status": "TRADING",
      "baseAsset": "ETH",
      "baseAssetPrecision": 8,
      "quoteAsset": "BTC",
      "quoteAssetPrecision": 8,
      "orderTypes": [
        "LIMIT",
        "MARKET",
        "LIMIT_MAKER",
        "STOP_LOSS_LIMIT",
        "STOP_LOSS",
        "TAKE_PROFIT_LIMIT",
        "TAKE_PROFIT"
      ],
      "filters": [
        {
          "filterType": "PRICE_FILTER",
          "minPrice": "0.00000100",
          "maxPrice": "100000.00000000",
          "tickSize": "0.00000100"
        },
        {
          "filterType": "LOT_SIZE",
          "minQty": "0.00100000",
          "maxQty": "100000.00000000",
          "stepSize": "0.00100000"
        },
        {
          "filterType": "NOTIONAL",
          "minNotional": "0.00100000"
        },
        {
          "filterType": "MIN_NOTIONAL",
          "minNotional": "0.00100000"
        },
        {
          "filterType": "MAX_NUM_ORDERS",
          "maxNumOrders": 200
        },
        {
          "filterType": "MAX_NUM_ALGO_ORDERS",
          "maxNumAlgoOrders": 5
        }
      ]
    }
  ]
}

Wallet endpoints

All Coins’ Information (USER_DATA)

GET /openapi/wallet/v1/config/getall  (HMAC SHA256)

Get information of coins (available for deposit and withdraw) for user.

Weight(IP): 10

Parameters:

Response:

[
    {
        "coin": "ETH",
        "name": "ETH",
        "depositAllEnable": true,
        "withdrawAllEnable": true,
        "free": "1.9144",
        "locked": "0.0426",
        "networkList": [
            {
                "addressRegex": "0x([0-9a-fA-F]){40}",
                "memoRegex": "^[0-9A-Za-z\\-_]{1,120}$",
                "network": "ETH",
                "name": "ERC20",
                "depositEnable": true,
                "minConfirm": 8,
                "unLockConfirm": 12,
                "withdrawDesc": "1234567890",
                "withdrawEnable": true,
                "withdrawFee": "0",
                "withdrawIntegerMultiple": "0.00000001",
                "withdrawMax": "1",
                "withdrawMin": "0.001",
                "sameAddress": false
            }
        ],
        "legalMoney": false
    }
  ]

Deposit Address (USER_DATA)

GET /openapi/wallet/v1/deposit/address  (HMAC SHA256)

Fetch deposit address with network.

Weight(IP): 10

Parameters:

Response:

{
    "coin": "ETH",
    "address": "0xfe98628173830bf79c59f04585ce41f7de168784",
    "addressTag": ""
}

Withdraw(USER_DATA)

POST /openapi/wallet/v1/withdraw/apply  (HMAC SHA256)

Submit a withdraw request.

Weight(UID): 100

Parameters:

• Please notice coin/network/address/addressTag combination MUST be in withdraw address whitelist, it is needed to setup the withdraw address whitelist before doing this api call.

Response:

{
  "id":"459165282044051456"
}

Deposit History (USER_DATA)

GET /openapi/wallet/v1/deposit/history  (HMAC SHA256)

Fetch deposit history.

Weight(IP): 2

Parameters:

• Please notice the default startTime and endTime to make sure that time interval is within 0-90 days.

• If both startTime and endTime are sent, time between startTime and endTime must be less than 90 days.

Response:

[
    {
        "id": "d_769800519366885376",
        "amount": "0.001",
        "coin": "BNB",
        "network": "BNB",
        "status": 0,
        "address": "bnb136ns6lfw4zs5hg4n85vdthaad7hq5m4gtkgf23",
        "addressTag": "101764890",
        "txId": "98A3EA560C6B3336D348B6C83F0F95ECE4F1F5919E94BD006E5BF3BF264FACFC",
        "insertTime": 1661493146000,
        "confirmNo": 10,
    },
    {
        "id": "d_769754833590042625",
        "amount":"0.5",
        "coin":"IOTA",
        "network":"IOTA",
        "status":1,
        "address":"SIZ9VLMHWATXKV99LH99CIGFJFUMLEHGWVZVNNZXRJJVWBPHYWPPBOSDORZ9EQSHCZAMPVAPGFYQAUUV9DROOXJLNW",
        "addressTag":"",
        "txId":"ESBFVQUTPIWQNJSPXFNHNYHSQNTGKRVKPRABQWTAXCDWOAKDKYWPTVG9BGXNVNKTLEJGESAVXIKIZ9999",
        "insertTime":1599620082000,
        "confirmNo": 20,
    }
]

Withdraw History (USER_DATA)

GET /openapi/wallet/v1/withdraw/history  (HMAC SHA256)

Fetch withdraw history.

Weight(IP): 2

Parameters:

• Please notice the default startTime and endTime to make sure that time interval is within 0-90 days.

• If both startTime and endTime are sent, time between startTime and endTime must be less than 90 days.

• If withdrawOrderId is sent, time between startTime and endTime must be less than 7 days.

• If withdrawOrderId is sent, startTime and endTime are not sent, will return last 7 days records by default.

Response:

[
    {
        "id": "459890698271244288",
        "amount": "0.01",
        "transactionFee": "0",
        "coin": "ETH",
        "status": 1,
        "address": "0x386AE30AE2dA293987B5d51ddD03AEb70b21001F",
        "addressTag": "",
        "txId": "0x4ae2fed36a90aada978fc31c38488e8b60d7435cfe0b4daed842456b4771fcf7",
        "applyTime": 1673601139000,
        "network": "ETH",
        "withdrawOrderId": "thomas123",
        "info": "",
        "confirmNo": 100
    },
    {
        "id": "451899190746456064",
        "amount": "0.00063",
        "transactionFee": "0.00037",
        "coin": "ETH",
        "status": 1,
        "address": "0x386AE30AE2dA293987B5d51ddD03AEb70b21001F",
        "addressTag": "",
        "txId": "0x62690ca4f9d6a8868c258e2ce613805af614d9354dda7b39779c57b2e4da0260",
        "applyTime": 1671695815000,
        "network": "ETH",
        "withdrawOrderId": "",
        "info": "",
        "confirmNo": 100
    }
]

Transfers (USER_DATA)

POST /openapi/transfer/v3/transfers

This endpoint is used to transfer funds between two accounts.

Weight: 50

Parameters:

Request:

{
  "account": "1451431230880900352",
  "target_address": "christina@coins.ph",
  "amount": "1232"
}

Response:

{
  "transfer":
    {
      "id": "1451431230880900352",
      "status": "success",//status enum: pending,success,failed
      "account": "90dfg03goamdf02fs",
      "target_address": "testsub@gmail.com",
      "amount": "1",
      "exchange": "1",
      "payment": "23094j0amd0fmag9agjgasd",
      "client_transfer_id": "1487573639841995271",
      "message": "example",
      "errorMessage":""//Error message returned when transfer fails, eg: Insufficient balance
     }
}

Account information (USER_DATA)

GET /openapi/v1/account (HMAC SHA256)

GET current account information.

Weight: 10

Parameters:

Response:

{
   "accountType":"SPOT",
   "canDeposit":true,
   "canTrade":true,
   "canWithdraw":true,
   "balances":[
      {
         "asset":"BTC",
         "free":"0",
         "locked":"0"
      },
      {
         "asset":"ETH",
         "free":"0.000731",
         "locked":"0"
      },
      {
         "asset":"USDT",
         "free":"0.4918",
         "locked":"0"
      }
   ],
   "token":"USD",
   "daily":{
      "cashInLimit":"100000",
      "cashInRemaining":"100000",
      "cashOutLimit":"100000",
      "cashOutRemaining":"100000",
      "totalWithdrawLimit":"100000",
      "totalWithdrawRemaining":"100000"
   },
   "monthly":{
      "cashInLimit":"3000000",
      "cashInRemaining":"3000000",
      "cashOutLimit":"3000000",
      "cashOutRemaining":"3000000",
      "totalWithdrawLimit":"3000000",
      "totalWithdrawRemaining":"3000000"
   },
   "annually":{
      "cashInLimit":"36500000",
      "cashInRemaining":"36500000",
      "cashOutLimit":"36500000",
      "cashOutRemaining":"36500000",
      "totalWithdrawLimit":"36500000",
      "totalWithdrawRemaining":"36499970.98"
   },
   "updateTime":1715308392448
}

Market Data endpoints

Order book

GET /openapi/quote/v1/depth

Weight:

Adjusted based on the limit:

Parameters:

Caution: setting limit=0 can return 200 records.

Response:

[PRICE, QTY]

{
  "lastUpdateId": 1027024,
  "bids": [
    [
      "4.90000000",   // PRICE
      "331.00000000"  // QTY
    ],
    [
      "4.00000000",
      "431.00000000"
    ]
  ],
  "asks": [
    [
      "4.00000200",  // PRICE
      "12.00000000"  // QTY
    ],
    [
      "5.10000000",
      "28.00000000"
    ]
  ]
}

Recent trades list

GET /openapi/quote/v1/trades

Get recent trades (up to last 60).

Weight: 1

Parameters:

Response:

[
  {
    "id": 28457,
    "price": "4.00000100",
    "qty": "12.00000000",
    "quoteQty": "48.000012",
    "time": 1499865549590,
    "isBuyerMaker": true,
    "isBestMatch": true
  }
]

Kline/Candlestick data

GET /openapi/quote/v1/klines

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

Weight: 1

Parameters:

• If startTime and endTime are not sent, the most recent klines are returned.

Response:

[
  [
    1499040000000,      // Open time
    "0.01634790",       // Open
    "0.80000000",       // High
    "0.01575800",       // Low
    "0.01577100",       // Close
    "148976.11427815",  // Volume
    1499644799999,      // Close time
    "2434.19055334",    // Quote asset volume
    308,                // Number of trades
    "1756.87402397",    // Taker buy base asset volume
    "28.46694368"       // Taker buy quote asset volume
  ]
]

24hr ticker price change statistics

GET /openapi/quote/v1/ticker/24hr

24 hour price change statistics. Careful when accessing this with no symbol.

Weight:

Parameters:

• Parameter symbol and symbols cannot be used in combination.If neither parameter is sent, tickers for all symbols will be returned in an array.Examples of accepted format for the symbols parameter: [“BTCUSDT”,”BNBUSDT”] and not case sensitive

Response:

{
  "symbol": "BNBBTC",
  "priceChange": "-94.99999800",
  "priceChangePercent": "-95.960",
  "weightedAvgPrice": "0.29628482",
  "prevClosePrice": "0.10002000",
  "lastPrice": "4.00000200",
  "lastQty": "200.00000000",
  "bidPrice": "4.00000000",
  "bidQty": "100.00000000",
  "askPrice": "4.00000200",
  "askQty": "100.00000000",
  "openPrice": "99.00000000",
  "highPrice": "100.00000000",
  "lowPrice": "0.10000000",
  "volume": "8913.30000000",
  "quoteVolume": "15.30000000",
  "openTime": 1499783499040,
  "closeTime": 1499869899040,
  "firstId": 28385,   // first trade id
  "lastId": 28460,    // Last tradeId
  "count": 76         // Trade count
}

OR

[
  {
    "symbol": "BNBBTC",
    "priceChange": "-94.99999800",
    "priceChangePercent": "-95.960",
    "weightedAvgPrice": "0.29628482",
    "prevClosePrice": "0.10002000",
    "lastPrice": "4.00000200",
    "lastQty": "200.00000000",
    "bidPrice": "4.00000000",
    "bidQty": "100.00000000",
    "askPrice": "4.00000200",
    "askQty": "100.00000000",
    "openPrice": "99.00000000",
    "highPrice": "100.00000000",
    "lowPrice": "0.10000000",
    "volume": "8913.30000000",
    "quoteVolume": "15.30000000",
    "openTime": 1499783499040,
    "closeTime": 1499869899040,
    "firstId": 28385,   // First tradeId
    "lastId": 28460,    // Last tradeId
    "count": 76         // Trade count
  }
]

Symbol price ticker

GET /openapi/quote/v1/ticker/price

Latest price for a symbol or symbols.

Weight:

Parameters:

• Parameter symbol and symbols cannot be used in combination.If neither parameter is sent, prices for all symbols will be returned in an array.Examples of accepted format for the symbols parameter: [“BTCUSDT”,”BNBUSDT”] and not case sensitive

Response:

{
  "symbol": "LTCBTC",
  "price": "4.00000200"
}

OR

[
  {
    "symbol": "LTCBTC",
    "price": "4.00000200"
  },
  {
    "symbol": "ETHBTC",
    "price": "0.07946600"
  }
]

Symbol order book ticker

GET /openapi/quote/v1/ticker/bookTicker

Best price/qty on the order book for a symbol or symbols.

Weight:

Parameters:

• Parameter symbol and symbols cannot be used in combination.If neither parameter is sent, bookTickers for all symbols will be returned in an array.Examples of accepted format for the symbols parameter: [“BTCUSDT”,”BNBUSDT”] and not case sensitive

Response:

{
  "symbol": "LTCBTC",
  "bidPrice": "4.00000000",
  "bidQty": "431.00000000",
  "askPrice": "4.00000200",
  "askQty": "9.00000000"
}

OR

[
  {
    "symbol": "LTCBTC",
    "bidPrice": "4.00000000",
    "bidQty": "431.00000000",
    "askPrice": "4.00000200",
    "askQty": "9.00000000"
  },
  {
    "symbol": "ETHBTC",
    "bidPrice": "0.07946700",
    "bidQty": "9.00000000",
    "askPrice": "100000.00000000",
    "askQty": "1000.00000000"
  }
]

Current average price

GET /openapi/quote/v1/avgPrice

Current average price for a symbol.

Weight: 1

Parameters:

Response:

{
  "mins": 5,
  "price": "9.35751834"
}

Cryptoasset trading pairs

GET /openapi/v1/pairs

a summary on cryptoasset trading pairs available on the exchange

Weight: 1

Parameters:

None

Response:

[
  {
    "symbol": "LTCBTC",
    "quoteToken": "LTC",
    "baseToken": "BTC"
  },
  {
    "symbol": "BTCUSDT",
    "quoteToken": "BTC",
    "baseToken": "USDT"
  }
]

Spot Trading Endpoints

New order (TRADE)

POST /openapi/v1/order  (HMAC SHA256)

Send in a new order.

Weight: 1

Parameters:

Additional mandatory parameters based on type:

Trigger order price rules against market price for both MARKET and LIMIT versions:

• Price above market price: STOP_LOSS/STOP_LOSS_LIMIT BUY, TAKE_PROFIT/TAKE_PROFIT_LIMIT SELL
• Price below market price: STOP_LOSS/STOP_LOSS_LIMIT SELL, TAKE_PROFIT/TAKE_PROFIT_LIMIT BUY

Response ACK:

{
  "symbol": "BCHUSDT",
  "orderId": 1202289462787244800,
  "clientOrderId": "165806007267756",
  "transactTime": 1656900365976
}

Response RESULT:

{
    "symbol": "BCHUSDT",
    "orderId": 1202289462787244800,
    "clientOrderId": "165806007267756",
    "transactTime": 1656900365976,
    "price": "1",
    "origQty": "101",
    "executedQty": "101",
    "cummulativeQuoteQty": "101",
    "status": "FILLED",
    "timeInForce": "GTC",
    "type": "LIMIT",
    "side": "SELL",
    "stopPrice": "0",
    "origQuoteOrderQty": "0"
}

Response FULL:

{
    "symbol": "BCHUSDT",
    "orderId": 1202289462787244800,
    "clientOrderId": "165806007267756",
    "transactTime": 1656900365976,
    "price": "1",
    "origQty": "101",
    "executedQty": "101",
    "cummulativeQuoteQty": "101",
    "status": "FILLED",
    "timeInForce": "GTC",
    "type": "LIMIT",
    "side": "SELL",
    "stopPrice": "0",
    "origQuoteOrderQty": "0"
    "fills": [
        {
            "price": "2",
            "qty": "100",
            "commission": "0.01",
            "commissionAsset": "USDT",
            "tradeId": "1205027741844507648"
        },
        {
            "price": "1",
            "qty": "1",
            "commission": "0.005",
            "commissionAsset": "USDT",
            "tradeId": "1205027331347975169"
        }
    ]
}

Test new order (TRADE)

POST /openapi/v1/order/test (HMAC SHA256)

Test new order creation and signature/recvWindow long. Creates and validates a new order but does not send it into the matching engine.

Weight: 1

Parameters:

Same as POST /openapi/v1/order

Response:

{}

Query order (USER_DATA)

GET /openapi/v1/order (HMAC SHA256)

Check an order’s status.

Weight: 2

Parameters:

Notes:

• Either orderId or origClientOrderId must be sent. If both parameters are sent, orderId takes precedence. A list will be returned for orders with identical clientOrderId.

Response Single Order:

{
    'clientOrderId': 'test5678',
    'cummulativeQuoteQty': '3946.87326',
    'executedQty': '0.001',
    'isWorking': False,
    'orderId': 1799249051008066560,
    'origQty': '0.001',
    'origQuoteOrderQty': '3946.87326',
    'price': '0',
    'side': 'BUY',
    'status': 'FILLED',
    'stopPrice': '0',
    'symbol': 'BTCPHP',
    'time': 1729223201090,
    'timeInForce': 'GTC',
    'type': 'MARKET',
    'updateTime': 1729223201201
}

Response Order List:

[
    {
        'clientOrderId': 'test5678',
        'cummulativeQuoteQty': '3946.87326',
        'executedQty': '0.001',
        'isWorking': False,
        'orderId': 1799249051008066560,
        'origQty': '0.001',
        'origQuoteOrderQty': '3946.87326',
        'price': '0',
        'side': 'BUY',
        'status': 'FILLED',
        'stopPrice': '0',
        'symbol': 'BTCPHP',
        'time': 1729223201090,
        'timeInForce': 'GTC',
        'type': 'MARKET',
        'updateTime': 1729223201201
    },
    {
        'clientOrderId': 'test5678',
        'cummulativeQuoteQty': '127.24738',
        'executedQty': '2.21',
        'isWorking': False,
        'orderId': 1799253321187025920,
        'origQty': '2.21',
        'origQuoteOrderQty': '127.24738',
        'price': '0',
        'side': 'BUY',
        'status': 'FILLED',
        'stopPrice': '0',
        'symbol': 'USDCPHP',
        'time': 1729223710134,
        'timeInForce': 'GTC',
        'type': 'MARKET',
        'updateTime': 1729223710186
    }
]

Cancel order (TRADE)

DELETE /openapi/v1/order  (HMAC SHA256)

Cancel an active order.

Weight: 1

Parameters:

Notes:

• Either orderId or origClientOrderId must be sent. If both parameters are sent, orderId takes precedence.

Response:

{
  "symbol": "BCHBUSD",
  "orderId": 1205324142243592448,
  "clientOrderId": "165830718862761",
  "price": "2",
  "origQty": "10",
  "executedQty": "8",
  "cummulativeQuoteQty": "16",
  "status": "CANCELED",
  "timeInForce": "GTC",
  "type": "LIMIT",
  "side": "SELL",
  "stopPrice": "0",
  "origQuoteOrderQty": "0"
}

Cancel All Open Orders on a Symbol (TRADE)

DELETE /openapi/v1/openOrders  (HMAC SHA256)

Cancels all active orders on a symbol.

Weight: 1

Parameters:

Response:

[
    {
        "symbol": "BTCUSDT",
        "orderId": 1200757068661824000,
        "clientOrderId": "165787739706155",
        "price": "19999",
        "origQty": "0.01",
        "executedQty": "0",
        "cummulativeQuoteQty": "0",
        "status": "CANCELED",
        "timeInForce": "GTC",
        "type": "LIMIT",
        "side": "BUY",
        "stopPrice": "0",
        "origQuoteOrderQty": "0"
    },
    {
        "symbol": "BTCUSDT",
        "orderId": 1200760572449167872,
        "clientOrderId": "165787781474653",
        "price": "19999",
        "origQty": "0.01",
        "executedQty": "0",
        "cummulativeQuoteQty": "0",
        "status": "CANCELED",
        "timeInForce": "GTC",
        "type": "LIMIT",
        "side": "BUY",
        "stopPrice": "0",
        "origQuoteOrderQty": "0"
    },
    {
        "symbol": "BTCUSDT",
        "orderId": 1200760629206489600,
        "clientOrderId": "165787782151456",
        "price": "19999",
        "origQty": "0.01",
        "executedQty": "0",
        "cummulativeQuoteQty": "0",
        "status": "CANCELED",
        "timeInForce": "GTC",
        "type": "LIMIT",
        "side": "BUY",
        "stopPrice": "0",
        "origQuoteOrderQty": "0"
    }
]

Current open orders (USER_DATA)

GET /openapi/v1/openOrders  (HMAC SHA256)

GET all open orders on a symbol. Careful when accessing this with no symbol.

Weight: 10

Parameters:

Response:

[
    {
        "symbol": "BTCUSDT",
        "orderId": 1200757068661824000,
        "clientOrderId": "165787739706155",
        "price": "19999",
        "origQty": "0.01",
        "executedQty": "0",
        "cummulativeQuoteQty": "0",
        "status": "NEW",
        "timeInForce": "GTC",
        "type": "LIMIT",
        "side": "BUY",
        "stopPrice": "0",
        "time": 1657877397079,
        "updateTime": 1657877397092,
        "isWorking": true,
        "origQuoteOrderQty": "0"
    },
    {
        "symbol": "BTCUSDT",
        "orderId": 1200760572449167872,
        "clientOrderId": "165787781474653",
        "price": "19999",
        "origQty": "0.01",
        "executedQty": "0",
        "cummulativeQuoteQty": "0",
        "status": "NEW",
        "timeInForce": "GTC",
        "type": "LIMIT",
        "side": "BUY",
        "stopPrice": "0",
        "time": 1657877814763,
        "updateTime": 1657877814776,
        "isWorking": true,
        "origQuoteOrderQty": "0"
    },
    {
        "symbol": "BTCUSDT",
        "orderId": 1200760629206489600,
        "clientOrderId": "165787782151456",
        "price": "19999",
        "origQty": "0.01",
        "executedQty": "0",
        "cummulativeQuoteQty": "0",
        "status": "NEW",
        "timeInForce": "GTC",
        "type": "LIMIT",
        "side": "BUY",
        "stopPrice": "0",
        "time": 1657877821529,
        "updateTime": 1657877821542,
        "isWorking": true,
        "origQuoteOrderQty": "0"
    }
]

History orders (USER_DATA)

GET /openapi/v1/historyOrders (HMAC SHA256)

GET all orders of the account; canceled, filled or rejected.

Weight: 10 with symbol, 40 when the symbol parameter is omitted;

Parameters:

Notes:

• If orderId is set, it will get orders >= that orderId. Otherwise most recent orders are returned.

Response:

[
    {
        "symbol": "BCHBUSD",
        "orderId": 1194453962386908672,
        "clientOrderId": "1657126007990",
        "price": "4.56",
        "origQty": "1",
        "executedQty": "1",
        "cummulativeQuoteQty": "4.56",
        "status": "FILLED",
        "timeInForce": "GTC",
        "type": "LIMIT",
        "side": "SELL",
        "stopPrice": "0",
        "time": 1657126008273,
        "updateTime": 1657126008357,
        "isWorking": false,
        "origQuoteOrderQty": "0"
    },
    {
        "symbol": "BCHBUSD",
        "orderId": 1194453774196830976,
        "clientOrderId": "165712598575253",
        "price": "0",
        "origQty": "0",
        "executedQty": "4",
        "cummulativeQuoteQty": "18",
        "status": "FILLED",
        "timeInForce": "GTC",
        "type": "MARKET",
        "side": "BUY",
        "stopPrice": "0",
        "time": 1657126008363,
        "updateTime": 1657126008402,
        "isWorking": false,
        "origQuoteOrderQty": "18"
    },
    {
        "symbol": "BCHBUSD",
        "orderId": 1194460299787314688,
        "clientOrderId": "1657126763487",
        "price": "0.46",
        "origQty": "1",
        "executedQty": "1",
        "cummulativeQuoteQty": "4.56",
        "status": "FILLED",
        "timeInForce": "GTC",
        "type": "LIMIT",
        "side": "SELL",
        "stopPrice": "0",
        "time": 1657126763736,
        "updateTime": 1657126763786,
        "isWorking": false,
        "origQuoteOrderQty": "0"
    }
]

Account trade list (USER_DATA)

GET /openapi/v1/myTrades  (HMAC SHA256)

Get trades for a specific account and symbol.

Weight: 10

Parameters:

Notes:

• If fromId (tradeId) is set, it will get id (tradeId) >= that fromId (tradeId). Otherwise most recent trades are returned.

Response:

[
  {
    "symbol": "BNBBTC",
    "id": 1194460299787317856,
    "orderId": 1194453774196830977,
    "price": "4.00000100",
    "qty": "12.00000000",
    "quoteQty": "48.000012",
    "commission": "10.10000000",
    "commissionAsset": "BNB",
    "time": 1499865549590,
    "isBuyer": true,
    "isMaker": false,
    "isBestMatch": true
  }
]

Trade Fee (USER_DATA)

GET /openapi/v1/asset/tradeFee (HMAC SHA256)

Fetch trade fee

Weight: 1

Parameters:

Response:

  [
    {
      "symbol": "BTCUSDT",
      "makerCommission": "0.002",
      "takerCommission": "0.003"
    },
    {
      "symbol": "ETHUSDT",
      "makerCommission": "0.001",
      "takerCommission": "0.001"
    }
  ]

User data stream endpoints

Specifics on how user data streams work is in another document(user-data-stream.md).

Start user data stream (USER_STREAM)

POST /openapi/v1/userDataStream

Start a new user data stream. The stream will close after 60 minutes unless a keepalive is sent.

Weight: 1

Parameters:

None

Response:

{
  "listenKey": "xDqtskqOciCzRashthgjTHBcymasBBShEEzPiXgOGEujviYWCuyYwcPDVPeezJOT"
}

Keepalive user data stream (USER_STREAM)

PUT /openapi/v1/userDataStream

Keepalive a user data stream to prevent a time out. User data streams will close after 60 minutes. It’s recommended to send a ping about every 30 minutes.

Weight: 1

Parameters:

Response:

{}

Close user data stream (USER_STREAM)

DELETE /openapi/v1/userDataStream

Close out a user data stream.

Weight: 1

Parameters:

Response:

{}

Filters

Filters define trading rules on a symbol or an exchange. Filters come in two forms: symbol filters and exchange filters.

Symbol filters

PRICE_FILTER

The PRICE_FILTER defines the price rules for a symbol. There are 3 parts:

• minPrice defines the minimum price/stopPrice allowed.
• maxPrice defines the maximum price/stopPrice allowed.
• tickSize defines the intervals that a price/stopPrice can be increased/decreased by.

In order to pass the price filter, the following must be true for price/stopPrice:

• price >= minPrice
• price <= maxPrice
• (price-minPrice) % tickSize == 0

/exchangeInfo format:

  {
    "filterType": "PRICE_FILTER",
    "minPrice": "0.00000100",
    "maxPrice": "100000.00000000",
    "tickSize": "0.00000100"
  }

PERCENT_PRICE

The PERCENT_PRICE filter defines valid range for a price based on the weighted average of the previous trades. avgPriceMins is the number of minutes the weighted average price is calculated over.

In order to pass the percent price, the following must be true for price:

• price <= weightedAveragePrice * multiplierUp
• price >= weightedAveragePrice * multiplierDown

/exchangeInfo format:

  {
    "filterType": "PERCENT_PRICE",
    "multiplierUp": "1.3000",
    "multiplierDown": "0.7000",
    "avgPriceMins": 5
  }

PERCENT_PRICE_SA

The PERCENT_PRICE_SA filter defines valid range for a price based on the simple average of the previous trades. avgPriceMins is the number of minutes the simple average price is calculated over.

In order to pass the percent_price_sa, the following must be true for price:

• price <= simpleAveragePrice * multiplierUp
• price >= simpleAveragePrice * multiplierDown

/exchangeInfo format:

  {
    "filterType": "PERCENT_PRICE_SA",
    "multiplierUp": "1.3000",
    "multiplierDown": "0.7000",
    "avgPriceMins": 5
  }

PERCENT_PRICE_BY_SIDE

The PERCENT_PRICE_BY_SIDE filter defines the valid range for the price based on the last price of the symbol. There is a different range depending on whether the order is placed on the BUY side or the SELL side.

Buy orders will succeed on this filter if:

• Order price <= bidMultiplierUp * lastPrice
• Order price >= bidMultiplierDown * lastPrice

Sell orders will succeed on this filter if:

• Order Price <= askMultiplierUp * lastPrice
• Order Price >= askMultiplierDown * lastPrice

/exchangeInfo format:

  {
    "filterType": "PERCENT_PRICE_BY_SIDE",
    "bidMultiplierUp": "1.2",
    "bidMultiplierDown": "0.2",
    "askMultiplierUp": "1.5",
    "askMultiplierDown": "0.8",
  }

PERCENT_PRICE_INDEX

The PERCENT_PRICE_INDEX filter defines valid range for a price based on the index price which is calculated based on several exhanges in the market by centain rule. (indexPrice wobsocket pushing will be available in future)

In order to pass the percent_price_index, the following must be true for price:

• price <= indexPrice * multiplierUp
• price >= indexPrice * multiplierDown

/exchangeInfo format:

  {
    "filterType": "PERCENT_PRICE_INDEX",
    "multiplierUp": "1.3000",
    "multiplierDown": "0.7000",
  }

PERCENT_PRICE_ORDER_SIZE

The PERCENT_PRICE_ORDER_SIZE filter is used to determine whether the execution of an order would cause the market price to fluctuate beyond the limit price, and if so, the order will be rejected.

In order to pass the percent_price_order_size, the following must be true:

• A buy order needs to meet: the market price after the order get filled <askPrice * multiplierUp
• A sell order needs to meet: the market price after the order get filled >bidPrice * multiplierDown

/exchangeInfo format:

  {
    "filterType": "PERCENT_PRICE_ORDER_SIZE",
    "multiplierUp": "1.3000",
    "multiplierDown": "0.7000"
  }

STATIC_PRICE_RANGE

The STATIC_PRICE_RANGE filter defines a static valid range for the price.

In order to pass the static_price_range, the following must be true for price:

• price <= priceUp
• price >= priceDown

/exchangeInfo format:

  {
    "filterType": "STATIC_PRICE_RANGE",
    "priceUp": "520",
    "priceDown": "160"
  }

LOT_SIZE

The LOT_SIZE filter defines the quantity (aka “lots” in auction terms) rules for a symbol. There are 3 parts:

• minQty defines the minimum quantity allowed.
• maxQty defines the maximum quantity allowed.
• stepSize defines the intervals that a quantitycan be increased/decreased by.

In order to pass the lot size, the following must be true for quantity:

• quantity >= minQty
• quantity <= maxQty
• (quantity-minQty) % stepSize == 0

/exchangeInfo format:

  {
    "filterType": "LOT_SIZE",
    "minQty": "0.00100000",
    "maxQty": "99999999.00000000",
    "stepSize": "0.00100000"
  }

NOTIONAL

The NOTIONAL filter defines the acceptable notional range allowed for an order on a symbol.

In order to pass this filter, the notional (price * quantity) has to pass the following conditions:

• price * quantity <= maxNotional
• price * quantity >= minNotional

/exchangeInfo format:

{
   "filterType": "NOTIONAL",
   "minNotional": "10.00000000",
   "maxNotional": "10000.00000000"
}

MAX_NUM_ORDERS

The MAX_NUM_ORDERS filter defines the maximum number of orders an account is allowed to have open on a symbol. Note that both triggered “algo” orders and normal orders are counted for this filter.

/exchangeInfo format:

  {
    "filterType": "MAX_NUM_ORDERS",
    "maxNumOrders": 200
  }

MAX_NUM_ALGO_ORDERS

The MAX_ALGO_ORDERS filter defines the maximum number of untriggered “algo” orders an account is allowed to have open on a symbol. “Algo” orders are STOP_LOSS, STOP_LOSS_LIMIT, TAKE_PROFIT, and TAKE_PROFIT_LIMIT orders.

/exchangeInfo format:

  {
    "filterType": "MAX_NUM_ALGO_ORDERS",
    "maxNumAlgoOrders": 5
  }

Exchange Filters

None for now

Sub-account endpoints

Query Sub-account List (For Master Account)

Applies to master accounts only.

GET /openapi/v1/sub-account/list

Weight: 1

Parameters:

Response:

{
  "subAccounts": [
    {
      "createTime": "1689744671462",
      "email": "testsub@gmail.com",
      "isFreeze": false
    },
    {
      "createTime": "1689744700710",
      "email": "testsub2@gmail.com",
      "isFreeze": false
    }
  ],
 "total": 2
}

Create a Virtual Sub-account(For Master Account)

This interface currently supports the creation of virtual sub-accounts (maximum 30).

POST /openapi/v1/sub-account/create

Weight: 1

Parameters:

Response:

{
  "email": "testsub@gmail.com",
  "createTime": 1689744700710,
  "isFreeze": false
}

Query Sub-account Assets (For Master Account)

Query detailed balance information of a sub-account via the master account (applies to master accounts only).

GET /openapi/v1/sub-account/asset

Weight: 1

Parameters:

Response:

{
  "balances": [
    {
      "asset": "BTC",
      "free": "0.1",
      "locked": "0"
    },
    {
      "asset": "ETH",
      "free": "0.1",
      "locked": "0"
    }
  ]
}

Universal Transfer (For Master Account)

Master account can initiate a transfer from any of its sub-accounts to the master account, or from the master account to any sub-account.

POST /openapi/v1/sub-account/transfer/universal-transfer

Weight: 1

Parameters:

• Transfer from master account by default if fromEmail is not sent.
• Transfer to master account by default if toEmail is not sent.
• Specify at least one of fromEmail and toEmail.

Response:

{
  "clientTransferId": "1487573639841995271",
  "result": true//true:success,false:failed
}

Transfer to Master (For Sub-account)

Sub-account can initiate a transfer from itself to the master account.

POST /openapi/v1/sub-account/transfer/sub-to-master

Weight: 1

Parameters:

Response:

{
  "clientTransferId": "1487573639841995271",
  "result": true//true:success,false:failed
}

Query Universal Transfer History (For Master Account)

Applies to master accounts only. If startTime and endTime are not sent, this will return records of the last 30 days by default.

GET /openapi/v1/sub-account/transfer/universal-transfer-history

Weight: 1

Parameters:

• fromEmail and toEmail cannot be sent at the same time.
• Return fromEmail equal master account email by default.
• The query time period must be less than 30 days.
• If startTime and endTime not sent, return records of the last 30 days by default.

Response:

{
  "result": [
    {
      "clientTranId": "1",
      "fromEmail": "testsub@gmail",
      "toEmail": "testsub1@gmail",
      "asset": "BTC",
      "amount": "0.1",
      "createdAt": 1689744700710,
      "status": "success"//success,pending,failed
    }
  ],
  "total": 1
}

Sub-account Transfer History (For Sub-account)

Applies to sub-accounts only. If startTime and endTime are not sent, this will return records of the last 30 days by default.

GET /openapi/v1/sub-account/transfer/sub-history

Weight: 1

Parameters:

• If type is not sent, the records of type 2: transfer out will be returned by default.
• If startTime and endTime are not sent, the recent 30-day data will be returned.

Response:

{
  "result": [
    {
      "clientTranId": "1",
      "fromEmail": "testsub@gmail",
      "toEmail": "testsub1@gmail",
      "asset": "BTC",
      "amount": "0.1",
      "createdAt": 1689744700710,
      "status": "success"//success,pending,failed
    }
  ],
  "total": 1
}

Get IP Restriction for a Sub-account API Key (For Master Account)

Query detailed IPs for a sub-account API key.

GET /openapi/v1/sub-account/apikey/ip-restriction

Weight: 1

Parameters:

Response:

{
  "apikey": "k5V49ldtn4tszj6W3hystegdfvmGbqDzjmkCtpTvC0G74WhK7yd4rfCTo4lShf",
  "ipList": [
    "8.8.8.8"
  ],
  "ipRestrict": true,
  "role": "2,3,4,5,6",//0:READ_ONLY, 2:TRADE_ONLY, 3:CONVERT_ONLY, 4:CRYPTO_WALLET_ONLY, 5:FIAT_ONLY, 6:ACCOUNT_ONLY
  "updateTime": 1689744700710
}

Add IP Restriction for Sub-Account API key (For Master Account)

POST /openapi/v1/sub-account/apikey/add-ip-restriction

Weight: 1

Parameters:

Response:

{
  "apikey": "k5V49ldtn4tszj6W3hystegdfvmGbqDzjmkCtpTvC0G74WhK7yd4rfCTo4lShf",
  "ipList": [
    "8.8.8.8"
  ],
  "ipRestrict": true,
  "role": "2,3,4,5,6",//0:READ_ONLY, 2:TRADE_ONLY, 3:CONVERT_ONLY, 4:CRYPTO_WALLET_ONLY, 5:FIAT_ONLY, 6:ACCOUNT_ONLY
  "updateTime": 1689744700710
}

Delete IP List For a Sub-account API Key (For Master Account)

POST /openapi/v1/sub-account/apikey/delete-ip-restriction

Weight: 1

Parameters:

Response:

{
  "apikey": "k5V49ldtn4tszj6W3hystegdfvmGbqDzjmkCtpTvC0G74WhK7yd4rfCTo4lShf",
  "ipList": [
    "8.8.8.8"
  ],
  "ipRestrict": true,
  "role": "2,3,4,5,6",//0:READ_ONLY, 2:TRADE_ONLY, 3:CONVERT_ONLY, 4:CRYPTO_WALLET_ONLY, 5:FIAT_ONLY, 6:ACCOUNT_ONLY
  "updateTime": 1689744700710
}

Get Sub-account Deposit Address(For Master Account)

GET /openapi/v1/sub-account/wallet/deposit/address

Fetch sub account deposit address with network.

Weight: 10

Parameters:

Response:

{
  "coin": "ETH",
  "address": "0xfe98628173830bf79c59f04585ce41f7de168784",
  "addressTag": ""
}

Get Sub-account Deposit History(For Master Account)

GET /openapi/v1/sub-account/wallet/deposit/history

Fetch deposit history.

Weight(IP): 2

Parameters: