NAV Navbar
Derivatives Exchange API
javascript python c# java

Introduction

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

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

Change Logs

Generating the API Key

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

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

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

API Key and Secret are randomly generated by the system and can not be modified. Default settings will be set to "Can Read" only, and you have the option of adding or removing certain permissions for your API Key via Web UI.

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

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

Rate Limits

REST API

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

Method Limit
private/create-order
private/cancel-order
private/cancel-all-orders		 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.

REST API Root Endpoint

UAT Sandbox

REST API

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

Production

REST API

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

Websocket Root Endpoints

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

UAT Sandbox

Websocket (User API and Subscriptions)

wss://uat-deriv-stream.3ona.co/v1/user

Websocket (Market Data Subscriptions)

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

Production

Websocket (User API and Subscriptions)

wss://deriv-stream.crypto.com/v1/user

Websocket (Market Data Subscriptions)

wss://deriv-stream.crypto.com/v1/market

Derivative API Reference

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

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

Naming Conventions

Request Format

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

Name Type Required Description
id long 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, apiKey, apiSecret) => {
  const { id, method, params, nonce } = request;

  const paramsString =
    params == null
      ? ""
      : Object.keys(params)
          .sort()
          .reduce((a, b) => {
            let value = params[b];
            if (value != null && Array.isArray(value)) {
                let len = value.length;
                let lastIdx = len - 1;
                let valueString = '';
                value.forEach(function (v) {
                    if (v == null) {
                        valueString += 'null';
                    } else {
                        valueString += v;
                    }
                    if (i < lastIdx) {
                        valueString += ',';
                    }
                    i++;
                });
                return a + b + valueString;
            } else {
                return a + b + value;
            }
          }, "");

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

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

  return request;
};

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

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

const requestBody = JSON.stringify(signRequest(request, apiKey, apiSecret)));

import hmac
import hashlib
import json
import requests
import time

API_KEY = "API_KEY"
SECRET_KEY = "SECRET_KEY"

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

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

if "params" in req:
  for key in sorted(req['params']):
    paramString += key
    value = req['params'][key]
    if value is None:
      paramString += 'null'
    elif isinstance(value, list):
      paramString += ','.join(value)
    else:
      paramString += str(value)

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

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


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

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

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

  // Ensure the params are alphabetically sorted by key
  // 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 org.apache.commons.codec.binary.Hex;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Map;
import java.util.TreeMap;

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

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

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

  public static String generateParamsString(Map<String, Object> rawParams) {
    StringBuilder paramsString = new StringBuilder();

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

      for (Map.Entry<String, Object> entry : params.entrySet()) {
        Object value = entry.getValue();
        paramsString
            .append(entry.getKey());
        if (value instanceof Double) {
          paramsString
              .append((new BigDecimal(value.toString())).stripTrailingZeros()
                  .toPlainString());
        } else if (value instanceof Collection<?>) {
          Collection<?> items = (Collection<?>) value;
          int size = items.size();
          int i = 0;
          int lastIdx = size - 1;
          for (Object item : items) {
            paramsString.append(item);
            if (i < lastIdx) {
              paramsString.append(",");
            }
            i++;
          }
        } else {
          paramsString.append(value);
        }
      }
    }

    return paramsString.toString();

  }

  public static String genSigPayload(ApiRequestJson apiRequestJson) {
    if (apiRequestJson == null) {
      return "";
    }

    return apiRequestJson.getMethod()
        + apiRequestJson.getId()
        + apiRequestJson.getApiKey()
        + generateParamsString(apiRequestJson.getParams())
        + (apiRequestJson.getNonce() == null ? "" : apiRequestJson.getNonce());
  }

  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 sigPayload = genSigPayload(apiRequestJson);

      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:

Spot vs. Derivatives: Request Format

For spot, prices can be numbers or strings (wrapped in double quotes)

However, for Derivatives, 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
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.

public/auth

Request Sample

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

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)

Applies To:

