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/{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 N Request Identifier
Range: 0 to 9,223,372,036,854,775,807
Response message will contain the same id
method string Y The method to be invoked
params object N Parameters for the methods
api_key string Depends API key. See Digital Signature section
sig string Depends Digital signature. See Digital Signature section
nonce long Y Current timestamp (milliseconds since the Unix epoch)

Digital Signature

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

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

  const paramsString =
    params == null
      ? ""
      : Object.keys(params)
          .sort()
          .reduce((a, b) => {
            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
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_Stable_Coin",
        "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_Stable_Coin
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      // End time
        }
    ],
        "instrument_name": "BTCUSD-PERP"
    }
}

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

period can be:

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

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 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_rate, mark_price, settlement_price
count number N Default is 25
start_ts number N Default timestamp is 1hr 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. 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_Stable_Coin&count=1

Response Sample

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

Fetches balance of Insurance Fund for a particular currency.

Request Params

Name Type Required Description
instrument_name string Y e.g. USD_Stable_Coin
count number N Default is 25
start_ts number N Default timestamp is 1hr 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_Stable_Coin
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": "152564.962839",
                "total_margin_balance": "152573.752342",
                "total_initial_margin": "8.782312",
                "total_maintenance_margin": "6.013212",
                "total_position_cost": "341.830000",
                "total_cash_balance": "152577.522312",
                "total_collateral_value": "152523.235221",
                "total_session_unrealized_pnl": "-3.770000",
                "instrument_name": "USD_Stable_Coin",
                "total_session_realized_pnl": "0.003112",
                "is_liquidating": false
            }
        ]
    }
}

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

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_Stable_Coin",
        "data": [
            {
                "t": 1629478800000,
                "c": "811.621851"
            }
        ]
    }
}

Returns the user's balance history.

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_Stable_Coin
t number timestamp
c string total cash balance

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.50",
        "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 to be sold
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 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

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

Request Params

Name Type Required Description
order_id number Depends Optional Order ID
Either order_id or client_oid must be present
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 number Order ID
client_oid string Client Order ID

private/cancel-all-orders

Request Sample

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

Response Sample

{
    "id": 1,
    "method": "private/cancel-all-orders",
    "code": 0
}

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

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

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

Request Params

Name Type Required Description
instrument_name string N e.g. BTCUSD-PERP. If not provided, the orders of ALL instruments will be cancelled
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.00"
    }
}

{
    "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 all orders for a particular instrument/pair (asynchronous).

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

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

Request Params

Name Type Required Description
instrument_name string Y e.g. 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 number Order ID
client_oid string Client Order ID

private/convert-collateral

Request Sample

{
    "id": 1,
    "nonce" : 1610905028000,
    "method": "private/convert-collateral",
    "params": {
        "client_oid": "b147b72d-3d69-4846-90f3-aa51de30d9ed",
        "from_instrument_name": "USDT",
        "to_instrument_name": "USDC",
        "from_quantity": "40000",
        "slippage_tolerance": "0.001000",
        "floor_price": "0.999999"
    }
}

Response Sample

{
    "id": 1,
    "method": "private/convert-collateral",
    "code": 0
}

Convert one type of collateral into another (asynchronous).

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

Request Params

Name Type Required Description
client_oid string N Client Order ID
from_instrument_name string Y e.g. USDT
to_instrument_name string Y e.g. USDC
from_quantity string Y e.g. 40000
slippage_tolerance string N e.g. 0.001000
floor_price string N e.g. 0.999999

Applies To

REST

REST Method

POST

Response Attributes

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

private/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.00",
            "order_value": "3.900100",
            "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": "fd797356-55db-48c2-a44d-157aabf702e8",
            "order_date": "2021-02-17",
            "instrument_name": "BTCUSD-PERP",
            "fee_instrument_name": "USD_Stable_Coin",
            "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.00",
            "order_value": "2564.150000",
            "maker_fee_rate": "0.000250",
            "taker_fee_rate": "0.000400",
            "avg_price": "51278.50",
            "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_Stable_Coin",
            "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 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
- CANCELLED
- 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-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.00",
            "order_value": "500.000000",
            "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": "ACTIVE",
            "update_user_id": "fd797356-55db-48c2-a44d-157aabf702e8",
            "order_date": "2021-02-17",
            "instrument_name": "BTCUSD-PERP",
            "fee_instrument_name": "USD_Stable_Coin",
            "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 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
- CANCELLED
- 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-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.00",
        "order_value": "500.000000",
        "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": "ACTIVE",
        "update_user_id": "fd797356-55db-48c2-a44d-157aabf702e8",
        "order_date": "2021-02-17",
        "instrument_name": "BTCUSD-PERP",
        "fee_instrument_name": "USD_Stable_Coin",
        "create_time": 1613575617173,
        "create_time_ns": "1613575617173123456",
        "update_time": 1613575617173
    }
}

Request Params

Name Type Required Description
order_id number Y Order ID

Applies To

REST

REST Method

POST

Response Attributes

An array, consisting of:

Name Type Description
account_id string Account ID
order_id 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
- CANCELLED
- 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",
            "journal_id": 618069,
            "traded_quantity": "0.0500",
            "traded_price": "51278.50",
            "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_Stable_Coin",
            "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
