NAV Navbar
Spot 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. Default settings will be set to "Can Read" only, and you have the option of adding or removing certain permissions for your API Key via Web UI.

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
private/margin/create-order
private/margin/cancel-order
private/margin/cancel-all-orders
15 requests per 100ms each
private/get-order-detail
private/margin/get-order-detail
30 requests per 100ms
private/get-trades
private/margin/get-trades
1 requests per second
private/get-order-history
private/margin/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

Important Note

We recommend adding a 1-second sleep after establishing the websocket connection, and before requests are sent.

This will avoid occurrences of rate-limit (`TOO_MANY_REQUESTS`) errors, as the websocket rate limits are pro-rated based on the calendar-second that the websocket connection was opened.

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

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

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 Y Current timestamp (milliseconds since the Unix epoch)

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 sorted(req['params']):
    paramString += key
    paramString += str(req['params'][key])

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

req['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.Keys.OrderBy(key => key).Select(key => key + Params[key]));

    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
30023 400 MIN_AMOUNT_VIOLATED Amount is lower than the minimum
30024 400 MAX_AMOUNT_VIOLATED Amount is higher than the maximum
30025 400 AMOUNT_PRECISION_OVERFLOW Amount precision exceeds the maximum
40001 400 MG_INVALID_ACCOUNT_STATUS Operation has failed due to your account's status. Please try again later.
40002 400 MG_TRANSFER_ACTIVE_LOAN Transfer has failed due to holding an active loan. Please repay your loan and try again later.
40003 400 MG_INVALID_LOAN_CURRENCY Currency is not same as loan currency of active loan
40004 400 MG_INVALID_REPAY_AMOUNT Only supporting full repayment of all margin loans
40005 400 MG_NO_ACTIVE_LOAN No active loan
40006 400 MG_BLOCKED_BORROW Borrow has been suspended. Please try again later.
40007 400 MG_BLOCKED_NEW_ORDER Placing new order has been suspended. Please try again later.
50001 400 DW_CREDIT_LINE_NOT_MAINTAINED Please ensure your credit line is maintained and try again later.

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.

Important Note

We recommend adding a 1-second sleep after establishing the websocket connection, and before requests are sent.

This will avoid occurrences of rate-limit (`TOO_MANY_REQUESTS`) errors, as the websocket rate limits are pro-rated based on the calendar-second that the websocket connection was opened.

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": "BTC_USDT",
         "quote_currency": "BTC",
         "base_currency": "USDT",
         "price_decimals": 2,
         "quantity_decimals": 6,
         "margin_trading_enabled": true

       },
       {
         "instrument_name": "CRO_BTC",
         "quote_currency": "BTC",
         "base_currency": "CRO",
         "price_decimals": 8,
         "quantity_decimals": 2,
         "margin_trading_enabled": false
       }
     ]
   }
}

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
margin_trading_enabled boolean true or false

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

Request Sample

https://{URL}/v2/public/get-candlestick?instrument_name=BTC_USDT&timeframe=5m

Response Sample

{
  "code":0,
  "method":"public/get-candlestick",
  "result":{
    "instrument_name":"BTC_USDT",
    "interval":"5m",
    "data":[
      {"t":1596944700000,"o":11752.38,"h":11754.77,"l":11746.65,"c":11753.64,"v":3.694583},
      {"t":1596945000000,"o":11753.63,"h":11754.77,"l":11739.83,"c":11746.17,"v":2.073019},
      {"t":1596945300000,"o":11746.16,"h":11753.24,"l":11738.1,"c":11740.65,"v":0.867247},
      ...
    ]
  }
}

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

period can be:

Applies To

REST

Response Attributes

Name Type Description
instrument_name string e.g. ETH_CRO, BTC_USDT
interval string The period (e.g. 5m)
data array See below

data consists of:

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

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/set-cancel-on-disconnect

Request Sample

{
 "id": "11",
 "method": "private/set-cancel-on-disconnect",
 "params": {
   "scope": "CONNECTION"
 }
}

Response Sample

{
 "id": "11",
 "method": "private/set-cancel-on-disconnect",
 "code": 0,
 "result": {
   "scope": "CONNECTION"
 }
}

Cancel on Disconnect is an optional feature that will cancel all open orders created by the connection upon loss of connectivity between client or server.

This feature is only available via the Websocket.

Request Params

Name Type Required Description
scope string Y Specifies the scope of cancellation, whether it should be applied to the specific connection or to the account (all orders created via Websocket)

ACCOUNT or CONNECTION

Helpful Information

Applies To

Websocket (User API)

Response Attributes

Name Type Description
scope string Specifies the scope of cancellation, whether it should be applied to the specific connection or to the account (all orders created via Websocket)

ACCOUNT or CONNECTION

private/get-cancel-on-disconnect

Request Sample

{
 "id": "11",
 "method": "private/get-cancel-on-disconnect"
}

Response Sample

{
 "id": "11",
 "method": "private/get-cancel-on-disconnect",
 "code": 0,
 "result": {
   "scope": "CONNECTION"
 }
}

Returns the scope of cancellation for the connection.

Request Params

None

Applies To

Websocket (User API)

Response Attributes

Name Type Description
scope string Specifies the scope of cancellation, whether it should be applied to the specific connection or to the account (all orders created via Websocket)

ACCOUNT or CONNECTION

private/create-withdrawal

Request Sample

{
  "id": -1,
  "method": "private/create-withdrawal",
  "params": {
      "client_wid": "my_withdrawal_002",
      "currency": "BTC",
      "amount": "1",
      "address": "2NBqqD5GRJ8wHy1PYyCXTe9ke5226FhavBf",
      "address_tag": ""
  },
  "nonce": "1607063412000"
}

Response Sample

{
   "id":-1,
   "method":"private/create-withdrawal",
   "code":0,
   "result": {
       "id": 2220,
       "amount": 1,
       "fee": 0.0004,
       "symbol": "BTC",
       "address": "2NBqqD5GRJ8wHy1PYyCXTe9ke5226FhavBf",
       "client_wid": "my_withdrawal_002",
       "create_time":1607063412000
   }
}

