NAV Navbar
Exchange API
javascript python c# java

Introduction

Welcome to the Crypto.com Exchange V2 API reference documentation.

The Crypto.com Exchange provides developers with a REST and websocket API.

The majority of API calls are available across both mediums in the same request and response formats, allowing smooth transition and a reduced learning curve between the two platforms.

Where applicable, all API calls come with detailed information on both the request and response parameters, all in a simple JSON format, as well as sample requests and code snippets in JavaScript, Python, C#, and Java which can be viewed on the right.

Documentation for the old REST API V1 can be found here.

Change Logs

Generating the API Key

Before sending any requests, you'll need to generate a new API key.

This can be done in the Exchange website under User Center - API.

After generating the key, there are two things you need to carefully note down:

API Key and Secret are randomly generated by the system and can not be modified.

You can optionally specify a whitelist of IP addresses when generating the API Key.

If specified, the API can only be used from the whitelisted IP addresses.

Rate Limits

REST API

For authenticated calls, rate limits are per API method, per API key:

Method Limit
private/create-order
private/cancel-order
private/cancel-all-orders
15 requests per 100ms each
private/get-order-detail 30 requests per 100ms
private/get-trades 1 requests per second
private/get-order-history 1 requests per second
All others 3 requests per 100ms each

For public market data calls, rate limits are per API method, per IP address:

Method Limit
public/get-book
public/get-ticker
public/get-trades
100 requests per second each

Websocket

Websocket Limit
User API 150 requests per second
Market Data 100 requests per second

private/get-trades and private/get-order-history is rate limited at 5 requests per second on the Websocket

REST API Root Endpoint

REST API v1 and v2 have separate endpoints.

Future versions will share the same endpoint as v2, but with the version incremented.

Documentation for the old REST API V1 can be found here.

UAT Sandbox

REST API v2

https://uat-api.3ona.co/v2/{method}

REST API v1

https://uat-api.3ona.co/v1/{method}

Production

These production endpoints will be enabled from 15 June 2020 onwards

REST API v2

https://api.crypto.com/v2/{method}

REST API v1

https://api.crypto.com/v1/{method}

Websocket Root Endpoints

The Websocket is available across two servers -- the User API Websocket (for authenticated requests and subscriptions), and Market Data Websocket:

UAT Sandbox

Websocket (User API and Subscriptions)

wss://uat-stream.3ona.co/v2/user

Websocket (Market Data Subscriptions)

wss://uat-stream.3ona.co/v2/market

Production

These production endpoints will be enabled from 15 June 2020 onwards

Websocket (User API and Subscriptions)

wss://stream.crypto.com/v2/user

Websocket (Market Data Subscriptions)

wss://stream.crypto.com/v2/market

Common API Reference

Most of the APIs for REST and Websockets are shared, and follow the same request format and response, allowing users to easily switch between the two methods.

The Applies To section under each API allows you to see which platform supports the API.

Naming Conventions

Request Format

The following information applies to both REST API and websockets commands:

Name Type Required Description
id long N Request Identifier
Range: 0 to 9,223,372,036,854,775,807
Response message will contain the same id
method string Y The method to be invoked
params object N Parameters for the methods
api_key string Depends API key. See Digital Signature section
sig string Depends Digital signature. See Digital Signature section
nonce long Depends Current timestamp (milliseconds since the Unix epoch)
Required for cases where Digital Signatures are involved

Digital Signature

const crypto = require("crypto-js");

const signRequest = (request, apiKey, apiSecret) => {
  const { id, method, params, nonce } = request;

  const paramsString =
    params == null
      ? ""
      : Object.keys(params)
          .sort()
          .reduce((a, b) => {
            return a + b + params[b];
          }, "");

  const sigPayload = method + id + apiKey + paramsString + nonce;

  request.sig = crypto
    .HmacSHA256(sigPayload, apiSecret)
    .toString(crypto.enc.Hex);

  return request;
};

const apiKey = "token"; /* User API Key */
const apiSecret = "secretKey"; /* User API Secret */

let request = {
  id: 11,
  method: "private/get-order-detail",
  api_key: API_KEY,
  params: {
    order_id: 53287421324
  },
  nonce: 1587846358253,
};

const requestBody = JSON.stringify(signRequest(request, apiKey, apiSecret)));
import hmac
import hashlib
import json
import requests
import time

API_KEY = "API_KEY"
SECRET_KEY = "SECRET_KEY"

req = {
  "id": 11,
  "method": "private/get-order-detail",
  "api_key": API_KEY,
  "params": {
    "order_id": "337843775021233500",
  },
  "nonce": int(time.time() * 1000)
};

# First ensure the params are alphabetically sorted by key
paramString = ""

if "params" in req:
  for key in req['params']:
    paramString += key
    paramString += str(req['params'][key])

sigPayload = req['method'] + str(req['id']) + req['api_key'] + paramString + str(req['nonce'])

request['sig'] = hmac.new(
  bytes(str(SECRET_KEY), 'utf-8'),
  msg=bytes(sigPayload, 'utf-8'),
  digestmod=hashlib.sha256
).hexdigest()

using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Net;
using System.Security.Cryptography;
using System.Text;
using System.Threading.Tasks;
using System.Web;
using System.Net.WebSockets;

private const string API_KEY = "YOUR_API_KEY";
private const string API_SECRET = "YOUR_API_SECRET";

private static string GetSign (Dictionary Request)
{   
    Dictionary Params = Request.Params;

    // Ensure the params are alphabetically sorted by key        
    string ParamString = string.Join("", Params.Select(entry => $"{entry.Key}{entry.Value}"));

    string SigPayload = Request.method + Request.id + API_KEY + ParamString + Request.nonce;

    var hash = new HMACSHA256(API_SECRET);
    var ComputedHash = hash.ComputeHash(SigPayload);
    return ToHex(ComputedHash, false);
}
import com.fasterxml.jackson.annotation.JsonProperty;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.util.Map;

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class ApiRequestJson {
  private Long id;
  private String method;
  private Map<String, Object> params;
  private String sig;

  @JsonProperty("api_key")
  private String apiKey;

  private Long nonce;
}

