NAV Navbar
Exchange API v1

javascript python c# java

Introduction

Welcome

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

The Crypto.com Exchange API v1 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.

Notes on Exchange Upgrade and API Versions

Change Logs

Breaking Change Schedule

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

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.

REST API Root Endpoint

UAT Sandbox

REST API

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

Production

REST API

https://api.crypto.com/exchange/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/exchange/v1/user

Websocket (Market Data Subscriptions)

wss://uat-stream.3ona.co/exchange/v1/market

Production

Websocket (User API and Subscriptions)

wss://stream.crypto.com/exchange/v1/user

Websocket (Market Data Subscriptions)

wss://stream.crypto.com/exchange/v1/market

Rate Limits

REST API

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

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

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

Method Limit
public/get-book
public/get-ticker
public/get-trades
public/get-valuations
public/get-candlestick
public/get-insurance		 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.

Request Format

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

Name Type Required Description
id long Y 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_body, api_key, secret) => {
  const { id, method, params, nonce } = request_body;

  function isObject(obj) { return obj !== undefined && obj !== null && obj.constructor == Object; }
  function isArray(obj) { return obj !== undefined && obj !== null && obj.constructor == Array; }
  function arrayToString(obj) { return obj.reduce((a,b) => { return a + (isObject(b) ? objectToString(b) : (isArray(b) ? arrayToString(b) : b)); }, ""); }
  function objectToString(obj) { return (obj == null ? "" : Object.keys(obj).sort().reduce((a, b) => { return a + b + (isArray(obj[b]) ? arrayToString(obj[b]) : (isObject(obj[b]) ? objectToString(obj[b]) : obj[b])); }, "")); }

  const paramsString = objectToString(params);

  console.log(paramsString);

  const sigPayload = method + id + api_key + paramsString + nonce;
  request_body.sig = crypto.HmacSHA256(sigPayload, secret).toString(crypto.enc.Hex);
};

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 time

API_KEY = "API_KEY"
SECRET_KEY = "SECRET_KEY"

req = {
    "id": 14,
    "method": "private/create-order-list",
    "api_key": API_KEY,
    "params": {
        "contingency_type": "LIST",
        "order_list": [
            {
                "instrument_name": "ONE_USDT",
                "side": "BUY",
                "type": "LIMIT",
                "price": "0.24",
                "quantity": "1.0"
            },
            {
                "instrument_name": "ONE_USDT",
                "side": "BUY",
                "type": "STOP_LIMIT",
                "price": "0.27",
                "quantity": "1.0",
                "trigger_price": "0.26"
            }
        ]
    },
    "nonce": int(time.time() * 1000)
}

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

MAX_LEVEL = 3


def params_to_str(obj, level):
    if level >= MAX_LEVEL:
        return str(obj)

    return_str = ""
    for key in sorted(obj):
        return_str += key
        if obj[key] is None:
            return_str += 'null'
        elif isinstance(obj[key], list):
            for subObj in obj[key]:
                return_str += params_to_str(subObj, level + 1)
        else:
            return_str += str(obj[key])
    return return_str


if "params" in req:
    param_str = params_to_str(req['params'], 0)

payload_str = req['method'] + str(req['id']) + req['api_key'] + param_str + str(req['nonce'])

