General API

General API Information

  • The base endpoint is: https://api-adapter.backend.cryptocurrencieshub.com
  • All endpoints return either a JSON object or array.
  • Data is returned in ascending order. Oldest first, newest last.
  • All time and timestamp related fields are in milliseconds.
  • All the tokenised assets except companies tokens, tokenized bonds, tokens “KARMA.cx” and tokenised assets from Hong Kong markets are available within our API.
  • The list of assets available for leverage trading within API can be found here.

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 cryptocurrencieshub.com 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.

Sample Payload below:

Response:
{ "code": -1121, "msg": "Invalid symbol." }
  • Specific error codes and messages are defined in Error Codes.

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. You may mix parameters between both the query string and request body if you wish to do so.
  • Parameters may be sent in any order.
  • If a parameter sent in both the query string and request body, the query string parameter will be used.

Endpoint security type

  • Each endpoint has a security type that determines the how you will interact with it. This is stated next to the NAME of the endpoint.
    • If no security type is stated, assume the security type is NONE.
  • API-keys are passed into the Rest API via the X-MBX-APIKEY header.
  • API-keys and secret-keys are case sensitive.
  • API-keys can be configured to only access certain types of secure endpoints. For example, one API-key could be used for TRADE only, while another API-key can access everything except for TRADE routes.
  • By default, API-keys can access all secure routes.
Security type Description
NONE Endpoint can be accessed freely.
TRADE Endpoint requires sending a valid API-Key and signature.
USER_DATA Endpoint requires sending a valid API-Key and signature.
USER_STREAM Endpoint requires sending a valid API-Key.
MARKET_DATA Endpoint requires sending a valid API-Key.
  • TRADE and USER_DATA endpoints are SIGNED endpoints.

SIGNED (TRADE, USER_DATA, AND MARGIN) 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.

Timing security

  • A SIGNED endpoint also requires a parameter, timestamp, to be sent which should be the millisecond timestamp of when the request was created and sent.
  • An additional parameter, recvWindow, may be sent to specify the number of milliseconds after timestamp the request is valid for. If recvWindow is not sent, it defaults to 5000.

The logic is as follows:

Response:
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.

It is recommended to use a small recvWindow of 5000 or less! The max cannot go beyond 60,000!

SIGNED Endpoint Examples for POST /api/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.

Key Value
apiKey vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A
secretKey NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j
Parameter Value
symbol LTC/BTC
side BUY
type LIMIT
timeInforce GTC
quantity 1
price 0,1
recvWindow 5000
timestamp 1499827319559

Example 1: As a request body

Please note that some symbols like '/' should be url encoded and transformed into the following combination '%2F'.

Request body:

symbol=LTC%2FBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559

HMAC SHA256 signature

[linux]$ echo -n "symbol=LTC%2FBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j" (stdin)= ebec6528b2beb508b2417fa33453a4ad28c1aae8097bb243caa60d0524036f50

curl command:

(HMAC SHA256) [linux]$ curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://api-adapter.backend.cryptocurrencieshub.com/api/v1/order' -d 'symbol=LTC%2FBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000×tamp=1499827319559&signature=ebec6528b2beb508b2417fa33453a4ad28c1aae8097bb243caa60d0524036f50'

Example 2: As a query string

queryString:

symbol=LTC%2FBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559

HMAC SHA256 signature:

[linux]$ echo -n "symbol=LTC%2FBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j" (stdin)= ebec6528b2beb508b2417fa33453a4ad28c1aae8097bb243caa60d0524036f50

curl command:

(HMAC SHA256) [linux]$ curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://api-adapter.backend.cryptocurrencieshub.com/api/v1/order?symbol=LTC%2FBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559&signature=ebec6528b2beb508b2417fa33453a4ad28c1aae8097bb243caa60d0524036f50'

SIGNED Endpoint Examples for POST /api/v1/order (leverage trading mode)

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.