//------------

import org.apache.commons.codec.binary.Hex;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Map;
import java.util.TreeMap;

public class SigningUtil {
  private static final String HMAC_SHA256 = "HmacSHA256";

  public static boolean verifySignature(ApiRequestJson apiRequestJson, String secret) {

    try {
      return genSignature(apiRequestJson, secret).equals(apiRequestJson.getSig());
    } catch (Exception e) {
      return false;
    }
  }

  public static String genSignature(ApiRequestJson apiRequestJson, String secret) throws NoSuchAlgorithmException, InvalidKeyException {
      final byte[] byteKey = secret.getBytes(StandardCharsets.UTF_8);
      Mac mac = Mac.getInstance(HMAC_SHA256);
      SecretKeySpec keySpec = new SecretKeySpec(byteKey, HMAC_SHA256);
      mac.init(keySpec);


      String paramsString = "";

      if (apiRequestJson.getParams() != null) {
        TreeMap<String, Object> params = new TreeMap<>(apiRequestJson.getParams());

        for (Map.Entry<String, Object> entry : params.entrySet()) {
          paramsString += entry.getKey() + entry.getValue();
        }
      }

      String sigPayload =
              apiRequestJson.getMethod()
                      + apiRequestJson.getId()
                      + apiRequestJson.getApiKey()
                      + paramsString
                      + (apiRequestJson.getNonce() == null ? "" : apiRequestJson.getNonce());

      byte[] macData = mac.doFinal(sigPayload.getBytes(StandardCharsets.UTF_8));

      return Hex.encodeHexString(macData);
  }

  public static ApiRequestJson sign(ApiRequestJson apiRequestJson, String secret) throws InvalidKeyException, NoSuchAlgorithmException {
    apiRequestJson.setSig(genSignature(apiRequestJson, secret));

    return apiRequestJson;
  }

  public static void main(String[] argv) throws InvalidKeyException, NoSuchAlgorithmException {
    ApiRequestJson apiRequestJson = ApiRequestJson.builder()
            .id(11L)
            .apiKey("token")
            .method("public/auth")
            .nonce(1589594102779L)
            .build();

    System.out.println(genSignature(apiRequestJson, "secretKey"));

    System.out.println(sign(apiRequestJson, "secretKey"));

  }
}

For REST API, only the private methods require a Digital Signature (as "sig") and API key (as "api_key") to be passed in. These private endpoints are only accessible by authenticated users.

For Websocket (User API), the public/auth command has to be invoked ONCE per session, with the Digital Signature (as "sig") and API key (as "api_key") as part of the request. Once authenticated, you will gain access to user-specific commands, and no longer need to use the pass in the Digital Signature and API key anymore for the duration of the session.

The authentication is based on the pairing of the API Key, along with the HMAC-SHA256 hash of the request parameters using the API Secret as the cryptographic key.

The algorithm for generating the HMAC-SHA256 signature is as follows:

Digital Signature Issues

Based on the language, and the way data-types are handled, the digital signature may be incorrectly calculated for certain values.

One known case is if parameters contain numbers, and the value passed in is a whole numbers that still has decimal suffixes, e.g. 8000.000 instead of 8000.

When the JSON request is sent to the server, the client (when parsing as JSON) may cast the number 8000.000 as 8000 automatically, which is what the server would see.

However, the digital signature may have been calculated using 8000.000 in the payload, which would result in a digital signature mismatch.

If this scenario happens in your case, there are three options:

Response Format

Name Type Description
id long Original request identifier
method string Method invoked
result object Result object
code int 0 for success, see below for full list
message string (optional) For server or error messages
original string (optional) Original request as a string, for error cases

Response and Reason Codes

These codes are shared by both the response, and the reason field for rejected orders.

Code HTTP Status Message Code Description
0 200 -- Success
10001 500 SYS_ERROR Malformed request, (E.g. not using application/json for REST)
10002 401 UNAUTHORIZED Not authenticated, or key/signature incorrect
10003 401 IP_ILLEGAL IP address not whitelisted
10004 400 BAD_REQUEST Missing required fields
10005 401 USER_TIER_INVALID Disallowed based on user tier
10006 429 TOO_MANY_REQUESTS Requests have exceeded rate limits
10007 400 INVALID_NONCE Nonce value differs by more than 30 seconds from server
10008 400 METHOD_NOT_FOUND Invalid method specified
10009 400 INVALID_DATE_RANGE Invalid date range
20001 400 DUPLICATE_RECORD Duplicated record
20002 400 NEGATIVE_BALANCE Insufficient balance
30003 400 SYMBOL_NOT_FOUND Invalid instrument_name specified
30004 400 SIDE_NOT_SUPPORTED Invalid side specified
30005 400 ORDERTYPE_NOT_SUPPORTED Invalid type specified
30006 400 MIN_PRICE_VIOLATED Price is lower than the minimum
30007 400 MAX_PRICE_VIOLATED Price is higher than the maximum
30008 400 MIN_QUANTITY_VIOLATED Quantity is lower than the minimum
30009 400 MAX_QUANTITY_VIOLATED Quantity is higher than the maximum
30010 400 MISSING_ARGUMENT Required argument is blank or missing
30013 400 INVALID_PRICE_PRECISION Too many decimal places for Price
30014 400 INVALID_QUANTITY_PRECISION Too many decimal places for Quantity
30016 400 MIN_NOTIONAL_VIOLATED The notional amount is less than the minimum
30017 400 MAX_NOTIONAL_VIOLATED The notional amount exceeds the maximum

Websocket Termination Codes

Code Description
1000 Normal disconnection by server, usually when the heartbeat isn't handled properly
1006 Abnormal disconnection
1013 Server restarting -- try again later

Error Response Format