Creates a withdrawal request. Withdrawal setting must be enabled for your API Key. If you do not see the option when viewing your API Key, this feature is not yet available for you.

Request Params

Name Type Required Description
client_wid string N Optional Client withdrawal ID
currency string Y E.g. BTC, CRO
amount decimal Y
address string Y
address_tag string N Secondary address identifier for coins like XRP, XLM etc. Also known as memo or tags.

Helpful Information

Applies To

REST Websocket (User API)

REST Method

POST

Response Attributes

Name Type Description
id long Newly created withdrawal ID
client_wid string (Optional) if a Client withdrawal ID was provided in the request
currency string E.g. BTC, CRO
amount decimal
fee decimal
address string Address with Address Tag (if any)
create_time long

private/get-withdrawal-history

Request Sample

{
   "id": -1,
   "method": "private/get-withdrawal-history",
   "params": {
       "currency": "XRP",
       "start_ts": 1587846300000,
       "end_ts": 1587846358253,
       "page_size": 2,
       "page": 0,
       "status": "1"
   },
   "nonce": 1587846358253
}

Response Sample

{
   "id": 11,
   "method": "private/get-withdrawal-history",
   "code": 0,
   "result": {
     "withdrawal_list": [
       {
         "currency": "XRP",
         "client_wid": "my_withdrawal_002",
         "fee": 1.0,
         "create_time": 1607063412000,
         "id": "2220",
         "update_time": 1607063460000,
         "amount": 100,
         "address": "2NBqqD5GRJ8wHy1PYyCXTe9ke5226FhavBf?1234567890",
         "status": "1",
         "txid": ""
       }
     ]
   }
}

Fetches withdrawal history. Withdrawal setting must be enabled for your API Key. If you do not see the option when viewing your API Keys, this feature is not yet available for you.

Request Params

Name Type Required Description
currency string N E.g. BTC, CRO
start_ts long N Default is 90 days from current timestamp
end_ts long N Default is current timestamp
page_size int N Page size (Default: 20, Max: 200)
page int N Page number (0-based)
status string N "0"

0 - Pending
1 - Processing
2 - Rejected
3 - Payment In-progress
4 - Payment Failed
5 - Completed
6 - Cancelled

Applies To

REST Websocket (User API)

REST Method

POST

Response Attributes

An array of withdrawal_list, consisting of:

Name Type Description
id long Newly created withdrawal ID
client_wid string (Optional) if a Client withdrawal ID was provided in the request
currency string E.g. BTC, CRO
amount decimal
fee decimal
address string Address with Address Tag (if any)
create_time long
status string "0"

0 - Pending
1 - Processing
2 - Rejected
3 - Payment In-progress
4 - Payment Failed
5 - Completed
6 - Cancelled
txid string Transaction hash

private/get-deposit-history

Request Sample

{
   "id": -1,
   "method": "private/get-deposit-history",
   "params": {
       "currency": "XRP",
       "start_ts": 1587846300000,
       "end_ts": 1587846358253,
       "page_size": 2,
       "page": 0,
       "status": "1"
   },
   "nonce": 1587846358253
}

Response Sample

{
   "id": 11,
   "method": "private/get-deposit-history",
   "code": 0,
   "result": {
     "deposit_list": [
       {
         "currency": "XRP",
         "fee": 1.0,
         "create_time": 1607063412000,
         "id": "2220",
         "update_time": 1607063460000,
         "amount": 100,
         "address": "2NBqqD5GRJ8wHy1PYyCXTe9ke5226FhavBf?1234567890",
         "status": "1"
       }
     ]
   }
}

Fetches deposit history. Withdrawal setting must be enabled for your API Key. If you do not see the option when viewing your API Keys, this feature is not yet available for you.

Request Params

Name Type Required Description
currency string N E.g. BTC, CRO
start_ts long N Default is 90 days from current timestamp
end_ts long N Default is current timestamp
page_size int N Page size (Default: 20, Max: 200)
page int N Page number (0-based)
status string N "0"

0 - Not Arrived
1 - Arrived
2 - Failed
3 - Pending

Applies To

REST

REST Method

POST

Response Attributes

An array of deposit_list, consisting of:

Name Type Description
id long Newly created deposit ID
currency string E.g. BTC, CRO
amount decimal
fee decimal
address string Address with Address Tag (if any)
create_time long
status string "0"

0 - Not Arrived
1 - Arrived
2 - Failed
3 - Pending

private/get-deposit-address

Request Sample

{
   "id": -1,
   "method": "private/get-deposit-address",
   "params": {
       "currency": "CRO",
   },
   "nonce": 1587846358253
}

Response Sample

{
   "id": 11,
   "method": "private/get-deposit-address",
   "code": 0,
   "result": {
        "deposit_address_list": [
            {
                "currency": "CRO",
                "create_time": 1615886328000,
                "id": "12345",
                "address": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                "status": "1",
                "network": "CRO"
            },
            {
                "currency": "CRO",
                "create_time": 1615886332000,
                "id": "12346",
                "address": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
                "status": "1",
                "network": "ETH"
            }
        ]
  }
}

Fetches deposit address. Withdrawal setting must be enabled for your API Key. If you do not see the option when viewing your API Keys, this feature is not yet available for you.

Request Params

Name Type Required Description
currency string Y E.g. BTC, CRO

Applies To

REST

REST Method

POST

Response Attributes

An array of deposit_address_list, consisting of:

Name Type Description
id long Newly created deposit ID
currency string E.g. BTC, CRO
network string E.g. ETH, CRO

When currency = CRO, network = CRO, it is a main net address.
When currency = CRO, network = ETH, it is an ERC20 address.
address string Address with Address Tag (if any)
create_time long
status string "0"

0 - Inactive
1 - Active