journal_id number Journal ID
traded_quantity string Trade quantity
traded_price string Trade price
fees string Trade fees, the negative sign means a deduction on balance
order_id number Order ID
trade_id number Trade ID
trade_match_id 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_Stable_Coin
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_RESET",
        "journal_id": 186959,
        "transaction_qty": "0.0000",
        "transaction_cost": "0.000000",
        "realized_pnl": "0.000000",
        "order_id": -9223372036854776000,
        "trade_id": -9223372036854776000,
        "trade_match_id": 0,
        "event_timestamp_ms": 1613638800001,
        "event_timestamp_ns": "1613638800001124563",
        "client_oid": "",
        "taker_side": "",
        "side": "NULL_VAL",
        "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 number Journal ID
transaction_qty string Transaction quantity
transaction_cost string Transaction cost
realized_pnl string Realized PNL
order_id number Order ID
trade_id number Trade ID
trade_match_id 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_Stable_Coin",
                "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.00",
                "order_value": "10.000000",
                "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-08",
                "instrument_name": "BTCUSD-PERP",
                "fee_instrument_name": "USD_Stable_Coin",
                "create_time": 1615199206815,
                "create_time_ns": "1615199206815123456",
                "update_time": 1615199206871
            }
        ]
    }
}

Requeest 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_Stable_Coin",
                "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_Stable_Coin",
                "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_Stable_Coin",
                "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_Stable_Coin",
                "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_Stable_Coin",
                "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_Stable_Coin",
                "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",
                "journal_id": 6190,
                "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",
                "journal_id": 6142,
                "traded_quantity": "0.0002",
                "traded_price": "50000.00",
                "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"
            }
        ]
    }
}

Requeest 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",
                "journal_id": 6137,
                "traded_quantity": "0.0002",
                "traded_price": "50000.00",
                "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",
                "journal_id": 6088,
                "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",
                "journal_id": 6190,
                "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",
                "journal_id": 6185,
                "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",
                "journal_id": 6182,
                "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",
                "journal_id": 6177,
                "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",
                "side": "NULL_VAL",
                "instrument_name": "USD_Stable_Coin"
            }
        ]
    }
}

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",
                "side": "NULL_VAL",
                "instrument_name": "USD_Stable_Coin"
            },
            {
                "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_Stable_Coin, with page size of 2.

{
    "id": 12,
    "method": "private/get-transactions",
    "params": {
        "instrument_name": "USD_Stable_Coin",
        "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",
                "side": "NULL_VAL",
                "instrument_name": "USD_Stable_Coin"
            },
            {
                "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",
                "side": "NULL_VAL",
                "instrument_name": "USD_Stable_Coin"
            }
        ]
    }
}

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_Stable_Coin",
        "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",
                "side": "NULL_VAL",
                "instrument_name": "USD_Stable_Coin"
            },
            {
                "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",
                "order_id": -9223372036854776000,
                "trade_id": -9223372036854776000,
                "trade_match_id": -9223372036854776000,
                "event_timestamp_ms": 1615198560492,
                "event_timestamp_ns": "1615198560492000111",
                "client_oid": "",
                "taker_side": "",
                "side": "NULL_VAL",
                "instrument_name": "USD_Stable_Coin"
            }
        ]
    }
}

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": {
        "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.00",
            "order_value": "500.000000",
            "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": "ACTIVE",
            "update_user_id": "fd797356-55db-48c2-a44d-157aabf702e8",
            "order_date": "2021-02-17",
            "instrument_name": "BTCUSD-PERP",
            "fee_instrument_name": "USD_Stable_Coin",
            "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 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
- CANCELLED
- 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": {
        "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",
            "journal_id": 618069,
            "traded_quantity": "0.0500",
            "traded_price": "51278.50",
            "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_Stable_Coin",
            "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
journal_id number Journal ID
traded_quantity string Trade quantity
traded_price string Trade price
fees string Trade fees, the negative sign means a deduction on balance
order_id number Order ID
trade_id number Trade ID
trade_match_id 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_Stable_Coin
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": "135.871323",
            "total_margin_balance": "213.633231",
            "total_initial_margin": "77.768828",
            "total_maintenance_margin": "44.433218",
            "total_position_cost": "2561.523283",
            "total_cash_balance": "221.689283",
            "total_session_unrealized_pnl": "-8.050212",
            "instrument_name": "USD_Stable_Coin",
            "total_session_realized_pnl": "0.009823",
            "is_liquidating": false
        }]
    }
}

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

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.36",
            "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.64",
            "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

book.{instrument_name}

Request Sample

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

Response Sample

{
  "id": 1,
  "code": 0,
  "method": "subscribe",
  "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"
    }
}

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

Request Params

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

Applies To

Websocket (Market Data Subscriptions)

Response Attributes

Name Type Description
instrument_name string e.g. BTCUSD-PERP
depth string Number of bids and asks to return
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
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 where Number of Orders currently returns 0

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 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",
        "init": true,
        "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      // End 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:

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 End 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 1 second in the future, or 30 seconds in the past.

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

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