Due to the asynchronous nature of websocket requests, a robust and consistent error response is crucial in order to match the response with the request.

To ensure API consistency for websocket error responses, if the id and method is omitted in the original request, id will have a value of -1 and method will have a value of ERROR.

The original request will be returned as an escaped string in the original field.

public/auth

Request Sample

{
    "id": 11,
    "method": "public/auth",
    "api_key": "api_key",
    "sig": "d0267b151db609885bad2e4f8ad07610f7913e166c35adaf5697d59a64e3755a",
    "nonce": :1587846358253
}

Response Sample

{
    "id":11,
    "method":"public/auth",
    "code":0
}

To access user-specific websocket methods, public/auth has to be invoked with a valid API key and Digital Signature (refer to the Digital Signature section).

REST API calls do NOT need to do this.

Request Params

Name Type Description
api_key string API key
sig string Digital Signature (see Digital Signature section)

Applies To:

Websocket (User API)

public/get-instruments

Request Sample

{
  "id":11,
  "method":"public/get-instruments",
  "nonce":1506584998239
}

Response Sample

{
  "id": 11,
  "method": "public/get-instruments",
  "code": 0,
  "result": {
    "instruments": [
      {
        "instrument_name": "ETH_CRO",
        "quote_currency": "CRO",
        "base_currency": "ETH",
        "price_decimals": 2,
        "quantity_decimals": 2
      },
      {
        "instrument_name": "CRO_BTC",
        "quote_currency": "BTC",
        "base_currency": "CRO",
        "price_decimals": 8,
        "quantity_decimals": 2
      }
    ]
  }
}

Provides information on all supported instruments (e.g. BTC_USDT)

For the websocket, as a public function, it can be called without authentication.

Applies To

REST Websocket (User API)

REST Method

GET

Response Attributes

An array of instruments, consisting of:

Name Type Description
instrument_name string e.g. BTC_USDT
quote_currency string e.g. USDT
base_currency string e.g. BTC
price_decimals integer Maximum decimal places for specifying price
quantity_decimals integer Maximum decimal places for specifying quantity

public/get-book

Request Sample

https://{URL}/v2/public/get-book?instrument_name=BTC_USDT&depth=10

Response Sample

{
  "code":0,
  "method":"public/get-book",
  "result":{
    "bids":[[9668.44,0.006325,1.0],[9659.75,0.006776,1.0],[9653.14,0.011795,1.0],[9647.13,0.019434,1.0],[9634.62,0.013765,1.0],[9633.81,0.021395,1.0],[9628.46,0.037834,1.0],[9627.6,0.020909,1.0],[9621.51,0.026235,1.0],[9620.83,0.026701,1.0]],
    "asks":[[9697.0,0.68251,1.0],[9697.6,1.722864,2.0],[9699.2,1.664177,2.0],[9700.8,1.824953,2.0],[9702.4,0.85778,1.0],[9704.0,0.935792,1.0],[9713.32,0.002926,1.0],[9716.42,0.78923,1.0],[9732.19,0.00645,1.0],[9737.88,0.020216,1.0]],
    "t":1591704180270
  }
}

Fetches the public order book for a particular instrument and depth

Request Params

Name Type Required Description
instrument_name string Y e.g. BTC_USDT, ETH_CRO, etc.
depth string N Number of bids and asks to return (up to 150)

Applies To

REST

REST Method

GET

Response Attributes

Name Type Description
bids array Bids array: [0] = Price, [1] = Quantity, [2] = Number of Orders
asks array Asks array: [0] = Price, [1] = Quantity, [2] = Number of Orders
t long Timestamp of the data

public/get-ticker

Request Sample

https://{URL}/v2/public/get-ticker?instrument_name=BTC_USDT

Response Sample

{
  "code":0,
  "method":"public/get-ticker",
  "result":{
    "data": [ 
      {"i":"CRO_BTC","b":0.00000890,"k":0.00001179,"a":0.00001042,"t":1591770793901,"v":14905879.59,"h":0.00,"l":0.00,"c":0.00},
      {"i":"EOS_USDT","b":2.7676,"k":2.7776,"a":2.7693,"t":1591770798500,"v":774.51,"h":0.05,"l":0.05,"c":0.00}, 
      {"i":"BCH_USDT","b":247.49,"k":251.73,"a":251.67,"t":1591770797601,"v":1.01693,"h":0.01292,"l":0.01231,"c":-0.00047}, 
      ...
      ...
      {"i":"ETH_USDT","b":239.92,"k":242.59,"a":240.30,"t":1591770798701,"v":0.97575,"h":0.01236,"l":0.01199,"c":-0.00018}, 
      {"i":"ETH_CRO","b":2693.11,"k":2699.84,"a":2699.55,"t":1591770795053,"v":95.680,"h":8.218,"l":7.853,"c":-0.050} 
    ] 
  }
}

Fetches the public tickers for an instrument (e.g. BTC_USDT).

instrument_name can be omitted to show tickers for all instruments

Request Params

Name Type Required Description
instrument_name string N e.g. BTC_USDT, ETH_CRO, etc. Omit for 'all'

Applies To

REST

REST Method

GET

Response Attributes

Name Type Description
i number Instrument Name, e.g. BTC_USDT, ETH_CRO, etc.
b number The current best bid price, null if there aren't any bids
k number The current best ask price, null if there aren't any asks
a number The price of the latest trade, null if there weren't any trades
t number Timestamp of the data
v number The total 24h traded volume
h number Price of the 24h highest trade
l number Price of the 24h lowest trade, null if there weren't any trades
c number 24-hour price change, null if there weren't any trades

public/get-trades

Request Sample

https://{URL}/v2/public/get-trades

Response Sample

