General API

General API Information

  • The base endpoint is: https://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.

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

[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

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'

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

Order side (side):

  • BUY
  • SELL

Time in force (timeInForce):

  • GTC

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 }, ] }

Order Book

GET /api/v1/depth

Parameters:

Name Type Mandatory Description
symbol STRING YES
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
startTime LONG NO Timestamp in ms to get aggregate trades from INCLUSIVE.
endTime LONG NO Timestamp in ms to get aggregate trades from INCLUSIVE.
limit INT NO Default 500; max 1000.

If both startTime and endTime are sent, time between startTime and endTime must be less than 1 hour.

Response:
[ { "A":1582595833, // Aggregate tradeId "P":"8980.4", // Price "Q":"0.0", // Quantity "F":1582595833, // First tradeId "L":1582595833, // Last tradeId "T":1580204505793, // Timestamp "m":false, // Was the buyer the maker? "M":true // Was the trade the best price match? } ]

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

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, "firstId": 0, // First tradeId "lastId": 0, // Last tradeId "count": 0 // Trade count } OR { "symbol": "LTC/USD", "priceChange": null, "priceChangePercent": null, "weightedAvgPrice": "59.29", "prevClosePrice": null, "lastPrice": "59.23", "lastQty": "220.0", "bidPrice": "59.23", "askPrice": "59.35", "openPrice": null, "highPrice": null, "lowPrice": null, "volume": null, "quoteVolume": "432.18", "openTime": 0, "closeTime": 0, "firstId": 0, // First tradeId "lastId": 0, // Last tradeId "count": 0 // Trade count }

New Order (TRADE)

POST /api/v1/order (HMAC SHA256)

Send in a new order.

Parameters:

Name Type Mandatory Description
symbol STRING YES
side ENUM YES
type ENUM YES
timeInForce ENUM NO
quantity DECIMAL YES
price DECIMAL NO
newOrderRespType ENUM NO Set the response JSON. ACK, RESULT, or FULL; MARKET and LIMIT order types default to FULL, all other orders default to ACK.
recvWindow LONG NO The value cannot be greater than 60000.
timestamp LONG YES

Additional mandatory parameters based on type:

Type Additional mandatory parameters
LIMIT MARKET
timeInForce, price quoteOrderQty
Response ACK:
{ "clientOrderId" : "00000000-0000-0000-0000-00000002cac2" }
Response RESULT:
{ "clientOrderId" : "00000000-0000-0000-0000-00000002cac8", "status" : "FILLED", "cummulativeQuoteQty" : null, "executedQty" : "0.001", "type" : "MARKET", "transactTime" : 1577446511069, "origQty" : "0.001", "symbol" : "BTC/USD", "timeInForce" : "FOK", "side" : "BUY", "price" : "7173.6186", "orderId" : "00000000-0000-0000-0000-00000002cac8" }
Response FULL:
{ "orderId" : "00000000-0000-0000-0000-00000002ca43", "price" : "7183.3881", "clientOrderId" : "00000000-0000-0000-0000-00000002ca43", "side" : "BUY", "cummulativeQuoteQty" : null, "origQty" : "0.001", "transactTime" : 1577445603997, "type" : "MARKET", "executedQty" : "0.001", "status" : "FILLED", "fills" : [ { "price" : "7169.05", "qty" : "0.001", "commissionAsset" : "dUSD", "commission" : "0" } ], "timeInForce" : "FOK", "symbol" : "BTC/USD" }

Cancel Order (TRADE)

DELETE /api/v1/order (HMAC SHA256)

Cancel an active order.

Parameters:

Name Type Mandatory Description
symbol STRING YES
orderId LONG NO
origClientOrderId STRING NO
recvWindow LONG NO The value cannot be greater than 60000.
timestamp LONG YES
Response:
{ "symbol": "LTC/BTC", "origClientOrderId": "myOrder1", "orderId": "4", "orderListId": -1, "clientOrderId": "cancelMyOrder1", "price": "2.00000000", "origQty": "1.00000000", "executedQty": "0.00000000", "cummulativeQuoteQty": "0.00000000", "status": "CANCELED", "timeInForce": "GTC", "type": "LIMIT", "side": "BUY" }

Current Open Orders (USER_DATA)

GET /api/v1/openOrders (HMAC SHA256)

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

Parameters:

Name Type Mandatory Description
symbol STRING YES
recvWindow LONG NO The value cannot be greater than 60000.
timestamp LONG YES

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

Response:
[ { "symbol": "LTC/BTC", "orderId": "1", "orderListId": -1, "clientOrderId": "myOrder1", "price": "0.1", "origQty": "1.0", "executedQty": "0.0", "cummulativeQuoteQty": "0.0", "status": "NEW", "timeInForce": "GTC", "type": "LIMIT", "side": "BUY", "stopPrice": "0.0", "time": 1499827319559, "updateTime": 1499827319559, "isWorking": true, "origQuoteOrderQty": "0.000000" } ]

Account Information (USER_DATA)

GET /api/v1/account (HMAC SHA256)

Get current account information.

Parameters:

Name Type Mandatory Description
recvWindow LONG NO The value cannot be greater than 60000.
timestamp LONG YES
Response:
{ "makerCommission": 15, "takerCommission": 15, "buyerCommission": 0, "sellerCommission": 0, "canTrade": true, "canWithdraw": true, "canDeposit": true, "updateTime": 123456789, "accountType": "SPOT", "balances": [ { "asset": "BTC", "free": "4723846.89208129", "locked": "0.00000000" }, { "asset": "LTC", "free": "4763368.68006011", "locked": "0.00000000" } ] }

Account Trade List (USER_DATA)

GET /api/v1/myTrades (HMAC SHA256)

Get trades for a specific account and symbol.

Parameters:

Name Type Mandatory Description
symbol STRING YES
startTime LONG NO
endTime LONG NO
limit INT NO Default Value: 500; Max Value: 1000.
recvWindow LONG NO The value cannot be greater than 60000.
timestamp LONG YES
Response:
[ { "symbol": "BTC/USD", "orderId": "100234", "orderListId": -1, "price": "4.00000100", "qty": "12.00000000", "quoteQty": "48.000012", "commission": "10.10000000", "commissionAsset": "BTC", "time": 1499865549590, "isBuyer": true, "isMaker": false } ]

Error Codes

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

The error JSON payload:
{ "code":-1121, "msg":"Invalid symbol." }

10XX - General Server or Network issues

-1000 UNKNOWN
An unknown error occured while processing the request.
-1001 DISCONNECTED
Internal error; unable to process your request. Please try again.
-1002 UNAUTHORIZED
You are not authorized to execute this request.
-1003 TOO_MANY_REQUESTS
Too many requests queued.
-1006 UNEXPECTED_RESP
An unexpected response was received from the message bus. Execution status unknown.
-1007 TIMEOUT
Timeout waiting for response from backend server. Send status unknown; execution status unknown.
-1014 UNKNOWN_ORDER_COMPOSITION
Unsupported order combination.
-1015 TOO_MANY_ORDERS
Too many new orders.
Too many new orders; current limit is %s orders per %s.
-1016 SERVICE_SHUTTING_DOWN
This service is no longer available.
-1020 UNSUPPORTED_OPERATION
This operation is not supported.
-1021 INVALID_TIMESTAMP
Timestamp for this request is outside of the recvWindow.
Timestamp for this request was 1000ms ahead of the server's time.
-1022 INVALID_SIGNATURE
Signature for this request is not valid.
-1099 Not found, authenticated, or authorized
This replaces error code -1999.

11XX - Request Issues

-1100 ILLEGAL_CHARS
Illegal characters found in a parameter.
Illegal characters found in parameter '%s'; legal range is '%s'.
-1101 TOO_MANY_PARAMETERS
Too many parameters sent for this endpoint.
Too many parameters; expected '%s' and received '%s'.
Duplicate values for a parameter detected.
-1102 MANDATORY_PARAM_EMPTY_OR_MALFORMED
A mandatory parameter was not sent, was empty/null, or malformed.
Mandatory parameter '%s' was not sent, was empty/null, or malformed.
Param '%s' or '%s' must be sent, but both were empty/null!
-1103 UNKNOWN_PARAM
An unknown parameter was sent.
-1104 UNREAD_PARAMETERS
Not all sent parameters were read.
Not all sent parameters were read; read '%s' parameter(s) but was sent '%s'.
-1105 PARAM_EMPTY
A parameter was empty.
Parameter '%s' was empty.
-1106 PARAM_NOT_REQUIRED
A parameter was sent when not required.
Parameter '%s' sent when not required.
-1111 BAD_PRECISION
Precision is over the maximum defined for this asset.
-1112 NO_DEPTH
No orders on book for symbol.
-1114 TIF_NOT_REQUIRED
TimeInForce parameter sent when not required.
-1115 INVALID_TIF
Invalid timeInForce.
-1116 INVALID_ORDER_TYPE
Invalid orderType.
-1117 INVALID_SIDE
Invalid side.
-1118 EMPTY_NEW_CL_ORD_ID
New client order ID was empty.
-1119 EMPTY_ORG_CL_ORD_ID
Original client order ID was empty.
-1120 BAD_INTERVAL
Invalid interval.
-1121 BAD_SYMBOL
Invalid symbol.
-1125 INVALID_LISTEN_KEY
This listenKey does not exist.
-1127 MORE_THAN_XX_HOURS
Lookup interval is too big.
More than %s hours between startTime and endTime.
-1128 OPTIONAL_PARAMS_BAD_COMBO
Combination of optional parameters invalid.
-1130 INVALID_PARAMETER
Invalid data sent for a parameter.
Data sent for parameter '%s' is not valid.
-1131 BAD_RECV_WINDOW
recvWindow must be less than 60000
-2010 NEW_ORDER_REJECTED
NEW_ORDER_REJECTED
-2011 CANCEL_REJECTED
CANCEL_REJECTED
-2013 NO_SUCH_ORDER
Order does not exist.
-2014 BAD_API_KEY_FMT
API-key format invalid.
-2015 REJECTED_MBX_KEY
Invalid API-key, IP, or permissions for action.
-2016 NO_TRADING_WINDOW
No trading window could be found for the symbol. Try ticker/24hrs instead.

Messages for -1010 ERROR_MSG_RECEIVED, -2010 NEW_ORDER_REJECTED, and -2011 CANCEL_REJECTED

This code is sent when an error has been returned by the matching engine. The following messages which will indicate the specific error:

Error message Description
"Unknown order sent." The order (by either orderId, clientOrderId, origClientOrderId) could not be found.
"Duplicate order sent." The clientOrderId is already in use.
"Market is closed." The symbol is not trading.
"Account has insufficient balance for requested action." Not enough funds to complete the action.
"Market orders are not supported for this symbol." MARKET is not enabled on the symbol.
"Stop loss orders are not supported for this symbol." STOP_LOSS is not enabled on the symbol.
"Stop loss limit orders are not supported for this symbol." STOP_LOSS_LIMIT is not enabled on the symbol.
"Take profit orders are not supported for this symbol." TAKE_PROFIT is not enabled on the symbol.
"Take profit limit orders are not supported for this symbol." TAKE_PROFIT_LIMIT is not enabled on the symbol.
"Price * QTY is zero or less." price * quantity is too low.
"This action disabled is on this account." Contact customer support; some actions have been disabled on the account.
"Unsupported order combination." The orderType, timeInForce, stopPrice combination isn't allowed.
"Order would trigger immediately." The order's stop price is not valid when compared to the last traded price.
"Cancel order is invalid. Check origClientOrderId and orderId." No origClientOrderId or orderId was sent in.
"Order would immediately match and take." LIMIT_MAKER order type would immediately match and trade, and not be a pure maker order.
"The relationship of the prices for the orders is not correct." The rules are:
SELL Orders: Limit Price > Last Price > Stop Price
BUY Orders: Limit Price < Last Price < Stop Price