Websocket (User 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": [{
            "s": "SELL",            // Side
            "p": "50772.000000",    // Price
            "q": "0.181900",        // Quantity
            "t": 1613547060925,     // Trade timestamp
            "d": "15281981878",     // Trade ID
            "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 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
p number Trade price
q number Trade quantity
s string Side ("buy" or "sell")
i string Instrument name e.g. BTCUSD-PERP
t number Trade timestamp
d string of number Trade ID

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 e.g. index_price, funding_hist, mark_price, settlement_price
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

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

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_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_amount": "4537.302561971453",
                        "collateral_weight": "0.95",
                        "max_withdrawal_balance": "24422.72427884",
                        "reserved_qty" : "0.00000000"
                    },
                    {
                        "instrument_name": "USD",
                        "quantity": "3113.50747209",
                        "market_value": "3113.50747209",
                        "collateral_amount": "3113.50747209",
                        "collateral_weight": "1.0",
                        "max_withdrawal_balance": "3113.50747209",
                        "reserved_qty" : "0.00000000"
                    },
                    {
                        "instrument_name": "USDT",
                        "quantity": "0.19411607",
                        "market_value": "0.19389555414448",
                        "collateral_amount": "0.18904816529086801",
                        "collateral_weight": "0.975",
                        "max_withdrawal_balance": "0.19411607",
                        "reserved_qty" : "0.00000000"
                    },
                    {
                        "instrument_name": "DAI",
                        "quantity": "0.19387960",
                        "market_value": "0.1938796",
                        "collateral_amount": "0.18903261000000002",
                        "collateral_weight": "0.975",
                        "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 Balance for the margin calculation (Wallet Balance + Unrealized PnL)
total_initial_margin string Total initial margin requirement for all positions and all open orders
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_weight string Collateral weight
collateral_amount string Collateral amount derived by market_value times collateral_weight
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/create-subaccount-transfer

Request Sample

{
    "id": 1234,
    "method": "private/create-subaccount-transfer",
    "params": {
        "from": "00000000-0000-0000-0000-000000000001", // Possible value: the master account UUID, or a sub-account UUID.
        "to": "00000000-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",
                        "collateral_weight": "0.9500000000",
                        "collateral_amount": "20822.6225000000",
                        "market_value": "21918.5500000000",
                        "max_withdrawal_balance": "1.0000000000"
                    },
                    {
                        "instrument_name": "USD",
                        "quantity": "1.00000000",
                        "collateral_weight": "1.00000000",
                        "collateral_amount": "1.00000000",
                        "market_value": "1.00000000",
                        "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",
                        "collateral_weight": "0.9500000000",
                        "collateral_amount": "20822.6225000000",
                        "market_value": "21918.5500000000",
                        "max_withdrawal_balance": "1.0000000000"
                    },
                    {
                        "instrument_name": "USD",
                        "quantity": "100.00000000",
                        "collateral_weight": "1.00000000",
                        "collateral_amount": "100.00000000",
                        "market_value": "100.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 Balance for the margin calculation (Wallet Balance + Unrealized PnL)
total_initial_margin string Total initial margin requirement for all positions and all open orders
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_weight string Collateral weight
collateral_amount string Collateral amount derived by market_value times collateral_weight
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)

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

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/create-order-list

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.

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

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

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

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

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

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

Pagination - Orders of ALL Instruments

Request Example - First page, most recent order records, with page size of 10.

{
    "id": 12,
    "method": "private/get-order-history",
    "params": {
        "limit": 10
    }
}

Response Example - First page

{
    "id": 12,
    "method": "private/get-order-history",
    "code": 0,
    "result": {
        "data": [
            {
                "account_id": "88888888-8888-8888-8888-000000000008",
                "order_id": "2317",
                "client_oid": "f9452cc4-a8bd-4887-ba0d-26d95cee0234",
                "order_type": "LIMIT",
                "time_in_force": "GOOD_TILL_CANCEL",
                "side": "SELL",
                "exec_inst": [],
                "quantity": "0.0002",
                "limit_price": "1600.00",
                "order_value": "0.320000",
                "maker_fee_rate": "0.000250",
                "taker_fee_rate": "0.000400",
                "avg_price": "1600.00",
                "cumulative_quantity": "0.0002",
                "cumulative_value": "0.320000",
                "cumulative_fee": "0.000080",
                "status": "FILLED",
                "update_user_id": "11111111-1111-1111-1111-000000000008",
                "order_date": "2021-03-09",
                "instrument_name": "ETHUSD-PERP",
                "fee_instrument_name": "USD",
                "create_time": 1615280621728,
                "create_time_ns": "1615280621728123456",
                "update_time": 1615280621744
            },
            //...
            {
                "account_id": "88888888-8888-8888-8888-000000000008",
                "order_id": "2301",
                "client_oid": "dd50a978-bacc-4a03-9df1-5815a0adb2cb",
                "order_type": "LIMIT",
                "time_in_force": "GOOD_TILL_CANCEL",
                "side": "SELL",
                "exec_inst": [],
                "quantity": "0.0002",
                "limit_price": "50000.0",
                "order_value": "10.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": "CANCELED",
                "update_user_id": "11111111-1111-1111-1111-000000000008",
                "order_date": "2021-03-08",
                "instrument_name": "BTCUSD-PERP",
                "fee_instrument_name": "USD",
                "create_time": 1615199206815,
                "create_time_ns": "1615199206815123456",
                "update_time": 1615199206871
            }
        ]
    }
}

Request Example - Second page, look up for same search criteria, but only look for the records before create_time_ns 1615199206815123456, which is indicated in the last record of the first page.

{
    "id": 12,
    "method": "private/get-order-history",
    "params": {
        "end_time": "1615199206815123456",
        "limit": 10
    }
}

Response Example - Second page

{
    "id": 12,
    "method": "private/get-order-history",
    "code": 0,
    "result": {
        "data": [
            {
                "account_id": "88888888-8888-8888-8888-000000000008",
                "order_id": "2300",
                "client_oid": "73a1c4fa-2185-4793-ab3f-f9423e146af5",
                "order_type": "LIMIT",
                "time_in_force": "GOOD_TILL_CANCEL",
                "side": "SELL",
                "exec_inst": [],
                "quantity": "0.0002",
                "limit_price": "1600.00",
                "order_value": "0.320000",
                "maker_fee_rate": "0.000250",
                "taker_fee_rate": "0.000400",
                "avg_price": "1680.00",
                "cumulative_quantity": "0.0002",
                "cumulative_value": "0.336000",
                "cumulative_fee": "0.000135",
                "status": "FILLED",
                "update_user_id": "11111111-1111-1111-1111-000000000008",
                "order_date": "2021-03-08",
                "instrument_name": "ETHUSD-PERP",
                "fee_instrument_name": "USD",
                "create_time": 1615198368095,
                "create_time_ns": "1615198368095123456",
                "update_time": 1615198369904
            },
            //...
            {
                "account_id": "88888888-8888-8888-8888-000000000008",
                "order_id": "2255",
                "client_oid": "3625b98e-bf9c-4172-b3ec-a4e6fcc7cb57",
                "order_type": "LIMIT",
                "time_in_force": "GOOD_TILL_CANCEL",
                "side": "SELL",
                "exec_inst": [],
                "quantity": "0.0002",
                "limit_price": "1600.00",
                "order_value": "0.320000",
                "maker_fee_rate": "0.000250",
                "taker_fee_rate": "0.000400",
                "avg_price": "1680.00",
                "cumulative_quantity": "0.0002",
                "cumulative_value": "0.336000",
                "cumulative_fee": "0.000135",
                "status": "FILLED",
                "update_user_id": "11111111-1111-1111-1111-000000000008",
                "order_date": "2021-03-08",
                "instrument_name": "ETHUSD-PERP",
                "fee_instrument_name": "USD",
                "create_time": 1615198367594,
                "create_time_ns": "1615198367594123456",
                "update_time": 1615198369488
            }
        ]
    }
}

Pagination - Orders of Specific Instrument

{
    "id": 12,
    "method": "private/get-order-history",
    "params": {
        "limit": 2
    }
}

Response Example - First page

{
    "id": 12,
    "method": "private/get-order-history",
    "code": 0,
    "result": {
        "data": [
            {
                "account_id": "88888888-8888-8888-8888-000000000008",
                "order_id": "2317",
                "client_oid": "f9452cc4-a8bd-4887-ba0d-26d95cee0234",
                "order_type": "LIMIT",
                "time_in_force": "GOOD_TILL_CANCEL",
                "side": "SELL",
                "exec_inst": [],
                "quantity": "0.0002",
                "limit_price": "1600.00",
                "order_value": "0.320000",
                "maker_fee_rate": "0.000250",
                "taker_fee_rate": "0.000400",
                "avg_price": "1600.00",
                "cumulative_quantity": "0.0002",
                "cumulative_value": "0.320000",
                "cumulative_fee": "0.000080",
                "status": "FILLED",
                "update_user_id": "11111111-1111-1111-1111-000000000008",
                "order_date": "2021-03-09",
                "instrument_name": "ETHUSD-PERP",
                "fee_instrument_name": "USD",
                "create_time": 1615280621728,
                "create_time_ns": "1615280621728123456",
                "update_time": 1615280621744
            },
            {
                "account_id": "88888888-8888-8888-8888-000000000008",
                "order_id": "2316",
                "client_oid": "d165caa2-1901-4b0b-88e3-8d9d04b190c2",
                "order_type": "LIMIT",
                "time_in_force": "GOOD_TILL_CANCEL",
                "side": "SELL",
                "exec_inst": [],
                "quantity": "0.0002",
                "limit_price": "1700.00",
                "order_value": "0.340000",
                "maker_fee_rate": "0.000250",
                "taker_fee_rate": "0.000400",
                "avg_price": "0.00",
                "cumulative_quantity": "0.0000",
                "cumulative_value": "0.000000",
                "cumulative_fee": "0.000000",
                "status": "CANCELED",
                "update_user_id": "11111111-1111-1111-1111-000000000008",
                "order_date": "2021-03-09",
                "instrument_name": "ETHUSD-PERP",
                "fee_instrument_name": "USD",
                "create_time": 1615280621726,
                "create_time_ns": "1615280621726123456",
                "update_time": 1615280621739
            }
        ]
    }
}

Request Example - Second page, look up for same search criteria, but only look for the records before create_time_ns 1615280621744123001, which is indicated in the last record of the first page.

{
    "id": 12,
    "method": "private/get-order-history",
    "params": {
        "end_time": "1615280621726123456",
        "limit": 2
    }
}

Response Example - Second page

{
    "id": 12,
    "method": "private/get-order-history",
    "code": 0,
    "result": {
        "data": [
            {
                "account_id": "88888888-8888-8888-8888-000000000008",
                "order_id": "2315",
                "client_oid": "0270a222-c18f-48b1-a3d1-2f8ffe0e2013",
                "order_type": "LIMIT",
                "time_in_force": "GOOD_TILL_CANCEL",
                "side": "BUY",
                "exec_inst": [],
                "quantity": "0.0020",
                "limit_price": "1680.00",
                "order_value": "3.360000",
                "maker_fee_rate": "0.000250",
                "taker_fee_rate": "0.000400",
                "avg_price": "1600.00",
                "cumulative_quantity": "0.0002",
                "cumulative_value": "0.320000",
                "cumulative_fee": "0.000128",
                "status": "CANCELED",
                "update_user_id": "11111111-1111-1111-1111-000000000008",
                "order_date": "2021-03-09",
                "instrument_name": "ETHUSD-PERP",
                "fee_instrument_name": "USD",
                "create_time": 1615280532871,
                "create_time_ns": "1615280532871123456",
                "update_time": 1615280620728
            },
            {
                "account_id": "88888888-8888-8888-8888-000000000008",
                "order_id": "2314",
                "client_oid": "283ac508-c62f-47f7-b34a-9b795e845429",
                "order_type": "LIMIT",
                "time_in_force": "GOOD_TILL_CANCEL",
                "side": "SELL",
                "exec_inst": [],
                "quantity": "0.0002",
                "limit_price": "1600.00",
                "order_value": "0.320000",
                "maker_fee_rate": "0.000250",
                "taker_fee_rate": "0.000400",
                "avg_price": "1600.00",
                "cumulative_quantity": "0.0002",
                "cumulative_value": "0.320000",
                "cumulative_fee": "0.000080",
                "status": "FILLED",
                "update_user_id": "11111111-1111-1111-1111-000000000008",
                "order_date": "2021-03-09",
                "instrument_name": "ETHUSD-PERP",
                "fee_instrument_name": "USD",
                "create_time": 1615280532870,
                "create_time_ns": "1615280532870123456",
                "update_time": 1615280532894
            }
        ]
    }
}

Pagination - Trades of ALL Instruments

Request Example - First page, most recent trade records of all instruments, with page size of 10.

{
    "id": 12,
    "method": "private/get-trades",
    "params": {
        "limit": 10
    }
}

Response Example - First page

{
    "id": 12,
    "method": "private/get-trades",
    "code": 0,
    "result": {
        "data": [
            {
                "account_id": "88888888-8888-8888-8888-000000000008",
                "event_date": "2021-03-09",
                "journal_type": "TRADING",
                "traded_quantity": "0.0002",
                "traded_price": "1600.00",
                "fees": "0.319654",
                "order_id": "2317",
                "trade_id": "3578",
                "trade_match_id": "773",
                "client_oid": "f9452cc4-a8bd-4887-ba0d-26d95cee0234",
                "taker_side": "MAKER",
                "side": "SELL",
                "instrument_name": "ETHUSD-PERP",
                "create_time": 1615280621744,
                "create_time_ns": "1615280621744123456"
            },
            //...
            {
                "account_id": "88888888-8888-8888-8888-000000000008",
                "event_date": "2021-03-08",
                "journal_type": "TRADING",
                "traded_quantity": "0.0002",
                "traded_price": "50000.0",
                "fees": "9.997484",
                "order_id": "2302",
                "trade_id": "3545",
                "trade_match_id": "767",
                "client_oid": "c6288370-8977-4097-ab88-423d24aaacb2",
                "taker_side": "MAKER",
                "side": "SELL",
                "instrument_name": "BTCUSD-PERP",
                "create_time": 1615199206871,
                "create_time_ns": "1615199206871123456"
            }
        ]
    }
}

Request Example - Second page, look up for same search criteria, but only look for the records before create_time_ns 1615199206871123456, which is indicated in the last record of the first page.

{
    "id": 12,
    "method": "private/get-trades",
    "params": {
        "end_time": "1615199206871123456",
        "limit": 10
    }
}

Response Example - Second page

{
    "id": 12,
    "method": "private/get-trades",
    "code": 0,
    "result": {
        "data": [
            {
                "account_id": "88888888-8888-8888-8888-000000000008",
                "event_date": "2021-03-08",
                "journal_type": "TRADING",
                "traded_quantity": "0.0002",
                "traded_price": "50000.0",
                "fees": "-0.004000",
                "order_id": "2303",
                "trade_id": "3546",
                "trade_match_id": "767",
                "client_oid": "e800602b-ee71-4d46-a5a9-36a7f444f481",
                "taker_side": "TAKER",
                "side": "BUY",
                "instrument_name": "BTCUSD-PERP",
                "create_time": 1615199206871,
                "create_time_ns": "1615199206871000003",
            },
            //...
            {
                "account_id": "88888888-8888-8888-8888-000000000008",
                "event_date": "2021-03-08",
                "journal_type": "TRADING",
                "traded_quantity": "0.0002",
                "traded_price": "1680.00",
                "fees": "0.335348",
                "order_id": "2285",
                "trade_id": "3521",
                "trade_match_id": "761",
                "client_oid": "40af6320-cc45-4a12-81ac-887e98acce33",
                "taker_side": "TAKER",
                "side": "SELL",
                "instrument_name": "ETHUSD-PERP",
                "create_time": 1615198369766,
                "create_time": "1615198369766123456"
            }
        ]
    }
}

Pagination - Trades of Specific Instrument

Request Example - First page, most recent records of ETHUSD-PERP, with page size of 2.

{
    "id": 12,
    "method": "private/get-trades",
    "params": {
        "instrument_name": "ETHUSD-PERP",
        "limit": 2
    }
}

Response Example - First page

{
    "id": 12,
    "method": "private/get-trades",
    "code": 0,
    "result": {
        "data": [
            {
                "account_id": "88888888-8888-8888-8888-000000000008",
                "event_date": "2021-03-09",
                "journal_type": "TRADING",
                "traded_quantity": "0.0002",
                "traded_price": "1600.00",
                "fees": "0.319654",
                "order_id": "2317",
                "trade_id": "3578",
                "trade_match_id": "773",
                "client_oid": "f9452cc4-a8bd-4887-ba0d-26d95cee0234",
                "taker_side": "MAKER",
                "side": "SELL",
                "instrument_name": "ETHUSD-PERP",
                "create_time": 1615280621744,
                "create_time_ns": "1615280621744123456"
            },
            {
                "account_id": "88888888-8888-8888-8888-000000000008",
                "event_date": "2021-03-09",
                "journal_type": "TRADING",
                "traded_quantity": "0.0002",
                "traded_price": "1600.00",
                "fees": "-0.000128",
                "order_id": "2318",
                "trade_id": "3579",
                "trade_match_id": "773",
                "client_oid": "b03f4416-ae3e-426d-b385-baef69b6a397",
                "taker_side": "TAKER",
                "side": "BUY",
                "instrument_name": "ETHUSD-PERP",
                "create_time": 1615280621744,
                "create_time_ns": "1615280621744123001"
            }
        ]
    }
}

Request Example - Second page, look up for same search criteria, but only look for the records before create_time_ns 1615280621744123001, which is indicated in the last record of the first page.

{
    "id": 12,
    "method": "private/get-trades",
    "params": {
        "instrument_name": "ETHUSD-PERP",
        "end_time": "1615280621744123001",
        "limit": 2
    }
}

Response Example - Second page

{
    "id": 12,
    "method": "private/get-trades",
    "code": 0,
    "result": {
        "data": [
            {
                "account_id": "88888888-8888-8888-8888-000000000008",
                "event_date": "2021-03-09",
                "journal_type": "TRADING",
                "traded_quantity": "0.0002",
                "traded_price": "1600.00",
                "fees": "0.319655",
                "order_id": "2314",
                "trade_id": "3572",
                "trade_match_id": "772",
                "client_oid": "283ac508-c62f-47f7-b34a-9b795e845429",
                "taker_side": "MAKER",
                "side": "SELL",
                "instrument_name": "ETHUSD-PERP",
                "create_time": 1615280532894,
                "create_time_ns": "1615280532894123456"
            },
            {
                "account_id": "88888888-8888-8888-8888-000000000008",
                "event_date": "2021-03-09",
                "journal_type": "TRADING",
                "traded_quantity": "0.0002",
                "traded_price": "1600.00",
                "fees": "-0.000128",
                "order_id": "2315",
                "trade_id": "3573",
                "trade_match_id": "772",
                "client_oid": "0270a222-c18f-48b1-a3d1-2f8ffe0e2013",
                "taker_side": "TAKER",
                "side": "BUY",
                "instrument_name": "ETHUSD-PERP",
                "create_time": 1615280532894,
                "create_time_ns": "1615280532894123001"
            }
        ]
    }
}

Pagination - Transactions of ALL Instruments

Request Example - First page, most recent transaction records of all instruments, with page size of 2.

{
    "id": 12,
    "method": "private/get-transactions",
    "params": {
        "limit": 2
    }
}

Response Example - First page

{
    "id": 12,
    "method": "private/get-transactions",
    "code": 0,
    "result": {
        "data": [
            {
                "account_id": "88888888-8888-8888-8888-000000000008",
                "event_date": "2021-03-08",
                "journal_type": "TRADING",
                "journal_id": "6142",
                "transaction_qty": "-0.0002",
                "transaction_cost": "0.000000",
                "realized_pnl": "9.997484",
                "order_id": "2302",
                "trade_id": "3545",
                "trade_match_id": "767",
                "event_timestamp_ms": 1615199206871,
                "event_timestamp_ns": "1615199206871123456",
                "client_oid": "c6288370-8977-4097-ab88-423d24aaacb2",
                "taker_side": "MAKER",
                "side": "SELL",
                "instrument_name": "BTCUSD-PERP"
            },
            {
                "account_id": "88888888-8888-8888-8888-000000000008",
                "event_date": "2021-03-08",
                "journal_type": "REALIZED_PNL",
                "journal_id": "6140",
                "transaction_qty": "9.99",
                "transaction_cost": "9.999984",
                "realized_pnl": "0.000000",
                "order_id": "2302",
                "trade_id": "3545",
                "trade_match_id": "767",
                "event_timestamp_ms": 1615199206871,
                "event_timestamp_ns": "1615199206871123001",
                "client_oid": "c6288370-8977-4097-ab88-423d24aaacb2",
                "taker_side": "MAKER",
                "instrument_name": "USD"
            }
        ]
    }
}

Request Example - Second page, look up for same search criteria, but only look for the records before event_timestamp_ns 1615199206871123001, which is indicated in the last record of the first page

{
    "id": 12,
    "method": "private/get-transactions",
    "params": {
        "end_time": "1615199206871123001",
        "limit": 2
    }
}

Response Example - Second page

{
    "id": 12,
    "method": "private/get-transactions",
    "code": 0,
    "result": {
        "data": [
            {
                "account_id": "88888888-8888-8888-8888-000000000008",
                "event_date": "2021-03-08",
                "journal_type": "TRADE_FEE",
                "journal_id": "6138",
                "transaction_qty": "0.00",
                "transaction_cost": "-0.002500",
                "realized_pnl": "0.000000",
                "order_id": "2302",
                "trade_id": "3545",
                "trade_match_id": "767",
                "event_timestamp_ms": 1615199206871,
                "event_timestamp_ns": "1615199206871000003",
                "client_oid": "c6288370-8977-4097-ab88-423d24aaacb2",
                "taker_side": "MAKER",
                "instrument_name": "USD"
            },
            {
                "account_id": "88888888-8888-8888-8888-000000000008",
                "event_date": "2021-03-08",
                "journal_type": "TRADING",
                "journal_id": "6137",
                "transaction_qty": "0.0002",
                "transaction_cost": "10.000000",
                "realized_pnl": "-0.004000",
                "order_id": "2303",
                "trade_id": "3546",
                "trade_match_id": "767",
                "event_timestamp_ms": 1615199206871,
                "event_timestamp_ns": "1615199206871000001",
                "client_oid": "e800602b-ee71-4d46-a5a9-36a7f444f481",
                "taker_side": "TAKER",
                "side": "BUY",
                "instrument_name": "BTCUSD-PERP"
            }
        ]
    }
}

Pagination - Transactions of Specific Instrument

Request Example - First page, most recent transaction records of USD, with page size of 2.

{
    "id": 12,
    "method": "private/get-transactions",
    "params": {
        "instrument_name": "USD",
        "limit": 2
    }
}

Response Example - First page

{
    "id": 12,
    "method": "private/get-transactions",
    "code": 0,
    "result": {
        "data": [
            {
                "account_id": "88888888-8888-8888-8888-000000000008",
                "event_date": "2021-03-08",
                "journal_type": "REALIZED_PNL",
                "journal_id": "6140",
                "transaction_qty": "9.99",
                "transaction_cost": "9.999984",
                "realized_pnl": "0.000000",
                "order_id": "2302",
                "trade_id": "3545",
                "trade_match_id": "767",
                "event_timestamp_ms": 1615199206871,
                "event_timestamp_ns": "1615199206871123456",
                "client_oid": "c6288370-8977-4097-ab88-423d24aaacb2",
                "taker_side": "MAKER",
                "instrument_name": "USD"
            },
            {
                "account_id": "88888888-8888-8888-8888-000000000008",
                "event_date": "2021-03-08",
                "journal_type": "TRADE_FEE",
                "journal_id": "6138",
                "transaction_qty": "0.00",
                "transaction_cost": "-0.002500",
                "realized_pnl": "0.000000",
                "order_id": "2302",
                "trade_id": "3545",
                "trade_match_id": "767",
                "event_timestamp_ms": 1615199206871,
                "event_timestamp_ns": "1615199206871123333",
                "client_oid": "c6288370-8977-4097-ab88-423d24aaacb2",
                "taker_side": "MAKER",
                "instrument_name": "USD"
            }
        ]
    }
}

Request Example - Second page, look up for same search criteria, but only look for the records before event_timestamp_ns 1615199206871123333, which is indicated in the last record of the first page

{
    "id": 12,
    "method": "private/get-transactions",
    "params": {
        "instrument_name": "USD",
        "end_time": "1615199206871123333",
        "limit": 2
    }
}

Response Example - Second page

{
    "id": 12,
    "method": "private/get-transactions",
    "code": 0,
    "result": {
        "data": [
            {
                "account_id": "88888888-8888-8888-8888-000000000008",
                "event_date": "2021-03-08",
                "journal_type": "TRADE_FEE",
                "journal_id": "6135",
                "transaction_qty": "0.00",
                "transaction_cost": "-0.004000",
                "realized_pnl": "0.000000",
                "order_id": "2303",
                "trade_id": "3546",
                "trade_match_id": "767",
                "event_timestamp_ms": 1615199206871,
                "event_timestamp_ns": "1615199206871111111",
                "client_oid": "e800602b-ee71-4d46-a5a9-36a7f444f481",
                "taker_side": "TAKER",
                "instrument_name": "USD"
            },
            {
                "account_id": "88888888-8888-8888-8888-000000000008",
                "event_date": "2021-03-08",
                "journal_type": "ADMIN_ADJUSTMENT",
                "journal_id": "6134",
                "transaction_qty": "10000.00",
                "transaction_cost": "3.000000",
                "realized_pnl": "2.000000",
                "event_timestamp_ms": 1615198560492,
                "event_timestamp_ns": "1615198560492000111",
                "client_oid": "",
                "taker_side": "",
                "instrument_name": "USD"
            }
        ]
    }
}

Websocket Heartbeats

Heartbeat Example

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

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

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

public/respond-heartbeat

Request Sample

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

Responds to the server-initiated websocket heartbeat

Request Params

None

Applies To

Websocket (User API) Websocket (Market Data Subscriptions)

Websocket Subscriptions

Introduction

Request Sample

{
  "id": 1,
  "method": "subscribe",
  "params": {
    "channels": ["user.order.BTCUSD-PERP"]
  },
  "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 information is pushed every 100 milliseconds.

Websocket subscriptions involve two responses:

Important Note

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

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

Request Params

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

Applies To

Websocket (User API)

user.order.{instrument_name}

Request Sample

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

Response Sample

{
    "id": 1,
    "method": "subscribe",
    "code": 0,
    "result": {
        "instrument_name": "BTCUSD-PERP",
        "subscription": "user.order.BTCUSD-PERP",
        "channel": "user.order.BTCUSD-PERP",
        "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.BTCUSD-PERP"]
    }
}

Response Sample

{
    "id": 1,
    "method": "subscribe",
    "code": 0,
    "result": {
        "instrument_name": "BTCUSD-PERP",
        "subscription": "user.trade.BTCUSD-PERP",
        "channel": "user.trade.BTCUSD-PERP",
        "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_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_amount": "4537.302561971453",
                    "collateral_weight": "0.95",
                    "max_withdrawal_balance": "24422.72427884"
                },
                {
                    "instrument_name": "USD",
                    "quantity": "3113.50747209",
                    "market_value": "3113.50747209",
                    "collateral_amount": "3113.50747209",
                    "collateral_weight": "1.0",
                    "max_withdrawal_balance": "3113.50747209"
                },
                {
                    "instrument_name": "USDT",
                    "quantity": "0.19411607",
                    "market_value": "0.19389555414448",
                    "collateral_amount": "0.18904816529086801",
                    "collateral_weight": "0.975",
                    "max_withdrawal_balance": "0.19411607"
                },
                {
                    "instrument_name": "DAI",
                    "quantity": "0.19387960",
                    "market_value": "0.1938796",
                    "collateral_amount": "0.18903261000000002",
                    "collateral_weight": "0.975",
                    "max_withdrawal_balance": "0.1938796"
                }
            ]
        }]
    }
}

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 Balance for the margin calculation (Wallet Balance + Unrealized PnL)
total_initial_margin string Total initial margin requirement for all positions and all open orders
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_weight string Collateral weight
collateral_amount string Collateral amount derived by market_value times collateral_weight
max_withdrawal_balance string Max withdrawal balance of the collateral

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",
            "liquidation_price": "47665.3",
            "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
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.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",
            "reserved_qty": "0",
            "market_value": "9999999992.88690567",
            "collateral_amount": "9999999992.88690567",
            "collateral_weight": "1.000000",
            "max_withdrawal_balance": "9999999992.88690567",
            "hourly_interest_rate": "0"
          },
          {
            "instrument_name": "USDT",
            "quantity": "10000000",
            "reserved_qty": "0",
            "market_value": "9999800.00000000",
            "collateral_amount": "9749805.00000000",
            "collateral_weight": "0.975000",
            "max_withdrawal_balance": "10000000.00000000",
            "hourly_interest_rate": "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 Balance for the margin calculation (Wallet Balance + Unrealized PnL)
total_initial_margin string Total initial margin requirement for all positions and all open orders
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_weight string Collateral weight
collateral_amount string Collateral amount derived by market_value times collateral_weight
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,
  "code": 0,
  "method": "subscribe",
  "result": {
        "instrument_name": "BTCUSD-PERP",
        "subscription": "book.BTCUSD-PERP",
        "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.

Request Params

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,
    "code": 0,
    "method": "subscribe",
    "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,
  "code": 0,
  "method": "subscribe",
  "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,
  "code": 0,
  "method": "subscribe",
  "result": {
        "instrument_name": "BTCUSD-PERP",
        "subscription": "book.BTCUSD-PERP.10",
        "channel": "book.update",
        "depth": 10,
        "data": [{
            "update": {
              "bids":[["50097.000000", "0.252000", "1"]],
              "asks":[
                ["50126.000000", "0", "0"],
                ["50180.000000", "3.279000", "10"]
                ]
            }],
            "tt": 1647917463003,
            "t": 1647917463003,
            "u": 7845460002,
            "pu": 7845460001
        }]
    }
}