{
  "code":0,
  "method":"public/get-trades",
  "result": [ 
    {"dataTime":1591710781947,"d":465533583799589409,"s":"BUY","p":2.96,"q":16.0,"t":1591710781946,"i":"ICX_CRO"}, 
    {"dataTime":1591707701899,"d":465430234542863152,"s":"BUY","p":0.007749,"q":115.0,"t":1591707701898,"i":"VET_USDT"}, 
    {"dataTime":1591710786155,"d":465533724976458209,"s":"SELL","p":25.676,"q":0.55,"t":1591710786154,"i":"XTZ_CRO"}, 
    {"dataTime":1591710783300,"d":465533629172286576,"s":"SELL","p":2.9016,"q":0.6,"t":1591710783298,"i":"XTZ_USDT"}, 
    {"dataTime":1591710784499,"d":465533669425626384,"s":"SELL","p":2.7662,"q":0.58,"t":1591710784498,"i":"EOS_USDT"}, 
    {"dataTime":1591710784700,"d":465533676120104336,"s":"SELL","p":243.21,"q":0.01647,"t":1591710784698,"i":"ETH_USDT"}, 
    {"dataTime":1591710786600,"d":465533739878620208,"s":"SELL","p":253.06,"q":0.00516,"t":1591710786598,"i":"BCH_USDT"}, 
    {"dataTime":1591710786900,"d":465533749959572464,"s":"BUY","p":0.9999,"q":0.2,"t":1591710786898,"i":"USDC_USDT"}, 
    {"dataTime":1591710787500,"d":465533770081010000,"s":"BUY","p":3.159,"q":1.65,"t":1591710787498,"i":"ATOM_USDT"}, 
    ...
    ...
  ] 
}

Fetches the public trades for a particular instrument

instrument_name can be omitted to show tickers for all instruments

Request Params

Name Type Required Description
instrument_name string N e.g. BTC_USDT, ETH_CRO, etc. Omit for 'all'

Applies To

REST

REST Method

GET

Response Attributes

Name Type Description
p number Trade price
q number Trade quantity
s string Side ("buy" or "sell")
d number Trade ID
t number Trade timestamp
dataTime long Reserved. Can be ignored

private/get-account-summary

Request Sample

{
    "id": 11,
    "method": "private/get-account-summary",
    "params": {
        "currency": "CRO"
    },
    "nonce": 1587523073344
}

// OR (for all currencies, omit currency, but ensure params still exists as {})

{
    "id": 11,
    "method": "private/get-account-summary",
    "params": {},
    "nonce": 1587523073344
}

Response Sample

{
    "id": 11,
    "method": "private/get-account-summary",
    "code": 0,
    "result": {
        "accounts": [
            {
                "balance": 99999999.905000000000000000,
                "available": 99999996.905000000000000000,
                "order": 3.000000000000000000,
                "stake": 0,
                "currency": "CRO"
            }
        ]
    }
}

Returns the account balance of a user for a particular token

Request Params

Name Type Required Description
currency string N Specific currency, e.g. CRO. Omit for 'all'

Omit the currency parameter for ALL currencies, but ensure you keep params: {} for API request consistency.

Applies To

REST Websocket (User API)

REST Method

POST

Response Attributes

An array of accounts, consisting of:

Name Type Description
balance number Total balance
available number Available balance (e.g. not in orders, or locked, etc.)
order number Balance locked in orders
stake number Balance locked for staking (typically only used for CRO)
currency string e.g. CRO

private/create-order

Request Sample

{
  "id": 11,
  "method": "private/create-order",
  "params": {
    "instrument_name": "ETH_CRO",
    "side": "BUY",
    "type": "LIMIT",
    "price": 100.12,
    "quantity": 1.2,
    "client_oid": "my_order_0002"
  },
  "nonce": 1587846358253
}

Response Sample

{
  "id": 11,
  "method": "private/create-order",
  "result": {
    "order_id": "337843775021233500",
    "client_oid": "my_order_0002"
  }
}

Creates a new BUY or SELL order on the Exchange.

This call is asynchronous, so the response is simply a confirmation of the request.

The user.order subscription can be used to check when the order is successfully created.

Request Params

Name Type Required Description
instrument_name string Y e.g., ETH_CRO, BTC_USDT
side string Y BUY, SELL
type string Y LIMIT, MARKET
price number Depends For LIMIT orders only - Unit price
quantity number Depends For LIMIT Orders and MARKET (SELL) Orders only:
Order Quantity to be Sold
notional number Depends For MARKET (BUY) Orders only - Amount to spend
client_oid string N Optional Client order ID

Applies To

REST Websocket (User API)

REST Method

POST

Response Attributes

Name Type Description
order_id number Newly created order ID
client_oid string (Optional) if a Client order ID was provided in the request

private/cancel-order

Request Sample

{
    "id": 11,
    "method": "private/cancel-order",
    "params": {
        "instrument_name": "ETH_CRO",
        "order_id": "337843775021233500"
    },
    "nonce": 1587846358253
}

Response Sample

{
  "id": 11,
  "method": "private/cancel-order",
  "code":0
}

Cancels an existing order on the Exchange (asynchronous)

This call is asynchronous, so the response is simply a confirmation of the request.

The user.order subscription can be used to check when the order is successfully cancelled.

Request Params

Name Type Required Description
instrument_name string Y instrument_name, e.g., ETH_CRO, BTC_USDT
order_id string Y Order ID

Applies To

REST Websocket (User API)

REST Method

POST

Response Attributes

No result block is returned. The code (0 = success) is the primary indicator that the cancel request is queued.

private/cancel-all-orders

Request Sample

{
    "id": 12,
    "method": "private/cancel-all-orders",
    "params": {
        "instrument_name": "ETH_CRO"
    },
    "nonce": 1587846358253
}

Response Sample

{
  "id": 12,
  "method": "private/cancel-all-order",
  "code": 0
}

Cancels all orders for a particular instrument/pair (asynchronous)

This call is asynchronous, so the response is simply a confirmation of the request.

The user.order subscription can be used to check when the order is successfully cancelled.

Request Params

Name Type Required Description
instrument_name string Y e.g. ETH_CRO, BTC_USDT

Applies To

