General REST API Information

  • The base URL: https://api-adapter.backend.currency.com
  • The base URL, demo account: https://demo-api-adapter.backend.currency.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 in the first version (v1) of our API. In the second API version (v2) Hong Kong markets became also available.
  • The list of assets available for leverage trading within API can be found here.
  • When setting market, limit or stop orders and mentioning a bigger amount of precision numbers than required for a specific token a round_down logic is true. The allowed precision can be found in the exchangeInfo request response, quotePrecision parameter.
  • When mentioning a bigger amount of precision numbers for the price parameter a round_up logic is used. The allowed precision can be found in the exchangeInfo request response, quotePrecision parameter.

Please, refer to the REST API part within the Swagger in order to get the information needed. 

Troubleshooting

Change log

July, 2021: the second version (v2) of the REST API was added with a complete list of the leverage instruments available there, please note that for the demo accounts only the first version (v1) is available; added the /tradingPositionsHistory endpoint which provides an opportunity to view the historic trades info per symbol.

June, 2021: added an opportunity to use the demo account with the first version (v1) of the REST API; added the showZeroBalance parameter for the /account endpoint in order clients could turn on or off the zero balances depiction in the response.

May, 2021: added an opportunity to view data on the Heiken-Ashi type of the bars in the /klines endpoint.

December, 2020: fixed error message texts when setting the wrong stopLoss or takeProfit values, updated request limits for openOrders endpoint which is now equal to 5 requests per second instead of 10, fixed accountId parameter values wrong representation.

November, 2020: changing of the HTTP codes logic and representing them in the right way, unification of error messages between Rest and Websocket APIs, /updateTradingOrder endpoint fix, got rid off unnecessary parameters in /myTrades, /aggTrades, /order and /updateTradingOrder endpoints, fixed an inability to set expireTimestamp parameter for exchange limit orders.

June, 2020: 50 tokenised assets and cryptocurrency market pairs were added and became available for trading in the leverage mode within our API.

May, 2020: a new STOP order type was added. It is available within the ‘leverage’ trading mode; added an opportunity to use ‘leverage’ trading mode with BTC/USD; ETH/USD; Crude Oil (XTI.cx); Brent Oil (XBR.cx); S&P 500 (SPXm.cx); LTC/USD; Gold (XAUm.cx); EUR/USD; Tesla (TSLA.cx); XRP/USD market pairs.

March, 2020: SIGNED Endpoint Examples for POST /api/v1/order were changed in accordance to the ERL encoding requirements; responses descriptions were added in the GET/api/v1/klines and GET/api/v1/aggTrades parts of the API documentation.

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 Currency.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.
  • 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 typeDescription
NONEEndpoint can be accessed freely
TRADEEndpoint requires sending a valid API-Key and signature
USER_DATAEndpoint requires sending a valid API-Key and signature
USER_STREAMEndpoint requires sending a valid API-Key
MARKET_DATAEndpoint 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:

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.

KeyValue
apiKeyvmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A
secretKeyNhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j
ParameterValue
symbolLTC/BTC
sideBUY
typeLIMIT
timeInforceGTC
quantity1
price0,1
recvWindow5000
timestamp1499827319559

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

Example 1: As a request body

requestBody:

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.currency.com/api/v1/order' -d
'symbol=LTC%2FBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=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.currency.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.

KeyValue
apiKeyvmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A
secretKeyNhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j
ParameterValue
symbolBTC/USD_LEVERAGE
sideBUY
typeMARKET
timeInforceGTC
quantity0.01
quantity2
accountId2376109060084932
takeProfit8000
stopLoss6000
recvWindow60000
timestamp1586942164000

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

Example 1: As a request body

requestBody:

symbol=BTC%2FUSD_LEVERAGE&side=BUY&type=MARKET&timeInForce=GTC&quantity=0.01&leverage=2&accountId=2376109060084932&takeProfit=8000&stopLoss=6000&recvWindow=60000&timestamp=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&timestamp=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.currency.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&timestamp=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&timestamp=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&timestamp=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.currency.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&timestamp=1586942164000&signature=05fc9fd19c2b1a11215025c5dfa56da2204b04181add67670d4f92049b439f7b

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

/klines 'type' parameter:

  • heiken-ashi