Orderbook / L2 streaming at millisecond frequency.

Channel Parameters

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

Additional Optional Parameters (Honored only when depth is specified explicitly)

Name Description
book_subscription_type Allowed values: SNAPSHOT (default) or SNAPSHOT_AND_UPDATE (new beta feature)
book_update_frequency In milliseconds. See details below

Additional Details on book_update_frequency: If book_subscription_type is SNAPSHOT_AND_UPDATE, allowed values on book_update_frequency is 10 (default). book snapshot will be published every 500ms, book delta update will be published based on book_update_frequency value (e.g. 10ms).

If book_subscription_type is SNAPSHOT, allowed values on book_update_frequency is 100 (default), where book snapshot will be published every 100ms.

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

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

In book.update 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 dataframe will be sent. And book will be broadcasted periodically, regardless whether there were any updates.

If book_subscription_type is SNAPSHOT_AND_UPDATE, book.update will be broadcasted according to book_update_frequency, if any update happened within past interval, except on the same interval that book full snapshot is published.

Each full snapshot or partial update comes with a u field that is unique (per instrument per websocket session) & incremental. Each book.update update should only be processed if its pu field correspond to the last u you received. If this isn't the case, re-subscribe or call /public/get-book to acquire a new full snapshot.

Under certain scenarions (e.g. the book.update payload is determined to be too huge), a full book snapshot will be published instead of book.update.

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": {
        "channel": "ticker",
        "subscription": "ticker.BTCUSD-PERP",
        "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
        }],
        "instrument_name": "BTCUSD-PERP"
    }
}