Key Value
apiKey vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A
secretKey NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j
Parameter Value
symbol BTC/USD_LEVERAGE
side BUY
type MARKET
timeInforce GTC
quantity 0.01
leverage 2
accountId 2376109060084932
takeProfit 8000
stopLoss 6000
recvWindow 60000
timestamp 1586942164000

Please note that some symbols like '/' should be url encoded and transformed into the following combination '%2F'.

Example 1: As a request body

Request body:

symbol=BTC%2FUSD_LEVERAGE&side=BUY&type=MARKET&timeInForce=GTC&quantity=0.01&leverage=2&accountId=2376109060084932&takeProfit=8000&stopLoss=6000&recvWindow=60000×tamp=1586942164000

HMAC SHA256 signature

[linux]$ echo -n "symbol=BTC%2FUSD_LEVERAGE&side=BUY&type=MARKET&timeInForce=GTC&quantity=0.01&leverage=2&accountId=2376109060084932&takeProfit=8000&stopLoss=6000&recvWindow=60000×tamp=1586942164000" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j" (stdin)= 05fc9fd19c2b1a11215025c5dfa56da2204b04181add67670d4f92049b439f7b

curl command:

(HMAC SHA256) [linux]$ curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://api-adapter.backend.cryptocurrencieshub.com/api/v1/order' -d 'symbol=BTC%2FUSD_LEVERAGE&side=BUY&type=MARKET&timeInForce=GTC&quantity=0.01&leverage=2&accountId=2376109060084932&takeProfit=8000&stopLoss=6000&recvWindow=60000×tamp=1586942164000'

Example 2: As a query string

queryString:

symbol=BTC%2FUSD_LEVERAGE&side=BUY&type=MARKET&timeInForce=GTC&quantity=0.01&leverage=2&accountId=2376109060084932&takeProfit=8000&stopLoss=6000&recvWindow=60000×tamp=1586942164000

HMAC SHA256 signature:

[linux]$ echo -n "symbol=BTC%2FUSD_LEVERAGE&side=BUY&type=MARKET&timeInForce=GTC&quantity=0.01&leverage=2&accountId=2376109060084932&takeProfit=8000&stopLoss=6000&recvWindow=60000×tamp=1586942164000" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j" (stdin)= 05fc9fd19c2b1a11215025c5dfa56da2204b04181add67670d4f92049b439f7b

curl command:

(HMAC SHA256) [linux]$ curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://api-adapter.backend.cryptocurrencieshub.com/api/v1/order?symbol=BTC%2FUSD_LEVERAGE&side=BUY&type=MARKET&timeInForce=GTC&quantity=0.01&leverage=2&accountId=2376109060084932&takeProfit=8000&stopLoss=6000&recvWindow=60000×tamp=1586942164000&signature=05fc9fd19c2b1a11215025c5dfa56da2204b04181add67670d4f92049b439f7b

Public API Endpoints

Terminology

  • base asset refers to the asset that is the quantity of a symbol.
  • quote asset refers to the asset that is the price of a symbol.

ENUM definitions

Order status (status):

  • NEW
  • FILLED
  • CANCELED
  • REJECTED

Order types (orderTypes, type):

  • LIMIT
  • MARKET
  • STOP

Order side (side):

  • BUY
  • SELL

Time in force (timeInForce):

  • GTC
  • IOC
  • FOK

Kline/Candlestick chart intervals:

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

  • 1m
  • 5m
  • 15m
  • 30m
  • 1h
  • 4h
  • 1d
  • 1w

General endpoints

Check Server Time

GET /api/v1/time

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

Parameters:

NONE.

Response:
{ "serverTime": 1499827319559 }

Exchange Information

GET /api/v1/exchangeInfo

Current exchange trading rules and symbol information.

Parameters:

NONE.