Spot Trading API

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",
   "time_in_force": "GOOD_TILL_CANCEL",
   "exec_inst": "POST_ONLY"
 },
 "nonce": 1587846358253
}

// Stop Limit Example

{
   "id": 15,
   "method": "private/create-order",
   "params": {
       "instrument_name": "BTC_USDT",
       "side": "BUY",
       "type": "STOP_LIMIT",
       "quantity": 1,
       "trigger_price": 9000,
       "price": 9100,
       "client_oid": "my_stop_limit_order_0015",
       "time_in_force": "GOOD_TILL_CANCEL"
   },
   "nonce": "1598070206891”
}

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, STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT
price number Depends For LIMIT and STOP_LIMIT orders only:
Unit price
quantity number Depends For LIMIT Orders, MARKET, STOP_LOSS, TAKE_PROFIT orders only:
Order Quantity to be Sold
notional number Depends For MARKET (BUY), STOP_LOSS (BUY), TAKE_PROFIT (BUY) orders only:
Amount to spend
client_oid string N Optional Client order ID
time_in_force string N (Limit Orders Only)
Options are:
- GOOD_TILL_CANCEL (Default if unspecified)
- FILL_OR_KILL
- IMMEDIATE_OR_CANCEL
exec_inst string N (Limit Orders Only)
Options are:
- POST_ONLY
- Or leave empty
trigger_price number N Used with STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, and TAKE_PROFIT_LIMIT orders.
Dictates when order will be triggered


Here are the mandatory parameters based on order type:

Type Side Additional Mandatory Parameters
LIMIT Both quantity, price
MARKET BUY notional or quantity, mutually exclusive
MARKET SELL quantity
STOP_LIMIT Both price, quantity, trigger_price
TAKE_PROFIT_LIMIT Both price, quantity, trigger_price
STOP_LOSS BUY notional, trigger_price
STOP_LOSS SELL quantity, trigger_price
TAKE_PROFIT BUY notional, trigger_price
TAKE_PROFIT SELL quantity, trigger_price


Helpful information:


To create trigger orders against market price:

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",
        "time_in_force": "GOOD_TILL_CANCEL"
      },
      {
        "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",
        "time_in_force": "GOOD_TILL_CANCEL"
      }
    ]
  }
}

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.

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

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.

You will receive an INVALID_DATE_RANGE error if the difference exceeds the maximum duration.

For users looking to pull longer historical order data, users can create a loop to make a request for each 24-period from the desired start to end time.

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, STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT
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)
time_in_force string - GOOD_TILL_CANCEL
- FILL_OR_KILL
- IMMEDIATE_OR_CANCEL
exec_inst string Empty or POST_ONLY (Limit Orders Only)
trigger_price number Used for trigger-related orders

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",
        "time_in_force": "GOOD_TILL_CANCEL"
      },
      {
        "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",
        "time_in_force": "GOOD_TILL_CANCEL"
      }
    ]
  }
}

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, STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT
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)
time_in_force string - GOOD_TILL_CANCEL
- FILL_OR_KILL
- IMMEDIATE_OR_CANCEL
exec_inst string Empty or POST_ONLY (Limit Orders Only)
trigger_price number Used for trigger-related orders

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",
      "time_in_force": "GOOD_TILL_CANCEL",
      "exec_inst": "POST_ONLY"
    }
  }
}

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, STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT
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)
time_in_force string - GOOD_TILL_CANCEL
- FILL_OR_KILL
- IMMEDIATE_OR_CANCEL
exec_inst string Empty or POST_ONLY (Limit Orders Only)
trigger_price number Used for trigger-related orders

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.

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

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.

You will receive an INVALID_DATE_RANGE error if the difference exceeds the maximum duration.

For users looking to pull longer historical trade data, users can create a loop to make a request for each 24-period from the desired start to end time.

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
client_order_id string Client Order ID
liquidity_indicator string TAKER
MAKER

Margin Trading API

To enable Margin Trading, you will need to create a Margin Wallet; please refer to the Margin Trading Guide here.

Margin trading will use the same parameters as the spot trading API endpoints; the difference will simply be in the URL used:

There are end points specific to Margin Trading. Please find their respective section for details.

public/margin/get-transfer-currencies

Request Sample

https://{URL}/v2/public/margin/get-transfer-currencies

Response Sample

{
   "id": -1,
   "method": "public/margin/get-transfer-currencies",
   "code": 0,
   "result": {
       "transfer_currency_list": ["USDT", "BTC", "CRO"]
   }
}

Provides information on supported currencies that can be transferred into the Margin Wallet.

Ensure you keep params: {} for API request consistency.

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 transfer_currency_list, consisting of transfer currencies. E.g. BTC, USDT, CRO.

public/margin/get-loan-currencies

Request Sample

https://{URL}/v2/public/margin/get-loan-currencies

Response Sample

{
   "id": -1,
   "method": "public/margin/get-loan-currencies",
   "code": 0,
   "result": {
       "loan_currency_list": ["USDT", "BTC"]
   }
}

Provides information on supported currencies that can be transferred into the Margin Wallet.

Ensure you keep params: {} for API request consistency.

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 loan_currency_list, consisting of loan currencies. E.g. BTC, USDT, CRO.

private/margin/get-user-config

Request Sample

{
   "id": 11,
   "method": "private/margin/get-user-config",
   "params": {},
   "nonce": 1607988726735
}

Response Sample

{
   "id": 11,
   "method": "private/margin/get-user-config",
   "code": 0,
     "result": {
         "stake_amount": 10000,
         "currency_configs": [
             {
                 "currency": "BTC",
                 "hourly_rate": 0.00002125,
                 "max_borrow_limit": 16.97184374,
                 "min_borrow_limit": 0.003
             },
             {
                 "currency": "USDT",
                 "hourly_rate": 0.00002167,
                 "max_borrow_limit": 200376.88520530,
                 "min_borrow_limit": 20.0
             }
         ]
     }
}