Publishes new tickers 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 ticker.{instrument_name} or ticker (all instruments)
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
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
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

trade.{instrument_name}

Request Sample

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

Response Sample

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

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
s string Side (buy or sell)
p string Trade price
q string Trade quantity
t number Trade timestamp
d string of number Trade ID
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": {
        "channel": "candlestick",
        "subscription": "candlestick.1D.BTCUSD-PERP",
        "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
        }],
        "instrument_name": "BTCUSD-PERP"
    }
}

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

period can be:

Lagacy 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}
interval string The period (e.g. M5)
channel string Always candlestick
data array See below

subscription makes it easy to map to the initial subscription

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

data consists of:

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

index.{instrument_name}

Request Sample

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

Response Sample

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

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": {
        "channel": "mark",
        "subscription": "mark.BTCUSD-PERP",
        "data": [{
            "v": "51279.77000",
            "t": 1613582832000
        }],
        "instrument_name": "BTCUSD-PERP"
    }
}

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-210528m1"]
  }
}

Response Sample

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

Note: Settlement price will update approximately every 50 ms

Applies To

Websocket (Market Data Subscriptions)

Response Attributes

Name Type Description
instrument_name string e.g. BTCUSD-210528m1
subscription string settlement.{instrument_name} or settlement (all instruments)
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": {
        "channel": "funding",
        "subscription": "funding.BTCUSD-PERP",
        "data": [{
            "v": "0.00144",
            "t": 1613582880000
        }],
        "instrument_name": "BTCUSD-PERP"
    }
}

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

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