REST Websocket (User API)

REST Method

POST

Response Attributes

No result block is returned. The code (0 = success) is the primary indicator that the request is queued.

private/get-order-history

Request Sample

{
    "id": 12,
    "method": "private/get-order-history",
    "params": {
        "instrument_name": "ETH_CRO",
        "start_ts": 1587846300000,
        "end_ts": 1587846358253,
        "page_size": 2,
        "page": 0
    },
    "nonce": 1587846358253
}

Response Sample

{
  "id": 11,
  "method": "private/get-order-history",
  "code": 0,
  "result": {
    "order_list": [
      {
        "status": "FILLED",
        "side": "SELL",
        "price": 1,
        "quantity": 1,
        "order_id": "367107623521528457",
        "client_oid": "my_order_0002",
        "create_time": 1588777459755,
        "update_time": 1588777460700,
        "type": "LIMIT",
        "instrument_name": "ETH_CRO",
        "cumulative_quantity": 1,
        "cumulative_value": 1,
        "avg_price": 1,        
        "fee_currency": "CRO"
      },
      {
        "status": "FILLED",
        "side": "SELL",
        "price": 1,
        "quantity": 1,
        "order_id": "367063282527104905",
        "client_oid": "my_order_0002",
        "create_time": 1588776138290,
        "update_time": 1588776138679,
        "type": "LIMIT",
        "instrument_name": "ETH_CRO",
        "cumulative_quantity": 1,
        "cumulative_value": 1,
        "avg_price": 1,        
        "fee_currency": "CRO"
      }
    ]
  }
}

Gets the order history for a particular instrument

If paging is used, enumerate each page (starting with 0) until an empty order_list array appears in the response.

Request Params

Name Type Required Description
instrument_name string N e.g. ETH_CRO, BTC_USDT. Omit for 'all'
start_ts long N Start timestamp (milliseconds since the Unix epoch) - defaults to a week ago
end_ts long N End timestamp (milliseconds since the Unix epoch)
page_size int N Page size (Default: 20, max: 200)
page int N Page number (0-based)

Note: If you omit all parameters, you still need to pass in an empty params block like params: {} for API request consistency

Maximum Duration

The maximum duration between start_ts and end_ts is 24 hours.

Traders should use user.order to keep track of real-time order updates, and private/get-order-history should primarily be used for recovery; typically when the websocket is disconnected.

For users looking to pull longer historical order data, Crypto.com is working on a specific endpoint for this, tentatively available in August 2020.

Applies To

REST Websocket (User API)

REST Method

POST

Response Attributes

An array of order_list, consisting of:

Name Type Description
status string ACTIVE, CANCELED, FILLED, REJECTED or EXPIRED
reason string Reason code (see "Response and Reason Codes") -- only for REJECTED orders
side string BUY, SELL
price number Price specified in the order
quantity number Quantity specified in the order
order_id string Order ID
client_oid string (Optional) Client order ID if included in request
create_time number Order creation time (Unix timestamp)
update_time number Order update time (Unix timestamp)
type string LIMIT, MARKET
instrument_name string e.g. ETH_CRO, BTC_USDT
cumulative_quantity number Cumulative executed quantity (for partially filled orders)
cumulative_value number Cumulative executed value (for partially filled orders)
avg_price number Average filled price. If none is filled, returns 0
fee_currency string Currency used for the fees (e.g. CRO)

Note: To detect a 'partial filled' status, look for status as ACTIVE and cumulative_quantity > 0.

private/get-open-orders

Request Sample

{
    "id": 12,
    "method": "private/get-open-orders",
    "params": {
        "instrument_name": "ETH_CRO",
        "page_size": 2,
        "page": 0
    },
    "nonce": 1587846358253
}

Response Sample

{
  "id": 11,
  "method": "private/get-open-orders",
  "code": 0,
  "result": {
    "count": 1177,
    "order_list": [
      {
        "status": "ACTIVE",
        "side": "BUY",
        "price": 1,
        "quantity": 1,
        "order_id": "366543374673423753",
        "client_oid": "my_order_0002",
        "create_time": 1588760643829,
        "update_time": 1588760644292,
        "type": "LIMIT",
        "instrument_name": "ETH_CRO",
        "cumulative_quantity": 0,
        "cumulative_value": 0,
        "avg_price": 0,
        "fee_currency": "CRO"
      },
      {
        "status": "ACTIVE",
        "side": "BUY",
        "price": 1,
        "quantity": 1,
        "order_id": "366455245775097673",
        "client_oid": "my_order_0002",
        "create_time": 1588758017375,
        "update_time": 1588758017411,
        "type": "LIMIT",
        "instrument_name": "ETH_CRO",
        "cumulative_quantity": 0,
        "cumulative_value": 0,
        "avg_price": 0,        
        "fee_currency": "CRO"
      }
    ]
  }
}

Gets all open orders for a particular instrument

Request Params

Name Type Required Description
instrument_name string N instrument_name, e.g., ETH_CRO, BTC_USDT. Omit for "all"
page_size int N Page size (Default: 20, max: 200)
page int N Page number (0-based)

Applies To

REST Websocket (User API)

REST Method

POST

Response Attributes

Name Type Description
count number Total count of orders

Additionally, an array of order_list, consisting of:

Name Type Description
status string ACTIVE, CANCELED, FILLED, REJECTED or EXPIRED
reason string Reason code (see "Response and Reason Codes") -- only for REJECTED orders
side string BUY, SELL
price number Price specified in the order
quantity number Quantity specified in the order
order_id string Order ID
client_oid string (Optional) Client order ID if included in request
create_time number Order creation time (Unix timestamp)
update_time number Order update time (Unix timestamp)
type string LIMIT, MARKET
instrument_name string e.g. ETH_CRO, BTC_USDT
cumulative_quantity number Cumulative executed quantity (for partially filled orders)
cumulative_value number Cumulative executed value (for partially filled orders)
avg_price number Average filled price. If none is filled, returns 0
fee_currency string Currency used for the fees (e.g. CRO)