Provides information on borrowable amounts and limits.

Ensure you keep params: {} for API request consistency.

Applies To

REST Websocket (User API)

REST Method

POST

Response Attributes

Summary view of borrowable amounts and limits, and an array of currency_configs separated by currency:

Name Type Description
stake_amount number

The array of currency_configs:

Name Type Description
currency string E.g. BTC, USDT
hourly_rate int Hourly interest rate
max_borrow_limit int Maximum borrow limit based on collateral in the Margin Wallet
min_borrow_limit int Minimum borrow limit

private/margin/get-account-summary

Request Sample

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

Response Sample

{
   "id": 11,
   "method": "private/margin/get-account-summary",
   "code": 0,
   "result": {
       "accounts": [{
           "balance": 0,
           "available": 0,
           "order": 0,
           "borrowed": 0,
           "position": 0,
           "positionHomeCurrency": 0,
           "positionBtc": 0,
           "lastPriceHomeCurrency": 1,
           "lastPriceBtc": 0.00005236,
           "currency": "USDT",
           "accrued_interest": 0,
           "liquidation_price": 0
       }, {
           "balance": 0,
           "available": 0,
           "order": 0,
           "borrowed": 0,
           "position": 0,
           "positionHomeCurrency": 0,
           "positionBtc": 0,
           "lastPriceHomeCurrency": 19096.77,
           "lastPriceBtc": 1,
           "currency": BTC,
           "accrued_interest": 0,
           "liquidation_price": 0
       }, {
           "balance": 0,
           "available": 0,
           "order": 0,
           "borrowed": 0,
           "position": 0,
           "positionHomeCurrency": 0,
           "positionBtc": 0,
           "lastPriceHomeCurrency": 0.06,
           "lastPriceBtc": 0.00000314,
           "currency": "CRO",
           "accrued_interest": 0,
           "liquidation_price": 0
       }],
       "is_liquidating": false,
       "total_balance": 0,
       "total_balance_btc": 0,
       "equity_value": 0,
       "equity_value_btc": 0,
       "total_borrowed": 0,
       "total_borrowed_btc": 0,
       "total_accrued_interest": 0,
       "total_accrued_interest_btc": 0,
       "margin_score": "GOOD",
       "currency": "USDT"
   }
}

Returns the account balance of the user’s margin wallet

Request Params

None

Ensure you keep params: {} for API request consistency.

Applies To

REST Websocket (User API)

REST Method

POST

Response Attributes

Summary view of the margin wallet and an array of accounts separated by currency:

Name Type Description
is_liquidating boolean Describes whether the account is under liquidation
equity_value number Total equity value in home currency
total_borrowed number Total borrowed amount in home currency
margin_ratio number Margin score is determinant of the health of the margin wallet
margin_score string GOOD, FAIR, or CRITICAL
currency string Home currency in USDT

The array of accounts:

Name Type Description
currency string Currency
balance number Balance
available number Available balance
order number Order balance
borrowed number Borrowed balance
accrued_interest number Accrued interest

private/margin/transfer

Request Sample

{
   "id": 11,
   "method": "private/margin/transfer",
   "params": {
       "currency": "BTC",
       "from": "SPOT",
       "to": "MARGIN",
       "amount": 1
   },
   "nonce": 1607930374993,
}

Response Sample

{
   "id": 11,
   "method": "private/margin/transfer",
   "code": 0
}

Transfers funds between margin and spot wallet.

Request Params

Name Type Required Description
currency string Y Transfer currency, e.g. BTC, CRO
from string Y SPOT or MARGIN
to string Y SPOT or MARGIN
amount number Y The amount to be transferred

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/margin/borrow

Request Sample

{
   "id": 11,
   "method": "private/margin/borrow",
   "params": {
       "currency": "BTC",
       "amount": 2
   },
   "nonce": 1607930374993,
}

Response Sample

{
   "id": 11,
   "method": "private/margin/borrow",
   "code": 0
}

Borrow by specific amount and currency.

Request Params

Name Type Required Description
currency string Y Borrow currency, e.g. BTC, CRO
amount number Y The amount to be borrowed

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/margin/repay

Request Sample

{
   "id": 11,
   "method": "private/margin/repay",
   "params": {
       "currency": "BTC",
       "amount": 2
   },
   "nonce": 1607930374993,
}

Response Sample

{
   "id": 11,
   "method": "private/margin/repay",
   "code": 0
}

Repay by specific amount and currency.

Request Params

Name Type Required Description
currency string Y Repay currency, e.g. BTC, CRO
amount number Y The amount to be rapaid

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/margin/get-transfer-history

Request Sample

{
   "id": 11,
   "method": "private/margin/get-transfer-history",
   "params": {
       "direction": "IN",
       "currency": "BTC",
       "page_size": 1,
       "page": 0,
       "start_ts": 1488851410000,
       "end_ts": 1607939952520
   },
   "nonce": 1587523073344
}

Response Sample

{
   "id": 11,
   "method": "private/margin/get-transfer-history",
   "code": 0,
   "result": {
       "transfer_list": [{
           "direction": "IN",
           "time": 1607939938002,
           "amount": "11",
           "status": "COMPLETED",
           "information": "From Spot Wallet",
           "currency": "USDT"
       }, {
           "direction": "IN",
           "time": 1607939699671,
           "amount": "122",
           "status": "COMPLETED",
           "information": "From Spot Wallet",
           "currency": "USDT"
       }]
   }
}

Get the transfer history between the Spot and Margin Wallet.

Request Params

Name Type Required Description
direction string Y Transfer direction into or out of Margin Wallet E.g. IN or OUT
currency string N Currency being transferred E.g. BTC, CRO or omit for 'all'
start_ts long N Default is 24 hours ago from current timestamp
end_ts long N Default is current timestamp
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

An array of transfer_list, consisting of:

