Introduction
Welcome to the Crypto.com Exchange V2 API reference documentation.
The Crypto.com Exchange provides developers with a REST and websocket API.
The majority of API calls are available across both mediums in the same request and response formats, allowing smooth transition and a reduced learning curve between the two platforms.
Where applicable, all API calls come with detailed information on both the request and response parameters, all in a simple JSON format, as well as sample requests and code snippets in JavaScript, Python, C#, and Java which can be viewed on the right.
Documentation for the old REST API V1 can be found here.
Change Logs
2021-03-22 - Added 2 new endpoints for derivative account transfer management:
private/deriv/transferandprivate/deriv/get-transfer-history2021-03-22 - Added 1 new endpoint for deposit management:
private/get-deposit-address2021-02-24 - Added 1 new endpoint for deposit management:
private/get-deposit-history2021-02-24 - Updated example for :
private/margin/get-account-summary2020-12-23 - Added 2 new fields for trade:
client_order_idandliquidity_indicator2020-12-23 - Added two new endpoints for withdrawal management:
private/create-withdrawalandprivate/get-withdrawal-history2020-12-23 - New field added to the
public/get-instrumentsendpoint response to indicate whether a pair ismargin_trading_enabled2020-12-23 - Margin trading API functionality added; new endpoints added:
private/margin/create-orderprivate/margin/cancel-all-ordersprivate/margin/get-order-historyprivate/margin/get-open-ordersprivate/margin/get-order-detailprivate/margin/get-tradespublic/margin/get-transfer-currenciespublic/margin/get-loan-currenciesprivate/margin/transferprivate/margin/borrowprivate/margin/repayprivate/margin/get-transfer-historyprivate/margin/get-borrow-historyprivate/margin/get-interest-historyprivate/margin/get-liquidation-historyprivate/margin/get-liquidation-ordersprivate/margin/get-user-config
2020-12-07 - Add Cancel on Disconnect feature with new
private/set-cancel-on-disconnectandprivate/get-cancel-on-disconnectendpoints2020-09-17 - Added new order types:
STOP_LIMIT,STOP_LOSS,TAKE_PROFIT, andTAKE_PROFIT_LIMIT2020-09-17 - Updated
private/create-order,private/get-order-detail,private/get-open-orders,private/get-order-historyanduser.orderwith newtypeandtrigger_priceorder properties2020-08-10 - Updated
private/create-order,private/get-order-detail,private/get-open-orders,private/get-order-historyanduser.orderwith newtime_in_forceandexec_instorder properties2020-06-18 - Added
public/get-candlestickREST endpoint2020-06-14 - Set
page_sizemaximum to 200 for all calls that support paging2020-06-13 - Added
Websocket Termination Codessection2020-06-13 - Added
reasonas a field for REJECTED orders only, maps to theResponse and Reason Codessection2020-06-10 - Added new V2 REST endpoints for
public/book,public/trades,public/ticker2020-06-05 - Corrected
average_pricetoavg_pricein all occurrences in the documentation2020-06-02 - Corrected
private/get-order-historyto allow 'all' instruments by omittinginstrument_name2020-05-29 - Removed order
priceandquantityfrom trades list as it was irrelevant. Trade fields aretraded_quantityandtraded_price.2020-05-28 - Updated error codes
2020-05-25 - Updated
private/create-orderparameter requirements forLIMITandMARKETorders2020-05-22 - Websocket: Enhanced error message handling to always include
id,methodandoriginalto hold as much of the original request as possible2020-05-21 - Removed
instrument_nameas a required param forprivate/get-order-detail2020-05-21 - Enhanced
private/get-tradesto allow 'all' instruments by omittinginstrument_name2020-05-21 - Changed
trade_list[].bid_oidandtrade_list[].ask_oidinprivate/get-order-detailsto standardize astrade_list[].order_id2020-05-20 - Added clarification for ensuring POST Content Types are
application/json2020-05-20 - Amended description of
idin the Request Format section to show the range of values2020-05-18 - Added the ability to request all instruments for
user.order,user.trade,tickerandtrade(Websocket subscriptions) by omitting theinstrument_name2020-05-18 - Amended Request and Response samples for Websocket subscriptions
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
- Secret Key
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-orderprivate/cancel-orderprivate/cancel-all-ordersprivate/margin/create-orderprivate/margin/cancel-orderprivate/margin/cancel-all-orders |
15 requests per 100ms each |
private/get-order-detailprivate/margin/get-order-detail |
30 requests per 100ms |
private/get-tradesprivate/margin/get-trades |
1 requests per second |
private/get-order-historyprivate/margin/get-order-history |
1 requests per second |
| All others | 3 requests per 100ms each |
For public market data calls, rate limits are per API method, per IP address:
| Method | Limit |
|---|---|
public/get-bookpublic/get-tickerpublic/get-trades |
100 requests per second each |
Websocket
| Websocket | Limit |
|---|---|
| User API | 150 requests per second |
| Market Data | 100 requests per second |
private/get-trades and private/get-order-history is rate limited at 5 requests per second on the Websocket
We recommend adding a 1-second sleep after establishing the websocket connection, and before requests are sent.
This will avoid occurrences of rate-limit (`TOO_MANY_REQUESTS`) errors, as the websocket rate limits are pro-rated based on the calendar-second that the websocket connection was opened.
REST API Root Endpoint
REST API v1 and v2 have separate endpoints.
Future versions will share the same endpoint as v2, but with the version incremented.
Documentation for the old REST API V1 can be found here.
UAT Sandbox
REST API v2
https://uat-api.3ona.co/v2/{method}
REST API v1
https://uat-api.3ona.co/v1/{method}
Production
REST API v2
https://api.crypto.com/v2/{method}
REST API v1
https://api.crypto.com/v1/{method}
Websocket Root Endpoints
The Websocket is available across two servers -- the User API Websocket (for authenticated requests and subscriptions), and Market Data Websocket:
UAT Sandbox
Websocket (User API and Subscriptions)
wss://uat-stream.3ona.co/v2/user
Websocket (Market Data Subscriptions)
wss://uat-stream.3ona.co/v2/market
Production
Websocket (User API and Subscriptions)
wss://stream.crypto.com/v2/user
Websocket (Market Data Subscriptions)
wss://stream.crypto.com/v2/market
Common API Reference
Most of the APIs for REST and Websockets are shared, and follow the same request format and response, allowing users to easily switch between the two methods.
The Applies To section under each API allows you to see which platform supports the API.
Naming Conventions
All methods and URLs in dash-case
All parameters in snake_case
Enums in full uppercase and snake_case
Request Format
The following information applies to both REST API and websockets commands:
| Name | Type | Required | Description |
|---|---|---|---|
| id | long | N | Request Identifier Range: 0 to 9,223,372,036,854,775,807 Response message will contain the same id |
| method | string | Y | The method to be invoked |
| params | object | N | Parameters for the methods |
| api_key | string | Depends | API key. See Digital Signature section |
| sig | string | Depends | Digital signature. See Digital Signature section |
| nonce | long | Y | Current timestamp (milliseconds since the Unix epoch) |
Digital Signature
const crypto = require("crypto-js");
const signRequest = (request, apiKey, apiSecret) => {
const { id, method, params, nonce } = request;
const paramsString =
params == null
? ""
: Object.keys(params)
.sort()
.reduce((a, b) => {
return a + b + params[b];
}, "");
const sigPayload = method + id + apiKey + paramsString + nonce;
request.sig = crypto
.HmacSHA256(sigPayload, apiSecret)
.toString(crypto.enc.Hex);
return request;
};
const apiKey = "token"; /* User API Key */
const apiSecret = "secretKey"; /* User API Secret */
let request = {
id: 11,
method: "private/get-order-detail",
api_key: API_KEY,
params: {
order_id: 53287421324
},
nonce: 1587846358253,
};
const requestBody = JSON.stringify(signRequest(request, apiKey, apiSecret)));
import hmac
import hashlib
import json
import requests
import time
API_KEY = "API_KEY"
SECRET_KEY = "SECRET_KEY"
req = {
"id": 11,
"method": "private/get-order-detail",
"api_key": API_KEY,
"params": {
"order_id": "337843775021233500",
},
"nonce": int(time.time() * 1000)
};
# First ensure the params are alphabetically sorted by key
paramString = ""
if "params" in req:
for key in sorted(req['params']):
paramString += key
paramString += str(req['params'][key])
sigPayload = req['method'] + str(req['id']) + req['api_key'] + paramString + str(req['nonce'])
req['sig'] = hmac.new(
bytes(str(SECRET_KEY), 'utf-8'),
msg=bytes(sigPayload, 'utf-8'),
digestmod=hashlib.sha256
).hexdigest()
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Net;
using System.Security.Cryptography;
using System.Text;
using System.Threading.Tasks;
using System.Web;
using System.Net.WebSockets;
private const string API_KEY = "YOUR_API_KEY";
private const string API_SECRET = "YOUR_API_SECRET";
private static string GetSign (Dictionary Request)
{
Dictionary Params = Request.Params;
// Ensure the params are alphabetically sorted by key
string ParamString = string.Join("", Params.Keys.OrderBy(key => key).Select(key => key + Params[key]));
string SigPayload = Request.method + Request.id + API_KEY + ParamString + Request.nonce;
var hash = new HMACSHA256(API_SECRET);
var ComputedHash = hash.ComputeHash(SigPayload);
return ToHex(ComputedHash, false);
}
import com.fasterxml.jackson.annotation.JsonProperty;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;
import java.util.Map;
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class ApiRequestJson {
private Long id;
private String method;
private Map<String, Object> params;
private String sig;
@JsonProperty("api_key")
private String apiKey;
private Long nonce;
}
//------------
import org.apache.commons.codec.binary.Hex;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Map;
import java.util.TreeMap;
public class SigningUtil {
private static final String HMAC_SHA256 = "HmacSHA256";
public static boolean verifySignature(ApiRequestJson apiRequestJson, String secret) {
try {
return genSignature(apiRequestJson, secret).equals(apiRequestJson.getSig());
} catch (Exception e) {
return false;
}
}
public static String genSignature(ApiRequestJson apiRequestJson, String secret) throws NoSuchAlgorithmException, InvalidKeyException {
final byte[] byteKey = secret.getBytes(StandardCharsets.UTF_8);
Mac mac = Mac.getInstance(HMAC_SHA256);
SecretKeySpec keySpec = new SecretKeySpec(byteKey, HMAC_SHA256);
mac.init(keySpec);
String paramsString = "";
if (apiRequestJson.getParams() != null) {
TreeMap<String, Object> params = new TreeMap<>(apiRequestJson.getParams());
for (Map.Entry<String, Object> entry : params.entrySet()) {
paramsString += entry.getKey() + entry.getValue();
}
}
String sigPayload =
apiRequestJson.getMethod()
+ apiRequestJson.getId()
+ apiRequestJson.getApiKey()
+ paramsString
+ (apiRequestJson.getNonce() == null ? "" : apiRequestJson.getNonce());
byte[] macData = mac.doFinal(sigPayload.getBytes(StandardCharsets.UTF_8));
return Hex.encodeHexString(macData);
}
public static ApiRequestJson sign(ApiRequestJson apiRequestJson, String secret) throws InvalidKeyException, NoSuchAlgorithmException {
apiRequestJson.setSig(genSignature(apiRequestJson, secret));
return apiRequestJson;
}
public static void main(String[] argv) throws InvalidKeyException, NoSuchAlgorithmException {
ApiRequestJson apiRequestJson = ApiRequestJson.builder()
.id(11L)
.apiKey("token")
.method("public/auth")
.nonce(1589594102779L)
.build();
System.out.println(genSignature(apiRequestJson, "secretKey"));
System.out.println(sign(apiRequestJson, "secretKey"));
}
}
For REST API, only the private methods require a Digital Signature (as "sig") and API key (as "api_key") to be passed in. These private endpoints are only accessible by authenticated users.
For Websocket (User API), the public/auth command has to be invoked ONCE per session, with the Digital Signature (as "sig") and API key (as "api_key") as part of the request. Once authenticated, you will gain access to user-specific commands, and no longer need to use the pass in the Digital Signature and API key anymore for the duration of the session.
The authentication is based on the pairing of the API Key, along with the HMAC-SHA256 hash of the request parameters using the API Secret as the cryptographic key.
The algorithm for generating the HMAC-SHA256 signature is as follows:
If "params" exist in the request, sort the request parameter keys in ascending order.
Combine all the ordered parameter keys as
key+value(no spaces, no delimiters). Let's call this theparameter stringNext, do the following:
method+id+api_key+parameter string+nonceUse HMAC-SHA256 to hash the above using the API Secret as the cryptographic key
Encode the output as a hex string -- this is your Digital Signature
Digital Signature Issues
Based on the language, and the way data-types are handled, the digital signature may be incorrectly calculated for certain values.
One known case is if parameters contain numbers, and the value passed in is a whole numbers that still has decimal suffixes, e.g. 8000.000 instead of 8000.
When the JSON request is sent to the server, the client (when parsing as JSON) may cast the number 8000.000 as 8000 automatically, which is what the server would see.
However, the digital signature may have been calculated using 8000.000 in the payload, which would result in a digital signature mismatch.
If this scenario happens in your case, there are three options:
Don't allow whole number values to have decimals
Ensure the payload casts number values properly before concatenating
Wrap the values in quotation marks to make them strings -- this is allowed by the server even if the parameter is marked as a number data type
Response Format
| Name | Type | Description |
|---|---|---|
| id | long | Original request identifier |
| method | string | Method invoked |
| result | object | Result object |
| code | int | 0 for success, see below for full list |
| message | string | (optional) For server or error messages |
| original | string | (optional) Original request as a string, for error cases |
Response and Reason Codes
These codes are shared by both the response, and the reason field for rejected orders.
| Code | HTTP Status | Message Code | Description |
|---|---|---|---|
| 0 | 200 | -- | Success |
| 10001 | 500 | SYS_ERROR | Malformed request, (E.g. not using application/json for REST) |
| 10002 | 401 | UNAUTHORIZED | Not authenticated, or key/signature incorrect |
| 10003 | 401 | IP_ILLEGAL | IP address not whitelisted |
| 10004 | 400 | BAD_REQUEST | Missing required fields |
| 10005 | 401 | USER_TIER_INVALID | Disallowed based on user tier |
| 10006 | 429 | TOO_MANY_REQUESTS | Requests have exceeded rate limits |
| 10007 | 400 | INVALID_NONCE | Nonce value differs by more than 30 seconds from server |
| 10008 | 400 | METHOD_NOT_FOUND | Invalid method specified |
| 10009 | 400 | INVALID_DATE_RANGE | Invalid date range |
| 20001 | 400 | DUPLICATE_RECORD | Duplicated record |
| 20002 | 400 | NEGATIVE_BALANCE | Insufficient balance |
| 30003 | 400 | SYMBOL_NOT_FOUND | Invalid instrument_name specified |
| 30004 | 400 | SIDE_NOT_SUPPORTED | Invalid side specified |
| 30005 | 400 | ORDERTYPE_NOT_SUPPORTED | Invalid type specified |
| 30006 | 400 | MIN_PRICE_VIOLATED | Price is lower than the minimum |
| 30007 | 400 | MAX_PRICE_VIOLATED | Price is higher than the maximum |
| 30008 | 400 | MIN_QUANTITY_VIOLATED | Quantity is lower than the minimum |
| 30009 | 400 | MAX_QUANTITY_VIOLATED | Quantity is higher than the maximum |
| 30010 | 400 | MISSING_ARGUMENT | Required argument is blank or missing |
| 30013 | 400 | INVALID_PRICE_PRECISION | Too many decimal places for Price |
| 30014 | 400 | INVALID_QUANTITY_PRECISION | Too many decimal places for Quantity |
| 30016 | 400 | MIN_NOTIONAL_VIOLATED | The notional amount is less than the minimum |
| 30017 | 400 | MAX_NOTIONAL_VIOLATED | The notional amount exceeds the maximum |
| 30023 | 400 | MIN_AMOUNT_VIOLATED | Amount is lower than the minimum |
| 30024 | 400 | MAX_AMOUNT_VIOLATED | Amount is higher than the maximum |
| 30025 | 400 | AMOUNT_PRECISION_OVERFLOW | Amount precision exceeds the maximum |
| 40001 | 400 | MG_INVALID_ACCOUNT_STATUS | Operation has failed due to your account's status. Please try again later. |
| 40002 | 400 | MG_TRANSFER_ACTIVE_LOAN | Transfer has failed due to holding an active loan. Please repay your loan and try again later. |
| 40003 | 400 | MG_INVALID_LOAN_CURRENCY | Currency is not same as loan currency of active loan |
| 40004 | 400 | MG_INVALID_REPAY_AMOUNT | Only supporting full repayment of all margin loans |
| 40005 | 400 | MG_NO_ACTIVE_LOAN | No active loan |
| 40006 | 400 | MG_BLOCKED_BORROW | Borrow has been suspended. Please try again later. |
| 40007 | 400 | MG_BLOCKED_NEW_ORDER | Placing new order has been suspended. Please try again later. |
| 50001 | 400 | DW_CREDIT_LINE_NOT_MAINTAINED | Please ensure your credit line is maintained and try again later. |
Websocket Termination Codes
| Code | Description |
|---|---|
| 1000 | Normal disconnection by server, usually when the heartbeat isn't handled properly |
| 1006 | Abnormal disconnection |
| 1013 | Server restarting -- try again later |
Error Response Format
Due to the asynchronous nature of websocket requests, a robust and consistent error response is crucial in order to match the response with the request.
To ensure API consistency for websocket error responses, if the id and method is omitted in the original request, id will have a value of -1 and method will have a value of ERROR.
The original request will be returned as an escaped string in the original field.
public/auth
Request Sample
{
"id": 11,
"method": "public/auth",
"api_key": "api_key",
"sig": "d0267b151db609885bad2e4f8ad07610f7913e166c35adaf5697d59a64e3755a",
"nonce": :1587846358253
}
Response Sample
{
"id":11,
"method":"public/auth",
"code":0
}
To access user-specific websocket methods, public/auth has to be invoked with a valid API key and Digital Signature (refer to the Digital Signature section).
REST API calls do NOT need to do this.
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:
public/get-instruments
Request Sample
{
"id":11,
"method":"public/get-instruments",
"nonce":1506584998239
}
Response Sample
{
"id": 11,
"method": "public/get-instruments",
"code": 0,
"result": {
"instruments": [
{
"instrument_name": "BTC_USDT",
"quote_currency": "BTC",
"base_currency": "USDT",
"price_decimals": 2,
"quantity_decimals": 6,
"margin_trading_enabled": true
},
{
"instrument_name": "CRO_BTC",
"quote_currency": "BTC",
"base_currency": "CRO",
"price_decimals": 8,
"quantity_decimals": 2,
"margin_trading_enabled": false
}
]
}
}
Provides information on all supported instruments (e.g. BTC_USDT)
For the websocket, as a public function, it can be called without authentication.
Applies To
REST Method
GET
Response Attributes
An array of instruments, consisting of:
| Name | Type | Description |
|---|---|---|
| instrument_name | string | e.g. BTC_USDT |
| quote_currency | string | e.g. USDT |
| base_currency | string | e.g. BTC |
| price_decimals | integer | Maximum decimal places for specifying price |
| quantity_decimals | integer | Maximum decimal places for specifying quantity |
| margin_trading_enabled | boolean | true or false |
public/get-book
Request Sample
https://{URL}/v2/public/get-book?instrument_name=BTC_USDT&depth=10
Response Sample
{
"code":0,
"method":"public/get-book",
"result":{
"bids":[[9668.44,0.006325,1.0],[9659.75,0.006776,1.0],[9653.14,0.011795,1.0],[9647.13,0.019434,1.0],[9634.62,0.013765,1.0],[9633.81,0.021395,1.0],[9628.46,0.037834,1.0],[9627.6,0.020909,1.0],[9621.51,0.026235,1.0],[9620.83,0.026701,1.0]],
"asks":[[9697.0,0.68251,1.0],[9697.6,1.722864,2.0],[9699.2,1.664177,2.0],[9700.8,1.824953,2.0],[9702.4,0.85778,1.0],[9704.0,0.935792,1.0],[9713.32,0.002926,1.0],[9716.42,0.78923,1.0],[9732.19,0.00645,1.0],[9737.88,0.020216,1.0]],
"t":1591704180270
}
}
Fetches the public order book for a particular instrument and depth
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| instrument_name | string | Y | e.g. BTC_USDT, ETH_CRO, etc. |
| depth | string | N | Number of bids and asks to return (up to 150) |
Applies To
REST Method
GET
Response Attributes
| Name | Type | Description |
|---|---|---|
| bids | array | Bids array: [0] = Price, [1] = Quantity, [2] = Number of Orders |
| asks | array | Asks array: [0] = Price, [1] = Quantity, [2] = Number of Orders |
| t | long | Timestamp of the data |
public/get-candlestick
Request Sample
https://{URL}/v2/public/get-candlestick?instrument_name=BTC_USDT&timeframe=5m
Response Sample
{
"code":0,
"method":"public/get-candlestick",
"result":{
"instrument_name":"BTC_USDT",
"interval":"5m",
"data":[
{"t":1596944700000,"o":11752.38,"h":11754.77,"l":11746.65,"c":11753.64,"v":3.694583},
{"t":1596945000000,"o":11753.63,"h":11754.77,"l":11739.83,"c":11746.17,"v":2.073019},
{"t":1596945300000,"o":11746.16,"h":11753.24,"l":11738.1,"c":11740.65,"v":0.867247},
...
]
}
}
Retrieves candlesticks (k-line data history) over a given period for an instrument (e.g. BTC_USDT)
period can be:
1m: one minute5m: five minutes15m: 15 minutes30m: 30 minutes1h: one hour4h: 4 hours6h: 6 hours12h: 12 hours1D: one day7D: one week14D: two weeks1M: one month
Applies To
Response Attributes
| Name | Type | Description |
|---|---|---|
| instrument_name | string | e.g. ETH_CRO, BTC_USDT |
| interval | string | The period (e.g. 5m) |
| data | array | See below |
data consists of:
| Name | Type | Description |
|---|---|---|
| t | long | End time of candlestick (Unix timestamp) |
| o | number | Open |
| h | number | High |
| l | number | Low |
| c | number | Close |
| v | number | Volume |
public/get-ticker
Request Sample
https://{URL}/v2/public/get-ticker?instrument_name=BTC_USDT
Response Sample
{
"code":0,
"method":"public/get-ticker",
"result":{
"data": [
{"i":"CRO_BTC","b":0.00000890,"k":0.00001179,"a":0.00001042,"t":1591770793901,"v":14905879.59,"h":0.00,"l":0.00,"c":0.00},
{"i":"EOS_USDT","b":2.7676,"k":2.7776,"a":2.7693,"t":1591770798500,"v":774.51,"h":0.05,"l":0.05,"c":0.00},
{"i":"BCH_USDT","b":247.49,"k":251.73,"a":251.67,"t":1591770797601,"v":1.01693,"h":0.01292,"l":0.01231,"c":-0.00047},
...
...
{"i":"ETH_USDT","b":239.92,"k":242.59,"a":240.30,"t":1591770798701,"v":0.97575,"h":0.01236,"l":0.01199,"c":-0.00018},
{"i":"ETH_CRO","b":2693.11,"k":2699.84,"a":2699.55,"t":1591770795053,"v":95.680,"h":8.218,"l":7.853,"c":-0.050}
]
}
}
Fetches the public tickers for an instrument (e.g. BTC_USDT).
instrument_name can be omitted to show tickers for all instruments
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| instrument_name | string | N | e.g. BTC_USDT, ETH_CRO, etc. Omit for 'all' |
Applies To
REST Method
GET
Response Attributes
| Name | Type | Description |
|---|---|---|
| i | number | Instrument Name, e.g. BTC_USDT, ETH_CRO, etc. |
| b | number | The current best bid price, null if there aren't any bids |
| k | number | The current best ask price, null if there aren't any asks |
| a | number | The price of the latest trade, null if there weren't any trades |
| t | number | Timestamp of the data |
| v | number | The total 24h traded volume |
| h | number | Price of the 24h highest trade |
| l | number | Price of the 24h lowest trade, null if there weren't any trades |
| c | number | 24-hour price change, null if there weren't any trades |
public/get-trades
Request Sample
https://{URL}/v2/public/get-trades
Response Sample
{
"code":0,
"method":"public/get-trades",
"result": [
{"dataTime":1591710781947,"d":465533583799589409,"s":"BUY","p":2.96,"q":16.0,"t":1591710781946,"i":"ICX_CRO"},
{"dataTime":1591707701899,"d":465430234542863152,"s":"BUY","p":0.007749,"q":115.0,"t":1591707701898,"i":"VET_USDT"},
{"dataTime":1591710786155,"d":465533724976458209,"s":"SELL","p":25.676,"q":0.55,"t":1591710786154,"i":"XTZ_CRO"},
{"dataTime":1591710783300,"d":465533629172286576,"s":"SELL","p":2.9016,"q":0.6,"t":1591710783298,"i":"XTZ_USDT"},
{"dataTime":1591710784499,"d":465533669425626384,"s":"SELL","p":2.7662,"q":0.58,"t":1591710784498,"i":"EOS_USDT"},
{"dataTime":1591710784700,"d":465533676120104336,"s":"SELL","p":243.21,"q":0.01647,"t":1591710784698,"i":"ETH_USDT"},
{"dataTime":1591710786600,"d":465533739878620208,"s":"SELL","p":253.06,"q":0.00516,"t":1591710786598,"i":"BCH_USDT"},
{"dataTime":1591710786900,"d":465533749959572464,"s":"BUY","p":0.9999,"q":0.2,"t":1591710786898,"i":"USDC_USDT"},
{"dataTime":1591710787500,"d":465533770081010000,"s":"BUY","p":3.159,"q":1.65,"t":1591710787498,"i":"ATOM_USDT"},
...
...
]
}
Fetches the public trades for a particular instrument
instrument_name can be omitted to show tickers for all instruments
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| instrument_name | string | N | e.g. BTC_USDT, ETH_CRO, etc. Omit for 'all' |
Applies To
REST Method
GET
Response Attributes
| Name | Type | Description |
|---|---|---|
| p | number | Trade price |
| q | number | Trade quantity |
| s | string | Side ("buy" or "sell") |
| d | number | Trade ID |
| t | number | Trade timestamp |
| dataTime | long | Reserved. Can be ignored |
private/set-cancel-on-disconnect
Request Sample
{
"id": "11",
"method": "private/set-cancel-on-disconnect",
"params": {
"scope": "CONNECTION"
}
}
Response Sample
{
"id": "11",
"method": "private/set-cancel-on-disconnect",
"code": 0,
"result": {
"scope": "CONNECTION"
}
}
Cancel on Disconnect is an optional feature that will cancel all open orders created by the connection upon loss of connectivity between client or server.
This feature is only available via the Websocket.
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| scope | string | Y | Specifies the scope of cancellation, whether it should be applied to the specific connection or to the account (all orders created via Websocket) ACCOUNT or CONNECTION |
Helpful Information
- Once enabled, the scope of cancellation cannot be changed or disabled for the connection.
- Unsubscribing from any user channels will be considered as a loss of connectivity and will trigger cancelling orders.
- When feature is enabled for the account level, orders created via the Websocket will be in scope for cancellation.
Applies To
Response Attributes
| Name | Type | Description |
|---|---|---|
| scope | string | Specifies the scope of cancellation, whether it should be applied to the specific connection or to the account (all orders created via Websocket) ACCOUNT or CONNECTION |
private/get-cancel-on-disconnect
Request Sample
{
"id": "11",
"method": "private/get-cancel-on-disconnect"
}
Response Sample
{
"id": "11",
"method": "private/get-cancel-on-disconnect",
"code": 0,
"result": {
"scope": "CONNECTION"
}
}
Returns the scope of cancellation for the connection.
Request Params
None
Applies To
Response Attributes
| Name | Type | Description |
|---|---|---|
| scope | string | Specifies the scope of cancellation, whether it should be applied to the specific connection or to the account (all orders created via Websocket) ACCOUNT or CONNECTION |
private/create-withdrawal
Request Sample
{
"id": -1,
"method": "private/create-withdrawal",
"params": {
"client_wid": "my_withdrawal_002",
"currency": "BTC",
"amount": "1",
"address": "2NBqqD5GRJ8wHy1PYyCXTe9ke5226FhavBf",
"address_tag": ""
},
"nonce": "1607063412000"
}
Response Sample
{
"id":-1,
"method":"private/create-withdrawal",
"code":0,
"result": {
"id": 2220,
"amount": 1,
"fee": 0.0004,
"symbol": "BTC",
"address": "2NBqqD5GRJ8wHy1PYyCXTe9ke5226FhavBf",
"client_wid": "my_withdrawal_002",
"create_time":1607063412000
}
}
Creates a withdrawal request. Withdrawal setting must be enabled for your API Key. If you do not see the option when viewing your API Key, this feature is not yet available for you.
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| client_wid | string | N | Optional Client withdrawal ID |
| currency | string | Y | E.g. BTC, CRO |
| amount | decimal | Y | |
| address | string | Y | |
| address_tag | string | N | Secondary address identifier for coins like XRP, XLM etc. Also known as memo or tags. |
Helpful Information
- Withdrawal addresses must first be whitelisted in your account’s Withdrawal Whitelist page.
- Withdrawal fees and minimum withdrawal amount can be found on the Fees & Limits page on the Exchange website.
Applies To
REST Method
POST
Response Attributes
| Name | Type | Description |
|---|---|---|
| id | long | Newly created withdrawal ID |
| client_wid | string | (Optional) if a Client withdrawal ID was provided in the request |
| currency | string | E.g. BTC, CRO |
| amount | decimal | |
| fee | decimal | |
| address | string | Address with Address Tag (if any) |
| create_time | long |
private/get-withdrawal-history
Request Sample
{
"id": -1,
"method": "private/get-withdrawal-history",
"params": {
"currency": "XRP",
"start_ts": 1587846300000,
"end_ts": 1587846358253,
"page_size": 2,
"page": 0,
"status": "1"
},
"nonce": 1587846358253
}
Response Sample
{
"id": 11,
"method": "private/get-withdrawal-history",
"code": 0,
"result": {
"withdrawal_list": [
{
"currency": "XRP",
"client_wid": "my_withdrawal_002",
"fee": 1.0,
"create_time": 1607063412000,
"id": "2220",
"update_time": 1607063460000,
"amount": 100,
"address": "2NBqqD5GRJ8wHy1PYyCXTe9ke5226FhavBf?1234567890",
"status": "1"
}
]
}
}
Fetches withdrawal history. Withdrawal setting must be enabled for your API Key. If you do not see the option when viewing your API Keys, this feature is not yet available for you.
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| currency | string | N | E.g. BTC, CRO |
| start_ts | long | N | Default is 90 days from current timestamp |
| end_ts | long | N | Default is current timestamp |
| page_size | int | N | Page size (Default: 20, Max: 200) |
| page | int | N | Page number (0-based) |
| status | string | N | "0" 0 - Pending 1 - Processing 2 - Rejected 3 - Payment In-progress 4 - Payment Failed 5 - Completed 6 - Cancelled |
Applies To
REST Method
POST
Response Attributes
An array of withdrawal_list, consisting of:
| Name | Type | Description |
|---|---|---|
| id | long | Newly created withdrawal ID |
| client_wid | string | (Optional) if a Client withdrawal ID was provided in the request |
| currency | string | E.g. BTC, CRO |
| amount | decimal | |
| fee | decimal | |
| address | string | Address with Address Tag (if any) |
| create_time | long | |
| status | string | "0" 0 - Pending 1 - Processing 2 - Rejected 3 - Payment In-progress 4 - Payment Failed 5 - Completed 6 - Cancelled |
private/get-deposit-history
Request Sample
{
"id": -1,
"method": "private/get-deposit-history",
"params": {
"currency": "XRP",
"start_ts": 1587846300000,
"end_ts": 1587846358253,
"page_size": 2,
"page": 0,
"status": "1"
},
"nonce": 1587846358253
}
Response Sample
{
"id": 11,
"method": "private/get-deposit-history",
"code": 0,
"result": {
"deposit_list": [
{
"currency": "XRP",
"fee": 1.0,
"create_time": 1607063412000,
"id": "2220",
"update_time": 1607063460000,
"amount": 100,
"address": "2NBqqD5GRJ8wHy1PYyCXTe9ke5226FhavBf?1234567890",
"status": "1"
}
]
}
}
Fetches deposit history. Withdrawal setting must be enabled for your API Key. If you do not see the option when viewing your API Keys, this feature is not yet available for you.
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| currency | string | N | E.g. BTC, CRO |
| start_ts | long | N | Default is 90 days from current timestamp |
| end_ts | long | N | Default is current timestamp |
| page_size | int | N | Page size (Default: 20, Max: 200) |
| page | int | N | Page number (0-based) |
| status | string | N | "0" 0 - Not Arrived 1 - Arrived 2 - Failed 3 - Pending |
Applies To
REST Method
POST
Response Attributes
An array of deposit_list, consisting of:
| Name | Type | Description |
|---|---|---|
| id | long | Newly created deposit ID |
| currency | string | E.g. BTC, CRO |
| amount | decimal | |
| fee | decimal | |
| address | string | Address with Address Tag (if any) |
| create_time | long | |
| status | string | "0" 0 - Not Arrived 1 - Arrived 2 - Failed 3 - Pending |
private/get-deposit-address
Request Sample
{
"id": -1,
"method": "private/get-deposit-address",
"params": {
"currency": "CRO",
},
"nonce": 1587846358253
}
Response Sample
{
"id": 11,
"method": "private/get-deposit-address",
"code": 0,
"result": {
"deposit_address_list": [
{
"currency": "CRO",
"create_time": 1615886328000,
"id": "12345",
"address": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"status": "1",
"network": "CRO"
},
{
"currency": "CRO",
"create_time": 1615886332000,
"id": "12346",
"address": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
"status": "1",
"network": "ETH"
}
]
}
}
Fetches deposit address. Withdrawal setting must be enabled for your API Key. If you do not see the option when viewing your API Keys, this feature is not yet available for you.
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| currency | string | Y | E.g. BTC, CRO |
Applies To
REST Method
POST
Response Attributes
An array of deposit_address_list, consisting of:
| Name | Type | Description |
|---|---|---|
| id | long | Newly created deposit ID |
| currency | string | E.g. BTC, CRO |
| network | string | E.g. ETH, CRO When currency = CRO, network = CRO, it is a main net address. When currency = CRO, network = ETH, it is an ERC20 address. |
| address | string | Address with Address Tag (if any) |
| create_time | long | |
| status | string | "0" 0 - Inactive 1 - Active |
Spot Trading API
private/get-account-summary
Request Sample
{
"id": 11,
"method": "private/get-account-summary",
"params": {
"currency": "CRO"
},
"nonce": 1587523073344
}
// OR (for all currencies, omit currency, but ensure params still exists as {})
{
"id": 11,
"method": "private/get-account-summary",
"params": {},
"nonce": 1587523073344
}
Response Sample
{
"id": 11,
"method": "private/get-account-summary",
"code": 0,
"result": {
"accounts": [
{
"balance": 99999999.905000000000000000,
"available": 99999996.905000000000000000,
"order": 3.000000000000000000,
"stake": 0,
"currency": "CRO"
}
]
}
}
Returns the account balance of a user for a particular token
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| currency | string | N | Specific currency, e.g. CRO. Omit for 'all' |
Omit the currency parameter for ALL currencies, but ensure you keep params: {} for API request consistency.
Applies To
REST Method
POST
Response Attributes
An array of accounts, consisting of:
| Name | Type | Description |
|---|---|---|
| balance | number | Total balance |
| available | number | Available balance (e.g. not in orders, or locked, etc.) |
| order | number | Balance locked in orders |
| stake | number | Balance locked for staking (typically only used for CRO) |
| currency | string | e.g. CRO |
private/create-order
Request Sample
{
"id": 11,
"method": "private/create-order",
"params": {
"instrument_name": "ETH_CRO",
"side": "BUY",
"type": "LIMIT",
"price": 100.12,
"quantity": 1.2,
"client_oid": "my_order_0002",
"time_in_force": "GOOD_TILL_CANCEL",
"exec_inst": "POST_ONLY"
},
"nonce": 1587846358253
}
// Stop Limit Example
{
"id": 15,
"method": "private/create-order",
"params": {
"instrument_name": "BTC_USDT",
"side": "BUY",
"type": "STOP_LIMIT",
"quantity": 1,
"trigger_price": 9000,
"price": 9100,
"client_oid": "my_stop_limit_order_0015",
"time_in_force": "GOOD_TILL_CANCEL"
},
"nonce": "1598070206891”
}
Response Sample
{
"id": 11,
"method": "private/create-order",
"result": {
"order_id": "337843775021233500",
"client_oid": "my_order_0002"
}
}
Creates a new BUY or SELL order on the Exchange.
This call is asynchronous, so the response is simply a confirmation of the request.
The user.order subscription can be used to check when the order is successfully created.
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| instrument_name | string | Y | e.g., ETH_CRO, BTC_USDT |
| side | string | Y | BUY, SELL |
| type | string | Y | LIMIT, MARKET, STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT |
| price | number | Depends | For LIMIT and STOP_LIMIT orders only: Unit price |
| quantity | number | Depends | For LIMIT Orders, MARKET (SELL), STOP_LOSS (SELL) orders only: Order Quantity to be Sold |
| notional | number | Depends | For MARKET (BUY) and STOP_LOSS (BUY) orders only: Amount to spend |
| client_oid | string | N | Optional Client order ID |
| time_in_force | string | N | (Limit Orders Only) Options are: - GOOD_TILL_CANCEL (Default if unspecified)- FILL_OR_KILL- IMMEDIATE_OR_CANCEL |
| exec_inst | string | N | (Limit Orders Only) Options are: - POST_ONLY- Or leave empty |
| trigger_price | number | N | Used with STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, and TAKE_PROFIT_LIMIT orders. Dictates when order will be triggered |
Here are the mandatory parameters based on order type:
| Type | Side | Additional Mandatory Parameters |
|---|---|---|
| LIMIT | Both | quantity, price |
| MARKET | BUY | notional |
| MARKET | SELL | quantity |
| STOP_LIMIT | Both | price, quantity, trigger_price |
| TAKE_PROFIT_LIMIT | Both | price, quantity, trigger_price |
| STOP_LOSS | BUY | notional, trigger_price |
| STOP_LOSS | SELL | quantity, trigger_price |
| TAKE_PROFIT | BUY | notional, trigger_price |
| TAKE_PROFIT | SELL | quantity, trigger_price |
Helpful information:
STOP_LIMITandTAKE_PROFIT_LIMITwill execute a LIMIT order when the trigger_price is reached.STOP_LOSSandTAKE_PROFITwill execute a MARKET order when the trigger_price is reached.
To create trigger orders against market price:
trigger_priceabove market price: BUYSTOP_LOSSandSTOP_LIMIT, SELLTAKE_PROFITandTAKE_PROFIT_LIMITtrigger_pricebelow market price: SELLSTOP_LOSSandSTOP_LIMIT, BUYTAKE_PROFITandTAKE_PROFIT_LIMIT
Applies To
REST Method
POST
Response Attributes
| Name | Type | Description |
|---|---|---|
| order_id | number | Newly created order ID |
| client_oid | string | (Optional) if a Client order ID was provided in the request |
private/cancel-order
Request Sample
{
"id": 11,
"method": "private/cancel-order",
"params": {
"instrument_name": "ETH_CRO",
"order_id": "337843775021233500"
},
"nonce": 1587846358253
}
Response Sample
{
"id": 11,
"method": "private/cancel-order",
"code":0
}
Cancels an existing order on the Exchange (asynchronous)
This call is asynchronous, so the response is simply a confirmation of the request.
The user.order subscription can be used to check when the order is successfully cancelled.
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| instrument_name | string | Y | instrument_name, e.g., ETH_CRO, BTC_USDT |
| order_id | string | Y | Order ID |
Applies To
REST Method
POST
Response Attributes
No result block is returned. The code (0 = success) is the primary indicator that the cancel request is queued.
private/cancel-all-orders
Request Sample
{
"id": 12,
"method": "private/cancel-all-orders",
"params": {
"instrument_name": "ETH_CRO"
},
"nonce": 1587846358253
}
Response Sample
{
"id": 12,
"method": "private/cancel-all-order",
"code": 0
}
Cancels all orders for a particular instrument/pair (asynchronous)
This call is asynchronous, so the response is simply a confirmation of the request.
The user.order subscription can be used to check when the order is successfully cancelled.
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| instrument_name | string | Y | e.g. ETH_CRO, BTC_USDT |
Applies To
REST Method
POST
Response Attributes
No result block is returned. The code (0 = success) is the primary indicator that the request is queued.
private/get-order-history
Request Sample
{
"id": 12,
"method": "private/get-order-history",
"params": {
"instrument_name": "ETH_CRO",
"start_ts": 1587846300000,
"end_ts": 1587846358253,
"page_size": 2,
"page": 0
},
"nonce": 1587846358253
}
Response Sample
{
"id": 11,
"method": "private/get-order-history",
"code": 0,
"result": {
"order_list": [
{
"status": "FILLED",
"side": "SELL",
"price": 1,
"quantity": 1,
"order_id": "367107623521528457",
"client_oid": "my_order_0002",
"create_time": 1588777459755,
"update_time": 1588777460700,
"type": "LIMIT",
"instrument_name": "ETH_CRO",
"cumulative_quantity": 1,
"cumulative_value": 1,
"avg_price": 1,
"fee_currency": "CRO",
"time_in_force": "GOOD_TILL_CANCEL"
},
{
"status": "FILLED",
"side": "SELL",
"price": 1,
"quantity": 1,
"order_id": "367063282527104905",
"client_oid": "my_order_0002",
"create_time": 1588776138290,
"update_time": 1588776138679,
"type": "LIMIT",
"instrument_name": "ETH_CRO",
"cumulative_quantity": 1,
"cumulative_value": 1,
"avg_price": 1,
"fee_currency": "CRO",
"time_in_force": "GOOD_TILL_CANCEL"
}
]
}
}
Gets the order history for a particular instrument
If paging is used, enumerate each page (starting with 0) until an empty order_list array appears in the response.
Users should use user.order to keep track of real-time order updates, and private/get-order-history should primarily be used for recovery; typically when the websocket is disconnected.
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| instrument_name | string | N | e.g. ETH_CRO, BTC_USDT. Omit for 'all' |
| start_ts | long | N | Start timestamp (milliseconds since the Unix epoch) - defaults to 24 hours ago |
| end_ts | long | N | End timestamp (milliseconds since the Unix epoch) - defaults to 'now' |
| page_size | int | N | Page size (Default: 20, max: 200) |
| page | int | N | Page number (0-based) |
Note: If you omit all parameters, you still need to pass in an empty params block like params: {} for API request consistency
Maximum Duration
The maximum duration between start_ts and end_ts is 24 hours.
You will receive an INVALID_DATE_RANGE error if the difference exceeds the maximum duration.
For users looking to pull longer historical order data, users can create a loop to make a request for each 24-period from the desired start to end time.
Applies To
REST Method
POST
Response Attributes
An array of order_list, consisting of:
| Name | Type | Description |
|---|---|---|
| status | string | ACTIVE, CANCELED, FILLED, REJECTED or EXPIRED |
| reason | string | Reason code (see "Response and Reason Codes") -- only for REJECTED orders |
| side | string | BUY, SELL |
| price | number | Price specified in the order |
| quantity | number | Quantity specified in the order |
| order_id | string | Order ID |
| client_oid | string | (Optional) Client order ID if included in request |
| create_time | number | Order creation time (Unix timestamp) |
| update_time | number | Order update time (Unix timestamp) |
| type | string | LIMIT, MARKET, STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT |
| instrument_name | string | e.g. ETH_CRO, BTC_USDT |
| cumulative_quantity | number | Cumulative executed quantity (for partially filled orders) |
| cumulative_value | number | Cumulative executed value (for partially filled orders) |
| avg_price | number | Average filled price. If none is filled, returns 0 |
| fee_currency | string | Currency used for the fees (e.g. CRO) |
| time_in_force | string | - GOOD_TILL_CANCEL- FILL_OR_KILL- IMMEDIATE_OR_CANCEL |
| exec_inst | string | Empty or POST_ONLY (Limit Orders Only) |
| trigger_price | number | Used for trigger-related orders |
Note: To detect a 'partial filled' status, look for status as ACTIVE and cumulative_quantity > 0.
private/get-open-orders
Request Sample
{
"id": 12,
"method": "private/get-open-orders",
"params": {
"instrument_name": "ETH_CRO",
"page_size": 2,
"page": 0
},
"nonce": 1587846358253
}
Response Sample
{
"id": 11,
"method": "private/get-open-orders",
"code": 0,
"result": {
"count": 1177,
"order_list": [
{
"status": "ACTIVE",
"side": "BUY",
"price": 1,
"quantity": 1,
"order_id": "366543374673423753",
"client_oid": "my_order_0002",
"create_time": 1588760643829,
"update_time": 1588760644292,
"type": "LIMIT",
"instrument_name": "ETH_CRO",
"cumulative_quantity": 0,
"cumulative_value": 0,
"avg_price": 0,
"fee_currency": "CRO",
"time_in_force": "GOOD_TILL_CANCEL"
},
{
"status": "ACTIVE",
"side": "BUY",
"price": 1,
"quantity": 1,
"order_id": "366455245775097673",
"client_oid": "my_order_0002",
"create_time": 1588758017375,
"update_time": 1588758017411,
"type": "LIMIT",
"instrument_name": "ETH_CRO",
"cumulative_quantity": 0,
"cumulative_value": 0,
"avg_price": 0,
"fee_currency": "CRO",
"time_in_force": "GOOD_TILL_CANCEL"
}
]
}
}
Gets all open orders for a particular instrument
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| instrument_name | string | N | instrument_name, e.g., ETH_CRO, BTC_USDT. Omit for "all" |
| page_size | int | N | Page size (Default: 20, max: 200) |
| page | int | N | Page number (0-based) |
Applies To
REST Method
POST
Response Attributes
| Name | Type | Description |
|---|---|---|
| count | number | Total count of orders |
Additionally, an array of order_list, consisting of:
| Name | Type | Description |
|---|---|---|
| status | string | ACTIVE, CANCELED, FILLED, REJECTED or EXPIRED |
| reason | string | Reason code (see "Response and Reason Codes") -- only for REJECTED orders |
| side | string | BUY, SELL |
| price | number | Price specified in the order |
| quantity | number | Quantity specified in the order |
| order_id | string | Order ID |
| client_oid | string | (Optional) Client order ID if included in request |
| create_time | number | Order creation time (Unix timestamp) |
| update_time | number | Order update time (Unix timestamp) |
| type | string | LIMIT, MARKET, STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT |
| instrument_name | string | e.g. ETH_CRO, BTC_USDT |
| cumulative_quantity | number | Cumulative executed quantity (for partially filled orders) |
| cumulative_value | number | Cumulative executed value (for partially filled orders) |
| avg_price | number | Average filled price. If none is filled, returns 0 |
| fee_currency | string | Currency used for the fees (e.g. CRO) |
| time_in_force | string | - GOOD_TILL_CANCEL- FILL_OR_KILL- IMMEDIATE_OR_CANCEL |
| exec_inst | string | Empty or POST_ONLY (Limit Orders Only) |
| trigger_price | number | Used for trigger-related orders |
Note: To detect a 'partial filled' status, look for status as ACTIVE and cumulative_quantity > 0.
private/get-order-detail
Request Sample
{
"id": 12,
"method": "private/get-order-detail",
"params": {
"order_id": "337843775021233500"
},
"nonce": 1587846358253
}
Response Sample
{
"id": 11,
"method": "private/get-order-detail",
"code": 0,
"result": {
"trade_list": [
{
"side": "BUY",
"instrument_name": "ETH_CRO",
"fee": 0.007,
"trade_id": "371303044218155296",
"create_time": 1588902493045,
"traded_price": 7,
"traded_quantity": 7,
"fee_currency": "CRO",
"order_id": "371302913889488619"
}
],
"order_info": {
"status": "FILLED",
"side": "BUY",
"order_id": "371302913889488619",
"client_oid": "9_yMYJDNEeqHxLqtD_2j3g",
"create_time": 1588902489144,
"update_time": 1588902493024,
"type": "LIMIT",
"instrument_name": "ETH_CRO",
"cumulative_quantity": 7,
"cumulative_value": 7,
"avg_price": 7,
"fee_currency": "CRO",
"time_in_force": "GOOD_TILL_CANCEL",
"exec_inst": "POST_ONLY"
}
}
}
Gets details on a particular order ID
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| order_id | string | Y | Order ID |
Applies To
REST Method
POST
Response Attributes
An array of trade_list, consisting of:
| Name | Type | Description |
|---|---|---|
| side | string | BUY, SELL |
| instrument_name | string | e.g. ETH_CRO, BTC_USDT |
| fee | number | Trade fee |
| trade_id | string | Trade ID |
| create_time | long | Trade creation time |
| traded_price | number | Executed trade price |
| traded_quantity | number | Executed trade quantity |
| fee_currency | string | Currency used for the fees (e.g. CRO) |
| order_id | string | Order ID |
Additionally, an array of order_info, consisting of:
| Name | Type | Description |
|---|---|---|
| status | string | ACTIVE, CANCELED, FILLED, REJECTED or EXPIRED |
| reason | string | Reason code (see "Response and Reason Codes") -- only for REJECTED orders |
| side | string | BUY, SELL |
| price | number | Price specified in the order |
| quantity | number | Quantity specified in the order |
| order_id | string | Order ID |
| client_oid | string | (Optional) Client order ID if included in request |
| create_time | number | Order creation time (Unix timestamp) |
| update_time | number | Order update time (Unix timestamp) |
| type | string | LIMIT, MARKET, STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT |
| instrument_name | string | e.g. ETH_CRO, BTC_USDT |
| cumulative_quantity | number | Cumulative executed quantity (for partially filled orders) |
| cumulative_value | number | Cumulative executed value (for partially filled orders) |
| avg_price | number | Average filled price. If none is filled, returns 0 |
| fee_currency | string | Currency used for the fees (e.g. CRO) |
| time_in_force | string | - GOOD_TILL_CANCEL- FILL_OR_KILL- IMMEDIATE_OR_CANCEL |
| exec_inst | string | Empty or POST_ONLY (Limit Orders Only) |
| trigger_price | number | Used for trigger-related orders |
Note: To detect a 'partial filled' status, look for status as ACTIVE and cumulative_quantity > 0.
private/get-trades
Request Sample
{
"id": 11,
"method": "private/get-trades",
"params": {
"instrument_name": "ETH_CRO",
"page_size": 1,
"page": 0,
"start_ts": 1488851410000,
"end_ts": 1688851410000
},
"nonce": 1587523073344
}
Response Sample
{
"id": 11,
"method": "private/get-trades",
"code": 0,
"result": {
"trade_list": [
{
"side": "SELL",
"instrument_name": "ETH_CRO",
"fee": 0.014,
"trade_id": "367107655537806900",
"create_time": 1588777459755,
"traded_price": 7,
"traded_quantity": 1,
"fee_currency": "CRO",
"order_id": "367107623521528450"
}
]
}
}
Gets all executed trades for a particular instrument.
If paging is used, enumerate each page (starting with 0) until an empty trade_list array appears in the response.
Users should use user.trade to keep track of real-time trades, and private/get-trades should primarily be used for recovery; typically when the websocket is disconnected.
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| instrument_name | string | N | e.g. ETH_CRO, BTC_USDT. Omit for 'all' |
| start_ts | long | N | Start timestamp (milliseconds since the Unix epoch) - defaults to 24 hours ago |
| end_ts | long | N | End timestamp (milliseconds since the Unix epoch) - defaults to 'now' |
| page_size | int | N | Page size (Default: 20, max: 200) |
| page | int | N | Page number (0-based) |
Note: If you omit all parameters, you still need to pass in an empty params block like params: {} for API request consistency
Maximum Duration
The maximum duration between start_ts and end_ts is 24 hours.
You will receive an INVALID_DATE_RANGE error if the difference exceeds the maximum duration.
For users looking to pull longer historical trade data, users can create a loop to make a request for each 24-period from the desired start to end time.
Applies To
REST Method
POST
Response Attributes
An array of trade_list, consisting of:
| Name | Type | Description |
|---|---|---|
| side | string | BUY, SELL |
| instrument_name | string | e.g. ETH_CRO, BTC_USDT |
| fee | number | Trade fee |
| trade_id | string | Trade ID |
| create_time | long | Trade creation time |
| traded_price | number | Executed trade price |
| traded_quantity | number | Executed trade quantity |
| fee_currency | string | Currency used for the fees (e.g. CRO) |
| order_id | string | Order ID |
| client_order_id | string | Client Order ID |
| liquidity_indicator | string | TAKER MAKER |
Margin Trading API
To enable Margin Trading, you will need to create a Margin Wallet; please refer to the Margin Trading Guide here.
Margin trading will use the same parameters as the spot trading API endpoints; the difference will simply be in the URL used:
private/margin/create-orderprivate/margin/cancel-orderprivate/margin/cancel-all-ordersprivate/margin/get-order-historyprivate/margin/get-open-ordersprivate/margin/get-order-detailprivate/margin/get-trades
There are end points specific to Margin Trading. Please find their respective section for details.
public/margin/get-transfer-currencies
Request Sample
https://{URL}/v2/public/margin/get-transfer-currencies
Response Sample
{
"id": -1,
"method": "public/margin/get-transfer-currencies",
"code": 0,
"result": {
"transfer_currency_list": ["USDT", "BTC", "CRO"]
}
}
Provides information on supported currencies that can be transferred into the Margin Wallet.
Ensure you keep params: {} for API request consistency.
For the websocket, as a public function, it can be called without authentication.
Applies To
REST Method
GET
Response Attributes
An array of transfer_currency_list, consisting of transfer currencies. E.g. BTC, USDT, CRO.
public/margin/get-loan-currencies
Request Sample
https://{URL}/v2/public/margin/get-loan-currencies
Response Sample
{
"id": -1,
"method": "public/margin/get-loan-currencies",
"code": 0,
"result": {
"loan_currency_list": ["USDT", "BTC"]
}
}
Provides information on supported currencies that can be transferred into the Margin Wallet.
Ensure you keep params: {} for API request consistency.
For the websocket, as a public function, it can be called without authentication.
Applies To
REST Method
GET
Response Attributes
An array of loan_currency_list, consisting of loan currencies. E.g. BTC, USDT, CRO.
private/margin/get-user-config
Request Sample
{
"id": 11,
"method": "private/margin/get-user-config",
"params": {},
"nonce": 1607988726735
}
Response Sample
{
"id": 11,
"method": "private/margin/get-user-config",
"code": 0,
"result": {
"stake_amount": 10000,
"currency_configs": [
{
"currency": "BTC",
"hourly_rate": 0.00002125,
"max_borrow_limit": 16.97184374,
"min_borrow_limit": 0.003
},
{
"currency": "USDT",
"hourly_rate": 0.00002167,
"max_borrow_limit": 200376.88520530,
"min_borrow_limit": 20.0
}
]
}
}
Provides information on borrowable amounts and limits.
Ensure you keep params: {} for API request consistency.
Applies To
REST Method
POST
Response Attributes
Summary view of borrowable amounts and limits, and an array of currency_configs separated by currency:
| Name | Type | Description |
|---|---|---|
| stake_amount | number |
The array of currency_configs:
| Name | Type | Description |
|---|---|---|
| currency | string | E.g. BTC, USDT |
| hourly_rate | int | Hourly interest rate |
| max_borrow_limit | int | Maximum borrow limit based on collateral in the Margin Wallet |
| min_borrow_limit | int | Minimum borrow limit |
private/margin/get-account-summary
Request Sample
{
"id": 11,
"method": "private/margin/get-account-summary",
"params": {},
"nonce": 1587523073344
}
Response Sample
{
"id": 11,
"method": "private/margin/get-account-summary",
"code": 0,
"result": {
"accounts": [{
"balance": 0,
"available": 0,
"order": 0,
"borrowed": 0,
"position": 0,
"positionHomeCurrency": 0,
"positionBtc": 0,
"lastPriceHomeCurrency": 1,
"lastPriceBtc": 0.00005236,
"currency": "USDT",
"accrued_interest": 0,
"liquidation_price": 0
}, {
"balance": 0,
"available": 0,
"order": 0,
"borrowed": 0,
"position": 0,
"positionHomeCurrency": 0,
"positionBtc": 0,
"lastPriceHomeCurrency": 19096.77,
"lastPriceBtc": 1,
"currency": BTC,
"accrued_interest": 0,
"liquidation_price": 0
}, {
"balance": 0,
"available": 0,
"order": 0,
"borrowed": 0,
"position": 0,
"positionHomeCurrency": 0,
"positionBtc": 0,
"lastPriceHomeCurrency": 0.06,
"lastPriceBtc": 0.00000314,
"currency": "CRO",
"accrued_interest": 0,
"liquidation_price": 0
}],
"is_liquidating": false,
"total_balance": 0,
"total_balance_btc": 0,
"equity_value": 0,
"equity_value_btc": 0,
"total_borrowed": 0,
"total_borrowed_btc": 0,
"total_accrued_interest": 0,
"total_accrued_interest_btc": 0,
"margin_score": "GOOD",
"currency": "USDT"
}
}
Returns the account balance of the user’s margin wallet
Request Params
None
Ensure you keep params: {} for API request consistency.
Applies To
REST Method
POST
Response Attributes
Summary view of the margin wallet and an array of accounts separated by currency:
| Name | Type | Description |
|---|---|---|
| is_liquidating | boolean | Describes whether the account is under liquidation |
| equity_value | number | Total equity value in home currency |
| total_borrowed | number | Total borrowed amount in home currency |
| margin_ratio | number | Margin score is determinant of the health of the margin wallet |
| margin_score | string | GOOD, FAIR, or CRITICAL |
| currency | string | Home currency in USDT |
The array of accounts:
| Name | Type | Description |
|---|---|---|
| currency | string | Currency |
| balance | number | Balance |
| available | number | Available balance |
| order | number | Order balance |
| borrowed | number | Borrowed balance |
| accrued_interest | number | Accrued interest |
private/margin/transfer
Request Sample
{
"id": 11,
"method": "private/margin/transfer",
"params": {
"currency": "BTC",
"from": "SPOT",
"to": "MARGIN",
"amount": 1
},
"nonce": 1607930374993,
}
Response Sample
{
"id": 11,
"method": "private/margin/transfer",
"code": 0
}
Transfers funds between margin and spot wallet.
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| currency | string | Y | Transfer currency, e.g. BTC, CRO |
| from | string | Y | SPOT or MARGIN |
| to | string | Y | SPOT or MARGIN |
| amount | number | Y | The amount to be transferred |
Applies To
REST Method
POST
Response Attributes
No result block is returned. The code (0 = success) is the primary indicator that the request is queued.
private/margin/borrow
Request Sample
{
"id": 11,
"method": "private/margin/borrow",
"params": {
"currency": "BTC",
"amount": 2
},
"nonce": 1607930374993,
}
Response Sample
{
"id": 11,
"method": "private/margin/borrow",
"code": 0
}
Borrow by specific amount and currency.
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| currency | string | Y | Borrow currency, e.g. BTC, CRO |
| amount | number | Y | The amount to be borrowed |
Applies To
REST Method
POST
Response Attributes
No result block is returned. The code (0 = success) is the primary indicator that the request is queued.
private/margin/repay
Request Sample
{
"id": 11,
"method": "private/margin/repay",
"params": {
"currency": "BTC",
"amount": 2
},
"nonce": 1607930374993,
}
Response Sample
{
"id": 11,
"method": "private/margin/repay",
"code": 0
}
Repay by specific amount and currency.
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| currency | string | Y | Repay currency, e.g. BTC, CRO |
| amount | number | Y | The amount to be rapaid |
Applies To
REST Method
POST
Response Attributes
No result block is returned. The code (0 = success) is the primary indicator that the request is queued.
private/margin/get-transfer-history
Request Sample
{
"id": 11,
"method": "private/margin/get-transfer-history",
"params": {
"direction": "IN",
"currency": "BTC",
"page_size": 1,
"page": 0,
"start_ts": 1488851410000,
"end_ts": 1607939952520
},
"nonce": 1587523073344
}
Response Sample
{
"id": 11,
"method": "private/margin/get-transfer-history",
"code": 0,
"result": {
"transfer_list": [{
"direction": "IN",
"time": 1607939938002,
"amount": "11",
"status": "COMPLETED",
"information": "From Spot Wallet",
"currency": "USDT"
}, {
"direction": "IN",
"time": 1607939699671,
"amount": "122",
"status": "COMPLETED",
"information": "From Spot Wallet",
"currency": "USDT"
}]
}
}
Get the transfer history between the Spot and Margin Wallet.
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| direction | string | Y | Transfer direction into or out of Margin Wallet E.g. IN or OUT |
| currency | string | N | Currency being transferred E.g. BTC, CRO or omit for 'all' |
| start_ts | long | N | Default is 24 hours ago from current timestamp |
| end_ts | long | N | Default is current timestamp |
| page_size | int | N | Page size (Default: 20, Max: 200) |
| page | int | N | Page number (0-based) |
Applies To
REST Method
POST
Response Attributes
An array of transfer_list, consisting of:
| Name | Type | Description |
|---|---|---|
| direction | string | Transfer direction into or out of Margin Wallet E.g. IN or OUT |
| time | long | Transfer creation time (Unix timestamp) |
| amount | string | Amount transferred |
| status | string | Indicates status of the transfer |
| information | string | Text description of the transfer in relation to the Spot Wallet |
| currency | string | Currency E.g. BTC, USDT |
private/margin/get-borrow-history
Request Sample
{
"id": 11,
"method": "private/margin/get-borrow-history",
"params": {
"currency": "USDT",
"page_size": 1,
"page": 0,
"start_ts": 1488851410000,
"end_ts": 1607939952520
},
"nonce": 1587523073344
}
Response Sample
{
"id": 11,
"method": "private/margin/get-borrow-history",
"code": 0,
"result": {
"borrow_list": [{
"loan_id": "1011831376987895040",
"currency": "USDT",
"loan_amount": "717.07260818",
"borrow_time": 1607991724898,
"status": "ACTIVE"
}, {
"loan_id": "1010094184247490977",
"currency": "USDT",
"loan_amount": "266",
"borrow_time": 1607939952520,
"status": "ACTIVE"
}]
}
}
Get the borrow history in the Margin Wallet.
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| currency | string | N | Currency being borrowed E.g. BTC, CRO or omit for 'all' |
| start_ts | long | N | Default is 24 hours ago from current timestamp |
| end_ts | long | N | Default is current timestamp |
| page_size | int | N | Page size (Default: 20, Max: 200) |
| page | int | N | Page number (0-based) |
Note: If you omit all parameters, you still need to pass in an empty params block like params: {} for API request consistency
Applies To
REST Method
POST
Response Attributes
An array of borrow_list, consisting of:
| Name | Type | Description |
|---|---|---|
| loan_id | string | Unique identifier for the loan |
| currency | string | Currency E.g. BTC, USDT |
| loan_amount | string | Amount borrowed |
| borrow_time | long | Loan creation time (Unix timestamp) |
| status | string | Indicates status of the loan E.g. ACTIVE, PAID |
private/margin/get-interest-history
Request Sample
{
"id": 11,
"method": "private/margin/get-interest-history",
"params": {
"currency": "USDT",
"page_size": 1,
"page": 0,
"start_ts": 1488851410000,
"end_ts": 1607939952520
},
"nonce": 1587523073344
}
Response Sample
{
"id": 11,
"method": "private/margin/get-interest-history",
"code": 0,
"result": {
"list": [{
"loan_id": "1011842673839976993",
"currency": "USDT",
"interest": "0.0433491",
"time": 1607992061571,
"stake_amount": "10000",
"interest_rate": "0.00002167"
}]
}
}
Get the history of interest accrued for loans borrowed.
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| start_ts | long | N | Default is 24 hours ago from the current timestamp. Max time range is 1 month. |
| end_ts | long | N | Default is current timestamp |
| page_size | int | N | Page size (Default: 20, Max: 200) |
| page | int | N | Page number (0-based) |
Note: If you omit all parameters, you still need to pass in an empty params block like params: {} for API request consistency
Applies To
REST Method
POST
Response Attributes
An array of list, consisting of:
| Name | Type | Description |
|---|---|---|
| loan_id | string | Unique identifier for the loan |
| currency | string | Currency E.g. BTC, USDT |
| interest | string | Interest amount accrued |
| time | long | Interest accrued time |
| stake_amount | string | Amount of CRO staked. Interest rate depends on CRO staked. |
| interest_rate | string | Hourly interest rate |
private/margin/get-repay-history
Request Sample
{
"id": 11,
"method": "private/margin/get-repay-history",
"params": {
"currency": "BTC",
"page_size": 1,
"page": 0,
"start_ts": 1488851410000,
"end_ts": 1607939952520
},
"nonce": 1587523073344
}
Response Sample
{
"id": 11,
"method": "private/margin/get-repay-history",
"code": 0,
"result": {
"repay_list": [{
"repay_id": "995130146206694272",
"currency": "BTC",
"principle_amount": "10.0439503",
"total_interest": "0.0007533",
"repay_amount": "10.0447036",
"repay_time": 1607493989434,
"status": "CONFIRMED"
}]
}
}
Get history of repayment to loans taken out.
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| currency | string | N | Currency of loan that was repaid E.g. BTC, CRO or omit for 'all' |
| start_ts | long | N | Default is 24 hours ago from the current timestamp. |
| end_ts | long | N | Default is current timestamp |
| page_size | int | N | Page size (Default: 20, Max: 200) |
| page | int | N | Page number (0-based) |
Note: If you omit all parameters, you still need to pass in an empty params block like params: {} for API request consistency
Applies To
REST Method
POST
Response Attributes
An array of repay_list, consisting of:
| Name | Type | Description |
|---|---|---|
| repay_id | string | Unique identifier for the repayment |
| currency | string | Currency of the repayment E.g. BTC, USDT |
| principle_amount | string | Amount borrowed |
| total_interest | long | Total interest accrued |
| repay_amount | string | Total amount repaid |
| repay_time | long | Time that the repaid occurred |
| status | string | Status of the repayment E.g. CONFIRMED |
private/margin/get-liquidation-history
Request Sample
{
"id": 11,
"method": "private/margin/get-liquidation-history",
"params": {
"liquidation_status": "MARGIN_CALL",
"page_size": 1,
"page": 0,
"start_ts": 1488851410000,
"end_ts": 1607939952520
},
"nonce": 1587523073344
}
Response Sample
{
"id": 11,
"method": "private/margin/get-liquidation-history",
"code": 0,
"result": {
"list": [{
"time": 1606295944996,
"liquidation_status": "COMPLETED",
"email_status": 1,
"margin_level": "NORMAL",
"message": "Your Margin Wallet has been liquidated because your Margin Score dropped to or below 1.1.",
"message_code": 2
}, {
"time": 1606275158800,
"liquidation_status": "MARGIN_CALL",
"email_status": 1,
"margin_level": "MARGIN_CALL",
"message": "Please repay your loan or transfer more funds to your Margin Wallet to prevent liquidation of your Margin Wallet.",
"message_code": 1
}]
}
}
Get history of margin calls and liquidation events.
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| liquidation_status | string | N | Filter by whether a margin call has occurred or a liquidation event has occurred E.g. MARGIN_CALL, COMPLETED |
| start_ts | long | N | Default is 24 hours ago from the current timestamp. |
| end_ts | long | N | Default is current timestamp |
| page_size | int | N | Page size (Default: 20, Max: 200) |
| page | int | N | Page number (0-based) |
Note: If you omit all parameters, you still need to pass in an empty params block like params: {} for API request consistency
Applies To
REST Method
POST
Response Attributes
An array of list, consisting of:
| Name | Type | Description |
|---|---|---|
| time | long | Event history time for a margin call or liquidation event |
| liquidation_status | string | Liquidation status E.g. MARGIN_CALL is when a margin call has been issued, COMPLETED is when a liquidation event has completed |
| email_status | int | 1: Email sent, otherwise email not sent |
| margin_level | string | Text description of the Margin Score E.g. NORMAL means the Margin Score is > 1.30 MARGIN_CALL means 1.10 < Margin Score ≤ 1.30 LIQUIDATION means Margin Score ≤ 1.10 |
| message | string | Text description of the event |
private/margin/get-liquidation-orders
Request Sample
{
"id": 11,
"method": "private/margin/get-liquidation-orders",
"params": {
"page_size": 1,
"page": 0,
"start_ts": 1488851410000,
"end_ts": 1607939952520
},
"nonce": 1587523073344
}
Response Sample
{
"id": 11,
"method": "private/margin/get-liquidation-orders",
"code": 0,
"result": {
"order_list": [{
"status": "FILLED",
"side": "SELL",
"price": 0.0,
"quantity": 0.001138,
"order_id": "954930432466455584",
"client_oid": "LQ: 1606275158391",
"create_time": 1606295944606,
"update_time": 1606295944707,
"type": "MARKET",
"instrument_name": "BTC_USDT",
"avg_price": 15.0,
"cumulative_quantity": 0.001138,
"cumulative_value": 0.01707,
"fee_currency": "USDT",
"exec_inst": "",
"time_in_force": "GOOD_TILL_CANCEL"
}]
}
}
Get history of margin calls and liquidation events.
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| start_ts | long | N | Default is 24 hours ago from the current timestamp. |
| end_ts | long | N | Default is current timestamp |
| page_size | int | N | Page size (Default: 20, Max: 200) |
| page | int | N | Page number (0-based) |
Note: If you omit all parameters, you still need to pass in an empty params block like params: {} for API request consistency
Applies To
REST Method
POST
Response Attributes
An array of order_list, consisting of:
| Name | Type | Description |
|---|---|---|
| status | string | ACTIVE, CANCELED, FILLED, REJECTED or EXPIRED |
| reason | string | Reason code (see "Response and Reason Codes") -- only for REJECTED orders |
| side | string | BUY, SELL |
| price | number | Price specified in the order |
| quantity | number | Quantity specified in the order |
| order_id | string | Order ID |
| client_oid | string | Liquidation Order ID |
| create_time | number | Order creation time (Unix timestamp) |
| update_time | number | Order update time (Unix timestamp) |
| type | string | LIMIT, MARKET |
| instrument_name | string | e.g. BTC_USDT |
| cumulative_quantity | number | Cumulative executed quantity (for partially filled orders) |
| cumulative_value | number | Cumulative executed value (for partially filled orders) |
| avg_price | number | Average filled price. If none is filled, returns 0 |
| fee_currency | string | Currency used for the fees |
| time_in_force | string | GOOD_TILL_CANCEL FILL_OR_KILL IMMEDIATE_OR_CANCEL |
| exec_inst | string | Empty or POST_ONLY (Limit Orders Only) |
private/margin/create-order
Request Sample
{
"id": 11,
"method": "private/margin/create-order",
"params": {
"instrument_name": "ETH_CRO",
"side": "BUY",
"type": "LIMIT",
"price": 100.12,
"quantity": 1.2,
"client_oid": "my_order_0002",
"time_in_force": "GOOD_TILL_CANCEL",
"exec_inst": "POST_ONLY"
},
"nonce": 1587846358253
}
// Stop Limit Example
{
"id": 15,
"method": "private/margin/create-order",
"params": {
"instrument_name": "BTC_USDT",
"side": "BUY",
"type": "STOP_LIMIT",
"quantity": 1,
"trigger_price": 9000,
"price": 9100,
"client_oid": "my_stop_limit_order_0015",
"time_in_force": "GOOD_TILL_CANCEL"
},
"nonce": "1598070206891”
}
Response Sample
{
"id": 11,
"method": "private/margin/create-order",
"result": {
"order_id": "337843775021233500",
"client_oid": "my_order_0002"
}
}
Creates a new BUY or SELL order on the Exchange.
This call is asynchronous, so the response is simply a confirmation of the request.
The user.margin.order subscription can be used to check when the order is successfully created.
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| instrument_name | string | Y | e.g., ETH_CRO, BTC_USDT |
| side | string | Y | BUY, SELL |
| type | string | Y | LIMIT, MARKET, STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT |
| price | number | Depends | For LIMIT and STOP_LIMIT orders only: Unit price |
| quantity | number | Depends | For LIMIT Orders, MARKET (SELL), STOP_LOSS (SELL) orders only: Order Quantity to be Sold |
| notional | number | Depends | For MARKET (BUY) and STOP_LOSS (BUY) orders only: Amount to spend |
| client_oid | string | N | Optional Client order ID |
| time_in_force | string | N | (Limit Orders Only) Options are: - GOOD_TILL_CANCEL (Default if unspecified)- FILL_OR_KILL- IMMEDIATE_OR_CANCEL |
| exec_inst | string | N | (Limit Orders Only) Options are: - POST_ONLY- Or leave empty |
| trigger_price | number | N | Used with STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, and TAKE_PROFIT_LIMIT orders. Dictates when order will be triggered |
Here are the mandatory parameters based on order type:
| Type | Side | Additional Mandatory Parameters |
|---|---|---|
| LIMIT | Both | quantity, price |
| MARKET | BUY | notional |
| MARKET | SELL | quantity |
| STOP_LIMIT | Both | price, quantity, trigger_price |
| TAKE_PROFIT_LIMIT | Both | price, quantity, trigger_price |
| STOP_LOSS | BUY | notional, trigger_price |
| STOP_LOSS | SELL | quantity, trigger_price |
| TAKE_PROFIT | BUY | notional, trigger_price |
| TAKE_PROFIT | SELL | quantity, trigger_price |
Helpful information:
STOP_LIMITandTAKE_PROFIT_LIMITwill execute a LIMIT order when the trigger_price is reached.STOP_LOSSandTAKE_PROFITwill execute a MARKET order when the trigger_price is reached.
To create trigger orders against market price:
trigger_priceabove market price: BUYSTOP_LOSSandSTOP_LIMIT, SELLTAKE_PROFITandTAKE_PROFIT_LIMITtrigger_pricebelow market price: SELLSTOP_LOSSandSTOP_LIMIT, BUYTAKE_PROFITandTAKE_PROFIT_LIMIT
Applies To
REST Method
POST
Response Attributes
| Name | Type | Description |
|---|---|---|
| order_id | number | Newly created order ID |
| client_oid | string | (Optional) if a Client order ID was provided in the request |
private/margin/cancel-order
Request Sample
{
"id": 11,
"method": "private/margin/cancel-order",
"params": {
"instrument_name": "ETH_CRO",
"order_id": "337843775021233500"
},
"nonce": 1587846358253
}
Response Sample
{
"id": 11,
"method": "private/margin/cancel-order",
"code":0
}
Cancels an existing order on the Exchange (asynchronous)
This call is asynchronous, so the response is simply a confirmation of the request.
The user.margin.order subscription can be used to check when the order is successfully cancelled.
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| instrument_name | string | Y | instrument_name, e.g., ETH_CRO, BTC_USDT |
| order_id | string | Y | Order ID |
Applies To
REST Method
POST
Response Attributes
No result block is returned. The code (0 = success) is the primary indicator that the cancel request is queued.
private/margin/cancel-all-orders
Request Sample
{
"id": 12,
"method": "private/margin/cancel-all-orders",
"params": {
"instrument_name": "ETH_CRO"
},
"nonce": 1587846358253
}
Response Sample
{
"id": 12,
"method": "private/margin/cancel-all-order",
"code": 0
}
Cancels all orders for a particular instrument/pair (asynchronous)
This call is asynchronous, so the response is simply a confirmation of the request.
The user.margin.order subscription can be used to check when the order is successfully cancelled.
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| instrument_name | string | Y | e.g. ETH_CRO, BTC_USDT |
Applies To
REST Method
POST
Response Attributes
No result block is returned. The code (0 = success) is the primary indicator that the request is queued.
private/margin/get-order-history
Request Sample
{
"id": 12,
"method": "private/margin/get-order-history",
"params": {
"instrument_name": "ETH_CRO",
"start_ts": 1587846300000,
"end_ts": 1587846358253,
"page_size": 2,
"page": 0
},
"nonce": 1587846358253
}
Response Sample
{
"id": 11,
"method": "private/margin/get-order-history",
"code": 0,
"result": {
"order_list": [
{
"status": "FILLED",
"side": "SELL",
"price": 1,
"quantity": 1,
"order_id": "367107623521528457",
"client_oid": "my_order_0002",
"create_time": 1588777459755,
"update_time": 1588777460700,
"type": "LIMIT",
"instrument_name": "ETH_CRO",
"cumulative_quantity": 1,
"cumulative_value": 1,
"avg_price": 1,
"fee_currency": "CRO",
"time_in_force": "GOOD_TILL_CANCEL"
},
{
"status": "FILLED",
"side": "SELL",
"price": 1,
"quantity": 1,
"order_id": "367063282527104905",
"client_oid": "my_order_0002",
"create_time": 1588776138290,
"update_time": 1588776138679,
"type": "LIMIT",
"instrument_name": "ETH_CRO",
"cumulative_quantity": 1,
"cumulative_value": 1,
"avg_price": 1,
"fee_currency": "CRO",
"time_in_force": "GOOD_TILL_CANCEL"
}
]
}
}
Gets the order history for a particular instrument
If paging is used, enumerate each page (starting with 0) until an empty order_list array appears in the response.
Users should use user.margin.order to keep track of real-time order updates, and private/margin/get-order-history should primarily be used for recovery; typically when the websocket is disconnected.
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| instrument_name | string | N | e.g. ETH_CRO, BTC_USDT. Omit for 'all' |
| start_ts | long | N | Start timestamp (milliseconds since the Unix epoch) - defaults to 24 hours ago |
| end_ts | long | N | End timestamp (milliseconds since the Unix epoch) - defaults to 'now' |
| page_size | int | N | Page size (Default: 20, max: 200) |
| page | int | N | Page number (0-based) |
Note: If you omit all parameters, you still need to pass in an empty params block like params: {} for API request consistency
Maximum Duration
The maximum duration between start_ts and end_ts is 24 hours.
You will receive an INVALID_DATE_RANGE error if the difference exceeds the maximum duration.
For users looking to pull longer historical order data, users can create a loop to make a request for each 24-period from the desired start to end time.
Applies To
REST Method
POST
Response Attributes
An array of order_list, consisting of:
| Name | Type | Description |
|---|---|---|
| status | string | ACTIVE, CANCELED, FILLED, REJECTED or EXPIRED |
| reason | string | Reason code (see "Response and Reason Codes") -- only for REJECTED orders |
| side | string | BUY, SELL |
| price | number | Price specified in the order |
| quantity | number | Quantity specified in the order |
| order_id | string | Order ID |
| client_oid | string | (Optional) Client order ID if included in request |
| create_time | number | Order creation time (Unix timestamp) |
| update_time | number | Order update time (Unix timestamp) |
| type | string | LIMIT, MARKET, STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT |
| instrument_name | string | e.g. ETH_CRO, BTC_USDT |
| cumulative_quantity | number | Cumulative executed quantity (for partially filled orders) |
| cumulative_value | number | Cumulative executed value (for partially filled orders) |
| avg_price | number | Average filled price. If none is filled, returns 0 |
| fee_currency | string | Currency used for the fees (e.g. CRO) |
| time_in_force | string | - GOOD_TILL_CANCEL- FILL_OR_KILL- IMMEDIATE_OR_CANCEL |
| exec_inst | string | Empty or POST_ONLY (Limit Orders Only) |
| trigger_price | number | Used for trigger-related orders |
Note: To detect a 'partial filled' status, look for status as ACTIVE and cumulative_quantity > 0.
private/margin/get-open-orders
Request Sample
{
"id": 12,
"method": "private/margin/get-open-orders",
"params": {
"instrument_name": "ETH_CRO",
"page_size": 2,
"page": 0
},
"nonce": 1587846358253
}
Response Sample
{
"id": 11,
"method": "private/margin/get-open-orders",
"code": 0,
"result": {
"count": 1177,
"order_list": [
{
"status": "ACTIVE",
"side": "BUY",
"price": 1,
"quantity": 1,
"order_id": "366543374673423753",
"client_oid": "my_order_0002",
"create_time": 1588760643829,
"update_time": 1588760644292,
"type": "LIMIT",
"instrument_name": "ETH_CRO",
"cumulative_quantity": 0,
"cumulative_value": 0,
"avg_price": 0,
"fee_currency": "CRO",
"time_in_force": "GOOD_TILL_CANCEL"
},
{
"status": "ACTIVE",
"side": "BUY",
"price": 1,
"quantity": 1,
"order_id": "366455245775097673",
"client_oid": "my_order_0002",
"create_time": 1588758017375,
"update_time": 1588758017411,
"type": "LIMIT",
"instrument_name": "ETH_CRO",
"cumulative_quantity": 0,
"cumulative_value": 0,
"avg_price": 0,
"fee_currency": "CRO",
"time_in_force": "GOOD_TILL_CANCEL"
}
]
}
}
Gets all open orders for a particular instrument
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| instrument_name | string | N | instrument_name, e.g., ETH_CRO, BTC_USDT. Omit for "all" |
| page_size | int | N | Page size (Default: 20, max: 200) |
| page | int | N | Page number (0-based) |
Applies To
REST Method
POST
Response Attributes
| Name | Type | Description |
|---|---|---|
| count | number | Total count of orders |
Additionally, an array of order_list, consisting of:
| Name | Type | Description |
|---|---|---|
| status | string | ACTIVE, CANCELED, FILLED, REJECTED or EXPIRED |
| reason | string | Reason code (see "Response and Reason Codes") -- only for REJECTED orders |
| side | string | BUY, SELL |
| price | number | Price specified in the order |
| quantity | number | Quantity specified in the order |
| order_id | string | Order ID |
| client_oid | string | (Optional) Client order ID if included in request |
| create_time | number | Order creation time (Unix timestamp) |
| update_time | number | Order update time (Unix timestamp) |
| type | string | LIMIT, MARKET, STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT |
| instrument_name | string | e.g. ETH_CRO, BTC_USDT |
| cumulative_quantity | number | Cumulative executed quantity (for partially filled orders) |
| cumulative_value | number | Cumulative executed value (for partially filled orders) |
| avg_price | number | Average filled price. If none is filled, returns 0 |
| fee_currency | string | Currency used for the fees (e.g. CRO) |
| time_in_force | string | - GOOD_TILL_CANCEL- FILL_OR_KILL- IMMEDIATE_OR_CANCEL |
| exec_inst | string | Empty or POST_ONLY (Limit Orders Only) |
| trigger_price | number | Used for trigger-related orders |
Note: To detect a 'partial filled' status, look for status as ACTIVE and cumulative_quantity > 0.
private/margin/get-order-detail
Request Sample
{
"id": 12,
"method": "private/margin/get-order-detail",
"params": {
"order_id": "337843775021233500"
},
"nonce": 1587846358253
}
Response Sample
{
"id": 11,
"method": "private/margin/get-order-detail",
"code": 0,
"result": {
"trade_list": [
{
"side": "BUY",
"instrument_name": "ETH_CRO",
"fee": 0.007,
"trade_id": "371303044218155296",
"create_time": 1588902493045,
"traded_price": 7,
"traded_quantity": 7,
"fee_currency": "CRO",
"order_id": "371302913889488619"
}
],
"order_info": {
"status": "FILLED",
"side": "BUY",
"order_id": "371302913889488619",
"client_oid": "9_yMYJDNEeqHxLqtD_2j3g",
"create_time": 1588902489144,
"update_time": 1588902493024,
"type": "LIMIT",
"instrument_name": "ETH_CRO",
"cumulative_quantity": 7,
"cumulative_value": 7,
"avg_price": 7,
"fee_currency": "CRO",
"time_in_force": "GOOD_TILL_CANCEL",
"exec_inst": "POST_ONLY"
}
}
}
Gets details on a particular order ID
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| order_id | string | Y | Order ID |
Applies To
REST Method
POST
Response Attributes
An array of trade_list, consisting of:
| Name | Type | Description |
|---|---|---|
| side | string | BUY, SELL |
| instrument_name | string | e.g. ETH_CRO, BTC_USDT |
| fee | number | Trade fee |
| trade_id | string | Trade ID |
| create_time | long | Trade creation time |
| traded_price | number | Executed trade price |
| traded_quantity | number | Executed trade quantity |
| fee_currency | string | Currency used for the fees (e.g. CRO) |
| order_id | string | Order ID |
Additionally, an array of order_info, consisting of:
| Name | Type | Description |
|---|---|---|
| status | string | ACTIVE, CANCELED, FILLED, REJECTED or EXPIRED |
| reason | string | Reason code (see "Response and Reason Codes") -- only for REJECTED orders |
| side | string | BUY, SELL |
| price | number | Price specified in the order |
| quantity | number | Quantity specified in the order |
| order_id | string | Order ID |
| client_oid | string | (Optional) Client order ID if included in request |
| create_time | number | Order creation time (Unix timestamp) |
| update_time | number | Order update time (Unix timestamp) |
| type | string | LIMIT, MARKET, STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT |
| instrument_name | string | e.g. ETH_CRO, BTC_USDT |
| cumulative_quantity | number | Cumulative executed quantity (for partially filled orders) |
| cumulative_value | number | Cumulative executed value (for partially filled orders) |
| avg_price | number | Average filled price. If none is filled, returns 0 |
| fee_currency | string | Currency used for the fees (e.g. CRO) |
| time_in_force | string | - GOOD_TILL_CANCEL- FILL_OR_KILL- IMMEDIATE_OR_CANCEL |
| exec_inst | string | Empty or POST_ONLY (Limit Orders Only) |
| trigger_price | number | Used for trigger-related orders |
Note: To detect a 'partial filled' status, look for status as ACTIVE and cumulative_quantity > 0.
private/margin/get-trades
Request Sample
{
"id": 11,
"method": "private/margin/get-trades",
"params": {
"instrument_name": "ETH_CRO",
"page_size": 1,
"page": 0,
"start_ts": 1488851410000,
"end_ts": 1688851410000
},
"nonce": 1587523073344
}
Response Sample
{
"id": 11,
"method": "private/margin/get-trades",
"code": 0,
"result": {
"trade_list": [
{
"side": "SELL",
"instrument_name": "ETH_CRO",
"fee": 0.014,
"trade_id": "367107655537806900",
"create_time": 1588777459755,
"traded_price": 7,
"traded_quantity": 1,
"fee_currency": "CRO",
"order_id": "367107623521528450"
}
]
}
}
Gets all executed trades for a particular instrument.
If paging is used, enumerate each page (starting with 0) until an empty trade_list array appears in the response.
Users should use user.margin.trade to keep track of real-time trades, and private/margin/get-trades should primarily be used for recovery; typically when the websocket is disconnected.
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| instrument_name | string | N | e.g. ETH_CRO, BTC_USDT. Omit for 'all' |
| start_ts | long | N | Start timestamp (milliseconds since the Unix epoch) - defaults to 24 hours ago |
| end_ts | long | N | End timestamp (milliseconds since the Unix epoch) - defaults to 'now' |
| page_size | int | N | Page size (Default: 20, max: 200) |
| page | int | N | Page number (0-based) |
Note: If you omit all parameters, you still need to pass in an empty params block like params: {} for API request consistency
Maximum Duration
The maximum duration between start_ts and end_ts is 24 hours.
You will receive an INVALID_DATE_RANGE error if the difference exceeds the maximum duration.
For users looking to pull longer historical trade data, users can create a loop to make a request for each 24-period from the desired start to end time.
Applies To
REST Method
POST
Response Attributes
An array of trade_list, consisting of:
| Name | Type | Description |
|---|---|---|
| side | string | BUY, SELL |
| instrument_name | string | e.g. ETH_CRO, BTC_USDT |
| fee | number | Trade fee |
| trade_id | string | Trade ID |
| create_time | long | Trade creation time |
| traded_price | number | Executed trade price |
| traded_quantity | number | Executed trade quantity |
| fee_currency | string | Currency used for the fees (e.g. CRO) |
| order_id | string | Order ID |
| client_order_id | string | Client Order ID |
| liquidity_indicator | string | TAKER MAKER |
Derivatives Transfer API
To enable Derivatives Transfer, you will need to create a Derivative Wallet; please refer to the help article here.
private/deriv/transfer
Request Sample
{
"id": 11,
"method": "private/deriv/transfer",
"params": {
"currency": "BTC",
"from": "SPOT",
"to": "DERIVATIVES",
"amount": 1
},
"nonce": 1607930374993,
}
Response Sample
{
"id": 11,
"method": "private/deriv/transfer",
"code": 0
}
Transfers funds between derivative and spot wallet.
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| currency | string | Y | Transfer currency, e.g. BTC, CRO |
| from | string | Y | SPOT or DERIVATIVES |
| to | string | Y | SPOT or DERIVATIVES |
| amount | number | Y | The amount to be transferred |
Applies To
REST Method
POST
Response Attributes
No result block is returned. The code (0 = success) is the primary indicator that the request is queued.
private/deriv/get-transfer-history
Request Sample
{
"id": 11,
"method": "private/deriv/get-transfer-history",
"params": {
"direction": "IN",
"currency": "BTC",
"page_size": 1,
"page": 0,
"start_ts": 1488851410000,
"end_ts": 1688851410000
},
"nonce": 1587523073344
}
Response Sample
{
"id": 11,
"method": "private/deriv/get-transfer-history",
"code": 0,
"result": {
"transfer_list": [
{
"direction": "IN",
"currency": "BTC",
"time": 1488851410000,
"amount": 1,
"status": "COMPLETED",
"information": "From Spot Wallet"
},
{
"direction": "IN",
"currency": "BTC",
"time": 1488851410000,
"amount": 10,
"status": "PROCESSING",
"information": "From Spot Wallet"
}
]
}
}
Get the transfer history between the Spot and Derivatives Wallet.
Request Params
| Name | Type | Required | Description |
|---|---|---|---|
| direction | string | Y | Transfer direction into or out of Derivatives Wallet E.g. IN or OUT |
| currency | string | N | Currency being transferred E.g. BTC, CRO or omit for 'all' |
| start_ts | long | N | Default is 24 hours ago from current timestamp |
| end_ts | long | N | Default is current timestamp |
| page_size | int | N | Page size (Default: 20, Max: 200) |
| page | int | N | Page number (0-based) |
Applies To
REST Method
POST
Response Attributes
An array of transfer_list, consisting of:
| Name | Type | Description |
|---|---|---|
| direction | string | Transfer direction into or out of Derivatives Wallet E.g. IN or OUT |
| time | long | Transfer creation time (Unix timestamp) |
| amount | string | Amount transferred |
| status | string | Indicates status of the transfer |
| information | string | Text description of the transfer in relation to the Spot Wallet |
| currency | string | Currency E.g. BTC, USDT |
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 Subscriptions
Introduction
Request Sample
{
"id": 11,
"method": "subscribe",
"params": {
"channels": ["user.order.ETH_CRO"]
},
"nonce": 1587523073344
}
Response Sample (Initial)
{
"id": 11,
"code": 0,
"method": "subscribe"
}
One of the powerful features of a websocket is the ability to subscribe to incremental updates in particular channels.
This section covers the available channels that can be subscribed or unsubscribed for both the Websocket (User API) and Websocket (Market Data Subscriptions)
Market Data Subscriptions include features such as order book depth, all trades and ticker data. Market data information is pushed every 100 milliseconds.
Websocket subscriptions involve two responses:
An initial response to the subscribe command, which can subscribe to one or more channels
Periodic channel data for the specified channel
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
user.order.{instrument_name}
Request Sample
{
"id": 11,
"method": "subscribe",
"params": {
"channels": ["user.order.ETH_CRO"]
},
"nonce": 1587523073344
}
Response Sample
{
"method": "subscribe",
"result": {
"instrument_name": "ETH_CRO",
"subscription": "user.order.ETH_CRO",
"channel": "user.order",
"data": [
{
"status": "ACTIVE",
"side": "BUY",
"price": 1,
"quantity": 1,
"order_id": "366455245775097673",
"client_oid": "my_order_0002",
"create_time": 1588758017375,
"update_time": 1588758017411,
"type": "LIMIT",
"instrument_name": "ETH_CRO",
"cumulative_quantity": 0,
"cumulative_value": 0,
"avg_price": 0,
"fee_currency": "CRO",
"time_in_force":"GOOD_TILL_CANCEL"
}
],
"channel": "user.order.ETH_CRO"
}
}
For Spot Trading
Publishes all new orders or order updates for the user for a particular instrument (e.g. BTC_USDT).
instrument_name can be omitted to show tickers for all instruments
Requires initial authentication using public/auth (see public/auth for more information).
Applies To
Response Attributes
| Name | Type | Description |
|---|---|---|
| instrument_name | string | e.g. ETH_CRO, BTC_USDT |
| subscription | string | user.order.{instrument_name} -- even in the all case |
| channel | string | user.order |
| data | array | See below |
subscription makes it easy to map to the initial subscription
channel and instrument_name simply allow easier access to parameters without needing to parse the subscription
data consists of:
| Name | Type | Description |
|---|---|---|
| order_id | string | Order ID |
| client_oid | string | (Optional) Client order ID if included in request |
| create_time | number | Order creation time (Unix timestamp) |
| update_time | number | Order update time (Unix timestamp) |
| status | string | ACTIVE, CANCELED, FILLED, REJECTED or EXPIRED |
| reason | string | Reason code (see "Response and Reason Codes") -- only for REJECTED orders |
| type | string | LIMIT, MARKET, STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT |
| side | string | BUY, SELL |
| instrument_name | string | e.g. ETH_CRO, BTC_USDT |
| price | number | Price specified in the order |
| quantity | number | Quantity specified in the order |
| cumulative_quantity | number | Cumulative executed quantity (for partially filled orders) |
| cumulative_value | number | Cumulative executed value (for partially filled orders) |
| avg_price | number | Average filled price. If none is filled, returns 0 |
| fee_currency | string | Currency used for the fees (e.g. CRO) |
| time_in_force | string | - GOOD_TILL_CANCEL- FILL_OR_KILL- IMMEDIATE_OR_CANCEL |
| exec_inst | string | Empty or POST_ONLY (Limit Orders Only) |
| trigger_price | number | Used for trigger-related orders |
Note: To detect a 'partial filled' status, look for status as ACTIVE and cumulative_quantity > 0.
user.trade.{instrument_name}
Request Sample
{
"id": 11,
"method": "subscribe",
"params": {
"channels": ["user.trade.ETH_CRO"]
},
"nonce": 1587523073344
}
Response Sample
{
"method": "subscribe",
"code": 0,
"result": {
"instrument_name": "ETH_CRO",
"subscription": "user.trade.ETH_CRO",
"channel": "user.trade",
"data": [
{
"side": "SELL",
"instrument_name": "ETH_CRO",
"fee": 0.014,
"trade_id": "367107655537806900",
"create_time": "1588777459755",
"traded_price": 7,
"traded_quantity": 1,
"fee_currency": "CRO",
"order_id": "367107623521528450"
}
],
"channel": "user.trade.ETH_CRO"
}
}
For Spot Trading
Publishes all new trades updates related to the user for a particular instrument (e.g. BTC_USDT)
instrument_name can be omitted to show tickers for all instruments
Requires initial authentication using public/auth (see public/auth for more information).
Applies To
Response Attributes
| Name | Type | Description |
|---|---|---|
| instrument_name | string | e.g. ETH_CRO, BTC_USDT |
| subscription | string | user.trade.{instrument_name} -- even in the all case |
| channel | string | user.trade |
| data | array | See below |
subscription makes it easy to map to the initial subscription
channel and instrument_name simply allow easier access to parameters without needing to parse the subscription
data consists of:
| Name | Type | Description |
|---|---|---|
| side | string | BUY, SELL |
| fee | number | Trade fee |
| trade_id | string | Trade ID |
| create_time | long | Trade creation time |
| traded_price | number | Executed trade price |
| traded_quantity | number | Executed trade quantity |
| fee_currency | string | Currency used for the fees (e.g. CRO) |
| order_id | string | Order ID |
user.balance
Request Sample
{
"id": 11,
"method": "subscribe",
"params": {
"channels": ["user.balance"]
},
"nonce": 1587523073344
}
Response Sample
{
"method": "subscribe",
"result": {
"subscription": "user.balance",
"channel": "user.balance",
"data": [
{
"currency": "CRO",
"balance": 99999999947.99626,
"available": 99999988201.50826,
"order": 11746.488,
"stake": 0
}
],
"channel": "user.balance"
}
}
For Spot Trading
Publishes all new balance updates for the user
Requires initial authentication using public/auth (see public/auth for more information).
Applies To
Response Attributes
| Name | Type | Description |
|---|---|---|
| subscription | string | user.balance |
| channel | string | user.balance |
| data | array | See below |
data consists of:
| Name | Type | Description |
|---|---|---|
| currency | string | e.g. CRO |
| balance | number | Total balance |
| available | number | Available balance (e.g. not in orders, or locked, etc.) |
| order | number | Balance locked in orders |
| stake | number | Balance locked for staking (typically only used for CRO) |
user.margin.order.{instrument_name}
Request Sample
{
"id": 11,
"method": "subscribe",
"params": {
"channels": ["user.margin.order.ETH_CRO"]
},
"nonce": 1587523073344
}
Response Sample
{
"method": "subscribe",
"result": {
"instrument_name": "ETH_CRO",
"subscription": "user.margin.order.ETH_CRO",
"channel": "user.margin.order",
"data": [
{
"status": "ACTIVE",
"side": "BUY",
"price": 1,
"quantity": 1,
"order_id": "366455245775097673",
"client_oid": "my_order_0002",
"create_time": 1588758017375,
"update_time": 1588758017411,
"type": "LIMIT",
"instrument_name": "ETH_CRO",
"cumulative_quantity": 0,
"cumulative_value": 0,
"avg_price": 0,
"fee_currency": "CRO",
"time_in_force":"GOOD_TILL_CANCEL"
}
],
"channel": "user.margin.order.ETH_CRO"
}
}
For Margin Trading
Publishes all new orders or order updates for the user for a particular instrument (e.g. BTC_USDT).
instrument_name can be omitted to show tickers for all instruments
Requires initial authentication using public/auth (see public/auth for more information).
Applies To
Response Attributes
| Name | Type | Description |
|---|---|---|
| instrument_name | string | e.g. ETH_CRO, BTC_USDT |
| subscription | string | user.order.{instrument_name} -- even in the all case |
| channel | string | user.order |
| data | array | See below |
subscription makes it easy to map to the initial subscription
channel and instrument_name simply allow easier access to parameters without needing to parse the subscription
data consists of:
| Name | Type | Description |
|---|---|---|
| order_id | string | Order ID |
| client_oid | string | (Optional) Client order ID if included in request |
| create_time | number | Order creation time (Unix timestamp) |
| update_time | number | Order update time (Unix timestamp) |
| status | string | ACTIVE, CANCELED, FILLED, REJECTED or EXPIRED |
| reason | string | Reason code (see "Response and Reason Codes") -- only for REJECTED orders |
| type | string | LIMIT, MARKET, STOP_LOSS, STOP_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT |
| side | string | BUY, SELL |
| instrument_name | string | e.g. ETH_CRO, BTC_USDT |
| price | number | Price specified in the order |
| quantity | number | Quantity specified in the order |
| cumulative_quantity | number | Cumulative executed quantity (for partially filled orders) |
| cumulative_value | number | Cumulative executed value (for partially filled orders) |
| avg_price | number | Average filled price. If none is filled, returns 0 |
| fee_currency | string | Currency used for the fees (e.g. CRO) |
| time_in_force | string | - GOOD_TILL_CANCEL- FILL_OR_KILL- IMMEDIATE_OR_CANCEL |
| exec_inst | string | Empty or POST_ONLY (Limit Orders Only) |
| trigger_price | number | Used for trigger-related orders |
Note: To detect a 'partial filled' status, look for status as ACTIVE and cumulative_quantity > 0.
user.margin.trade.{instrument_name}
Request Sample
{
"id": 11,
"method": "subscribe",
"params": {
"channels": ["user.margin.trade.ETH_CRO"]
},
"nonce": 1587523073344
}
Response Sample
{
"method": "subscribe",
"code": 0,
"result": {
"instrument_name": "ETH_CRO",
"subscription": "user.margin.trade.ETH_CRO",
"channel": "user.margin.trade",
"data": [
{
"side": "SELL",
"instrument_name": "ETH_CRO",
"fee": 0.014,
"trade_id": "367107655537806900",
"create_time": "1588777459755",
"traded_price": 7,
"traded_quantity": 1,
"fee_currency": "CRO",
"order_id": "367107623521528450"
}
],
"channel": "user.margin.trade.ETH_CRO"
}
}
For Margin Trading
Publishes all new trades updates related to the user for a particular instrument (e.g. BTC_USDT)
instrument_name can be omitted to show tickers for all instruments
Requires initial authentication using public/auth (see public/auth for more information).
Applies To
Response Attributes
| Name | Type | Description |
|---|---|---|
| instrument_name | string | e.g. ETH_CRO, BTC_USDT |
| subscription | string | user.trade.{instrument_name} -- even in the all case |
| channel | string | user.trade |
| data | array | See below |
subscription makes it easy to map to the initial subscription
channel and instrument_name simply allow easier access to parameters without needing to parse the subscription
data consists of:
| Name | Type | Description |
|---|---|---|
| side | string | BUY, SELL |
| fee | number | Trade fee |
| trade_id | string | Trade ID |
| create_time | long | Trade creation time |
| traded_price | number | Executed trade price |
| traded_quantity | number | Executed trade quantity |
| fee_currency | string | Currency used for the fees (e.g. CRO) |
| order_id | string | Order ID |
user.margin.balance
Request Sample
{
"id": 11,
"method": "subscribe",
"params": {
"channels": ["user.margin.balance"]
},
"nonce": 1587523073344
}
Response Sample
{
"method": "subscribe",
"result": {
"subscription": "user.margin.balance",
"channel": "user.margin.balance",
"data": [
{
"currency": "CRO",
"balance": 99999999947.99626,
"available": 99999988201.50826,
"order": 11746.488,
"stake": 0
}
],
"channel": "user.margin.balance"
}
}
For Margin Trading
Publishes all new balance updates for the user
Requires initial authentication using public/auth (see public/auth for more information).
Applies To
Response Attributes
| Name | Type | Description |
|---|---|---|
| subscription | string | user.balance |
| channel | string | user.balance |
| data | array | See below |
data consists of:
| Name | Type | Description |
|---|---|---|
| currency | string | e.g. CRO |
| balance | number | Total balance |
| available | number | Available balance (e.g. not in orders, or locked, etc.) |
| order | number | Balance locked in orders |
| stake | number | Balance locked for staking (typically only used for CRO) |
book.{instrument_name}.{depth}
Request Sample
{
"id": 11,
"method": "subscribe",
"params": {
"channels": ["book.ETH_CRO.150"]
},
"nonce": 1587523073344
}
Response Sample
{
"method": "subscribe",
"result": {
"instrument_name": "ETH_CRO", // instrument_name
"subscription": "book.ETH_CRO.150",
"channel": "book",
"depth": 150
"data": [
{
"bids": [
[
11746.488, // price
128, // quantity
8 // number of Orders
]
],
"asks": [
[
11747.488, // price
201, // quantity
12 // number of Orders
]
],
"t": 1587523078844
}
]
}
}
Publishes order book changes for an instrument (e.g. BTC_USDT) based on price level depth
| Name | Description |
|---|---|
| depth | Number of bids and asks to return. Allowed values: 10 or 150 |
Applies To
Response Attributes
| Name | Type | Description |
|---|---|---|
| instrument_name | string | e.g. ETH_CRO, BTC_USDT |
| subscription | string | book.{instrument_name}.{depth} |
| channel | string | book |
| depth | number | Price level |
| data | array | See below |
subscription makes it easy to map to the initial subscription
channel, instrument_name and depth simply allow easier access to parameters without needing to parse the subscription
data consists of:
| Name | Type | Description |
|---|---|---|
| bids | array | Bids array: [0] = Price, [1] = Quantity, [2] = Number of Orders |
| asks | array | Asks array: [0] = Price, [1] = Quantity, [2] = Number of Orders |
| t | long | Timestamp of the data |
ticker.{instrument_name}
Request Sample
{
"id": 11,
"method": "subscribe",
"params": {
"channels": ["ticker.ETH_CRO"]
},
"nonce": 1587523073344
}
Response Sample
{
"method": "subscribe",
"result": {
"instrument_name": "ETH_CRO", // instrument_name
"subscription": "ticker.ETH_CRO",
"channel": "ticker",
"data": [
{
"h": 1, // Price of the 24h highest trade
"v": 10232.26315789, // The total 24h traded volume
"a": 173.60263169, // The price of the latest trade, null if there weren't any trades
"l": 0.01, // Price of the 24h lowest trade, null if there weren't any trades
"b": 0.01, // The current best bid price, null if there aren't any bids
"k": 1.12345680, // The current best ask price, null if there aren't any asks
"c": -0.44564773, // 24-hour price change, null if there weren't any trades
"t": 1587523078844 // update time
}
]
}
}
Publishes new tickers for an instrument (e.g. BTC_USDT)
instrument_name can be omitted to show tickers for all instruments
Applies To
Response Attributes
| Name | Type | Description |
|---|---|---|
| instrument_name | string | e.g. ETH_CRO, BTC_USDT |
| subscription | string | ticker.{instrument_name} -- even in the all case |
| channel | string | Channel category (ticker) |
| data | array | See below |
subscription makes it easy to map to the initial subscription
channel and instrument_name simply allow easier access to parameters without needing to parse the subscription
data consists of:
| Name | Type | Description |
|---|---|---|
| h | number | Price of the 24h highest trade |
| v | number | The total 24h traded volume |
| a | number | The price of the latest trade, null if there weren't any trades |
| l | number | Price of the 24h lowest trade, null if there weren't any trades |
| b | number | The current best bid price, null if there aren't any bids |
| k | number | The current best ask price, null if there aren't any asks |
| c | number | 24-hour price change, null if there weren't any trades |
| t | number | Timestamp of the data |
trade.{instrument_name}
Request Sample
{
"id": 11,
"method": "subscribe",
"params": {
"channels": ["trade.ETH_CRO"]
},
"nonce": 1587523073344
}
Response Sample
{
"method": "subscribe",
"result": {
"instrument_name": "ETH_CRO", // instrument_name
"subscription": "trade.ETH_CRO",
"channel": "trade",
"data": [
{
"p": 162.12, // price
"q": 11.085, // quantity
"s": "buy", // side
"d": 1210447366, // trade id
"t": 1587523078844 // trade time
"dataTime": 0 // please ignore this field
}
]
}
}
Publishes new trades for an instrument (e.g. BTC_USDT)
instrument_name can be omitted to show trades for all instruments
Applies To
Response Attributes
| Name | Type | Description |
|---|---|---|
| instrument_name | string | e.g. ETH_CRO, BTC_USDT |
| subscription | string | trade.{instrument_name} -- even in the all case |
| channel | string | Always "trade" |
| data | array | See below |
subscription makes it easy to map to the initial subscription
channel and instrument_name simply allow easier access to parameters without needing to parse the subscription
data consists of:
| Name | Type | Description |
|---|---|---|
| p | number | Trade price |
| q | number | Trade quantity |
| s | string | Side ("buy" or "sell") |
| d | number | Trade ID |
| t | number | Trade timestamp |
| dataTime | long | Reserved. Can be ignored |
candlestick.{interval}.{instrument_name}
Request Sample
{
"id": 11,
"method": "subscribe",
"params": {
"channels": ["candlestick.1h.ETH_CRO"]
},
"nonce": 1587523073344
}
Response Sample
{
"method": "subscribe",
"result": {
"instrument_name": "ETH_CRO", // instrument_name
"subscription": "candlestick.1m.ETH_CRO",
"channel": "candlestick",
"interval": "1m",
"data":[
{
"i": "ETH_CRO",
"o": 162.03, // open
"c": 162.04, // close
"h": 161.96, // high
"l": 161.98, // low
"v": 336.452694 // volume
"t": 1589441241 // start time of the stick, in epochtime
},
{
"i": "ETH_CRO",
"o": 163.03, // open
"c": 163.04, // close
"h": 162.96, // high
"l": 162.98, // low
"v": 336.452694 // volume
"t": 1589443241 // start time of the stick, in epochtime
}
]
}
}
Publishes candlesticks (k-line data history) over a given period for an instrument (e.g. BTC_USDT)
period can be:
1m: one minute5m: five minutes15m: 15 minutes30m: 30 minutes1h: one hour4h: 4 hours6h: 6 hours12h: 12 hours1D: one day7D: one week14D: two weeks1M: one month
Applies To
Response Attributes
| Name | Type | Description |
|---|---|---|
| instrument_name | string | e.g. ETH_CRO, BTC_USDT |
| subscription | string | candlestick.{interval}.{instrument_name} |
| channel | string | Always "candlestick" |
| data | array | See below |
subscription makes it easy to map to the initial subscription
channel and instrument_name simply allow easier access to parameters without needing to parse the subscription
data consists of:
| Name | Type | Description |
|---|---|---|
| o | number | Open |
| c | number | Close |
| h | number | High |
| l | number | Low |
| v | number | Volume |
| t | long | End time of candlestick (Unix timestamp) |
Common Issues
TOO_MANY_REQUESTS After Websocket Connects
Websocket rate limits are pro-rated based on the calendar-second that the websocket connection was opened.
This means, depending on the fraction of the calendar-second that the connection was established, the rate limit could be pro-rated to a small number.
By adding a 1-second sleep after establishing the websocket connection, and before requests are sent, this will ensure the rate limit is properly reset and sync'd to your session.
This will avoid occurrences of rate-limit (TOO_MANY_REQUESTS) errors.
INVALID_NONCE On All Requests
The nonce should be the UTC Unix timestamp in milliseconds.
If this has been carefully checked, then the issue occurs when the system clock of the client machine is greater than 1 second in the future, or 30 seconds in the past.
Usually, re-syncing with the NTP time server on the client machine will correct the issue.
If the issue persists, you can try deliberately subtracting 5 seconds from the nonce to force it to be 5 seconds in the past, which is still within the 30-second past tolerance.