Note: To detect a 'partial filled' status, look for status as ACTIVE and cumulative_quantity > 0.

private/get-order-detail

Request Sample

{
    "id": 12,
    "method": "private/get-order-detail",
    "params": {
        "order_id": "337843775021233500"
    },
    "nonce": 1587846358253
}

Response Sample

{
  "id": 11,
  "method": "private/get-order-detail",
  "code": 0,
  "result": {
    "trade_list": [
      {
        "side": "BUY",
        "instrument_name": "ETH_CRO",
        "fee": 0.007,
        "trade_id": "371303044218155296",
        "create_time": 1588902493045,
        "traded_price": 7,
        "traded_quantity": 7,
        "fee_currency": "CRO",
        "order_id": "371302913889488619"
      }
    ],
    "order_info": {
      "status": "FILLED",
      "side": "BUY",
      "order_id": "371302913889488619",
      "client_oid": "9_yMYJDNEeqHxLqtD_2j3g",
      "create_time": 1588902489144,
      "update_time": 1588902493024,
      "type": "LIMIT",
      "instrument_name": "ETH_CRO",
      "cumulative_quantity": 7,
      "cumulative_value": 7,
      "avg_price": 7,      
      "fee_currency": "CRO"
    }
  }
}

Gets details on a particular order ID

Request Params

Name Type Required Description
order_id string Y Order ID

Applies To

REST Websocket (User API)

REST Method

POST

Response Attributes

An array of trade_list, consisting of:

Name Type Description
side string BUY, SELL
instrument_name string e.g. ETH_CRO, BTC_USDT
fee number Trade fee
trade_id string Trade ID
create_time long Trade creation time
traded_price number Executed trade price
traded_quantity number Executed trade quantity
fee_currency string Currency used for the fees (e.g. CRO)
order_id string Order ID

Additionally, an array of order_info, consisting of:

Name Type Description
status string ACTIVE, CANCELED, FILLED, REJECTED or EXPIRED
reason string Reason code (see "Response and Reason Codes") -- only for REJECTED orders
side string BUY, SELL
price number Price specified in the order
quantity number Quantity specified in the order
order_id string Order ID
client_oid string (Optional) Client order ID if included in request
create_time number Order creation time (Unix timestamp)
update_time number Order update time (Unix timestamp)
type string LIMIT, MARKET
instrument_name string e.g. ETH_CRO, BTC_USDT
cumulative_quantity number Cumulative executed quantity (for partially filled orders)
cumulative_value number Cumulative executed value (for partially filled orders)
avg_price number Average filled price. If none is filled, returns 0
fee_currency string Currency used for the fees (e.g. CRO)

Note: To detect a 'partial filled' status, look for status as ACTIVE and cumulative_quantity > 0.

private/get-trades

Request Sample

{
    "id": 11,
    "method": "private/get-trades",
    "params": {
        "instrument_name": "ETH_CRO",
        "page_size": 1,
        "page": 0,
        "start_ts": 1488851410000,
        "end_ts": 1688851410000
    },
    "nonce": 1587523073344
}

Response Sample

{
  "id": 11,
  "method": "private/get-trades",
  "code": 0,
  "result": {
    "trade_list": [
      {
        "side": "SELL",
        "instrument_name": "ETH_CRO",
        "fee": 0.014,
        "trade_id": "367107655537806900",
        "create_time": 1588777459755,
        "traded_price": 7,
        "traded_quantity": 1,
        "fee_currency": "CRO",
        "order_id": "367107623521528450"
      }
    ]
  }
}

Gets all executed trades for a particular instrument.

If paging is used, enumerate each page (starting with 0) until an empty trade_list array appears in the response.

Request Params

Name Type Required Description
instrument_name string N e.g. ETH_CRO, BTC_USDT. Omit for 'all'
start_ts long N Start timestamp (milliseconds since the Unix epoch) - defaults to 24 hours ago
end_ts long N End timestamp (milliseconds since the Unix epoch) - defaults to 'now'
page_size int N Page size (Default: 20, max: 200)
page int N Page number (0-based)

Note: If you omit all parameters, you still need to pass in an empty params block like params: {} for API request consistency

Maximum Duration

The maximum duration between start_ts and end_ts is 24 hours.

Traders should use user.trade to keep track of real-time trades, and private/get-trades should primarily be used for recovery; typically when the websocket is disconnected.

For users looking to pull longer historical trade data, Crypto.com is working on a specific endpoint for this, tentatively available in August 2020.

Applies To

REST Websocket (User API)

REST Method

POST

Response Attributes

An array of trade_list, consisting of:

Name Type Description
side string BUY, SELL
instrument_name string e.g. ETH_CRO, BTC_USDT
fee number Trade fee
trade_id string Trade ID
create_time long Trade creation time
traded_price number Executed trade price
traded_quantity number Executed trade quantity
fee_currency string Currency used for the fees (e.g. CRO)
order_id string Order ID

Websocket Heartbeats

Heartbeat Example

{
  "id": 1587523073344,
  "method": "public/heartbeat",
  "code": 0
}

For websocket connections, the system will send a heartbeat message to the client every 30 seconds.

The client must respond back with the public/respond-heartbeat method, using the same matching id, within 5 seconds, or the connection will break.

public/respond-heartbeat

Request Sample

{
  "id": 1587523073344,
  "method": "public/respond-heartbeat"
}

Responds to the server-initiated websocket heartbeat

Request Params

None

Applies To

Websocket (User API) Websocket (Market Data Subscriptions)

Websocket Subscriptions

Introduction

Request Sample

{
  "id": 11,
  "method": "subscribe",
  "params": {
    "channels": ["user.order.ETH_CRO"]
  },
  "nonce": 1587523073344
}

Response Sample (Initial)

{
  "id": 11,
  "code": 0,
  "method": "subscribe"
}

One of the powerful features of a websocket is the ability to subscribe to incremental updates in particular channels.