Name Type Description
direction string Transfer direction into or out of Margin Wallet E.g. IN or OUT
time long Transfer creation time (Unix timestamp)
amount string Amount transferred
status string Indicates status of the transfer
information string Text description of the transfer in relation to the Spot Wallet
currency string Currency E.g. BTC, USDT

private/margin/get-borrow-history

Request Sample

{
   "id": 11,
   "method": "private/margin/get-borrow-history",
   "params": {
       "currency": "USDT",
       "page_size": 1,
       "page": 0,
       "start_ts": 1488851410000,
       "end_ts": 1607939952520
   },
   "nonce": 1587523073344
}

Response Sample

{
   "id": 11,
   "method": "private/margin/get-borrow-history",
   "code": 0,
   "result": {
       "borrow_list": [{
           "loan_id": "1011831376987895040",
           "currency": "USDT",
           "loan_amount": "717.07260818",
           "borrow_time": 1607991724898,
           "status": "ACTIVE"
       }, {
           "loan_id": "1010094184247490977",
           "currency": "USDT",
           "loan_amount": "266",
           "borrow_time": 1607939952520,
           "status": "ACTIVE"
       }]
   }
}

Get the borrow history in the Margin Wallet.

Request Params

Name Type Required Description
currency string N Currency being borrowed E.g. BTC, CRO or omit for 'all'
start_ts long N Default is 24 hours ago from current timestamp
end_ts long N Default is current timestamp
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

Applies To

REST Websocket (User API)

REST Method

POST

Response Attributes

An array of borrow_list, consisting of:

Name Type Description
loan_id string Unique identifier for the loan
currency string Currency E.g. BTC, USDT
loan_amount string Amount borrowed
borrow_time long Loan creation time (Unix timestamp)
status string Indicates status of the loan E.g. ACTIVE, PAID

private/margin/get-interest-history

Request Sample

{
     "id": 11,
     "method": "private/margin/get-interest-history",
     "params": {
         "currency": "USDT",
         "page_size": 1,
         "page": 0,
         "start_ts": 1488851410000,
         "end_ts": 1607939952520
     },
     "nonce": 1587523073344
 }

Response Sample

{
   "id": 11,
   "method": "private/margin/get-interest-history",
   "code": 0,
   "result": {
       "list": [{
           "loan_id": "1011842673839976993",
           "currency": "USDT",
           "interest": "0.0433491",
           "time": 1607992061571,
           "stake_amount": "10000",
           "interest_rate": "0.00002167"
       }]
  }
}

Get the history of interest accrued for loans borrowed.

Request Params

Name Type Required Description
currency long N
start_ts long N Default is 24 hours ago from the current timestamp. Max time range is 1 month.
end_ts long N Default is current timestamp
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

Applies To

REST Websocket (User API)

REST Method

POST

Response Attributes

An array of list, consisting of:

Name Type Description
loan_id string Unique identifier for the loan
currency string Currency E.g. BTC, USDT
interest string Interest amount accrued
time long Interest accrued time
stake_amount string Amount of CRO staked. Interest rate depends on CRO staked.
interest_rate string Hourly interest rate

private/margin/get-repay-history

Request Sample

{
   "id": 11,
   "method": "private/margin/get-repay-history",
   "params": {
       "currency": "BTC",
       "page_size": 1,
       "page": 0,
       "start_ts": 1488851410000,
       "end_ts": 1607939952520
   },
   "nonce": 1587523073344
}

Response Sample

{
   "id": 11,
   "method": "private/margin/get-repay-history",
   "code": 0,
   "result": {
       "repay_list": [{
           "repay_id": "995130146206694272",
           "currency": "BTC",
           "principle_amount": "10.0439503",
           "total_interest": "0.0007533",
           "repay_amount": "10.0447036",
           "repay_time": 1607493989434,
           "status": "CONFIRMED"
       }]
  }
}

Get history of repayment to loans taken out.

Request Params

Name Type Required Description
currency string N Currency of loan that was repaid E.g. BTC, CRO or omit for 'all'
start_ts long N Default is 24 hours ago from the current timestamp.
end_ts long N Default is current timestamp
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

Applies To

REST Websocket (User API)

REST Method

POST

Response Attributes

An array of repay_list, consisting of:

Name Type Description
repay_id string Unique identifier for the repayment
currency string Currency of the repayment E.g. BTC, USDT
principle_amount string Amount borrowed
total_interest long Total interest accrued
repay_amount string Total amount repaid
repay_time long Time that the repaid occurred
status string Status of the repayment E.g. CONFIRMED

private/margin/get-liquidation-history

Request Sample

{
   "id": 11,
   "method": "private/margin/get-liquidation-history",
   "params": {
       "liquidation_status": "MARGIN_CALL",
       "page_size": 1,
       "page": 0,
       "start_ts": 1488851410000,
       "end_ts": 1607939952520
   },
   "nonce": 1587523073344
}

Response Sample

{
   "id": 11,
   "method": "private/margin/get-liquidation-history",
   "code": 0,
   "result": {
       "list": [{
           "time": 1606295944996,
           "liquidation_status": "COMPLETED",
           "email_status": 1,
           "margin_level": "NORMAL",
           "message": "Your Margin Wallet has been liquidated because your Margin Score dropped to or below 1.1.",
           "message_code": 2
       }, {
           "time": 1606275158800,
           "liquidation_status": "MARGIN_CALL",
           "email_status": 1,
           "margin_level": "MARGIN_CALL",
           "message": "Please repay your loan or transfer more funds to your Margin Wallet to prevent liquidation of your Margin Wallet.",
           "message_code": 1
       }]
   }
}

Get history of margin calls and liquidation events.

Request Params

Name Type Required Description
liquidation_status string N Filter by whether a margin call has occurred or a liquidation event has occurred E.g. MARGIN_CALL, COMPLETED
start_ts long N Default is 24 hours ago from the current timestamp.
end_ts long N Default is current timestamp
Max date range between start_ts and end_ts: 90 days
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

Applies To

REST Websocket (User API)