req['sig'] = hmac.new(
    bytes(str(SECRET_KEY), 'utf-8'),
    msg=bytes(payload_str, '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
  // When params contains List value, please refer to the other language's example code for the correct implementation of ParamString
  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 java.math.BigDecimal;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.List;
import java.util.Map;
import java.util.TreeMap;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.apache.commons.codec.binary.Hex;

public class SigningUtil {

  private static final String HMAC_SHA256 = "HmacSHA256";
  private static final int MAX_LEVEL = 3;

  public static boolean verifySignature(ApiRequestJson apiRequestJson, String secret) {
    try {
      return genSignature(apiRequestJson, secret).equalsIgnoreCase(apiRequestJson.getSig());
    } catch (Exception e) {
      return false;
    }
  }

  @SuppressWarnings("unchecked")
  public static String getParamString(final Object paramObject) {
    StringBuilder sb = new StringBuilder();
    appendParamString(sb, paramObject, 0);
    return sb.toString();
  }


  @SuppressWarnings("unchecked")
  private static void appendParamString(final StringBuilder paramsStringBuilder, final Object paramObject, final int level) {
    if (level >= MAX_LEVEL) {
      paramsStringBuilder.append(paramObject.toString());
      return;
    }

    if (paramObject instanceof Map) {
      TreeMap<String, Object> params = new TreeMap<>((Map) paramObject);
      for (Map.Entry<String, Object> entry : params.entrySet()) {
        if (entry.getValue() instanceof Double) {
          paramsStringBuilder
              .append(entry.getKey())
              .append((new BigDecimal(entry.getValue().toString()))
                  .stripTrailingZeros()
                  .toPlainString());
        } else if (entry.getValue() instanceof List || entry.getValue() instanceof Map) {
          paramsStringBuilder
              .append(entry.getKey());
          appendParamString(paramsStringBuilder, entry.getValue(), level + 1);
        } else {
          paramsStringBuilder
              .append(entry.getKey())
              .append(entry.getValue());
        }
      }
    } else if (paramObject instanceof List) {
      List list = (List) paramObject;
      for (Object o : list) {
        appendParamString(paramsStringBuilder, o, level + 1);
      }
    } else {
      paramsStringBuilder.append(paramObject.toString());
    }
  }

  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) {
      paramsString += getParamString(apiRequestJson.getParams());
    }

    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:

Request Format

All prices must be strings, and must be wrapped in double quotes.

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
201 500 NO_POSITION No position
202 400 ACCOUNT_IS_SUSPENDED Account is suspended
203 500 ACCOUNTS_DO_NOT_MATCH Accounts do not match
204 400 DUPLICATE_CLORDID Duplicate client order id
205 500 DUPLICATE_ORDERID Duplicate order id
206 500 INSTRUMENT_EXPIRED Instrument has expired
207 400 NO_MARK_PRICE No mark price
208 400 INSTRUMENT_NOT_TRADABLE Instrument is not tradable
209 400 INVALID_INSTRUMENT Instrument is invalid
210 500 INVALID_ACCOUNT Account is invalid
211 500 INVALID_CURRENCY Currency is invalid
212 500 INVALID_ORDERID Invalid order id
213 400 INVALID_ORDERQTY Invalid order quantity
214 500 INVALID_SETTLE_CURRENCY Invalid settlement currency
215 500 INVALID_FEE_CURRENCY Invalid fee currency
216 500 INVALID_POSITION_QTY Invalid position quantity
217 500 INVALID_OPEN_QTY Invalid open quantity
218 400 INVALID_ORDTYPE Invalid order_type
219 500 INVALID_EXECINST Invalid exec_inst
220 400 INVALID_SIDE Invalid side
221 400 INVALID_TIF Invalid time_in_force
222 400 STALE_MARK_PRICE Stale mark price
223 400 NO_CLORDID No client order id
224 400 REJ_BY_MATCHING_ENGINE Rejected by matching engine
225 400 EXCEED_MAXIMUM_ENTRY_LEVERAGE Exceeds maximum entry leverage
226 400 INVALID_LEVERAGE Invalid leverage
227 400 INVALID_SLIPPAGE Invalid slippage
228 400 INVALID_FLOOR_PRICE Invalid floor price
229 400 INVALID_REF_PRICE Invalid ref price
230 400 INVALID_TRIGGER_TYPE Invalid ref price type
301 500 ACCOUNT_IS_IN_MARGIN_CALL Account is in margin call
302 500 EXCEEDS_ACCOUNT_RISK_LIMIT Exceeds account risk limit
303 500 EXCEEDS_POSITION_RISK_LIMIT Exceeds position risk limit
304 500 ORDER_WILL_LEAD_TO_IMMEDIATE_LIQUIDATION Order will lead to immediate liquidation
305 500 ORDER_WILL_TRIGGER_MARGIN_CALL Order will trigger margin call
306 500 INSUFFICIENT_AVAILABLE_BALANCE Insufficient available balance
307 500 INVALID_ORDSTATUS Invalid order status
308 400 INVALID_PRICE Invalid price
309 500 MARKET_IS_NOT_OPEN Market is not open
310 500 ORDER_PRICE_BEYOND_LIQUIDATION_PRICE Order price beyond liquidation price
311 500 POSITION_IS_IN_LIQUIDATION Position is in liquidation
312 500 ORDER_PRICE_GREATER_THAN_LIMITUPPRICE Order price is greater than the limit up price
313 500 ORDER_PRICE_LESS_THAN_LIMITDOWNPRICE Order price is less than the limit down price
314 400 EXCEEDS_MAX_ORDER_SIZE Exceeds max order size
315 400 FAR_AWAY_LIMIT_PRICE Far away limit price
316 500 NO_ACTIVE_ORDER No active order
317 500 POSITION_NO_EXIST Position does not exist
318 400 EXCEEDS_MAX_ALLOWED_ORDERS Exceeds max allowed orders
319 400 EXCEEDS_MAX_POSITION_SIZE Exceeds max position size
320 500 EXCEEDS_INITIAL_MARGIN Exceeds initial margin
321 500 EXCEEDS_MAX_AVAILABLE_BALANCE Exceeds maximum availble balance
401 400 ACCOUNT_DOES_NOT_EXIST Account does not exist
406 500 ACCOUNT_IS_NOT_ACTIVE Account is not active
407 500 MARGIN_UNIT_DOES_NOT_EXIST Margin unit does not exist
408 400 MARGIN_UNIT_IS_SUSPENDED Margin unit is suspended
409 500 INVALID_USER Invalid user
410 500 USER_IS_NOT_ACTIVE User is not active
411 500 USER_NO_DERIV_ACCESS User does not have derivative access
412 500 ACCOUNT_NO_DERIV_ACCESS Account does not have derivative access
501 500 EXCEED_MAXIMUM_EFFECTIVE_LEVERAGE Exceeds maximum effective leverage
604 500 INVALID_COLLATERAL_PRICE Invalid collateral price
605 500 INVALID_MARGIN_CALC Invalid margin calculation
606 500 EXCEED_ALLOWED_SLIPPAGE Exceed allowed slippage
40001 400 BAD_REQUEST Bad request
40002 400 METHOD_NOT_FOUND Method not found
40003 400 INVALID_REQUEST Invalid request
40004 400 MISSING_OR_INVALID_ARGUMENT Required argument is blank or missing
40005 400 INVALID_DATE Invalid date
40006 400 DUPLICATE_REQUEST Duplicate request received
40101 401 UNAUTHORIZED Not authenticated, or key/signature incorrect
40102 400 INVALID_NONCE Nonce value differs by more than 30 seconds from server
40103 401 IP_ILLEGAL IP address not whitelisted
40104 401 USER_TIER_INVALID Disallowed based on user tier
40107 400 EXCEED_MAX_SUBSCRIPTIONS Session subscription limit has been exceeded
40401 200 NOT_FOUND Not found
40801 408 REQUEST_TIMEOUT Request has timed out
42901 429 TOO_MANY_REQUESTS Requests have exceeded rate limits
43005 500 POST_ONLY_REJ Rejected POST_ONLY create-order request (normally happened when exec_inst contains POST_ONLY but time_in_force is NOT GOOD_TILL_CANCEL)
50001 400 ERR_INTERNAL Internal error

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.

Unified Wallet and System Label

Crypto.com Exchange has been upgraded from 1 account per wallet (SPOT, MARGIN, DERIVATIVES) into an unified wallet, such that you can use any account to perform margin trading and derivative trading with the respective entitlement granted.

In the transition period, you may have balances in the account which is formerly margin account, or formerly derivatives accounts. If you wish to continue using the fund for these account, you can specify the usage of these accounts respectively by

For Master Account API Key

system_label Meaning
ONEEX Use the balance from the master account.
FORMER_SPOT Use the balance from the master account.
FORMER_MARGIN Use the balance from the formerly master margin account.
FORMER_DERIVATIVES Use the balance from the formerly master derivatives account.

For Sub Account API Key

system_label Meaning
ONEEX Use the balance from the sub-account.
FORMER_SPOT Use the balance from the sub-account.
FORMER_MARGIN Use the balance from the formerly margin sub-account.
FORMER_DERIVATIVES Use the balance from the formerly derivatives sub-account.

Reference and Market Data API

public/get-instruments

Request Sample

N/A

Response Sample

{
  "id": 1,
  "method":"public/get-instruments",
  "code": 0,
  "result":{
    "data":[
      {
        "symbol":"BTCUSD-PERP",
        "inst_type":"PERPETUAL_SWAP",
        "display_name":"BTCUSD Perpetual",
        "base_ccy":"BTC",
        "quote_ccy":"USD",
        "quote_decimals":2,
        "quantity_decimals":4,
        "price_tick_size":"0.5",
        "qty_tick_size":"0.0001",
        "max_leverage":"50",
        "tradable":true,
        "expiry_timestamp_ms":1624012801123,
        "underlying_symbol": "BTCUSD-INDEX"
      }
    ]
  }
}

Provides information on all supported instruments (e.g. BTCUSD-PERP).

Applies To

REST

REST Method

GET

Response Attributes

An array, consisting of:

Name Type Description
symbol string e.g. BTCUSD-PERP
inst_type string e.g. PERPETUAL_SWAP
display_name string e.g. BTCUSD Perpetual
base_ccy string Base currency, e.g. BTC
quote_ccy string Quote currency, e.g. USD
quote_decimals number Minimum decimal place for price field
quantity_decimals number Minimum decimal place for qty field
price_tick_size string Minimum price tick size
qty_tick_size string Minimum trading quantity / tick size
max_leverage string Max leverage of the product
tradable boolean True or false
expiry_timestamp_ms number Expiry timestamp in millisecond
underlying_symbol string Underlying symbol

public/get-book

Request Sample

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

Response Sample

{
  "code":0,
  "method":"public/get-book",
  "result": {
    "depth": 10,
    "data": [{
      "asks": [
        ["50126.000000", "0.400000", "0"],
        ["50130.000000", "1.279000", "0"],
        ["50136.000000", "1.279000", "0"],
        ["50137.000000", "0.800000", "0"],
        ["50142.000000", "1.279000", "0"],
        ["50148.000000", "2.892900", "0"],
        ["50154.000000", "1.279000", "0"],
        ["50160.000000", "1.133000", "0"],
        ["50166.000000", "3.090700", "0"],
        ["50172.000000", "1.279000", "0"]
      ],
      "bids": [
        ["50113.500000", "0.400000", "0"],
        ["50113.000000", "0.051800", "0"],
        ["50112.000000", "1.455300", "0"],
        ["50106.000000", "1.174800", "0"],
        ["50100.500000", "0.800000", "0"],
        ["50100.000000", "1.455300", "0"],
        ["50097.500000", "0.048000", "0"],
        ["50097.000000", "0.148000", "0"],
        ["50096.500000", "0.399200", "0"],
        ["50095.000000", "0.399200", "0"]
      ]
    }],
    "instrument_name": "BTCUSD-PERP"
  }
}

Fetches the public order book for a particular instrument and depth.

Request Params

Name Type Required Description
instrument_name string Y e.g. BTCUSD-PERP
depth string Y Number of bids and asks to return (up to 50)

Applies To

REST

REST Method

GET

Response Attributes

Name Type Description
instrument_name string e.g. BTCUSD-PERP
depth string Number of bids and asks to return (up to 50)
data array See below

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

Note: Known issue: Number of Orders currently returns 0

public/get-candlestick

Request Sample

https://{URL}/public/get-candlestick?instrument_name=BTCUSD-PERP&timeframe=M5

Response Sample

{
  "id": 1,
  "method": "public/get-candlestick",
  "code": 0,
  "result": {
    "interval": "M5",
    "data": [{
      "o": "50508.500000",    // Open price
      "h": "50548.500000",    // High price
      "l": "50172.500000",    // Low price
      "c": "50202.000000",    // Close price
      "v": "17.203200",       // Volume
      "t": 1613544000000      // Start time
    }
    ],
    "instrument_name": "BTCUSD-PERP"
  }
}

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

Request Params

Name Type Required Description
instrument_name string Y e.g. BTCUSD-PERP
timeframe string N The period value as show below. Default is M1.
count number N Default is 25
start_ts number N Default timestamp is 1 day ago (Unix timestamp)
end_ts number N Default timestamp is current time (Unix timestamp)

period can be:

Lagacy format is still supported until further notice.

Applies To

REST

Response Attributes

Name Type Description
instrument_name string e.g. BTCUSD-PERP
interval string The period (e.g. M5)
data array See below

data consists of:

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

public/get-trades

Request Sample

https://{URL}/public/get-trades?instrument_name=BTCUSD-PERP&count=5

Response Sample

{
  "id": 1,
  "method": "public/get-trades",
  "code": 0,
  "result": {
    "data": [{
      "d": "15281981878",          // Trade ID
      "t": 1613547060925,          // Trade timestamp milliseconds
      "tn": "1613547060925523623", // Trade timestamp nanoseconds
      "q": "0.181900",             // Quantity
      "p": "50772.000000",         // Price
      "s": "SELL",                 // Side
      "i": "BTCUSD-PERP"           // Instrument name
    }]
  }
}

Fetches the public trades for a particular instrument.

Request Params

Name Type Required Description
instrument_name string Y e.g. BTCUSD-PERP
count number N The maximum number of trades to be retrieved.
Default: 25
Max: 150
start_ts number or string N Start time in Unix time format (inclusive).
Default: end_time - 1 day.
Nanosecond is recommended for accurate pagination
end_ts number or string N End time in Unix time format (exclusive)
Default: current system timestamp.
Nanosecond is recommended for accurate pagination

Applies To

REST

REST Method

GET

Response Attributes

Name Type Description
d string of number Trade ID
t number Trade timestamp in milliseconds
tn string of number Trade timestamp in nanoseconds
q number Trade quantity
p number Trade price
s string Side (BUY or SELL). Side is the side of the taker order
i string Instrument name e.g. BTCUSD-PERP

public/get-tickers

Request Sample

https://{URL}/public/get-tickers?instrument_name=BTCUSD-PERP

Response Sample

{
  "id": -1,
  "method": "public/get-tickers",
  "code": 0,
  "result": {
    "data": [{
      "h": "51790.00",        // Price of the 24h highest trade
      "l": "47895.50",        // Price of the 24h lowest trade, null if there weren't any trades
      "a": "51174.500000",    // The price of the latest trade, null if there weren't any trades
      "i": "BTCUSD-PERP",     // Instrument name
      "v": "879.5024",        // The total 24h traded volume
      "vv": "26370000.12",    // The total 24h traded volume value (in USD)
      "oi": "12345.12",       // Open interest
      "c": "0.03955106",      // 24-hour price change, null if there weren't any trades
      "b": "51170.000000",    // The current best bid price, null if there aren't any bids
      "k": "51180.000000",    // The current best ask price, null if there aren't any asks
      "t": 1613580710768
    }]
  }
}

Fetches the public tickers for all or a particular instrument.

Request Params

Name Type Required Description
instrument_name string N e.g. BTCUSD-PERP

Applies To

REST

REST Method

GET

Response Attributes

Name Type Description
h string Price of the 24h highest trade
l string Price of the 24h lowest trade, null if there weren't any trades
a string The price of the latest trade, null if there weren't any trades
i string Instrument name
v string The total 24h traded volum
vv string The total 24h traded volume value (in USD)
oi string The open interest
c string 24-hour price change, null if there weren't any trades
b string The current best bid price, null if there aren't any bids
k string The current best ask price, null if there aren't any asks
t number Trade timestamp

public/get-valuations

Request Sample

https://{URL}/public/get-valuations?instrument_name=BTCUSD-INDEX&valuation_type=index_price&count=1

Response Sample

{
  "id": 1,
  "method": "public/get-valuations",
  "code": 0,
  "result": {
    "data": [{
      "v": "50776.73000",
      "t": 1613547318000
    }],
    "instrument_name": "BTCUSD-INDEX"
  }
}

Fetches certain valuation type data for a particular instrument.

Request Params

Name Type Required Description
instrument_name string Y e.g. BTCUSD-INDEX
valuation_type string Y List of available types:
a. index_price: returns per minute data of underlying reference price of the instrument.
b. mark_price: returns per minute data of mark price of the instrument.
c. funding_hist: returns hourly data of the funding rate settled in past hourly settlement.
d. funding_rate: returns per minute data of current hourly funding rate that will settle at the end of each hour of current 4-hour interval.
e. estimated_funding_rate: returns per minute data of estimated funding rate for the next interval.
count number N Default is 25
start_ts number N Default timestamp is 30 days ago for funding_hist, and 1 day ago for other valuation_type (Unix timestamp)
end_ts number N Default timestamp is current time (Unix timestamp)

Applies To

REST

REST Method

GET

Response Attributes

Name Type Description
instrument_name string e.g. BTCUSD-INDEX
data array See below

data consists of:

Name Type Description
v string Value
t long Timestamp

public/get-expired-settlement-price

Request Sample

https://{URL}/public/get-expired-settlement-price?instrument_type=FUTURE&page=1

Response Sample

{
  "id": -1,
  "method": "public/get-expired-settlement-price",
  "code": 0,
  "result": {
    "data": [{
      "i": "BTCUSD-210528m2",
      "x": 1622145600000,
      "v": "50776.73000",
      "t": 1622145540000
    },
      {
        "i": "BTCUSD-210528m3",
        "x": 1622160000000,
        "v": "38545.570000",
        "t": 1622159940000
      }]
  }
}

Fetches settlement price of expired instruments.

Request Params

Name Type Required Description
instrument_type string Y FUTURE
page number N Default is 1

Applies To

REST

REST Method

GET

Response Attributes

Name Type Description
i string Instrument name
x long Expiry timestamp (millisecond)
v string Value
t long Timestamp

public/get-insurance

Request Sample

https://{URL}/public/get-insurance?instrument_name=USD&count=1

Response Sample

{
  "id": 1,
  "method": "public/get-insurance",
  "code": 0,
  "result": {
    "data": [{
      "v": "50000000",
      "t": 1613539503965
    }],
    "instrument_name": "USD"
  }
}

Fetches balance of Insurance Fund for a particular currency.

Request Params

Name Type Required Description
instrument_name string Y e.g. USD
count number N Default is 25
start_ts number N Default timestamp is 1 day ago (Unix timestamp)
end_ts number N Default timestamp is current time (Unix timestamp)

Applies To

REST

REST Method

GET

Response Attributes

Name Type Description
instrument_name string e.g. USD
data array See below

data consists of:

Name Type Description
v string Value
t long Timestamp

Account Balance and Position API

private/user-balance

Request Sample

{
  "id":11,
  "method": "private/user-balance",
  "params": {},
  "nonce": 1611022832613
}

Response Sample

{
  "id": 11,
  "method": "private/user-balance",
  "code": 0,
  "result": {
    "data": [
      {
        "total_available_balance": "7109.11298582",
        "total_margin_balance": "294.30450677",
        "total_initial_margin": "486.31273202",
        "total_position_im": "486.31273202",
        "total_haircut": "10.01",
        "total_maintenance_margin": "294.30450677",
        "total_position_cost": "14517.54641301",
        "total_cash_balance": "7890.00320721",
        "total_collateral_value": "7651.18811483",
        "total_session_unrealized_pnl": "-55.76239701",
        "instrument_name": "USD",
        "total_session_realized_pnl": "0.00000000",
        "is_liquidating": false,
        "total_effective_leverage": "1.90401230",
        "position_limit": "3000000.00000000",
        "used_position_limit": "40674.69622001",
        "position_balances": [
          {
            "instrument_name": "CRO",
            "quantity": "24422.72427884",
            "market_value": "4776.107959969951",
            "collateral_eligible": "true",
            "haircut": "0.95",
            "collateral_amount": "4537.302561971453",
            "max_withdrawal_balance": "24422.72427884",
            "reserved_qty" : "0.00000000"
          },
          {
            "instrument_name": "USD",
            "quantity": "3113.50747209",
            "market_value": "3113.50747209",
            "collateral_eligible": "true",
            "haircut": "1.0",
            "collateral_amount": "3113.50747209",
            "max_withdrawal_balance": "3113.50747209",
            "reserved_qty" : "0.00000000"
          },
          {
            "instrument_name": "USDT",
            "quantity": "0.19411607",
            "market_value": "0.19389555414448",
            "collateral_eligible": "true",
            "haircut": "0.975",
            "collateral_amount": "0.18904816529086801",
            "max_withdrawal_balance": "0.19411607",
            "reserved_qty" : "0.00000000"
          },
          {
            "instrument_name": "DAI",
            "quantity": "0.19387960",
            "market_value": "0.1938796",
            "collateral_eligible": "true",
            "haircut": "0.975",
            "collateral_amount": "0.18903261000000002",
            "max_withdrawal_balance": "0.1938796",
            "reserved_qty" : "0.00000000"
          }
        ]
      }
    ]
  }
}

Returns the user's wallet balance.

Request Params

Note: 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 consisting of:

Name Type Description
instrument_name string Instrument name of the balance e.g. USD
total_available_balance string Balance that user can open new order (Margin Balance - Initial Margin)
total_margin_balance string Positive cash balance on eligible collateral tokens + Negative balance on all tokens + Unrealised PnL - Fee reserves
total_initial_margin string Total margin requirement to support positions and all open orders IM and haircut from risk asset holdings
Total sum of total_position_im + total_haircut
total_position_im string initial margin requirement to support open positions and orders
total_haircut string the total haircut on eligible collateral token assets
total_maintenance_margin string Total maintenance margin requirement for all positions
total_position_cost string Position value in USD
total_cash_balance string Wallet Balance (Deposits - Withdrawals + Realized PnL - Fees)
total_collateral_value string Collateral Value
total_session_unrealized_pnl string Current unrealized profit and loss from all open positions (calculated with Mark Price and Avg Price)
total_session_realized_pnl string Current realized profit and loss from all open positions (calculated with Mark Price and Avg Price)
is_liquidating boolean Describes whether the account is under liquidation
total_effective_leverage string The actual leverage used (all open positions combined), i.e. position size / margin balance
position_limit string Maximum position size allowed (for all open positions combined)
used_position_limit string Combined position size of all open positions + order exposure on all instruments
position_balances array Collateral balances as shown below

position_balances is an array consisting of:

Name Type Description
instrument_name string Instrument name of the collateral e.g. USD, CRO, USDT, or DAI
quantity string Quantity of the collateral
market_value string Market value of the collateral
collateral_eligible boolean true or false
haircut string Show haircut for eligible collateral token
collateral_amount string Collateral amount derived by market_value minus haircut
max_withdrawal_balance string Max withdrawal balance of the collateral
reserved_qty string Fund/balance in use, not available for new orders or additional trading activities.

private/user-balance-history

Request Sample

{
  "id":11,
  "method": "private/user-balance-history",
  "params": {}
}

Response Sample

{
  "id": 11,
  "method": "private/user-balance-history",
  "code": 0,
  "result": {
    "instrument_name": "USD",
    "data": [
      {
        "t": 1629478800000,
        "c": "811.621851"
      }
    ]
  }
}

Returns the user's balance history. This call may temporarily have discrepancies with that shown on the GUI.

Request Params

Name Type Required Description
timeframe string N H1 means every hour, D1 means every day. Omit for 'D1'
end_time number N Can be millisecond or nanosecond. Exclusive. If not provided, will be current time.
limit int N If timeframe is D1, max limit will be 30 (days). If timeframe is H1, max limit will be 120 (hours).

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

REST Method

POST

Response Attributes

An array consisting of:

Name Type Description
instrument_name string instrument name of the balance e.g. USD
t number timestamp
c string total cash balance

private/get-accounts

Request Sample

{
  "id": 12,
  "method": "private/get-accounts",
  "params": {"page_size": 30,"page": 2},
  "nonce": 1587846358253
}

Response Sample

{
  "id": 12,
  "method": "private/get-accounts",
  "code": 0,
  "result": {
    "master_account": {
      "uuid": "243d3f39-b193-4eb9-1d60-e98f2fc17707",
      "master_account_uuid": "291879ae-b769-4eb3-4d75-3366ebee7dd6",
      "margin_account_uuid": "69c9ab41-5b95-4d75-b769-e45f2fc16507",
      "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
    },
    "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 Account and its Sub Accounts

Request Params

By default, the page_size is 20 and page is 0 respectively.

It can be overided in the JSON request: i.e. "page_size": 30, "page": 2

Note: if using default setting, please ensure you keep params: {} for API request consistency.

Applies To

REST

REST Method

POST

Response Attributes

an object of master_account, with an array of sub_account_list, both 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
system_label string Possible values if specified:

FORMER_MASTER_MARGIN
FORMER_MASTER_DERIVATIVES
FORMER_SUBACCOUNT_SPOT
FORMER_SUBACCOUNT_MARGIN
FORMER_SUBACCOUNT_DERIVATIVES
ONEEX_SUBACCOUNT

See Unified Wallet and System Label section for details

private/create-subaccount-transfer

Request Sample

{
  "id": 1234,
  "method": "private/create-subaccount-transfer",
  "params": {
    "from": "12345678-0000-0000-0000-000000000001", // Possible value: the master account UUID, or a sub-account UUID.
    "to": "12345678-0000-0000-0000-000000000002",   // Possible value: the master account UUID, or a sub-account UUID.
    "currency": "CRO",
    "amount": "500"
  },
  "nonce": 1587846358253
}

Response sample

{
  "id":1234,
  "method":"private/create-subaccount-transfer",
  "code":0
}

Transfer between subaccounts (and master account).

Request params

Name Type Required Description
from string Y Account UUID to be debited
to string Y Account UUID to be credit
currency string Y Currency symbol
amount string Y Amount to transfer - must a be positive number

Applies To

REST

Response attributes

Name Type Description
code number 0 for successful transfer (NO_ERROR) else the error code

private/get-subaccount-balances

Request Sample

{
  "id": 1,
  "method": "private/get-subaccount-balances",
  "params": {},
  "nonce": 1
}

Response Sample

{
  "id": 1,
  "method": "private/get-subaccount-balances",
  "code": 0,
  "result": {
    "data": [
      // Sub account with no balance
      {
        "account": "a0d206a1-6b06-47c5-9cd3-8bc6ef0915c5",
        "instrument_name": "USD",
        "total_available_balance": "0.00000000",
        "total_margin_balance": "0.00000000",
        "total_initial_margin": "0.00000000",
        "total_maintenance_margin": "0.00000000",
        "total_position_cost": "0.00000000",
        "total_cash_balance": "0.00000000",
        "total_collateral_value": "0.00000000",
        "total_session_unrealized_pnl": "0.00000000",
        "total_session_realized_pnl": "0.00000000",
        "total_effective_leverage": "0.00000000",
        "position_limit": "3000000.00000000",
        "used_position_limit": "0.00000000",
        "is_liquidating": false,
        "position_balances": [ ]
      },
      // Sub account with balance
      {
        "account": "49786818-6ead-40c4-a008-ea6b0fa5cf96",
        "instrument_name": "USD",
        "total_available_balance": "20823.62250000",
        "total_margin_balance": "20823.62250000",
        "total_initial_margin": "0.00000000",
        "total_maintenance_margin": "0.00000000",
        "total_position_cost": "0.00000000",
        "total_cash_balance": "21919.55000000",
        "total_collateral_value": "20823.62250000",
        "total_session_unrealized_pnl": "0.00000000",
        "total_session_realized_pnl": "0.00000000",
        "total_effective_leverage": "0.00000000",
        "position_limit": "3000000.00000000",
        "used_position_limit": "0.00000000",
        "is_liquidating": false,
        "position_balances": [
          {
            "instrument_name": "BTC",
            "quantity": "1.0000000000",
            "market_value": "21918.5500000000",
            "collateral_eligible": "true",
            "haircut": "0.5500000000",
            "collateral_amount": "21918.0000000000",
            "max_withdrawal_balance": "1.0000000000"
          },
          {
            "instrument_name": "USD",
            "quantity": "1.00000000",
            "market_value": "1.00000000",
            "collateral_eligible": "true",
            "haircut": "0.10000000",
            "collateral_amount": "0.90000000",
            "max_withdrawal_balance": "0.00000000"
          }
        ]
      },
      {
        "account": "507d3f7d-37c3-4a09-9076-b83c2fcbb638",
        "total_available_balance": "20922.62250000",
        "total_margin_balance": "20922.62250000",
        "total_initial_margin": "0.00000000",
        "total_maintenance_margin": "0.00000000",
        "total_position_cost": "0.00000000",
        "total_cash_balance": "22018.55000000",
        "total_collateral_value": "20922.62250000",
        "total_session_unrealized_pnl": "0.00000000",
        "instrument_name": "USD",
        "total_session_realized_pnl": "0.00000000",
        "total_effective_leverage": "0.00000000",
        "position_limit": "3000000.00000000",
        "used_position_limit": "0.00000000",
        "is_liquidating": false,
        "position_balances": [
          {
            "instrument_name": "BTC",
            "quantity": "1.0000000000",
            "market_value": "21918.5500000000",
            "collateral_eligible": "true",
            "haircut": "0.5500000000",
            "collateral_amount": "21918.0000000000",
            "max_withdrawal_balance": "1.0000000000"
          },
          {
            "instrument_name": "USD",
            "quantity": "100.00000000",
            "market_value": "100.00000000",
            "collateral_eligible": "true",
            "haircut": "1.00000000",
            "collateral_amount": "99.00000000",
            "max_withdrawal_balance": "0.00000000"
          }
        ]
      }
    ]
  }
}

Returns the user's wallet balances of all sub-accounts.

Request Params

Note: You still need to pass in an empty params block like params: {} for API request consistency

Applies To

REST

REST Method

POST

Response Attributes

An array consisting of:

Name Type Description
account string Sub account ID
instrument_name string Instrument name of the balance e.g. USD
total_available_balance string Balance that user can open new order (Margin Balance - Initial Margin)
total_margin_balance string Positive cash balance on eligible collateral tokens + Negative balance on all tokens + Unrealised PnL - Fee reserves
total_initial_margin string Total margin requirement to support positions and all open orders IM and haircut from risk asset holdings
total_maintenance_margin string Total maintenance margin requirement for all positions
total_position_cost string Position value in USD
total_cash_balance string Wallet Balance (Deposits - Withdrawals + Realized PnL - Fees)
total_collateral_value string Collateral Value
total_session_unrealized_pnl string Current unrealized profit and loss from all open positions (calculated with Mark Price and Avg Price)
total_session_realized_pnl string Current realized profit and loss from all open positions (calculated with Mark Price and Avg Price)
is_liquidating boolean Describes whether the account is under liquidation
total_effective_leverage string The actual leverage used (all open positions combined), i.e. position size / margin balance
position_limit string Maximum position size allowed (for all open positions combined)
used_position_limit string Combined position size of all open positions + order exposure on all instruments
position_balances array Collateral balances as shown below

position_balances is an array consisting of:

Name Type Description
instrument_name string Instrument name of the collateral e.g. USD, CRO, USDT, or DAI
quantity string Quantity of the collateral
market_value string Market value of the collateral
collateral_eligible boolean true or false
haircut string Show haircut for eligible collateral token
collateral_amount string Collateral amount derived by market_value minus haircut
max_withdrawal_balance string Max withdrawal balance of the collateral

private/get-positions

Request Sample

{
  "id": 1,
  "method": "private/get-positions",
  "params": {},
  "nonce": 1611022832613
}

Response Sample

{
  "id": 1,
  "method": "private/get-positions",
  "code": 0,
  "result": {
    "data": [{
      "account_id": "858dbc8b-22fd-49fa-bff4-d342d98a8acb",
      "quantity": "-0.1984",
      "cost": "-10159.573500",
      "open_position_pnl": "-497.743736",
      "open_pos_cost": "-10159.352200",
      "session_pnl": "2.236145",
      "update_timestamp_ms": 1613552240770,
      "instrument_name": "BTCUSD-PERP",
      "type": "PERPETUAL_SWAP"
    }]
  }
}

Returns the user's position.

Request Params

Name Type Required Description
instrument_name string N e.g. BTCUSD-PERP

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 consisting of:

Name Type Description
instrument_name string e.g. BTCUSD-PERP
type string e.g. Perpetual Swap
quantity string Position quantity
cost string Position cost or value in USD
open_position_pnl string Profit and loss for the open position
open_pos_cost string Open position cost
session_pnl string Profit and loss in the current trading session
update_timestamp_ms number Updated time (Unix timestamp)

Trading API

private/create-order

Request Sample

{
  "id": 1,
  "nonce" : 1610905028000,
  "method": "private/create-order",
  "params": {
    "instrument_name": "BTCUSD-PERP",
    "side": "SELL",
    "type": "LIMIT",
    "price": "50000.5",
    "quantity": "1",
    "client_oid": "c5f682ed-7108-4f1c-b755-972fcdca0f02",
    "exec_inst": ["POST_ONLY"],
    "time_in_force": "FILL_OR_KILL"
  }
}

Response Sample

{
  "id": 1,
  "method": "private/create-order",
  "code": 0,
  "result": {
    "client_oid": "c5f682ed-7108-4f1c-b755-972fcdca0f02",
    "order_id": "18342311"
  }
}

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. BTCUSD-PERP
side string Y BUY, SELL
type string Y LIMIT, MARKET, STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT
price string Y Price
quantity string Y Order Quantity
notional number Depends For MARKET (BUY), STOP_LOSS (BUY), TAKE_PROFIT (BUY) orders only:
Amount to spend
client_oid string N Client Order ID
exec_inst array of string N POST_ONLY
time_in_force string N GOOD_TILL_CANCEL, IMMEDIATE_OR_CANCEL, FILL_OR_KILL
When exec_inst contains POST_ONLY, time_in_force can only be GOOD_TILL_CANCEL
ref_price string N* Trigger price required for STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT order type
ref_price_type string N which price to use for ref_price: MARK_PRICE (default), INDEX_PRICE, LAST_PRICE
spot_margin string N SPOT: non-margin order, MARGIN: margin order

Applies To

REST Websocket (User API)

REST Method

POST

Response Attributes

Name Type Description
order_id string of number Newly created order ID
client_oid string If a Client Order ID was provided in the request, otherwise, will be the nonce in the request. As nonce can be the same among orders, it is recommened to specify client_oid.

private/cancel-order

Request Sample

{
  "id": 1,
  "nonce" : 1610905028000,
  "method": "private/cancel-order",
  "params": {
    "order_id": "18342311"
  }
}

Response Sample

{
  "id": 1,
  "method": "private/cancel-order",
  "code": 0,
  "message": "NO_ERROR",
  "result": {
    "client_oid": "c5f682ed-7108-4f1c-b755-972fcdca0f02",
    "order_id": "18342311"
  }
}

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

Request Params

Name Type Required Description
order_id number or string of number Depends Optional Order ID
Either order_id or client_oid must be present
string format is highly recommended.
client_oid string Depends Optional Client Order ID
Either order_id or client_oid must be present

Applies To

REST Websocket (User API)

REST Method

POST

Response Attributes

Name Type Description
order_id string of number Order ID
client_oid string Client Order ID

private/cancel-all-orders

Request Sample

{
  "id": 1,
  "nonce": 1611169184000,
  "method": "private/cancel-all-orders",
  "params": {
    "instrument_name": "BTCUSD-PERP"
  }
}

Response Sample

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

Request Params

Name Type Required Description
instrument_name string N e.g. BTCUSD-PERP. If not provided, the orders of ALL instruments will be canceled
type string N e.g. LIMIT, TRIGGER, ALL

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/close-position

Request Sample

{
  "id": 1,
  "nonce" : 1610905028000,
  "method": "private/close-position",
  "params": {
    "instrument_name": "BTCUSD-PERP",
    "type": "LIMIT",
    "price": "30000.0"
  }
}

{
  "id": 1,
  "nonce" : 1610905028000,
  "method": "private/close-position",
  "params": {
    "instrument_name": "BTCUSD-PERP",
    "type": "MARKET"
  }
}

Response Sample

{
  "id": 1,
  "method": "private/close-position",
  "code": 0,
  "result": {
    "client_oid": "1684d6e4-2c55-64e1-52c3-3aa9febc3a23",
    "order_id": "15744"
  }
}

Cancels position 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 canceled.

Request Params

Name Type Required Description
instrument_name string Y e.g. BTCUSD-PERP
type string Y LIMIT or MARKET
price string Depends For LIMIT orders only

Applies To

REST Websocket (User API)

REST Method

POST

Response Attributes

The code (0 = success) is the primary indicator that the request is queued.

Name Type Description
order_id string of number Order ID
client_oid string Client Order ID

private/get-open-orders

Request Sample

{
  "id": 1,
  "method": "private/get-open-orders",
  "params": {
    "instrument_name": "BTCUSD-PERP"
  }
}

Response Sample

{
  "id": 1,
  "method": "private/get-open-orders",
  "code": 0,
  "result": {
    "data": [{
      "account_id": "52e7c00f-1324-5a6z-bfgt-de445bde21a5",
      "order_id": "19848525",
      "client_oid": "1613571154900",
      "order_type": "LIMIT",
      "time_in_force": "GOOD_TILL_CANCEL",
      "side": "BUY",
      "exec_inst": [],
      "quantity": "0.0100",
      "limit_price": "50000.0",
      "order_value": "500.000000",
      "maker_fee_rate": "0.000250",
      "taker_fee_rate": "0.000400",
      "avg_price": "0.0",
      "cumulative_quantity": "0.0000",
      "cumulative_value": "0.000000",
      "cumulative_fee": "0.000000",
      "status": "ACTIVE",
      "update_user_id": "fd797356-55db-48c2-a44d-157aabf702e8",
      "order_date": "2021-02-17",
      "instrument_name": "BTCUSD-PERP",
      "fee_instrument_name": "USD",
      "create_time": 1613575617173,
      "create_time_ns": "1613575617173123456",
      "update_time": 1613575617173
    }]
  }
}

Gets all open orders for a particular instrument.

Request Params

Name Type Required Description
instrument_name string N e.g. BTCUSD-PERP. Omit for 'all'

Applies To

REST Websocket (User API)

REST Method

POST

Response Attributes

An array, consisting of:

Name Type Description
account_id string Account ID
order_id string of number Order ID
client_oid string Client Order ID
order_type string MARKET, LIMIT, STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT
time_in_force string
- GOOD_TILL_CANCEL
- IMMEDIATE_OR_CANCEL
- FILL_OR_KILL
side string BUY or SELL
exec_inst array
- POST_ONLY
- REDUCE_ONLY
- LIQUIDATION
quantity string Quantity specified in the order
limit_price string Limit price specified in the order
order_value string Order value
maker_fee_rate string User's maker fee rate
taker_fee_rate string User's taker fee rate
avg_price string Average price
cumulative_quantity string Cumulative executed quantity
cumulative_value string Cumulative executed value
cumulative_fee string Cumulative executed fee
status string Order status:
- NEW
- PENDING
- ACTIVE
update_user_id string Updated user
order_date string Order creation date
create_time number Order creation timestamp
create_time_ns string Order creation timestamp (nanosecond)
update_time number Order update timestamp
instrument_name string e.g. BTCUSD-PERP
fee_instrument_name string Currency used for the fees

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

private/get-order-detail

Request Sample

{
  "id": 1,
  "method": "private/get-order-detail",
  "params": {
    "order_id": "19848525"
  }
}

Response Sample

{
  "id": 1,
  "method": "private/get-order-detail",
  "code": 0,
  "result": {
    "account_id": "52e7c00f-1324-5a6z-bfgt-de445bde21a5",
    "order_id": "19848525",
    "client_oid": "1613571154900",
    "order_type": "LIMIT",
    "time_in_force": "GOOD_TILL_CANCEL",
    "side": "BUY",
    "exec_inst": [],
    "quantity": "0.0100",
    "limit_price": "50000.0",
    "order_value": "500.000000",
    "maker_fee_rate": "0.000250",
    "taker_fee_rate": "0.000400",
    "avg_price": "0.0",
    "cumulative_quantity": "0.0000",
    "cumulative_value": "0.000000",
    "cumulative_fee": "0.000000",
    "status": "ACTIVE",
    "update_user_id": "fd797356-55db-48c2-a44d-157aabf702e8",
    "order_date": "2021-02-17",
    "instrument_name": "BTCUSD-PERP",
    "fee_instrument_name": "USD",
    "create_time": 1613575617173,
    "create_time_ns": "1613575617173123456",
    "update_time": 1613575617173
  }
}

Request Params

Name Type Required Description
order_id number or string of number N Order ID. string format is highly recommended, especially for JavaScript client. If not provided, client_oid must be specified.
client_oid string N Client Order ID. If not provided, order_id must be specified.

Note: Either order_id or client_oid must be specified.

Applies To

REST

REST Method

POST

Response Attributes

An array, consisting of:

Name Type Description
account_id string Account ID
order_id string of number Order ID
client_oid string Client Order ID
order_type string MARKET, LIMIT, STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT
time_in_force string
- GOOD_TILL_CANCEL
- IMMEDIATE_OR_CANCEL
- FILL_OR_KILL
side string BUY or SELL
exec_inst array
- POST_ONLY
- REDUCE_ONLY
- LIQUIDATION
quantity string Quantity specified in the order
limit_price string Limit price specified in the order
order_value string Order value
maker_fee_rate string User's maker fee rate
taker_fee_rate string User's taker fee rate
avg_price string Average price
cumulative_quantity string Cumulative executed quantity
cumulative_value string Cumulative executed value
cumulative_fee string Cumulative executed fee
status string Order status:
- REJECTED
- CANCELED
- FILLED
- EXPIRED
update_user_id string Updated user
order_date string Order creation date
create_time number Order creation timestamp
create_time_ns string Order creation timestamp (nanosecond)
update_time number Order update timestamp
instrument_name string e.g. BTCUSD-PERP
fee_instrument_name string Currency used for the fees

Note: Please note NEW,PENDING,ACTIVE can only be found in private/get-open-orders REST endpoint or user.order WebSocket subscription.

private/change-account-leverage

Request Sample

{
  "id": 1,
  "method": "private/change-account-leverage",
  "params": {
    "account_id": "52e7c00f-1324-5a6z-bfgt-de445bde21a5",
    "leverage": 10
  }
}

Response Sample

{
  "id": 1,
  "method": "private/change-account-leverage",
  "code": 0
}

Changes the maximum leverage used by the account. Please note, each instrument has its own maximum leverage. Whichever leverage (account or instrument) is lower will be used.

Request Params

Name Type Required Description
account_id string Y account ID to change the leverage. Must be currently the logged user's account
leverage number Y maximum leverage to be used for the account. Valid values are between 1-100 (inclusive)

Applies To

REST

REST Method

POST

Response Attributes

Name Type Description
code number error code or 0 if no error
message string text description of the error code if non-zero code returned

Advanced Order Management API

private/create-order (Conditional Order)

Conditional Orders automatically place a mark or limit order when the mark price reaches a trigger price specified by the user. If the mark price reaches or exceeds the trigger price, the Stop-Loss/Take-Profit order will be converted to a live order and placed in the order book. If the mark price does not reach the trigger price, the Stop-Loss/Take-Profit order will remain active until it is canceled or triggered.

See private/create-order and the type parameter for more information.

private/create-order-list (LIST)

Request Sample

// Create List of Orders example
{
  "id": 12,
  "method": "private/create-order-list",
  "params": {
    "contingency_type": "LIST",
    "order_list": [
      {
        "instrument_name": "ETH_CRO",
        "side": "BUY",
        "type": "LIMIT",
        "price": "5799",
        "quantity": "1",
        "client_oid": "my_order_0001",
        "time_in_force": "GOOD_TILL_CANCEL",
        "exec_inst": "POST_ONLY"
      },
      {
        "instrument_name": "ETH_CRO",
        "side": "BUY",
        "type": "LIMIT",
        "price": "5780",
        "quantity": "1",
        "client_oid": "my_order_0002",
        "time_in_force": "GOOD_TILL_CANCEL",
        "exec_inst": ["POST_ONLY"]
      }
    ]
  },
  "nonce": 1637891379231
}

> Response Sample

```json
// Create List of Orders - All ok
{
  "id": 12,
  "method": "private/create-order-list",
  "code": 0,
  "result": {
    "result_list": [
      {
        "index": 0,
        "code": 0,
        "order_id": "2015106383706015873",
        "client_oid": "my_order_0001"
      },
      {
        "index": 1,
        "code": 0,
        "order_id": "2015119459882149857",
        "client_oid": "my_order_0002"
      }
    ]
  }
}

// Create List of Orders - Some rejected
{
  "id": 12,
  "method": "private/create-order-list",
  "code": 10001,
  "result": {
    "result_list": [
      {
        "index": 0,
        "code": 0,
        "order_id": "2015106383706015873",
        "client_oid": "my_order_0001"
      },
      {
        "index": 1,
        "code": 20007,
        "message": "INVALID_REQUEST",
        "client_oid": "my_order_0002"
      }
    ]
  }
}

Create a list of orders on the Exchange.

contingency_type must be LIST, for list of orders creation.

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

The user.order subscription can be used to check if the orders are successfully created.

Request Params

Name Type Required Description
contingency_type string Y LIST
order_list array of orders Y LIST: 1-10 orders

Content of each order in order_list

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 (Maximum 36 characters)
time_in_force string N (Limit Orders Only)
Options are:
- GOOD_TILL_CANCEL (Default if unspecified)
- FILL_OR_KILL
- IMMEDIATE_OR_CANCEL
exec_inst array 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


Contingency Type:

Type Description
LIST Create a list of orders


Helpful information:


To create trigger orders against market price:

Applies To

REST Websocket (User API)

REST Method

POST

Response Attributes

Name Type Description
result_list array of results List of order creation result

Content of each order in result_list

Name Type Description
index number The index of corresponding order request (Start from 0)
code number 0 if success
message string (Optional) For server or error messages
order_id number Newly created order ID
client_oid string (Optional) if a Client order ID was provided in the request. (Maximum 36 characters)

private/cancel-order-list (LIST)

Request Sample

// Cancel List of Orders example
{
  "id": 13,
  "method": "private/cancel-order-list",
  "params": {
    "order_list": [
      {
        "instrument_name": "ETH_CRO",
        "order_id": "2015106383706015873"
      },
      {
        "instrument_name": "ETH_CRO",
        "order_id": "2015119459882149857"
      }
    ]
  },
  "nonce": 1587846358253
}

Response Sample

// Cancel List of Orders - All ok
{
  "id": 13,
  "method": "private/cancel-order-list",
  "code":0,
  "result": {
    "result_list": [
      {
        "index": 0,
        "code": 0,
      },
      {
        "index": 1,
        "code": 0,
      }
    ]
  }
}

// Cancel List of Orders - Error encountered
{
  "id": 13,
  "method": "private/cancel-order-list",
  "code": 10001,
  "result": {
    "order_list": [
      {
        "index": 0,
        "code": 0,
      },
      {
        "index": 1,
        "code": 20007,
        "message": "INVALID_REQUEST"
      }
    ]
  }
}

Cancel a list of orders 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 each of the orders is successfully cancelled.

Request Params (List of Orders)

Name Type Required Description
order_list array of orders N For non contingency orders, A list of orders to be cancelled
instrument_name string N Instrument name of contingency order, e.g., ETH_CRO, BTC_USDT
contingency_id string N ID of the contingency order

Content of each order in order_list

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 (List of Orders)

A result_list will be received:

Name Type Description
result_list array of results List of order cancellation result

Content of each order in result_list

Name Type Description
index number The index of corresponding order request (Start from 0)
code number 0 if success
message string (Optional) For server or error messages

private/create-order-list (OCO)

Request Example

{
  "method":"private/create-order-list",
  "id":123456789,
  "nonce":123456789000,
  "params":{
    "contingency_type":"OCO",
    "order_list":[
      {
        "instrument_name":"BTCUSD-PERP",
        "quantity":"0.1",
        "type":"LIMIT",
        "price":"23000",
        "side":"SELL"
      },
      {
        "instrument_name":"BTCUSD-PERP",
        "quantity":"0.1",
        "type":"STOP_LOSS",
        "ref_price":"19000",
        "side":"SELL"
      }
    ]
  }
}

Response Example

{
  "id" : 1661331443,
  "method" : "private/create-order-list",
  "code" : 0,
  "result" : {
    "list_id" : 6498090546073120100
  }
}

Creates a One-Cancel-the-Other (OCO) order on the Exchange.

OCO Order allows users to place two orders at the same time. Users are able to place a limit order with a stop order, and only one of them will be executed. When either one of the above orders is executed, the other is automatically canceled. This allows users to take a profit while minimizing potential loss. The OCO order type is available for Spot trading pairs and Futures and Perpetual contracts only.

This call is asynchronous, so the response is simply a confirmation of the request. The user.order subscription can be used to check if the orders are successfully created.

Request Params

Name Type Required Description
contingency_type string Y OCO
order_list array of orders Y Exactly 2 orders

For the content of each order in order_list, please refer to private/create-order for details.

Applies To

REST Websocket (User API)

REST Method

POST

Response Attributes

Name Type Description
list_id number List ID

private/cancel-order-list (OCO)

Request Example

{
  "method":"private/cancel-order-list",
  "id":1234,
  "nonce":123456789000,
  "params":{
    "instrument_name":"BTCUSD-PERP",
    "list_id":"4421958062479290999",
    "contingency_type":"OCO"
  }
}

Response Example

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

Cancel a contingency 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 each of the orders is successfully cancelled.

Request Params

Name Type Required Description
contingency_type string Y OCO
list_id string Y List ID
instrument_name string Y Instrument Name

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-list (OCO)

Request Example

{
  "method":"private/get-order-list",
  "id":123,
  "nonce":123456789000,
  "params":{
    "instrument_name":"BTCUSD-PERP",
    "list_id":"6498090546073120100",
    "contingency_type":"OCO"
  }
}

Response Example

{
  "id":1661331609,
  "method":"private/get-order-list",
  "code":0,
  "result":{
    "data":[
      {
        "account_id":"88888888-8888-8888-8888-000000000001",
        "order_id":"4611686018427387905",
        "client_oid":"1661331443",
        "type":"LIMIT",
        "time_in_force":"GOOD_TILL_CANCEL",
        "side":"SELL",
        "exec_inst":[],
        "quantity":"0.1000",
        "price":"23000.0",
        "order_value":"2300.00000000",
        "avg_price":"0",
        "trigger_price":"0",
        "cumulative_quantity":"0",
        "cumulative_value":"0",
        "cumulative_fee":"0",
        "status":"ACTIVE",
        "update_user_id":"11111111-1111-1111-1111-000000000001",
        "order_date":"2022-08-24",
        "instrument_name":"BTCUSD-PERP",
        "fee_instrument_name":"USD",
        "list_id":"6498090546073120100",
        "contingency_type":"OCO",
        "trigger_price_type":"NULL_VAL",
        "create_time":1661331445398,
        "create_time_ns":"1661331445398773329",
        "update_time":1661331445482
      },
      {
        "account_id":"88888888-8888-8888-8888-000000000001",
        "order_id":"4611686018427387906",
        "client_oid":"1661331443-2",
        "type":"STOP_LOSS",
        "time_in_force":"GOOD_TILL_CANCEL",
        "side":"SELL",
        "exec_inst":[],
        "quantity":"0.1000",
        "order_value":"1900.00000000",
        "avg_price":"0",
        "trigger_price":"0",
        "cumulative_quantity":"0",
        "cumulative_value":"0",
        "cumulative_fee":"0",
        "status":"PENDING",
        "update_user_id":"11111111-1111-1111-1111-000000000001",
        "order_date":"2022-08-24",
        "instrument_name":"BTCUSD-PERP",
        "fee_instrument_name":"USD",
        "list_id":"6498090546073120100",
        "contingency_type":"OCO",
        "trigger_price_type":"NULL_VAL",
        "create_time":1661331445040,
        "create_time_ns":"1661331445040100934",
        "update_time":0
      }
    ]
  }
}

Gets the details of an outstanding (not executed) contingency order on Exchange.

Request Params

Name Type Required Description
contingency_type string Y OCO
list_id string Y ID of the contingency order
instrument_name string Y instrument_name of the contingency order, e.g. ETH_CRO, BTC_USDT.

Applies To

REST

REST Method

POST

Response Attributes

List of order in the field data. For content of data, please refer to private/get-open-orders for details

Order, Trade, Transaction History API

private/get-order-history

Request Sample

{
  "id": 1,
  "method": "private/get-order-history",
  "params": {
    "instrument_name": "BTCUSD-PERP",
    "start_time": 1610905028000081486,
    "end_time": 1613570791058211357,
    "limit": 20
  }
}

Response Sample

{
  "id": 1,
  "method": "private/get-order-history",
  "code": 0,
  "result": {
    "data": [{
      "account_id": "52e7c00f-1324-5a6z-bfgt-de445bde21a5",
      "order_id": "18342311",
      "client_oid": "1613571154795",
      "order_type": "LIMIT",
      "time_in_force": "GOOD_TILL_CANCEL",
      "side": "BUY",
      "exec_inst": [],
      "quantity": "0.0001",
      "limit_price": "51000.0",
      "order_value": "3.900100",
      "maker_fee_rate": "0.000250",
      "taker_fee_rate": "0.000400",
      "avg_price": "0.0",
      "cumulative_quantity": "0.0000",
      "cumulative_value": "0.000000",
      "cumulative_fee": "0.000000",
      "status": "CANCELED",
      "update_user_id": "fd797356-55db-48c2-a44d-157aabf702e8",
      "order_date": "2021-02-17",
      "instrument_name": "BTCUSD-PERP",
      "fee_instrument_name": "USD",
      "create_time": 1610905028000,
      "create_time_ns": "1610905028000123456",
      "update_time": 1613571320251
    },
      {
        "account_id": "52e7c00f-1324-5a6z-bfgt-de445bde21a5",
        "order_id": "18342500",
        "client_oid": "1613571154800",
        "order_type": "LIMIT",
        "time_in_force": "GOOD_TILL_CANCEL",
        "side": "BUY",
        "exec_inst": [],
        "quantity": "0.0500",
        "limit_price": "51283.0",
        "order_value": "2564.150000",
        "maker_fee_rate": "0.000250",
        "taker_fee_rate": "0.000400",
        "avg_price": "51278.5",
        "cumulative_quantity": "0.0500",
        "cumulative_value": "2563.925000",
        "cumulative_fee": "1.025570",
        "status": "FILLED",
        "update_user_id": "fd797356-55db-48c2-a44d-157aabf702e8",
        "order_date": "2021-02-17",
        "instrument_name": "BTCUSD-PERP",
        "fee_instrument_name": "USD",
        "create_time": 1613570791059,
        "create_time_ns": "1613570791059123456",
        "update_time": 1613570791060
      }]
  }
}

Gets the order history for a particular instrument.

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. BTCUSD-PERP. Omit for 'all'
start_time number or string N Start time in Unix time format (inclusive).
Default: end_time - 1 day.
Nanosecond is recommended for accurate pagination
end_time number or string N End time in Unix time format (exclusive)
Default: current system timestamp.
Nanosecond is recommended for accurate pagination
limit int N The maximum number of trades to be retrieved before the end_time.
Default: 100.
Max: 100.

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

REST Method

POST

Response Attributes

An array, consisting of:

Name Type Description
account_id string Account ID
order_id string of number Order ID
client_oid string Client Order ID
order_type string MARKET, LIMIT, STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT
time_in_force string
- GOOD_TILL_CANCEL
- IMMEDIATE_OR_CANCEL
- FILL_OR_KILL
side string BUY or SELL
exec_inst array
- POST_ONLY
- REDUCE_ONLY
- LIQUIDATION
quantity string Quantity specified in the order
limit_price string Limit price specified in the order
order_value string Order value
maker_fee_rate string User's maker fee rate
taker_fee_rate string User's taker fee rate
avg_price string Average price
cumulative_quantity string Cumulative executed quantity
cumulative_value string Cumulative executed value
cumulative_fee string Cumulative executed fee
status string Order status:
- REJECTED
- CANCELED
- FILLED
- EXPIRED
update_user_id string Updated user
order_date string Order creation date
create_time number Order creation timestamp
create_time_ns string Order creation timestamp (nanosecond)
update_time number Order update timestamp
instrument_name string e.g. BTCUSD-PERP
fee_instrument_name string Currency used for the fees

Note: Please note NEW,PENDING,ACTIVE can only be found in private/get-open-orders REST endpoint or user.order WebSocket subscription.

private/get-trades

Request Sample

{
  "id": 1,
  "method": "private/get-trades",
  "params": {
    "instrument_name": "BTCUSD-PERP",
    "start_time": "1619089031996081486",
    "end_time": "1619200052124211357",
    "limit": 20
  }
}

Response Sample

{
  "id": 1,
  "method": "private/get-trades",
  "code": 0,
  "result": {
    "data": [{
      "account_id": "52e7c00f-1324-5a6z-bfgt-de445bde21a5",
      "event_date": "2021-02-17",
      "journal_type": "TRADING",
      "traded_quantity": "0.0500",
      "traded_price": "51278.5",
      "fees": "-1.025570",
      "order_id": "19708564",
      "trade_id": "38554669",
      "trade_match_id": "76423",
      "client_oid": "7665b001-2753-4d17-b266-61ecb755922d",
      "taker_side": "MAKER",
      "side": "BUY",
      "instrument_name": "BTCUSD-PERP",
      "fee_instrument_name": "USD",
      "create_time": 1613570791060,
      "create_time_ns": "1613570791060827635"
    }]
  }
}

Gets all executed trades for a particular instrument.

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. BTCUSD-PERP. Omit for 'all'
start_time number or string N Start time in Unix time format (inclusive).
Default: end_time - 1 day.
Nanosecond is recommended for accurate pagination
end_time number or string N End time in Unix time format (exclusive)
Default: current system timestamp.
Nanosecond is recommended for accurate pagination
limit int N The maximum number of trades to be retrievd before the end_time.
Default: 100.
Max: 100.

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

REST Method

POST

Response Attributes

An array, consisting of:

Name Type Description
account_id string Account ID
event_date string Event date
journal_type string Journal type would be TRADING
traded_quantity string Trade quantity
traded_price string Trade price
fees string Trade fees, the negative sign means a deduction on balance
order_id string of number Order ID
trade_id string of number Trade ID
trade_match_id string of number Trade match ID
client_oid string Client Order ID
taker_side string MAKER or TAKER or empty
side string BUY or SELL
instrument_name string e.g. BTCUSD-PERP
fee_instrument_name string e.g. USD
create_time number Create timestamp in milliseconds
create_time_ns string Create timestamp in nanoseconds

private/get-transactions

Request Sample

{
  "id": 1,
  "method": "private/get-transactions",
  "params": {
    "instrument_name": "BTCUSD-PERP",
    "start_time": "1619089031996081486",
    "end_time": "1619200052124211357",
    "limit": 20
  }
}

Response Sample

{
  "id": 1,
  "method": "private/get-transactions",
  "code": 0,
  "result": {
    "data": [
      {
        "account_id": "88888888-8888-8888-8888-000000000007",
        "event_date": "2021-02-18",
        "journal_type": "TRADING",
        "journal_id": "187078",
        "transaction_qty": "-0.0005",
        "transaction_cost": "-24.500000",
        "realized_pnl": "-0.006125",
        "order_id": "72062",
        "trade_id": "71497",
        "trade_match_id": "8625",
        "event_timestamp_ms": 1613640752166,
        "event_timestamp_ns": "1613640752166234567",
        "client_oid": "6ac2421d-5078-4ef6-a9d5-9680602ce123",
        "taker_side": "MAKER",
        "side": "SELL",
        "instrument_name": "BTCUSD-PERP"
      },
      {
        "account_id": "9c72d8f1-583d-4b9d-b27c-55e695a2d116",
        "event_date": "2021-02-18",
        "journal_type": "SESSION_SETTLE",
        "journal_id": "186959",
        "transaction_qty": "0",
        "transaction_cost": "0.000000",
        "realized_pnl": "-0.007800",
        "trade_match_id": "0",
        "event_timestamp_ms": 1613638800001,
        "event_timestamp_ns": "1613638800001124563",
        "client_oid": "",
        "taker_side": "",
        "instrument_name": "BTCUSD-PERP"
      }
    ]
  }
}

Fetches recent transactions

Request Params

Name Type Required Description
instrument_name string N e.g. instrument_name, e.g. BTCUSD-PERP, Omit for 'all'
journal_type string N Refer to the journal_type in Response Attributes
start_time number or string N Start time in Unix time format (inclusive).
Default: end_time - 1 day.
Nanosecond is recommended for accurate pagination
end_time number or string N End time in Unix time format (exclusive)
Default: current system timestamp.
Nanosecond is recommended for accurate pagination
limit int N The maximum number of trades to be retrievd before the end_time.
Default: 100.
Max: 100.

Applies To

REST

REST Method

POST

Response Attributes

Name Type Description
account_id string Account ID
event_date string Event date
journal_type string Journal type would be TRADING, TRADE_FEE, WITHDRAW_FEE, WITHDRAW, DEPOSIT, ROLLBACK_DEPOSIT, ROLLBACK_WITHDRAW, FUNDING, REALIZED_PNL, INSURANCE_FUND, SOCIALIZED_LOSS, LIQUIDATION_FEE, SESSION_RESET, ADJUSTMENT, SESSION_SETTLE, UNCOVERED_LOSS, ADMIN_ADJUSTMENT, DELIST, SETTLEMENT_FEE, AUTO_CONVERSION, MANUAL_CONVERSION,SUBACCOUNT_TX
journal_id string of number Journal ID
transaction_qty string Transaction quantity
transaction_cost string Transaction cost
realized_pnl string Realized PNL
order_id string of number Order ID
trade_id string of number Trade ID
trade_match_id string of number Trade match ID applicable to trades only. Non-trade related transactions will have zero or null value.
client_oid string Client Order ID (can be empty)
taker_side string MAKER or TAKER or empty
side string BUY or SELL
instrument_name string e.g. BTCUSD-PERP
event_timestamp_ms number Event timestamp in milliseconds
event_timestamp_ns string Event timestamp in nanoseconds

Wallet API

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": "",
    "network_id": null
  },
  "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,
    "network_id": null
  }
}

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.
network_id string N Select the desired network, require the address to be whitelisted first. See default_network and network in get-currency-networks for the value.

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

Request Sample

{
  "id": 12,
  "method": "private/get-currency-networks",
  "params": {},
  "api_key": "api_key",
  "sig": "9b4e5428970d88270ac18aa680d33bf6a42390db2060e7f3b81f579a99cea9d5",
  "nonce": :1640830660110
}

Response Sample

{
  "code": 0,
  "result": {
    "update_time": 1641151604000,
    "currency_map": {
      "AGLD": {
        "full_name": "Adventure Gold",
        "default_network": null,
        "network_list": [
          {
            "network_id": "ETH",
            "withdrawal_fee": null,
            "withdraw_enabled": true,
            "min_withdrawal_amount": 10.0,
            "deposit_enabled": true,
            "confirmation_required": 12
          }
        ]
      },
      "MATIC": {
        "full_name": "Polygon",
        "default_network": "ETH",
        "network_list": [
          {
            "network_id": "BNB",
            "withdrawal_fee": 0.80000000,
            "withdraw_enabled": true,
            "min_withdrawal_amount": 1.6,
            "deposit_enabled": true,
            "confirmation_required": 0
          },
          {
            "network_id": "ETH",
            "withdrawal_fee": 20.00000000,
            "withdraw_enabled": true,
            "min_withdrawal_amount": 40.0,
            "deposit_enabled": true,
            "confirmation_required": 0
          },
          {
            "network_id": "MATIC",
            "withdrawal_fee": 0.08000000,
            "withdraw_enabled": true,
            "min_withdrawal_amount": 0.16,
            "deposit_enabled": true,
            "confirmation_required": 0
          }
        ]
      }
    }
  }
}

Get the symbol network mapping.

Request Params

Name Type Required Description
no param required N/A

Note: You still need to pass in an empty params block like params: {} for API request consistency

Applies To

REST

REST Method

POST

Response Attributes

An Map of currency, consisting of:

Name Type Description
full_name string e.g. SHIBA INU
default_network string If network is not provided in create-withdrawal, it will search for default_network, if there is more than 1 network available.
network_list string A list of networks

network_list:

Name Type Description
network_id string the network id, can be used in create-withdrawal
withdraw_enabled boolean
deposit_enabled boolean
withdrawal_fee decimal
min_withdrawal_amount decimal
confirmation_required int confirmation blocks count

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

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-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": "",
        "network_id": null
      }
    ]
  }
}

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
network_id string Network for the transaction - please see get-currency-networks. Only available when Exchange support multiple network on the currency

Websocket Subscriptions

Introduction

Request Sample

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

Response Sample (Initial)

{
  "id": 1,
  "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 Websocket Subscription Limits

Websocket (Market Data Subscriptions)

To better distribute system load, a single market data websocket connection is limited to a maximum of 400 subscriptions. Once this limit is reached, further subscription requests will be rejected with the EXCEED_MAX_SUBSCRIPTIONS error code.

A user should establish multiple connections if additional market data subscriptions are required.

Subscription Requests

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) Websocket (Market Data Subscriptions)

Websocket Heartbeats

Heartbeat Example

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

Request Sample

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

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.

Request Params

None

Applies To

Websocket (User API) Websocket (Market Data Subscriptions)

user.order.{instrument_name}

Request Sample

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

Response Sample

{
  "id": 1,
  "method": "subscribe",
  "code": 0,
  "result": {
    "instrument_name": "BTCUSD-PERP",
    "subscription": "user.order.BTCUSD-PERP",
    "channel": "user.order",
    "data": [{
      "account_id": "52e7c00f-1324-5a6z-bfgt-de445bde21a5",
      "order_id": "19848525",
      "client_oid": "1613571154900",
      "order_type": "LIMIT",
      "time_in_force": "GOOD_TILL_CANCEL",
      "side": "BUY",
      "exec_inst": [],
      "quantity": "0.0100",
      "limit_price": "50000.0",
      "order_value": "500.000000",
      "maker_fee_rate": "0.000250",
      "taker_fee_rate": "0.000400",
      "avg_price": "0.0",
      "cumulative_quantity": "0.0000",
      "cumulative_value": "0.000000",
      "cumulative_fee": "0.000000",
      "status": "ACTIVE",
      "update_user_id": "fd797356-55db-48c2-a44d-157aabf702e8",
      "order_date": "2021-02-17",
      "instrument_name": "BTCUSD-PERP",
      "fee_instrument_name": "USD",
      "create_time": 1613575617173,
      "create_time_ns": "1613575617173123456",
      "update_time": 1613575617173
    }]
  }
}

Publishes all new orders or order updates for the user for a particular instrument, where the early response containing the same id as the request is the current open orders, and the rest of the responses with "id":-1 are live updates

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. BTCUSD-PERP
subscription string user.order.{instrument_name} or user.order (all instruments)
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
account_id string Account ID
order_id string of number Order ID
client_oid string Client Order ID
order_type string MARKET, LIMIT, STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT
time_in_force string
- GOOD_TILL_CANCEL
- IMMEDIATE_OR_CANCEL
- FILL_OR_KILL
side string BUY or SELL
exec_inst array
- POST_ONLY
- REDUCE_ONLY
- LIQUIDATION
quantity string Quantity specified in the order
limit_price string Limit price specified in the order
order_value string Order value
maker_fee_rate string User's maker fee rate
taker_fee_rate string User's taker fee rate
avg_price string Average price
cumulative_quantity string Cumulative executed quantity
cumulative_value string Cumulative executed value
cumulative_fee string Cumulative executed fee
status string Order status:
- NEW
- PENDING
- REJECTED
- ACTIVE
- CANCELED
- FILLED
- EXPIRED
update_user_id string Updated user
order_date string Order creation date
create_time number Order creation timestamp
create_time_ns string Order creation timestamp (nanosecond)
update_time number Order update timestamp
instrument_name string e.g. BTCUSD-PERP
fee_instrument_name string Currency used for the fees

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

user.trade.{instrument_name}

Request Sample

{
  "id": 1,
  "method": "subscribe",
  "params": {
    "channels": ["user.trade"]
  }
}

Response Sample

{
  "id": 1,
  "method": "subscribe",
  "code": 0,
  "result": {
    "instrument_name": "BTCUSD-PERP",
    "subscription": "user.trade.BTCUSD-PERP",
    "channel": "user.trade",
    "data": [{
      "account_id": "52e7c00f-1324-5a6z-bfgt-de445bde21a5",
      "event_date": "2021-02-17",
      "journal_type": "TRADING",
      "traded_quantity": "0.0500",
      "traded_price": "51278.5",
      "fees": "-1.025570",
      "order_id": "19708564",
      "trade_id": "38554669",
      "trade_match_id": "76423",
      "client_oid":"6ac2421d-5078-4ef6-a9d5-9680602ce123",
      "taker_side":"MAKER",
      "side": "BUY",
      "instrument_name": "BTCUSD-PERP",
      "fee_instrument_name": "USD",
      "create_time": 1613570791060,
      "create_time_ns": "1613570791060123456"
    }]
  }
}

Publishes all new trades updates related to the user for a particular instrument, where the early response containing the same id serves as the confirmation to the request, and the rest of the responses with "id":-1 are live updates

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. BTCUSD-PERP
subscription string user.trade.{instrument_name} or user.trade (all instruments)
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
account_id string Account ID
event_date string Event date
journal_type string Journal type would be TRADING
traded_quantity string Trade quantity
traded_price string Trade price
fees string Trade fees, the negative sign means a deduction on balance
order_id string of number Order ID
trade_id string of number Trade ID
trade_match_id string of number Trade match ID
client_oid string Client Order ID
taker_side string MAKER or TAKER or empty
side string BUY or SELL
instrument_name string e.g. BTCUSD-PERP
fee_instrument_name string e.g. USD
create_time number Create timestamp
create_time_ns string Create timestamp (nanosecond)

user.balance

Request Sample

{
  "id": 1,
  "method":"subscribe",
  "params":{
    "channels":["user.balance"]
  }
}

Response Sample

{
  "id": 1,
  "method": "subscribe",
  "code": 0,
  "result": {
    "subscription": "user.balance",
    "channel": "user.balance",
    "data": [{
      "total_available_balance": "7109.11298582",
      "total_margin_balance": "7595.42571783",
      "total_initial_margin": "486.31273202",
      "total_position_im": "486.31273202",
      "total_haircut": "10.01",
      "total_maintenance_margin": "294.30450677",
      "total_position_cost": "14517.54641301",
      "total_cash_balance": "7890.00320721",
      "total_collateral_value": "7651.18811483",
      "total_session_unrealized_pnl": "-55.76239701",
      "instrument_name": "USD",
      "total_session_realized_pnl": "0.00000000",
      "is_liquidating": false,
      "total_effective_leverage" : "1.90401230",
      "position_limit" : "3000000.00000000",
      "used_position_limit" : "40674.69622001",
      "position_balances": [
        {
          "instrument_name": "CRO",
          "quantity": "24422.72427884",
          "market_value": "4776.107959969951",
          "collateral_eligible": "true",
          "haircut": "0.10",
          "collateral_amount": "4776.007959969951",
          "max_withdrawal_balance": "24422.72427884",
          "reserved_qty" : "0.00000000"
        },
        {
          "instrument_name": "USD",
          "quantity": "3113.50747209",
          "market_value": "3113.50747209",
          "collateral_eligible": "true",
          "haircut": "1.0",
          "collateral_amount": "3112.50747209",
          "max_withdrawal_balance": "3113.50747209",
          "reserved_qty" : "0.00000000"
        },
        {
          "instrument_name": "USDT",
          "quantity": "0.19411607",
          "market_value": "0.19389555414448",
          "collateral_eligible": "true",
          "haircut": "0.193",
          "collateral_amount": "0.00089555414448",
          "max_withdrawal_balance": "0.19411607",
          "reserved_qty" : "0.00000000"
        },
        {
          "instrument_name": "DAI",
          "quantity": "0.19387960",
          "market_value": "0.1938796",
          "collateral_eligible": "true",
          "haircut": "0.193",
          "collateral_amount": "0.0008796",
          "max_withdrawal_balance": "0.1938796",
          "reserved_qty" : "0.00000000"
        }
      ]
    }]
  }
}

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
instrument_name string instrument name of the balance e.g. USD
total_available_balance string Balance that user can open new order (Margin Balance - Initial Margin)
total_margin_balance string Positive cash balance on eligible collateral tokens + Negative balance on all tokens + Unrealised PnL - Fee reserves
total_initial_margin string Total margin requirement to support positions and all open orders IM and haircut from risk asset holdings
Total sum of total_position_im + total_haircut
total_position_im string initial margin requirement to support open positions and orders
total_haircut string the total haircut on eligible collateral token assets
total_maintenance_margin string Total maintenance margin requirement for all positions
total_position_cost string Position value in USD
total_cash_balance string Wallet Balance (Deposits - Withdrawals + Realized PnL - Fees)
total_collateral_value string Collateral Value
total_session_unrealized_pnl string Current unrealized profit and loss from all open positions (calculated with Mark Price and Avg Price)
total_session_realized_pnl string Current realized profit and loss from all open positions (calculated with Mark Price and Avg Price)
is_liquidating boolean Describes whether the account is under liquidation
total_effective_leverage string The actual leverage used (all open positions combined), i.e. position size / margin balance
position_limit string Maximum position size allowed (for all open positions combined)
used_position_limit string Combined position size of all open positions + order exposure on all instruments
position_balances array Collateral balances as shown below

position_balances is an array consisting of:

Name Type Description
instrument_name string Instrument name of the collateral e.g. USD, CRO, USDT, or DAI
quantity string Quantity of the collateral
market_value string Market value of the collateral
collateral_eligible boolean true or false
haircut string Show haircut for eligible collateral token
collateral_amount string Collateral amount derived by market_value minus haircut
max_withdrawal_balance string Max withdrawal balance of the collateral
reserved_qty string Fund/balance in use, not available for new orders or additional trading activities.

user.positions

Request Sample

{
  "id": 1,
  "method":"subscribe",
  "params":{
    "channels":["user.positions"]
  }
}

Response Sample

{
  "id": 1,
  "method": "subscribe",
  "code": 0,
  "result": {
    "subscription": "user.positions",
    "channel": "user.positions",
    "data": [{
      "account_id": "52e7c00f-8716-4d6f-afdf-de334bde8ea5",
      "quantity": "0.0500",
      "session_unrealized_pnl": "-14.884000",
      "cost": "2561.516000",
      "open_position_pnl": "-7.302460",
      "open_pos_cost": "2561.328000",
      "session_pnl": "0.000000",
      "pos_initial_margin": "64.684453",
      "pos_maintenance_margin": "44.311397",
      "market_value": "2546.632000",
      "mark_price": "50932.6",
      "target_leverage": "50.00",
      "update_timestamp_ms": 1613578676735,
      "instrument_name": "BTCUSD-PERP",
      "type": "PERPETUAL_SWAP"
    }]
  }
}

Publishes all new position 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.positions
channel string user.positions
data array See below

data consists of:

Name Type Description
account_id string Account ID
quantity string Position quantity
session_unrealized_pnl string Unrealized profit and loss for the current trading session
cost string Position cost or value in USD
open_position_pnl string Profit and loss for the open position
open_pos_cost string Open pos cost
session_pnl string Profit and loss in the current trading session
pos_initial_margin string Position's initial margin
pos_maintenance_margin string Position's maintenance margin
market_value string Market value of position size with Mark Price
mark_price string Mark price
target_leverage string Leverage
update_timestamp_ms number Update time (Unix timestamp)
instrument_name string e.g. BTCUSD-PERP
type string e.g. PERPETUAL_SWAP

user.account_risk

Request Sample

{
  "id": 1,
  "method":"subscribe",
  "params":{
    "channels":["user.account_risk"]
  }
}

Response Sample

{
  "method": "subscribe",
  "code": 0,
  "result": {
    "account_id": "11111111-1111-1111-1000-000000000003",
    "subscription": "user.account_risk",
    "channel": "user.account_risk",
    "data": [
      {
        "instrument_name": "USD",
        "total_available_balance": "10009769008.34209823",
        "total_cash_balance": "10010020146.28690719",
        "total_initial_margin": "62.47231001",
        "total_maintenance_margin": "30.29753001",
        "total_position_cost": "1907.12000000",
        "total_session_unrealized_pnl": "2.61999999999989088",
        "total_margin_balance": "10009769070.81440734",
        "total_session_realized_pnl": "0",
        "total_effective_leverage": "0.00000019",
        "position_limit": "3000000.00000000",
        "used_position_limit": "4025.50000000",
        "is_liquidating": false,
        "total_borrow": "0.00000000",
        "margin_score": "0.00000000",
        "balances": [
          {
            "instrument_name": "USD",
            "quantity": "9999999992.88690568152",
            "market_value": "9999999992.88690567",
            "collateral_eligible": "true",
            "haircut": "0.8800000",
            "collateral_amount": "9999999992.00690567",
            "max_withdrawal_balance": "9999999992.88690567",
            "reserved_qty": "0"
          },
          {
            "instrument_name": "USDT",
            "quantity": "10000000",
            "market_value": "9999801.00000000",
            "collateral_eligible": "true",
            "haircut": "1.00000",
            "collateral_amount": "9999800.000000000",
            "max_withdrawal_balance": "10000000.00000000",
            "reserved_qty": "0"
          }
        ],
        "positions": [
          {
            "account_id": "11111111-1111-1111-1000-000000000003",
            "quantity": "-0.1",
            "market_value": "-1904.50000000",
            "session_unrealized_pnl": "2.61999999",
            "open_position_pnl": "-7.11309431848",
            "session_pnl": "0",
            "cost": "-1907.12",
            "open_pos_cost": "-1900",
            "liquidation_price": "0.0",
            "pos_initial_margin": "29.21503000",
            "pos_maintenance_margin": "21.59703000",
            "mark_price": "19045.0",
            "effective_leverage": "0.000000",
            "target_leverage": "100.000000",
            "update_timestamp_ms": 1663927002224,
            "instrument_name": "BTCUSD-PERP",
            "type": "PERPETUAL_SWAP"
          }
        ],
        "total_collateral_value": "10009769068.19440460"
      }
    ]
  },
  "id": -1
}

Publishes position and balance snapshot for the user on a regular basis

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.account_risk
channel string user.account_risk
data array See below

data consists of:

Name Type Description
instrument_name string instrument name of the balance e.g. USD
total_available_balance string Balance that user can open new order (Margin Balance - Initial Margin)
total_margin_balance string Positive cash balance on eligible collateral tokens + Negative balance on all tokens + Unrealised PnL - Fee reserves
total_initial_margin string Total margin requirement to support positions and all open orders IM and haircut from risk asset holdings
total_maintenance_margin string Total maintenance margin requirement for all positions
total_position_cost string Position value in USD
total_cash_balance string Wallet Balance (Deposits - Withdrawals + Realized PnL - Fees)
total_collateral_value string Collateral Value
total_session_unrealized_pnl string Current unrealized profit and loss from all open positions (calculated with Mark Price and Avg Price)
total_session_realized_pnl string Current realized profit and loss from all open positions (calculated with Mark Price and Avg Price)
is_liquidating boolean Describes whether the account is under liquidation
total_effective_leverage string The actual leverage used (all open positions combined), i.e. position size / margin balance
position_limit string Maximum position size allowed (for all open positions combined)
used_position_limit string Combined position size of all open positions + order exposure on all instruments

balances is an array consisting of:

Name Type Description
instrument_name string Instrument name of the collateral e.g. USD, CRO, USDT, or DAI
quantity string Quantity of the collateral
market_value string Market value of the collateral
collateral_eligible boolean true or false
haircut string Show haircut for eligible collateral token
collateral_amount string Collateral amount derived by market_value minus haircut
max_withdrawal_balance string Max withdrawal balance of the collateral
reserved_qty string Fund/balance in use, not available for new orders or additional trading activities.

positions is an array consisting of:

Name Type Description
account_id string Account ID
quantity string Position quantity
liquidation_price string Liquidation price
session_unrealized_pnl string Unrealized profit and loss for the current trading session
cost string Position cost or value in USD
open_position_pnl string Profit and loss for the open position
open_pos_cost string Open pos cost
session_pnl string Profit and loss in the current trading session
pos_initial_margin string Position's initial margin
pos_maintenance_margin string Position's maintenance margin
market_value string Market value of position size with Mark Price
mark_price string Mark price
target_leverage string Leverage
update_timestamp_ms number Update time (Unix timestamp)
instrument_name string e.g. BTCUSD-PERP
type string e.g. PERPETUAL_SWAP

user.position_balance

Request Sample

{
  "id": 1,
  "method":"subscribe",
  "params":{
    "channels":["user.position_balance"]
  }
}

Response Sample

{
  "method": "subscribe",
  "code": 0,
  "result": {
    "subscription": "user.position_balance",
    "channel": "user.position_balance",
    "data": [
      "balances"
      :
      [
        {
          "instrument_name": "BTC",
          "quantity": "-0.0002"
        }
      ],
      "positions"
      :
      [
        {
          "account_id": "11111111-1111-1111-1000-000000000003",
          "instrument_name": "BTCUSD-PERP",
          "type": "PERPETUAL_SWAP",
          "quantity": "-0.2",
          "cost": "-3807.12",
          "open_position_pnl": "-7.11309431848",
          "session_pnl": "0",
          "update_timestamp_ms": 1663927145933,
          "open_pos_cost": "-3800"
        }
      ]
    ]
  },
  "id": -1
}

Publishes position and balance realtime update 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.position_balance
channel string user.position_balance
data array See below

balances is an array consisting of:

Name Type Description
instrument_name string Instrument name of the collateral e.g. USD, CRO, USDT, or DAI
quantity string Quantity of the collateral
update_timestamp_ms number Update time (Unix timestamp)

positions is an array consisting of:

Name Type Description
account_id string Account ID
quantity string Position quantity
cost string Position cost or value in USD
open_position_pnl string Profit and loss for the open position
open_pos_cost string Open pos cost
session_pnl string Profit and loss in the current trading session
update_timestamp_ms number Update time (Unix timestamp)
instrument_name string e.g. BTCUSD-PERP
type string e.g. PERPETUAL_SWAP

book.{instrument_name}

Request Sample

{
  "id": 1,
  "method": "subscribe",
  "params": {
    "channels": ["book.BTCUSD-PERP"]
  },
  "nonce": 1654784123465
}

Response Sample

{
  "id": -1,
  "method": "subscribe",
  "code": 0,
  "result": {
    "instrument_name": "BTCUSD-PERP",
    "subscription": "book.BTCUSD-PERP.50",
    "channel": "book",
    "depth": 50,
    "data": [{
      "asks": [
        ["50126.000000", "0.400000", "0"],
        ["50130.000000", "1.279000", "0"],
        ["50136.000000", "1.279000", "0"],
        ["50137.000000", "0.800000", "0"],
        ["50142.000000", "1.279000", "0"],
        ["50148.000000", "2.892900", "0"],
        ["50154.000000", "1.279000", "0"],
        ["50160.000000", "1.133000", "0"],
        ["50166.000000", "3.090700", "0"],
        ["50172.000000", "1.279000", "0"],
        ["50173.000000", "1.300000", "0"],
        ["50176.000000", "0.179000", "0"],
        ["50180.000000", "2.173000", "0"],
        ["50186.000000", "0.500000", "0"],
        ["50192.000000", "3.229000", "0"],
        ["50193.000000", "1.292900", "0"],
        ["50194.000000", "0.133000", "0"],
        ["50201.000000", "3.239000", "0"],
        ["50206.000000", "2.317700", "0"],
        ["50210.000000", "2.568000", "0"],
        ["50212.000000", "1.432000", "0"],
        ["50213.000000", "2.523000", "0"],
        ["50216.000000", "0.772000", "0"],
        ["50218.000000", "1.298000", "0"],
        ["50220.000000", "2.382000", "0"],
        ["50221.000000", "0.338900", "0"],
        ["50223.000000", "3.374000", "0"],
        ["50227.000000", "2.233000", "0"],
        ["50230.000000", "1.170700", "0"],
        ["50232.000000", "3.028000", "0"],
        ["50236.000000", "1.140000", "0"],
        ["50239.000000", "2.239000", "0"],
        ["50240.000000", "2.374000", "0"],
        ["50241.000000", "0.683000", "0"],
        ["50342.000000", "1.982000", "0"],
        ["50343.000000", "3.093900", "0"],
        ["50344.000000", "3.234000", "0"],
        ["50346.000000", "2.493000", "0"],
        ["50347.000000", "1.987700", "0"],
        ["50348.000000", "0.908000", "0"],
        ["50350.000000", "2.230000", "0"],
        ["50351.000000", "3.093000", "0"],
        ["50352.000000", "2.395000", "0"],
        ["50353.000000", "0.098000", "0"],
        ["50355.000000", "2.234000", "0"],
        ["50357.000000", "3.264900", "0"],
        ["50358.000000", "2.293000", "0"],
        ["50360.000000", "1.098000", "0"],
        ["50361.000000", "1.293700", "0"],
        ["50362.000000", "0.872000", "0"]
      ],
      "bids": [
        ["50113.500000", "0.400000", "0"],
        ["50113.000000", "0.051800", "0"],
        ["50112.000000", "1.455300", "0"],
        ["50106.000000", "1.174800", "0"],
        ["50100.500000", "0.800000", "0"],
        ["50100.000000", "1.455300", "0"],
        ["50097.500000", "0.048000", "0"],
        ["50097.000000", "0.148000", "0"],
        ["50096.500000", "0.399200", "0"],
        ["50095.000000", "0.399200", "0"],
        ["50093.500000", "0.300000", "0"],
        ["50092.000000", "0.023400", "0"],
        ["50091.000000", "1.367300", "0"],
        ["50089.000000", "2.198800", "0"],
        ["50088.500000", "2.300000", "0"],
        ["50086.000000", "0.398300", "0"],
        ["50085.500000", "1.389000", "0"],
        ["50084.000000", "2.387000", "0"],
        ["50083.500000", "3.233200", "0"],
        ["50082.000000", "1.287200", "0"],
        ["50081.500000", "1.384000", "0"],
        ["50080.000000", "2.384800", "0"],
        ["50078.000000", "0.982300", "0"],
        ["50076.000000", "2.387800", "0"],
        ["50074.500000", "2.387200", "0"],
        ["50072.000000", "1.455300", "0"],
        ["50070.500000", "1.342000", "0"],
        ["50069.000000", "0.987000", "0"],
        ["50068.500000", "0.287300", "0"],
        ["50066.000000", "0.276300", "0"],
        ["50063.500000", "1.873000", "0"],
        ["50062.000000", "0.082700", "0"],
        ["50061.000000", "2.123400", "0"],
        ["50060.000000", "3.298300", "0"],
        ["50059.500000", "1.283000", "0"],
        ["50057.000000", "2.483300", "0"],
        ["50056.500000", "1.221000", "0"],
        ["50054.000000", "0.387000", "0"],
        ["50053.500000", "1.287200", "0"],
        ["50052.000000", "2.376200", "0"],
        ["50051.500000", "1.280000", "0"],
        ["50050.000000", "1.398800", "0"],
        ["50049.000000", "2.345300", "0"],
        ["50049.000000", "9.038700", "0"],
        ["50047.500000", "1.230000", "0"],
        ["50046.000000", "2.375300", "0"],
        ["50045.500000", "3.238000", "0"],
        ["50044.000000", "1.298000", "0"],
        ["50042.500000", "2.121000", "0"],
        ["50040.000000", "2.123200", "0"]
      ],
      "t": 1654784843465,
      "tt": 1654784843435,
      "u": 545391566464
    }]
  }
}

Publishes order book changes for an instrument (e.g. BTCUSD-PERP) based on price level depth. By default, returns maximum depth of 50.

Applies To

Websocket (Market Data Subscriptions)

Channel Parameters

Name Type Required Description
instrument_name string Y e.g. BTCUSD-PERP

Response Fields

Please refer to the "Response Fields" of book.{instrument_name}.{depth} section below.

book.{instrument_name}.{depth}

Request Sample - Subscription (SNAPSHOT by default)

{
  "id": 1,
  "method": "subscribe",
  "params": {
    "channels": ["book.BTCUSD-PERP.10"]
  }
}

Response Sample - Subscription (SNAPSHOT)

// Snapshot
{
  "id": -1,
  "method": "subscribe",
  "code": 0,
  "result": {
    "instrument_name": "BTCUSD-PERP",
    "subscription": "book.BTCUSD-PERP.10",
    "channel": "book",
    "depth": 10,
    "data": [
      {
        "asks": [
          ["30082.5", "0.1689", "1"],
          ["30083.0", "0.1288", "1"],
          ["30084.5", "0.0171", "1"],
          ["30085.0", "0.0369", "2"],
          ["30086.5", "0.2664", "1"],
          ["30087.0", "0.8000", "1"],
          ["30089.0", "0.1828", "1"],
          ["30089.5", "0.1828", "1"],
          ["30090.0", "0.1995", "1"],
          ["30091.0", "0.1986", "2"]
        ],
        "bids": [
          ["30079.0", "0.0505", "1"],
          ["30077.5", "1.0527", "2"],
          ["30076.0", "0.1689", "1"],
          ["30075.5", "0.0171", "1"],
          ["30075.0", "0.1288", "1"],
          ["30074.5", "0.0033", "1"],
          ["30073.5", "0.1675", "1"],
          ["30072.5", "0.3424", "1"],
          ["30072.0", "0.2161", "2"],
          ["30071.5", "0.1829", "1"]
        ],
        "t": 1654780033786,
        "tt": 1654780033755,
        "u": 542048017824
      }
    ]
  }
}

Request Sample - Subscription (SNAPSHOT_AND_UPDATE)

{
  "id": 1,
  "method": "subscribe",
  "params": {
    "channels": ["book.BTCUSD-PERP.10"],
    "book_subscription_type": "SNAPSHOT_AND_UPDATE",
    "book_update_frequency": 10
  }
}

Response Sample - Subscription (SNAPSHOT_AND_UPDATE)

// Snapshot
{
  "id": -1,
  "method": "subscribe",
  "code": 0,
  "result": {
    "instrument_name": "BTCUSD-PERP",
    "subscription": "book.BTCUSD-PERP.10",
    "channel": "book",
    "depth": 10,
    "data": [{
      "asks": [
        ["50126.000000", "0.400000", "2"],
        ["50130.000000", "1.279000", "3"],
        ["50136.000000", "1.279000", "5"],
        ["50137.000000", "0.800000", "7"],
        ["50142.000000", "1.279000", "1"],
        ["50148.000000", "2.892900", "9"],
        ["50154.000000", "1.279000", "5"],
        ["50160.000000", "1.133000", "2"],
        ["50166.000000", "3.090700", "1"],
        ["50172.000000", "1.279000", "1"]
      ],
      "bids": [
        ["50113.500000", "0.400000", "3"],
        ["50113.000000", "0.051800", "1"],
        ["50112.000000", "1.455300", "1"],
        ["50106.000000", "1.174800", "2"],
        ["50100.500000", "0.800000", "4"],
        ["50100.000000", "1.455300", "5"],
        ["50097.500000", "0.048000", "8"],
        ["50097.000000", "0.148000", "9"],
        ["50096.500000", "0.399200", "2"],
        ["50095.000000", "0.399200", "3"]
      ],
      "tt": 1647917462799,
      "t": 1647917463000,
      "u": 7845460001
    }]
  }
}

// Update
{
  "id": -1,
  "method": "subscribe",
  "code": 0,
  "result": {
    "instrument_name": "BTCUSD-PERP",
    "subscription": "book.BTCUSD-PERP.10",
    "channel": "book.update",
    "depth": 10,
    "data": [{
      "update": {
        "asks":[
          ["50126.000000", "0", "0"],
          ["50180.000000", "3.279000", "10"]],
        "bids":[["50097.000000", "0.252000", "1"]]
      }],
      "tt": 1647917463003,
      "t": 1647917463003,
      "u": 7845460002,
      "pu": 7845460001
    }]
  }
}

Orderbook / L2 streaming at millisecond frequency.

Applies To

Websocket (Market Data Subscriptions)

Channel Parameters

Name Description
instrument_name Must be formal symbol. e.g. BTCUSD-PERP
depth Maximum number of depth levels. Allowed values:
- 50 (default)
- 10

Two types of book subscription are supported:

Optional parameters are used for specify the subscription type:

Name Description
book_subscription_type The subscription type. Allowed values:
- SNAPSHOT full snapshot. This is the default if not specified.
- SNAPSHOT_AND_UPDATE delta updates
book_update_frequency Book update interval in ms. Allowed values:
- 100 for snapshot subscription
- 10 for delta subscription

Response Fields

Name Type Description
instrument_name string Same as requested instrument_name
subscription string Same as requested channel
channel string book or book.update, see below
depth string Same as requested depth
data array See below

For book snapshot broadcasts, data consists of:

Name Type Description
bids array Array of level
asks array Array of level
tt integer Epoch millis of last book update
t integer Epoch millis of message publish
u integer Update sequence, See below

For book.update delta broadcasts, data consists of:

Name Type Description
update object bids and asks
tt integer Epoch millis of last book update
t integer Epoch millis of message publish
u integer Update sequence, See below
pu integer Previous update sequence, See below

level is an array:

Index Type Description
0 string Price of the level
1 string Total size of the level
2 string Number of standing orders in the level

Upon successful subscription, a book snapshot will be sent. Subsequently behaviour is then dependent on subscription type.

For snapshot subscriptions:

For delta subscriptions:

ticker.{instrument_name}

Request Sample

{
  "id": 1,
  "method": "subscribe",
  "params": {
    "channels": ["ticker.BTCUSD-PERP"]
  },
  "nonce": 1587523073344
}

Response Sample

{
  "id": -1,
  "method": "subscribe",
  "code": 0,
  "result": {
    "instrument_name": "BTCUSD-PERP",
    "subscription": "ticker.BTCUSD-PERP",
    "channel": "ticker",
    "data": [{
      "h": "51790.00",        // Price of the 24h highest trade
      "l": "47895.50",        // Price of the 24h lowest trade, null if there weren't any trades
      "a": "51174.500000",    // The price of the latest trade, null if there weren't any trades
      "c": "0.03955106",      // 24-hour price change, null if there weren't any trades
      "b": "51170.000000",    // The current best bid price, null if there aren't any bids
      "bs": "0.1000",         // The current best bid size, null if there aren't any bids
      "k": "51180.000000",    // The current best ask price, null if there aren't any asks
      "ks": "0.2000",         // The current best ask size, null if there aren't any bids
      "i": "BTCUSD-PERP",     // Instrument name
      "v": "879.5024",        // The total 24h traded volume
      "vv": "26370000.12",    // The total 24h traded volume value (in USD)
      "oi": "12345.12",       // Open interest
      "t": 1613580710768
    }]
  }
}

Publishes new tickers for an instrument (e.g. BTCUSD-PERP).

Applies To

Websocket (Market Data Subscriptions)

Channel Parameters

Name Type Required Description
instrument_name string Y Must be formal symbol. e.g. BTCUSD-PERP

Response Attributes

Name Type Description
instrument_name string e.g. BTCUSD-PERP
subscription string ticker.{instrument_name}
channel string Always 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 string Price of the 24h highest trade
l string Price of the 24h lowest trade, null if there weren't any trades
a string The price of the latest trade, null if there weren't any trades
c string 24-hour price change, null if there weren't any trades
b string The current best bid price, null if there aren't any bids
bs string The current best bid size, null if there aren't any bids
k string The current best ask price, null if there aren't any asks
ks string The current best ask size, null if there aren't any bids
i string Instrument name
v string The total 24h traded volume
vv string The total 24h traded volume value (in USD)
oi string The open interest
t number Trade timestamp

trade.{instrument_name}

Request Sample

{
  "id": 1,
  "method": "subscribe",
  "params": {
    "channels": ["trade.BTCUSD-PERP"]
  }
}

Response Sample

{
  "id": 1,
  "method": "subscribe",
  "code": 0,
  "result": {
    "instrument_name": "BTCUSD-PERP",
    "subscription": "trade.BTCUSD-PERP",
    "channel": "trade",
    "data": [{
      "d" : "2030407068",    // Trade ID
      "t": 1613581138462,    // Trade time
      "p": "51327.500000",   // Price
      "q": "0.000100",       // Quantity
      "s": "SELL",           // Side
      "i": "BTCUSD-PERP"     // Instrument name
    }]
  }
}

Publishes new trades for an instrument (e.g. BTCUSD-PERP).

Applies To

Websocket (Market Data Subscriptions)

Response Attributes

Name Type Description
instrument_name string e.g. BTCUSD-PERP
subscription string trade.{instrument_name}
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
d string of number Trade ID
t number Trade timestamp
p string Trade price
q string Trade quantity
s string Side (BUY or SELL). Side is the side of the taker order
i string Instrument name

candlestick.{time_frame}.{instrument_name}

Request Sample

{
  "id": 1,
  "method": "subscribe",
  "params": {
    "channels": ["candlestick.D1.BTCUSD-PERP"]
  }
}

Response Sample

{
  "id": 1,
  "method": "subscribe",
  "code": 0,
  "result": {
    "instrument_name": "BTCUSD-PERP",
    "subscription": "candlestick.1D.BTCUSD-PERP",
    "channel": "candlestick",
    "interval": "1D",
    "data": [{
      "o": "51140.500000",    // Open price
      "h": "51699.000000",    // High price
      "l": "49212.000000",    // Low price
      "c": "51313.500000",    // Close price
      "v": "867.9432",        // Volume
      "t": 1612224000000      // Start time
    }]
  }
}

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

period can be:

Legacy format is still supported until further notice.

Applies To

Websocket (Market Data Subscriptions)

Response Attributes

Name Type Description
instrument_name string e.g. BTCUSD-PERP
subscription string candlestick.{time_frame}.{instrument_name}
channel string Always candlestick
interval string The period (e.g. M5)
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
h number High
l number Low
c number Close
v number Volume
t long Start time of candlestick (Unix timestamp)

index.{instrument_name}

Request Sample

{
  "id": 1,
  "method": "subscribe",
  "params": {
    "channels": ["index.BTCUSD-INDEX"]
  }
}

Response Sample

{
  "id": 1,
  "method": "subscribe",
  "code": 0,
  "result": {
    "instrument_name": "BTCUSD-INDEX",
    "subscription": "index.BTCUSD-INDEX",
    "channel": "index",
    "data": [{
      "v": "51204.52000",
      "t": 1613582703000
    }]
  }
}

Applies To

Websocket (Market Data Subscriptions)

Response Attributes

Name Type Description
instrument_name string e.g. BTCUSD-INDEX
subscription string index.{instrument_name}
channel string Always index
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
t number Updated time (Unix timestamp)
v string Value of the Index Price

mark.{instrument_name}

Request Sample

{
  "id": 1,
  "method": "subscribe",
  "params": {
    "channels": ["mark.BTCUSD-PERP"]
  }
}

Response Sample

{
  "id": 1,
  "method": "subscribe",
  "code": 0,
  "result": {
    "instrument_name": "BTCUSD-PERP",
    "subscription": "mark.BTCUSD-PERP",
    "channel": "mark",
    "data": [{
      "v": "51279.77000",
      "t": 1613582832000
    }]
  }
}

Note: Mark price will update approximately every 50 ms

Applies To

Websocket (Market Data Subscriptions)

Response Attributes

Name Type Description
instrument_name string e.g. BTCUSD-PERP
subscription string mark.{instrument_name}
channel string Always mark
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
t number Updated time (Unix timestamp)
v string Value of the Mark Price

settlement.{instrument_name}

Request Sample

{
  "id": 1,
  "method": "subscribe",
  "params": {
    "channels": ["settlement.BTCUSD-210528"]
  }
}

Response Sample

{
  "id": 1,
  "method": "subscribe",
  "code": 0,
  "result": {
    "instrument_name": "BTCUSD-210528",
    "subscription": "settlement.BTCUSD-210528",
    "channel": "settlement",
    "data": [{
      "v": "35279.77000",
      "t": 1613582832000
    }]
  }
}

Publishes settlement prices for either a single instrument (e.g. BTCUSD-210528") or all instruments.

Applies To

Websocket (Market Data Subscriptions)

Channel Parameters

Name Type Required Description
instrument_name string N Optional, if not set this is a wildcard subscription for all instruments

Response Attributes

Name Type Description
instrument_name string e.g. BTCUSD-210528
subscription string settlement.{instrument_name}
channel string Always settlement
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
t number Updated time (Unix timestamp)
v string Value of the Settlement Price

funding.{instrument_name}

Request Sample

{
  "id": 1,
  "method": "subscribe",
  "params": {
    "channels": ["funding.BTCUSD-PERP"]
  }
}

Response Sample

{
  "id": 1,
  "method": "subscribe",
  "code": 0,
  "result": {
    "instrument_name": "BTCUSD-PERP",
    "subscription": "funding.BTCUSD-PERP",
    "channel": "funding",
    "data": [{
      "v": "0.00144",
      "t": 1613582880000
    }]
  }
}

Applies To

Websocket (Market Data Subscriptions)

Response Attributes

Name Type Description
instrument_name string e.g. BTCUSD-PERP
subscription string funding.{instrument_name}
channel string funding - Refers to hourly rate that will settle at the end of the current hour
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
t number Updated time (Unix timestamp)
v string Value of the Funding Rate

estimatedfunding.{instrument_name}

Request Sample

{
  "id": 1,
  "method": "subscribe",
  "params": {
    "channels": ["estimatedfunding.BTCUSD-PERP"]
  }
}

Response Sample

{
  "id": 1,
  "method": "subscribe",
  "code": 0,
  "result": {
    "instrument_name": "BTCUSD-PERP",
    "subscription": "estimated.BTCUSD-PERP",
    "channel": "estimatedfunding",
    "data": [{
      "v": "0.00144",
      "t": 1613582880000
    }]
  }
}

Applies To

Websocket (Market Data Subscriptions)

Response Attributes

Name Type Description
instrument_name string e.g. BTCUSD-PERP
subscription string estimatedfunding.{instrument_name}
channel string estimatedfunding - Refers to estimated hourly rate that will be effective at the end of each hour in the next interval.

Funding intervals are 00:00 - 04:00, 04:00 - 08:00, 08:00 - 12:00, 12:00 - 16:00, 16:00 - 20:00, 20:00 - 00:00 UTC
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
t number Updated time (Unix timestamp)
v string Value of the Estimated Funding Rate

public/auth

Request Sample #0: Auth with the master account

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

Request Sample #1: Auth with the master account (same effect as sample #0)

{
  "id": 1,
  "method": "public/auth",
  "api_key": "master_api_key",
  "sig": "d0267b151db609885bad2e4f8ad07610f7913e166c35adaf5697d59a64e3755a",
  "nonce": :1587846358253,
  "params": {
    "system_label": "ONEEX"
  }
}

Request Sample #2: Auth with former spot account (same effect as sample #0)

{
  "id": 1,
  "method": "public/auth",
  "api_key": "master_api_key",
  "sig": "d0267b151db609885bad2e4f8ad07610f7913e166c35adaf5697d59a64e3755a",
  "nonce": :1587846358253,
  "params": {
    "system_label": "FORMER_SPOT"
  }
}

Request Sample #3: Auth with former master margin account

{
  "id": 1,
  "method": "public/auth",
  "api_key": "master_api_key",
  "sig": "d0267b151db609885bad2e4f8ad07610f7913e166c35adaf5697d59a64e3755a",
  "nonce": :1587846358253,
  "params": {
    "system_label": "FORMER_MARGIN"
  }
}

Request Sample #4: Auth with former master derivative account

{
  "id": 1,
  "method": "public/auth",
  "api_key": "master_api_key",
  "sig": "d0267b151db609885bad2e4f8ad07610f7913e166c35adaf5697d59a64e3755a",
  "nonce": :1587846358253,
  "params": {
    "system_label": "FORMER_DERIVATIVES"
  }
}

Request Sample #5: Auth with default sub-account

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

Request Sample #6: Auth with former spot sub-account

{
  "id": 1,
  "method": "public/auth",
  "api_key": "subaccount_api_key",
  "sig": "d0267b151db609885bad2e4f8ad07610f7913e166c35adaf5697d59a64e3755a",
  "nonce": :1587846358253,
  "params": {
    "system_label": "FORMER_SPOT"
  }
}

Request Sample #7: Auth with former margin sub-account

{
  "id": 1,
  "method": "public/auth",
  "api_key": "subaccount_api_key",
  "sig": "d0267b151db609885bad2e4f8ad07610f7913e166c35adaf5697d59a64e3755a",
  "nonce": :1587846358253,
  "params": {
    "system_label": "FORMER_MARGIN"
  }
}

Request Sample #8: Auth with former derivative sub-account

{
  "id": 1,
  "method": "public/auth",
  "api_key": "subaccount_api_key",
  "sig": "d0267b151db609885bad2e4f8ad07610f7913e166c35adaf5697d59a64e3755a",
  "nonce": :1587846358253,
  "params": {
    "system_label": "FORMER_DERIVATIVES"
  }
}

Response Sample

{
  "id": 1,
  "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)
system_label string see Unified Wallet and System Label section

Applies To:

Websocket (User API)

private/set-cancel-on-disconnect

Request Sample

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

Response Sample

{
  "id": 1,
  "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 to be applied to the specific connection (all orders created via Websocket). The ONLY scope supported is CONNECTION

Helpful Information

Applies To

Websocket (User API)

Response Attributes

Name Type Description
scope string Specifies the scope of cancellation to be applied to the specific connection (all orders created via Websocket). The ONLY scope supported is CONNECTION

private/get-cancel-on-disconnect

Request Sample

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

Response Sample

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

Returns the scope of cancellation.

Request Params

None

Applies To

Websocket (User API)

Response Attributes

Name Type Description
scope string Specifies the scope of cancellation to be applied to the specific connection (all orders created via Websocket). The ONLY scope supported is CONNECTION

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 60 seconds in the future / 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 N seconds from the nonce to force it to be N seconds in the past, which is still within the 60-second past tolerance.

javascript python c# java