This section covers the available channels that can be subscribed or unsubscribed for both the Websocket (User API) and Websocket (Market Data Subscriptions)

Market Data Subscriptions include features such as order book depth, all trades and ticker data. Market data information is pushed every 100 milliseconds.

Websocket subscriptions involve two responses:

Request Params

Name Type Required Description
method string Y subscribe, unsubscribe
channels array of strings Y Channels to be subscribed

Applies To

Websocket (User API)

user.order.{instrument_name}

Request Sample

{
  "id": 11,
  "method": "subscribe",
  "params": {
    "channels": ["user.order.ETH_CRO"]
  },
  "nonce": 1587523073344
}

Response Sample

{
  "method": "subscribe",
  "result": {
    "instrument_name": "ETH_CRO",
    "subscription": "user.order.ETH_CRO",
    "channel": "user.order",
    "data": [
      {
        "status": "ACTIVE",
        "side": "BUY",
        "price": 1,
        "quantity": 1,
        "order_id": "366455245775097673",
        "client_oid": "my_order_0002",
        "create_time": 1588758017375,
        "update_time": 1588758017411,
        "type": "LIMIT",
        "instrument_name": "ETH_CRO",
        "cumulative_quantity": 0,
        "cumulative_value": 0,
        "avg_price": 0,        
        "fee_currency": "CRO"
      }
    ],
    "channel": "user.order.ETH_CRO"
  }
}

Publishes all new orders or order updates for the user for a particular instrument (e.g. BTC_USDT).

instrument_name can be omitted to show tickers for all instruments

Requires initial authentication using public/auth (see public/auth for more information).

Applies To

Websocket (User API)

Response Attributes

Name Type Description
instrument_name string e.g. ETH_CRO, BTC_USDT
subscription string user.order.{instrument_name} -- even in the all case
channel string user.order
data array See below

subscription makes it easy to map to the initial subscription

channel and instrument_name simply allow easier access to parameters without needing to parse the subscription

data consists of:

Name Type Description
order_id string Order ID
client_oid string (Optional) Client order ID if included in request
create_time number Order creation time (Unix timestamp)
update_time number Order update time (Unix timestamp)
status string ACTIVE, CANCELED, FILLED, REJECTED or EXPIRED
reason string Reason code (see "Response and Reason Codes") -- only for REJECTED orders
type string LIMIT, MARKET
side string BUY, SELL
instrument_name string e.g. ETH_CRO, BTC_USDT
price number Price specified in the order
quantity number Quantity specified in the order
cumulative_quantity number Cumulative executed quantity (for partially filled orders)
cumulative_value number Cumulative executed value (for partially filled orders)
avg_price number Average filled price. If none is filled, returns 0

Note: To detect a 'partial filled' status, look for status as ACTIVE and cumulative_quantity > 0.

user.trade.{instrument_name}

Request Sample

{
  "id": 11,
  "method": "subscribe",
  "params": {
    "channels": ["user.trade.ETH_CRO"]
  },
  "nonce": 1587523073344
}

Response Sample

{
  "method": "subscribe",
  "code": 0,
  "result": {
    "instrument_name": "ETH_CRO",
    "subscription": "user.trade.ETH_CRO",
    "channel": "user.trade",
    "data": [
      {
        "side": "SELL",
        "instrument_name": "ETH_CRO",
        "fee": 0.014,
        "trade_id": "367107655537806900",
        "create_time": "1588777459755",
        "traded_price": 7,
        "traded_quantity": 1,
        "fee_currency": "CRO",
        "order_id": "367107623521528450"
      }
    ],
    "channel": "user.trade.ETH_CRO"
  }
}

Publishes all new trades updates related to the user for a particular instrument (e.g. BTC_USDT)

instrument_name can be omitted to show tickers for all instruments

Requires initial authentication using public/auth (see public/auth for more information).

Applies To

Websocket (User API)

Response Attributes

Name Type Description
instrument_name string e.g. ETH_CRO, BTC_USDT
subscription string user.trade.{instrument_name} -- even in the all case
channel string user.trade
data array See below

subscription makes it easy to map to the initial subscription

channel and instrument_name simply allow easier access to parameters without needing to parse the subscription

data consists of:

Name Type Description
side string BUY, SELL
fee number Trade fee
trade_id string Trade ID
create_time long Trade creation time
traded_price number Executed trade price
traded_quantity number Executed trade quantity
fee_currency string Currency used for the fees (e.g. CRO)
order_id string Order ID

user.balance

Request Sample

{
  "id": 11,
  "method": "subscribe",
  "params": {
    "channels": ["user.balance"]
  },
  "nonce": 1587523073344
}

Response Sample

{
  "method": "subscribe",
  "result": {
    "subscription": "user.balance",
    "channel": "user.balance",
    "data": [
      {
        "currency": "CRO",
        "balance": 99999999947.99626,
        "available": 99999988201.50826,
        "order": 11746.488,
        "stake": 0
      }
    ],
    "channel": "user.balance"
  }
}

Publishes all new balance updates for the user

Requires initial authentication using public/auth (see public/auth for more information).

Applies To

Websocket (User API)

Response Attributes

Name Type Description
subscription string user.balance
channel string user.balance
data array See below

data consists of:

Name Type Description
currency string e.g. CRO
balance number Total balance
available number Available balance (e.g. not in orders, or locked, etc.)
order number Balance locked in orders
stake number Balance locked for staking (typically only used for CRO)

book.{instrument_name}.{depth}

Request Sample

{
  "id": 11,
  "method": "subscribe",
  "params": {
    "channels": ["book.ETH_CRO.150"]
  },
  "nonce": 1587523073344
}

Response Sample