REST Method

POST

Response Attributes

An array of list, consisting of:

Name Type Description
time long Event history time for a margin call or liquidation event
liquidation_status string Liquidation status E.g. MARGIN_CALL is when a margin call has been issued, COMPLETED is when a liquidation event has completed
email_status int 1: Email sent, otherwise email not sent
margin_level string Text description of the Margin Score E.g. NORMAL means the Margin Score is > 1.30 MARGIN_CALL means 1.10 < Margin Score ≤ 1.30 LIQUIDATION means Margin Score ≤ 1.10
message string Text description of the event

private/margin/get-liquidation-orders

Request Sample

{
   "id": 11,
   "method": "private/margin/get-liquidation-orders",
   "params": {
       "page_size": 1,
       "page": 0,
       "start_ts": 1488851410000,
       "end_ts": 1607939952520
   },
   "nonce": 1587523073344
}

Response Sample

{
   "id": 11,
   "method": "private/margin/get-liquidation-orders",
   "code": 0,
   "result": {
       "order_list": [{
           "status": "FILLED",
           "side": "SELL",
           "price": 0.0,
           "quantity": 0.001138,
           "order_id": "954930432466455584",
           "client_oid": "LQ: 1606275158391",
           "create_time": 1606295944606,
           "update_time": 1606295944707,
           "type": "MARKET",
           "instrument_name": "BTC_USDT",
           "avg_price": 15.0,
           "cumulative_quantity": 0.001138,
           "cumulative_value": 0.01707,
           "fee_currency": "USDT",
           "exec_inst": "",
           "time_in_force": "GOOD_TILL_CANCEL"
       }]
   }
}

Get history of margin calls and liquidation events.

Request Params

Name Type Required Description
start_ts long N Default is 24 hours ago from the current timestamp.
end_ts long N Default is current timestamp
Max date range between start_ts and end_ts: 30 days
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

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 Liquidation Order ID
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. 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
time_in_force string GOOD_TILL_CANCEL
FILL_OR_KILL
IMMEDIATE_OR_CANCEL
exec_inst string Empty or POST_ONLY (Limit Orders Only)

private/margin/create-order

Request Sample

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

// Stop Limit Example

{
   "id": 15,
   "method": "private/margin/create-order",
   "params": {
       "instrument_name": "BTC_USDT",
       "side": "BUY",
       "type": "STOP_LIMIT",
       "quantity": 1,
       "trigger_price": 9000,
       "price": 9100,
       "client_oid": "my_stop_limit_order_0015",
       "time_in_force": "GOOD_TILL_CANCEL"
   },
   "nonce": "1598070206891”
}

Response Sample

{
  "id": 11,
  "method": "private/margin/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.margin.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, STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT
price number Depends For LIMIT and STOP_LIMIT orders only:
Unit price
quantity number Depends For LIMIT Orders, MARKET, STOP_LOSS, TAKE_PROFIT orders only:
Order Quantity to be Sold
notional number Depends For MARKET (BUY), STOP_LOSS (BUY), TAKE_PROFIT (BUY) orders only:
Amount to spend
client_oid string N Optional Client order ID
time_in_force string N (Limit Orders Only)
Options are:
- GOOD_TILL_CANCEL (Default if unspecified)
- FILL_OR_KILL
- IMMEDIATE_OR_CANCEL
exec_inst string N (Limit Orders Only)
Options are:
- POST_ONLY
- Or leave empty
trigger_price number N Used with STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, and TAKE_PROFIT_LIMIT orders.
Dictates when order will be triggered


Here are the mandatory parameters based on order type:

Type Side Additional Mandatory Parameters
LIMIT Both quantity, price
MARKET BUY notional or quantity, mutually exclusive
MARKET SELL quantity
STOP_LIMIT Both price, quantity, trigger_price
TAKE_PROFIT_LIMIT Both price, quantity, trigger_price
STOP_LOSS BUY notional, trigger_price
STOP_LOSS SELL quantity, trigger_price
TAKE_PROFIT BUY notional, trigger_price
TAKE_PROFIT SELL quantity, trigger_price


Helpful information:


To create trigger orders against market price:

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/margin/cancel-order

Request Sample

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

Response Sample

{
  "id": 11,
  "method": "private/margin/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.margin.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/margin/cancel-all-orders

Request Sample

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

Response Sample

{
  "id": 12,
  "method": "private/margin/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.margin.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/margin/get-order-history

Request Sample

{
    "id": 12,
    "method": "private/margin/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/margin/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",
        "time_in_force": "GOOD_TILL_CANCEL"
      },
      {
        "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",
        "time_in_force": "GOOD_TILL_CANCEL"
      }
    ]
  }
}

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.

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

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.

You will receive an INVALID_DATE_RANGE error if the difference exceeds the maximum duration.

For users looking to pull longer historical order data, users can create a loop to make a request for each 24-period from the desired start to end time.

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, STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT
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)
time_in_force string - GOOD_TILL_CANCEL
- FILL_OR_KILL
- IMMEDIATE_OR_CANCEL
exec_inst string Empty or POST_ONLY (Limit Orders Only)
trigger_price number Used for trigger-related orders

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

private/margin/get-open-orders

Request Sample

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

Response Sample

{
  "id": 11,
  "method": "private/margin/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",
        "time_in_force": "GOOD_TILL_CANCEL"
      },
      {
        "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",
        "time_in_force": "GOOD_TILL_CANCEL"
      }
    ]
  }
}

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, STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT
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)
time_in_force string - GOOD_TILL_CANCEL
- FILL_OR_KILL
- IMMEDIATE_OR_CANCEL
exec_inst string Empty or POST_ONLY (Limit Orders Only)
trigger_price number Used for trigger-related orders

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

private/margin/get-order-detail

Request Sample

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

Response Sample