Response:
{ "timezone": "UTC", "serverTime": 1577178958852, "rateLimits": [ { //These are defined in the `ENUM definitions` // section under `Rate Limiters (rateLimitType)`. //All limits are optional } ], "symbols": [ { "symbol": "DPW", "name":"Deutsche Post", "status": "TRADING", "baseAsset": "DPW", "baseAssetPrecision": 3, "quoteAsset": "EUR", "quotePrecision": 3, "orderTypes": [ "LIMIT", "MARKET" ], "icebergAllowed": false, "filters": [], "marginTradingAllowed": true, "spotTradingAllowed": true }, ] }

Market Data endpoints

Order Book

GET /api/v1/depth

Parameters:

Name Type Mandatory Description
symbol STRING YES ‘Symbol’ parameter value from the exchangeInfo endpoint.
limit INT NO Default 100; max 1000. Valid limits:[5, 10, 20, 50, 100, 500, 1000, 5000]
Response:
{ "lastUpdateId": 1027024, "asks": [ [ "4.00000200", // PRICE "12.00000000" // QTY ] ], "bids": [ [ "4.00000000", // PRICE "431.00000000" // QTY ] ] }

Compressed/Aggregate Trades List

GET /api/v1/aggTrades

Get compressed, aggregate trades. Trades that fill at the same time, from the same order, with the same price will have the quantity aggregated.

Parameters:

Name Type Mandatory Description
symbol STRING YES ‘Symbol’ parameter value from the exchangeInfo endpoint.
limit INT NO Default 500; max 1000.
Response:
[ { "a":1582595833, // Aggregate tradeId "p":"8980.4", // Price "q":"0.0", // Quantity (should be ignored) "T":1580204505793, // Timestamp "m":false, // Was the buyer the maker? } ]

Kline/Candlestick Data

GET /api/v1/klines

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

Parameters:

Name Type Mandatory Description
symbol STRING YES ‘Symbol’ parameter value from the exchangeInfo endpoint.
interval ENUM YES
startTime LONG NO
endTime LONG NO
limit INT NO Default 500; max 1000.

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. ] ]

24hr Ticker Price Change Statistics

GET /api/v1/ticker/24hr

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

Parameters:

Name Type Mandatory Description
symbol STRING NO ‘Symbol’ parameter value from the exchangeInfo endpoint.

If the symbol is not sent, tickers for all symbols will be returned in an array.

Response:
{ "symbol": "LTC/USD", "priceChange": "0.88", "priceChangePercent": "1.49", "weightedAvgPrice": "59.29", "prevClosePrice": "58.37", "lastPrice": "59.25", "lastQty": "220.0", "bidPrice": "59.25", "askPrice": "59.32", "openPrice": "58.37", "highPrice": "61.39", "lowPrice": "58.37", "volume": "22632", "quoteVolume": "440.0", "openTime": 1580169600000, "closeTime": 1580205307222, } OR { "symbol": "LTC/USD", "weightedAvgPrice": "45.08", "lastPrice": "44.99", "lastQty": "60.0", "bidPrice": "44.99", "askPrice": "45.16", "highPrice": "46.61", "lowPrice": "43.61", "volume": "665.01", "quoteVolume": "30178.1538", "openTime": 1589727691000, "closeTime": 1589814091000 }

New Order (TRADE)

POST /api/v1/order (HMAC SHA256)

To create a market or limit order in the exchange trading mode, and market, limit or stop order in the leverage trading mode.
*Please note that to open an order within the ‘leverage’ trading mode symbolLeverage should be used and additional accountId parameter should be mentioned in the request (‘New leverage trade’ section).

Send in a new order.

Parameters:

Name Type Mandatory Description
symbol STRING YES ‘Symbol’ parameter value from the exchangeInfo endpoint.
side ENUM YES
type ENUM YES
timeInForce ENUM NO
quantity DECIMAL YES
price DECIMAL NO
newOrderRespType ENUM NO Set the response JSON. RESULT, or FULL; MARKET order type default to FULL. LIMIT order type can be only RESULT.
recvWindow LONG NO The value cannot be greater than 60000.
timestamp LONG YES

Additional mandatory parameters based on type:

Type Additional mandatory parameters
LIMIT timeInForce, price
Response RESULT:
{ "symbol": "BTC/USD", "orderId": "00000000-0000-0000-0000-0000000c028d", "clientOrderId": "00000000-0000-0000-0000-0000000c028d", "transactTime": 1589879478020, "price": "9797.05500000", "origQty": "0.01", "executedQty": "0.01", "status": "FILLED", "timeInForce": "FOK", "type": "MARKET", "side": "BUY" }
Response FULL:
{ "symbol": "BTC/USD", "orderId": "00000000-0000-0000-0000-0000000c0263", "clientOrderId": "00000000-0000-0000-0000-0000000c0263", "transactTime": 1589878206426, "price": "9825.66210000", "origQty": "0.01", "executedQty": "0.01", "status": "FILLED", "timeInForce": "FOK", "type": "MARKET", "side": "BUY", "fills": [ { "price": "9807.05", "qty": "0.01", "commission": "0", "commissionAsset": "dUSD" } ] }

New leverage trade (TRADE)

POST /api/v1/order (HMAC SHA256)

Send in a new leverage trade or order.

Parameters:

Name Type Mandatory Description
symbol STRING YES In order to mention the right symbolLeverage it should be checked with the ‘symbol’ parameter value from the exchangeInfo endpoint. In case ‘symbol’ has currencies in its name then the following format should be used: ‘BTC%2FUSD_LEVERAGE’. In case ‘symbol’ has only an asset name then for the leverage trading mode the following format is correct: ‘Oil%20-%20Brent.’.
side ENUM YES
type ENUM YES
timeInForce ENUM NO
quantity DECIMAL YES
leverage INTEGER NO
accountId LONG YES
takeProfit DECIMAL NO
stopLoss DECIMAL NO
price DECIMAL NO
guaranteedStopLoss DECIMAL NO
recvWindow LONG NO
timestamp LONG YES

Additional mandatory parameters based on type:

Type Additional mandatory parameters
LIMIT timeInForce, price
Response RESULT:
{ "symbol": "BTC/USD_LEVERAGE", "orderId": "00a02503-0079-54c4-0000-000040670063", "clientOrderId": "03f3f76f-b497-4b5c-995c-747141b81314", "transactTime": 1586951469082, "price": "6788.90000000", "origQty": "0.01", "executedQty": "0.01", "status": "FILLED", "timeInForce": "IOC", "type": "MARKET", "side": "BUY", "stopLoss": -788.9, "guaranteedStopLoss": false, "takeProfit": 1211.1 }

Leverage settings (USER_DATA)

GET /api/v1/leverageSettings (HMAC SHA256)

General leverage settings can be seen.

Parameters:

Name Type Mandatory Description
symbol STRING YES In order to mention the right symbolLeverage it should be checked with the ‘symbol’ parameter value from the exchangeInfo endpoint. In case ‘symbol’ has currencies in its name then the following format should be used: ‘BTC%2FUSD_LEVERAGE’. In case ‘symbol’ has only an asset name then for the leverage trading mode the following format is correct: ‘Oil%20-%20Brent.’.
recvWindow LONG NO The value cannot be greater than 60000.
timestamp LONG YES
Response:
{ "values": [ 2, 5, 10, 20, 50, 100 ], // the possible leverage sizes; "value": 20 // depicts a default leverage size which will be set in case you don’t mention the ‘leverage’ parameter in the corresponding requests. }

Edit leverage position (TRADE)

POST /api/v1/updateTradingPosition (HMAC SHA256)

To edit current leverage trade by changing stop loss and take profit levels.

Parameters:

Name Type Mandatory Description
positionId LONG YES
takeProfit DECIMAL NO One of these parameters should be mentioned.
stopLoss DECIMAL NO
guaranteedStopLoss BOOLEAN NO
recvWindow LONG NO The value cannot be greater than 60000.
LONG YES timestamp
Response:
{ "requestId": 242040, "state": "PROCESSED" }

Edit leverage order (TRADE)

POST /api/v1/updateTradingOrder

Edit current leverage orders by changing take profit and stop loss levels.

Parameters:

Name Type Mandatory Description
orderId LONG YES
type ENUM YES