{
  "method": "subscribe",
  "result": {
    "instrument_name": "ETH_CRO", // instrument_name
    "subscription": "book.ETH_CRO.150",
    "channel": "book",
    "depth": 150
    "data": [
      {
        "bids": [
          [
            11746.488,    // price
            128,          // quantity
            8             // number of Orders
          ]
        ],
        "asks": [
          [
            11747.488,    // price
            201,          // quantity
            12            // number of Orders
          ]
        ],
        "t": 1587523078844
      }
    ]
  }
}

Publishes order book changes for an instrument (e.g. BTC_USDT) based on price level depth

Name Description
depth Number of bids and asks to return. Allowed values: 10 or 150

Applies To

Websocket (Market Data Subscriptions)

Response Attributes

Name Type Description
instrument_name string e.g. ETH_CRO, BTC_USDT
subscription string book.{instrument_name}.{depth}
channel string book
depth number Price level
data array See below

subscription makes it easy to map to the initial subscription

channel, instrument_name and depth simply allow easier access to parameters without needing to parse the subscription

data consists of:

Name Type Description
bids array Bids array: [0] = Price, [1] = Quantity, [2] = Number of Orders
asks array Asks array: [0] = Price, [1] = Quantity, [2] = Number of Orders
t long Timestamp of the data

ticker.{instrument_name}

Request Sample

{
  "id": 11,
  "method": "subscribe",
  "params": {
    "channels": ["ticker.ETH_CRO"]
  },
  "nonce": 1587523073344
}

Response Sample

{
  "method": "subscribe",
  "result": {
    "instrument_name": "ETH_CRO", // instrument_name
    "subscription": "ticker.ETH_CRO",
    "channel": "ticker",
    "data": [
      {
        "h": 1, // Price of the 24h highest trade
        "v": 10232.26315789, // The total 24h traded volume
        "a": 173.60263169, // The price of the latest trade, null if there weren't any trades
        "l": 0.01, // Price of the 24h lowest trade, null if there weren't any trades
        "b": 0.01, // The current best bid price, null if there aren't any bids
        "k": 1.12345680, // The current best ask price, null if there aren't any asks
        "c": -0.44564773, // 24-hour price change, null if there weren't any trades
        "t": 1587523078844 // update time
      }
    ]
  }
}

Publishes new tickers for an instrument (e.g. BTC_USDT)

instrument_name can be omitted to show tickers for all instruments

Applies To

Websocket (Market Data Subscriptions)

Response Attributes

Name Type Description
instrument_name string e.g. ETH_CRO, BTC_USDT
subscription string ticker.{instrument_name} -- even in the all case
channel string Channel category (ticker)
data array See below

subscription makes it easy to map to the initial subscription

channel and instrument_name simply allow easier access to parameters without needing to parse the subscription

data consists of:

Name Type Description
h number Price of the 24h highest trade
v number The total 24h traded volume
a number The price of the latest trade, null if there weren't any trades
l number Price of the 24h lowest trade, null if there weren't any trades
b number The current best bid price, null if there aren't any bids
k number The current best ask price, null if there aren't any asks
c number 24-hour price change, null if there weren't any trades
t number Timestamp of the data

trade.{instrument_name}

Request Sample

{
  "id": 11,
  "method": "subscribe",
  "params": {
    "channels": ["trade.ETH_CRO"]
  },
  "nonce": 1587523073344
}

Response Sample

{
  "method": "subscribe",
  "result": {
    "instrument_name": "ETH_CRO", // instrument_name
    "subscription": "trade.ETH_CRO",
    "channel": "trade",
    "data": [
      {
        "p": 162.12, // price
        "q": 11.085, // quantity
        "s": "buy", // side
        "d": 1210447366, // trade id
        "t": 1587523078844 // trade time
        "dataTime": 0 // please ignore this field
      }
    ]
  }
}

Publishes new trades for an instrument (e.g. BTC_USDT)

instrument_name can be omitted to show trades for all instruments

Applies To

Websocket (Market Data Subscriptions)

Response Attributes

Name Type Description
instrument_name string e.g. ETH_CRO, BTC_USDT
subscription string trade.{instrument_name} -- even in the all case
channel string Always "trade"
data array See below

subscription makes it easy to map to the initial subscription

channel and instrument_name simply allow easier access to parameters without needing to parse the subscription

data consists of:

Name Type Description
p number Trade price
q number Trade quantity
s string Side ("buy" or "sell")
d number Trade ID
t number Trade timestamp
dataTime long Reserved. Can be ignored

candlestick.{interval}.{instrument_name}

Request Sample

{
  "id": 11,
  "method": "subscribe",
  "params": {
    "channels": ["candlestick.1h.ETH_CRO"]
  },
  "nonce": 1587523073344
}

Response Sample

{
  "method": "subscribe",
  "result": {
    "instrument_name": "ETH_CRO", // instrument_name
    "subscription": "candlestick.1m.ETH_CRO",
    "channel": "candlestick",
    "interval": "1m",
    "data":[
      {
        "i": "ETH_CRO",
        "o": 162.03,  // open
        "c": 162.04,  // close
        "h": 161.96,  // high
        "l": 161.98,  // low
        "v": 336.452694 // volume
        "t": 1589441241 // start time of the stick, in epochtime
      },
      {
        "i": "ETH_CRO",
        "o": 163.03,  // open
        "c": 163.04,  // close
        "h": 162.96,  // high
        "l": 162.98,  // low
        "v": 336.452694 // volume
        "t": 1589443241 // start time of the stick, in epochtime
      }
      ]
  }
}

Publishes candlesticks (k-line data history) over a given period for an instrument (e.g. BTC_USDT)

period can be:

Applies To

Websocket (Market Data Subscriptions)

Response Attributes

Name Type Description
instrument_name string e.g. ETH_CRO, BTC_USDT
subscription string candlestick.{interval}.{instrument_name}
channel string Always "candlestick"
data array See below

subscription makes it easy to map to the initial subscription

channel and instrument_name simply allow easier access to parameters without needing to parse the subscription

data consists of:

Name Type Description
o number Open
c number Close
h number High
l number Low
v number Volume
t long End time of candlestick (Unix timestamp)