{
  "id": 11,
  "method": "private/margin/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",
      "time_in_force": "GOOD_TILL_CANCEL",
      "exec_inst": "POST_ONLY"
    }
  }
}

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, STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT
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)
time_in_force string - GOOD_TILL_CANCEL
- FILL_OR_KILL
- IMMEDIATE_OR_CANCEL
exec_inst string Empty or POST_ONLY (Limit Orders Only)
trigger_price number Used for trigger-related orders

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

private/margin/get-trades

Request Sample

{
    "id": 11,
    "method": "private/margin/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/margin/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.

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

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.

You will receive an INVALID_DATE_RANGE error if the difference exceeds the maximum duration.

For users looking to pull longer historical trade data, users can create a loop to make a request for each 24-period from the desired start to end time.

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
client_order_id string Client Order ID
liquidity_indicator string TAKER
MAKER

Derivatives Transfer API

To enable Derivatives Transfer, you will need to create a Derivative Wallet; please refer to the help article here.

private/deriv/transfer

Request Sample

{
   "id": 11,
   "method": "private/deriv/transfer",
   "params": {
       "currency": "BTC",
       "from": "SPOT",
       "to": "DERIVATIVES",
       "amount": 1
   },
   "nonce": 1607930374993,
}

Response Sample

{
   "id": 11,
   "method": "private/deriv/transfer",
   "code": 0
}

Transfers funds between derivative and spot wallet.

Request Params

Name Type Required Description
currency string Y Transfer currency, e.g. BTC, CRO
from string Y SPOT or DERIVATIVES
to string Y SPOT or DERIVATIVES
amount number Y The amount to be transferred

Applies To

REST

REST Method

POST

Response Attributes

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

private/deriv/get-transfer-history

Request Sample

{
    "id": 11,
    "method": "private/deriv/get-transfer-history",
    "params": {
        "direction": "IN",
        "currency": "BTC",
        "page_size": 1,
        "page": 0,
        "start_ts": 1488851410000,
        "end_ts": 1688851410000
    },
    "nonce": 1587523073344
}

Response Sample

{
  "id": 11,
  "method": "private/deriv/get-transfer-history",
  "code": 0,
  "result": {
    "transfer_list": [
      {
        "direction": "IN",
        "currency": "BTC",
        "time": 1488851410000,
        "amount": 1,
        "status": "COMPLETED",
        "information": "From Spot Wallet"
      },
      {
        "direction": "IN",
        "currency": "BTC",
        "time": 1488851410000,
        "amount": 10,
        "status": "PROCESSING",
        "information": "From Spot Wallet"
      }
    ]
  }
}

Get the transfer history between the Spot and Derivatives Wallet.

Request Params

Name Type Required Description
direction string Y Transfer direction into or out of Derivatives Wallet E.g. IN or OUT
currency string N Currency being transferred E.g. BTC, CRO or omit for 'all'
start_ts long N Default is 24 hours ago from current timestamp
end_ts long N Default is current timestamp
page_size int N Page size (Default: 20, Max: 200)
page int N Page number (0-based)

Applies To

REST

REST Method

POST

Response Attributes

An array of transfer_list, consisting of:

Name Type Description
direction string Transfer direction into or out of Derivatives Wallet E.g. IN or OUT
time long Transfer creation time (Unix timestamp)
amount string Amount transferred
status string Indicates status of the transfer
information string Text description of the transfer in relation to the Spot Wallet
currency string Currency E.g. BTC, USDT

Sub-account API

private/subaccount/get-sub-accounts

Request Sample

{
    "id": 12,
    "method": "private/subaccount/get-sub-accounts",
    "params": {},
    "nonce": 1587846358253
}

Response Sample

{
    "id": 12,
    "method": "private/subaccount/get-sub-accounts",
    "code": 0,
    "result": {
        "sub_account_list": [
            {
                "uuid": "243d3f39-b193-4eb9-1d60-e98f2fc17707",
                "master_account_uuid": "291879ae-b769-4eb3-4d75-3366ebee7dd6",
                "margin_account_uuid": "69c9ab41-5b95-4d75-b769-e45f2fc16507",
                "label": "Sub Account",
                "enabled": true,
                "tradable": true,
                "name": "",
                "email": "[email protected]",
                "mobile_number": "",
                "country_code": "",
                "address": "",
                "margin_access": "DEFAULT",
                "derivatives_access": "DISABLED",
                "create_time": 1620962543792,
                "update_time": 1622019525960,
                "two_fa_enabled": true,
                "kyc_level": "ADVANCED",
                "suspended": false,
                "terminated": false
            }
        ]
    }
}

Get Sub Accounts

Request Params

None

Ensure you keep params: {} for API request consistency.

Applies To

REST

REST Method

POST

Response Attributes

An array of sub_account_list, consisting of:

Name Type Description
uuid string Sub account uuid
master_account_uuid string Master account uuid
margin_account_uuid string (optional) Margin account uuid
label string Sub account label
enabled boolean true or false
tradable boolean true or false
name string Name of sub account
email string Email of sub account
mobile_number string Mobile number of sub account
country_code string Country Code of sub account
address string Address of sub account
margin_access string DEFAULT or DISABLED
derivatives_access string DEFAULT or DISABLED
create_time number Creation timestamp (milliseconds since the Unix epoch)
update_time number Last update timestamp (milliseconds since the Unix epoch)
two_fa_enabled boolean true or false
kyc_level string Kyc Level
suspended boolean true or false
terminated boolean true or false

private/subaccount/get-transfer-history

Request Sample

{
    "id": 12,
    "method": "private/subaccount/get-transfer-history",
    "params": {
        "sub_account_uuid": "243d3f39-b193-4eb9-1d60-e98f2fc17707",
        "direction": "IN",
        "currency": "CRO",
        "start_ts": 1622036629355,
        "end_ts": 1622077885606
    },
    "nonce": 1587846358253
}

Response Sample

{
  "id": 12,
  "method": "private/subaccount/get-transfer-history",
  "code": 0,
  "result": {
        "transfer_list": [
            {
                "direction": "IN",
                "time": 1622077688890,
                "amount": 50,
                "status": "COMPLETED",
                "information": "From Master Spot Wallet",
                "sub_account_uuid": "243d3f39-b193-4eb9-1d60-e98f2fc17707",
                "currency": "CRO",
                "sub_account_label": "Sub Account",
                "from": "MASTER",
                "from_wallet": "SPOT",
                "to": "SUBACCOUNT",
                "to_wallet": "SPOT"
            },
            {
                "direction": "IN",
                "time": 1620979799332,
                "amount": 100,
                "status": "COMPLETED",
                "information": "From Master Spot Wallet",
                "sub_account_uuid": "243d3f39-b193-4eb9-1d60-e98f2fc17707",
                "currency": "CRO",
                "sub_account_label": "Sub Account",
                "from": "MASTER",
                "from_wallet": "SPOT",
                "to": "SUBACCOUNT",
                "to_wallet": "SPOT"
            }
        ]
    }
}

Get the transfer history between the Master Account and Sub-account.

Request Params

Name Type Required Description
sub_account_uuid string Y
direction string Y Transfer direction into or out of Account E.g. IN or OUT
currency string N Currency being transferred E.g. BTC, CRO or omit for 'all'
start_ts long N Default is 24 hours ago from current timestamp
end_ts long N Default is current timestamp
page_size int N Page size (Default: 20, Max: 200)
page int N Page number (0-based)

Applies To

REST

REST Method

POST

Response Attributes

An array of transfer_list, consisting of:

Name Type Description
direction string Transfer direction into or out of Account E.g. IN or OUT
time long Transfer creation time (Unix timestamp)
amount number Amount transferred
status string Indicates status of the transfer
information string Text description of the transfer
currency string Currency E.g. BTC, USDT
sub_account_uuid string
sub_account_label string
from string MASTER or SUBACCOUNT
from_wallet string SPOT or MARGIN
to string MASTER or SUBACCOUNT
to_wallet string SPOT or MARGIN

private/subaccount/transfer

Request Sample

{
    "id": 12,
    "method": "private/subaccount/transfer",
    "params": {
        "from": "MASTER",
        "to": "SUBACCOUNT",
        "sub_account_uuid": "243d3f39-b193-4eb9-1d60-e98f2fc17707",
        "currency": "CRO",
        "amount": "50"
    },
    "nonce": 1587846358253
}

Response Sample

{
  "id": 12,
  "method": "private/subaccount/transfer",
  "code": 0
}

Transfers funds between master and subaccount.

Request Params

Name Type Required Description
currency string Y Transfer currency, e.g. BTC, CRO
from string Y MASTER or SUBACCOUNT
from_wallet string N SPOT or MARGIN (Default: SPOT)
to string Y MASTER or SUBACCOUNT
to_wallet string N SPOT or MARGIN (Default: SPOT)
sub_account_uuid string Y
amount string Y The amount to be transferred

Applies To

REST

REST Method

POST

Response Attributes

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

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:

Important Note

We recommend adding a 1-second sleep after establishing the websocket connection, and before requests are sent.

This will avoid occurrences of rate-limit (`TOO_MANY_REQUESTS`) errors, as the websocket rate limits are pro-rated based on the calendar-second that the websocket connection was opened.

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",
        "time_in_force":"GOOD_TILL_CANCEL"
      }
    ],
    "channel": "user.order.ETH_CRO"
  }
}

For Spot Trading

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, STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT
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
fee_currency string Currency used for the fees (e.g. CRO)
time_in_force string - GOOD_TILL_CANCEL
- FILL_OR_KILL
- IMMEDIATE_OR_CANCEL
exec_inst string Empty or POST_ONLY (Limit Orders Only)
trigger_price number Used for trigger-related orders

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

For Spot Trading

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

For Spot Trading

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)

user.margin.order.{instrument_name}

Request Sample

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

Response Sample

{
  "method": "subscribe",
  "result": {
    "instrument_name": "ETH_CRO",
    "subscription": "user.margin.order.ETH_CRO",
    "channel": "user.margin.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",
        "time_in_force":"GOOD_TILL_CANCEL"
      }
    ],
    "channel": "user.margin.order.ETH_CRO"
  }
}

For Margin Trading

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, STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT
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
fee_currency string Currency used for the fees (e.g. CRO)
time_in_force string - GOOD_TILL_CANCEL
- FILL_OR_KILL
- IMMEDIATE_OR_CANCEL
exec_inst string Empty or POST_ONLY (Limit Orders Only)
trigger_price number Used for trigger-related orders

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

user.margin.trade.{instrument_name}

Request Sample

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

Response Sample

{
  "method": "subscribe",
  "code": 0,
  "result": {
    "instrument_name": "ETH_CRO",
    "subscription": "user.margin.trade.ETH_CRO",
    "channel": "user.margin.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.margin.trade.ETH_CRO"
  }
}

For Margin Trading

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.margin.balance

Request Sample

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

Response Sample

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

For Margin Trading

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)

Common Issues

TOO_MANY_REQUESTS After Websocket Connects

Websocket rate limits are pro-rated based on the calendar-second that the websocket connection was opened.

This means, depending on the fraction of the calendar-second that the connection was established, the rate limit could be pro-rated to a small number.

By adding a 1-second sleep after establishing the websocket connection, and before requests are sent, this will ensure the rate limit is properly reset and sync'd to your session.

This will avoid occurrences of rate-limit (TOO_MANY_REQUESTS) errors.

INVALID_NONCE On All Requests

The nonce should be the UTC Unix timestamp in milliseconds.

If this has been carefully checked, then the issue occurs when the system clock of the client machine is greater than 1 second in the future, or 30 seconds in the past.

Usually, re-syncing with the NTP time server on the client machine will correct the issue.

If the issue persists, you can try deliberately subtracting 5 seconds from the nonce to force it to be 5 seconds in the past, which is still within the 30-second past tolerance.