Crypto.com Exchange API v1

Welcome​

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

The Crypto.com Exchange API v1 provides developers with a REST and WebSocket API. The majority of API calls are available across both mediums in the same request and response formats, allowing smooth transition and a reduced learning curve between the two platforms.

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 which can be viewed on the right.

Notes on Exchange Upgrade and API Versions​

• Exchange v1 API is the latest version of API which can trade Spot / Derivatives / Margin.
• Derivatives v1 API has been upgraded into Exchange v1 API with additional capabilities for Spot Trading / Margin Trading / Wallet Management. As Exchange v1 API is a superset of Derivatives v1 API, existing customer can continue using the same for trading.
• For full details about the exchange upgrade, please refer to this (blog post)[https://crypto.com/product-news/introducing-the-gen-3-0-crypto-com-exchange] with FAQ documents.

Breaking Change Schedule​

• On 2025-12-17 8:00 UTC,
  The current trigger order creation/cancellation will be migrated to Advanced Order Management API.

• On 2025-02-27 8:00 UTC,
  For book.{instrument_name}.{depth}, the full snapshot subscription (book_subscription_type=SNAPSHOT) 100ms frequency is removed.
  Customers wishing to continue with the faster 100ms frequency should switch to the delta subscription (book_subscription_type=SNAPSHOT_AND_UPDATE).
  This higher performing subscription benefits the user with reduced bandwidth/processing compared to the snapshot subscription.
  For a transition period, users subscribing to the removed 100ms snapshot will receive the 500ms subscription.

  The book.{instrument_name} subscription (default depth) will be removed.
  Customers should use the explicit book.{instrument_name}.{depth} subscription and specify the required depth.

  For a transition period, users subscribing to the removed subscription will receive the default 50 depth subscription.

• These changes will take place around 17 December 2023 8:00 UTC.

• Market Data wildcard ticker subscription will be removed. Users should use the instrument specific subscription.

Change Log​

• 2026-05-21
  • public/get-instruments response updated, new field product_type was added
  • Trading Bot API section was added: private/bot/create-trading-bot (DCA, TWAP, GRID, FUNDING_ARBITRAGE) private/bot/terminate-trading-bot private/bot/update-trading-bot private/bot/pause-trading-bot private/bot/resume-trading-bot private/bot/get-trading-bots private/bot/get-trading-bot-executions
• 2026-05-07
  • Advanced Order Management API section was updated for DerivAttach
  • private/advanced/create-oto and private/advanced/create-otoco — contingency type is now resolved from instrument type: spot instruments create SPOT_ATTACH, derivative instruments create DERIV_ATTACH. DerivAttach supports isolation_id, leverage, isolated_margin_amount on the primary leg and ISOLATED_MARGIN in exec_inst. Trigger legs inherit isolation mode from the parent.
  • private/advanced/create-order — attach_order_id now applies to both SpotAttach and DerivAttach. New optional field attach_isolation_id for DerivAttach attach-to-position (derivatives only).
  • private/advanced/cancel-oto and private/advanced/cancel-otoco — updated to cover both SPOT_ATTACH and DERIV_ATTACH.
  • private/advanced/cancel-all-orders — new optional field position_type (CROSS_MARGIN, ISOLATED_MARGIN).
  • private/advanced/get-open-orders, private/advanced/get-order-detail, private/advanced/get-order-history, and user.advance.order — response attributes extended with exchange_order_id, ref_price, ref_price_type, reject_reason, attach_isolation_id, isolation_id, isolation_type, leverage, isolated_margin_amount. contingency_type now includes DERIV_ATTACH.
  • private/advanced/amend-order — corrected required/optional flags: new_price is Y, new_quantity is Y, new_ref_price is N.
• 2026-04-29
  • Fee Credits
  • private/get-fee-credit-balances was added
  • private/get-trades response updated, new field fee_credits was added
  • user.trade.{instrument_name} response updated, new field fee_credits was added
• 2026-04-07
  • private/get-accounts response updated, new field hierarchy was added
• 2026-04-01
  • private/create-order request updated, REDUCE_ONLY was added to exec_inst
• 2026-01-08
  • Add support for isolated position
  • private/create-isolated-margin-transfer was added
  • private/change-isolated-margin-leverage was added
  • private/user-balance response updated, new fields total_isolated_cash_balance and isolated_positions were added
  • private/user-balance-history response updated, new field i was added
  • private/get-subaccount-balances response updated, new fields total_isolated_cash_balance and isolated_positions were added
  • private/get-positions response updated, new fields isolation_id and isolation_type were added
  • private/create-order request updated, new optional fields isolation_id, leverage, isolated_margin_amount were added, exec_inst added support for ISOALTED_MARGIN
  • private/close-position request updated, new optional field isolation_id was added
  • private/get-open-orders response updated, new fields isolation_id and isolation_type were added
  • private/get-order-detail response updated, new fields isolation_id and isolation_type were added
  • private/get-order-history request updated, new optional field isolation_id was added, response updated, new fields isolation_id and isolation_type were added
  • private/get-trades request updated, new optional field isolation_id was added, response updated, new fields isolation_id and isolation_type were added
  • private/get-transactions request updated, new optional field isolation_id was added, response updated, new fields isolation_id and isolation_type were added
  • user.order.{instrument_name} response updated, new fields isolation_id and isolation_type were added
  • user.trade.{instrument_name} response updated, new fields isolation_id and isolation_type were added
  • user.balance response updated, new fields total_isolated_cash_balance and isolated_positions were added
  • user.positions response updated, new fields isolation_id, leverage, isolation_type, liquidation_price and isolated_margin_balance were added
  • user.account_risk response updated, new fields total_isolated_cash_balance, isolated_positions were added
  • user.position_balance response updated, new field isolated_positions was added
• 2025-03-26
  • transaction_time was added into user.order.{instrument_name}
• 2025-11-18
  • public/get-risk-parameters was added new columns
• 2025-10-16
  • Advanced Order Management API section was updated
• 2025-07-17
  • private/fiat/fiat-deposit-info was added
  • private/fiat/fiat-deposit-history was added
  • private/fiat/fiat-withdraw-history was added
  • private/fiat/fiat-create-withdraw was added
  • private/fiat/fiat-get-bank-accounts was added
  • private/fiat/fiat-transaction-quota was added
  • private/fiat/fiat-transaction-limit was added
• 2025-07-04
  • private/create-order exec_inst was added SMART_POST_ONLY
  • private/create-order-list (LIST) exec_inst was added SMART_POST_ONLY
  • private/get-open-orders exec_inst was added SMART_POST_ONLY
  • private/get-order-detail was added, exec_inst was added SMART_POST_ONLY
  • private/get-order-history exec_inst was added SMART_POST_ONLY
• 2025-06-10
  • private/amend-order was added
  • public/get-announcements was added
• 2025-05-29
  • transaction_time_ns field was added into user.order.{instrument_name} response
• 2025-03-14
  • Removed deprecated attributes system_label in private/get-accounts
• 2025-03-06
  • Removed deprecated book.{instrument_name} default book subscription
  • Removed deprecated 100ms interval from full snapshot book.{instrument_name}.{depth} book subscription
• 2025-03-04
  • Remove section: Unified Wallet and System Label
• 2025-01-27
  • book.{instrument_name}.{depth} - The following additional update frequencies are now supported:
    Full snapshot subscription (book_subscription_type=SNAPSHOT) 500ms
    Delta subscription (book_subscription_type=SNAPSHOT_AND_UPDATE) 100ms
• 2024-12-11
  • private/create-order fee_instrument_name was added
• 2024-10-02
  • public/get-risk-parameters was added
• 2024-08-15
  • private/get-fee-rate was added
  • private/get-instrument-fee-rate was added
• 2024-07-12
  • Staking API added:
    private/staking/stake
private/staking/unstake
private/staking/get-staking-position
private/staking/get-staking-instruments
private/staking/get-open-stake
private/staking/get-stake-history
private/staking/get-reward-history
private/staking/convert
private/staking/get-open-convert
private/staking/get-convert-history
public/staking/get-conversion-rate
• 2024-06-27
  • private/create-order self-trade prevent (STP) was added
  • private/create-order-list (LIST) self-trade prevent (STP) was added
• 2024-02-12
  • public/get-trades, trade.{instrument_name} subscription, clarification for the public trade side field
  • Side is the side of the taker order
  • book.{instrument_name}.{depth} clarifications for book delta sequence number handling and re-subscription
• 2024-01-04
  • Market data websocket subscription enhancements:
  • book.{instrument_name} - The subscription result value is now explicit
    e.g. previous "subscription": "book.BTC_USD" -> new "subscription": "book.BTC_USD.50"
  • book.{instrument_name}.{depth} - For delta updates, the fixed 500ms delta full book snapshot heartbeat is replaced with empty delta in the case of no book changes
  • ticker - Documented existing 'bs' and 'ks' fields (bid/ask size)
  • settlement - For wildcard subscription, the subscription result value is now explicit
    e.g. previous "subscription": "settlement" -> new "subscription": "settlement.BTCUSD-231124"
  • Applied consistent field ordering for all market data subscriptions (book, ticker, trade, candlestick, index, mark, settlement, funding, estimatedfunding).
    Result fields are always in the following order:
    id, method, code, instrument_name, subscription, channel
  • Market data REST public/get-trades
  • Added additional tn nanoseconds timestamp field to the trade response
  • Clarified timestamp pagination parameters
• 2023-12-18
  • Market Data wildcard ticker subscription removed. Users should use the instrument specific subscription.
• 2023-12-11
  • Introduced Market Data subscription limiting. Refer to Market Data Websocket Subscription Limits for more details
• 2023-10-31
  • user.balance, private/user-balance will be updated:
    1. Existing field total_margin_balance will represent new margin balance calculation without haircut.
    2. Existing field total_initial_margin previously is made up of position IM only. On effective date, this field will represent the total sum of total_position_im + total_haircut
    3. New field total_position_im will be introduced to represent initial margin requirement to support open positions and orders
    4. New field total_haircut will be introduced to represent the total haircut on eligible collateral token assets. Refer to Smart Cross Margin Enhancement Guide for details
  • user.balance, user.account_risk, private/user-balance, private/get-subaccount-balances will be updated:
    1. New field collateral_eligible will be introduced to indicate if token is eligible Collateral
    2. collateral_weight will be deprecated
    3. New field haircut will be introduced to show haircut of eligible collateral token instead of collateral Weight. Refer to Smart Cross Margin Enhancement Guide for details
• 2023-08-11
  • private/create-order-list (LIST) for batch order creation added
  • private/cancel-order-list (LIST) for batch order cancel added
• 2023-07-31
  • Market Data Websocket Subscriptions is effective:
  • funding.{instrument_name} - channel will return the fixed hourly rate that will settle at the end of the hour.
  • estimatedfunding.{instrument_name} - channel will return the estimated hourly rate that will begin in the next interval.
  • Added new "funding_rate" and "estimated_funding_rate" valuation types for public/get-valuations
• 2023-06-28
  • private/get-deposit-history added
  • private/get-withdrawal-history added
• 2022-11-30
  • Support using client_oid to query in private/get-order-detail REST API
• 2022-11-10
  • USD_Stable_Coin (aka USD Bundle), will be renamed as USD. Customer can test the change in UAT from 2022-11-10 before the change is effective in PROD. Target date for PROD is TBD.
  • Customer can input both USD and USD_Stable_Coin to mean the same USD Bundle.
  • However, on response, USD will be used to mean USD Bundle, instead of USD_Stable_Coin.
• 2022-10-31
  • Added private/create-order-list, private/create-subaccount-transfer REST APIs
  • Added user.account_risk and user.position_balance WebSocket subscriptions
  • Added more period in public/get-candlestick candlestick.{time_frame}.{instrument_name} WebSocket subscription
• 2022-09-21 - Added Unified Wallet and System Label section, to illustrate the transition from multiple wallets into unified wallet.
• 2022-09-21 - Added new sub-account management endpoints: private/get-accounts, private/create-subaccount-transfer
• 2022-09-21 - Added new exchange wallet management endpoints: private/create-withdrawal, private/get-deposit-address, private/get-curency-networks
• 2022-09-21 - First publish, based on Derivative Exchange API v1.

Common API References​

Naming Conventions​

• All methods and URLs in dash-case
• All parameters in snake_case
• Enums in full UPPERCASE and snake_case

Generating the API Key​

Before sending any requests, generate a new API key on the Exchange website under User Center → API. Note down:

• API Key
• Secret Key

Default settings are "Can Read" only; you can add or remove permissions via the Web UI. You may optionally specify a whitelist of IP addresses; if set, the API can only be used from those IPs.

REST API Root Endpoints​

REST API requests must be sent with Content-Type: application/json.

Websocket Root Endpoints​

Rate Limits​

REST API​

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

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

Staking​

Websocket​

Request Format​

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

⚠️ All numbers must be strings, and must be wrapped in double quotes. e.g. "12.34", instead of 12.34.

Digital Signature​

For REST API, only 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 pass in the digital signature and API key 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.

⚠️ You should NEVER explicitly include the API Secret Key in plain-text in your request

The algorithm for generating the HMAC-SHA256 signature is as follows:

1. If "params" exist in the request, sort the request parameter keys in ascending order.
2. Combine all the ordered parameter keys as key + value (no spaces, no delimiters). Let's call this the parameter string
3. Next, do the following: method + id + api_key + parameter string + nonce
4. Use HMAC-SHA256 to hash the above using the API Secret as the cryptographic key
5. Encode the output as a hex string -- this is your Digital Signature

Since all parameters for calculating the HMAC-SHA256 hash are present in the request except the API Secret, the server-side will independently calculate the Digital Signature as well, and if done correctly, the computed hashes will match.

Besides, for JavaScript client calling private/get-order-detail API, it is highly recommended to use STRING format of order_id in the JSON request payload, in order to guarantee the correctness of Digital Signature.

JavaScript Example​

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

const signRequest = (request_body, api_key, secret) => {
  const { id, method, params, nonce } = request_body;

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

  const paramsString = objectToString(params);

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

  return request_body;
};

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

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

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

Python Example​

import hmac
import hashlib
import time

API_KEY = "API_KEY"
SECRET_KEY = "SECRET_KEY"

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

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

MAX_LEVEL = 3


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

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


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

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

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

C# Example​

using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Text;

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

private static string GetSign(Dictionary<string, object> request)
{
  var paramsDict = request["params"] as Dictionary<string, object>;

  // Ensure the params are alphabetically sorted by key
  // Note: For nested objects or lists, implement recursive sorting similar to JS/Python examples
  string paramString = paramsDict != null
    ? string.Join("", paramsDict.Keys.OrderBy(key => key).Select(key => key + paramsDict[key]))
    : "";

  string sigPayload = request["method"].ToString()
    + request["id"].ToString()
    + API_KEY
    + paramString
    + request["nonce"].ToString();

  using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(API_SECRET)))
  {
    var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(sigPayload));
    return BitConverter.ToString(hash).Replace("-", "").ToLowerInvariant();
  }
}

Java Example​

import com.fasterxml.jackson.annotation.JsonProperty;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.util.Map;

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class ApiRequestJson {
  private Long id;
  private String method;
  private Map<String, Object> params;
  private String sig;

  @JsonProperty("api_key")
  private String apiKey;

  private Long nonce;
}

//------------

import java.math.BigDecimal;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.List;
import java.util.Map;
import java.util.TreeMap;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.apache.commons.codec.binary.Hex;

public class SigningUtil {

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

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

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


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

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

  public static String genSignature(ApiRequestJson apiRequestJson, String secret)
      throws NoSuchAlgorithmException, InvalidKeyException {
    final byte[] byteKey = secret.getBytes(StandardCharsets.UTF_8);
    Mac mac = Mac.getInstance(HMAC_SHA256);
    SecretKeySpec keySpec = new SecretKeySpec(byteKey, HMAC_SHA256);
    mac.init(keySpec);

    String paramsString = "";

    if (apiRequestJson.getParams() != null) {
      paramsString += getParamString(apiRequestJson.getParams());
    }

    String sigPayload =
        apiRequestJson.getMethod()
            + apiRequestJson.getId()
            + apiRequestJson.getApiKey()
            + paramsString
            + (apiRequestJson.getNonce() == null ? "" : apiRequestJson.getNonce());

    byte[] macData = mac.doFinal(sigPayload.getBytes(StandardCharsets.UTF_8));

    return Hex.encodeHexString(macData);
  }

  public static ApiRequestJson sign(ApiRequestJson apiRequestJson, String secret)
      throws InvalidKeyException, NoSuchAlgorithmException {
    apiRequestJson.setSig(genSignature(apiRequestJson, secret));

    return apiRequestJson;
  }

  public static void main(String[] argv) throws InvalidKeyException, NoSuchAlgorithmException {
    ApiRequestJson apiRequestJson = ApiRequestJson.builder()
            .id(11L)
            .apiKey("token")
            .method("public/auth")
            .nonce(1589594102779L)
            .build();

    System.out.println(genSignature(apiRequestJson, "secretKey"));

    System.out.println(sign(apiRequestJson, "secretKey"));

  }
}

Response Format​

Response and Reason Codes​

200 OK​

400 Bad Request​

401 Unauthorized​

408 Request Timeout​

429 Too Many Requests​

500 Internal Server Error​

Websocket Termination Codes​

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.

Common Issues​

TOO_MANY_REQUESTS After Websocket Connects​

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

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

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

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

INVALID_NONCE On All Requests​

The nonce should be the UTC Unix timestamp in milliseconds.

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

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

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

Reference and market data endpoints provide public, unauthenticated access to instrument metadata, real-time market data, and historical pricing information. These endpoints form the foundation for price discovery, order book analysis, and trading decision workflows.

Core Data Types​

Instrument Reference Data​

Use public/get-instruments to retrieve the full catalog of tradable instruments. Each instrument includes:

• Contract specifications (tick size, quantity decimals, leverage limits)
• Product classification (perpetual swap, future, option)
• Trading status and expiry information
• Underlying index reference

This endpoint should be called on application startup and periodically refreshed to detect new listings or contract expirations.

Real-Time Market Data​

For low-latency applications, use WebSocket subscriptions instead:

• book.{instrument_name}.{depth} - Order book updates (10 or 50 levels)
• ticker.{instrument_name} - Real-time ticker updates
• trade.{instrument_name} - Trade feed

Settlement and Expiry​

public/get-expired-settlement-price provides historical settlement prices for expired futures contracts. Use this for post-trade reconciliation and historical PnL calculations.

Rate Limits​

Public endpoints share a global rate limit pool. For market data-intensive applications:

• Use WebSocket subscriptions instead of polling REST endpoints
• Cache public/get-instruments responses (updates infrequently)
• Batch ticker requests by omitting instrument_name to get all tickers in one call

Typical Integration Flow​

Step 1 — Bootstrap Reference Data

Call public/get-instruments to load the instrument catalog. Store contract specifications locally.

Step 2 — Subscribe to Market Data

For real-time pricing, establish WebSocket connections and subscribe to:

• book.{instrument_name}.10 - top 10 order book levels
• ticker.{instrument_name} - 24h summary stats
• trade.{instrument_name} - trade feed

Step 3 — Polling Fallback

If WebSocket connections are unavailable, poll public/get-tickers and public/get-book at reasonable intervals (e.g., 1-5 seconds).

Retrieve real-time and historical snapshots of wallet balances, open positions, margin requirements, and collateral status. Use these endpoints to monitor account health, risk exposure, and available trading capacity.

Account Balance​

The user balance response provides a comprehensive view of the account:

• Available balance — funds available for new positions and withdrawals
• Margin balance — total collateral value (cash + collateral-eligible tokens after haircut)
• Initial margin (IM) — collateral required to open current positions and orders
• Maintenance margin (MM) — minimum collateral threshold to avoid liquidation
• Position balance — per-token breakdown showing quantity, market value, haircut rate, and collateral contribution

If margin balance falls below maintenance margin, the account enters liquidation.

Positions​

The positions endpoint returns all open derivative contracts, including instrument name, quantity (signed to indicate direction), position cost, and session PnL. For real-time mark price, liquidation price, and margin requirements, subscribe to the user.positions WebSocket channel.

Subaccounts​

Master accounts can create subaccounts to isolate trading activity. Use the subaccount transfer endpoint to move funds between accounts.

Private trading endpoints manage order placement and lifecycle. All order operations (create, amend, cancel) are asynchronous — the REST response confirms the request was received, but order lifecycle updates arrive via WebSocket subscriptions.

Order Management Workflow​

Create Order Call private/create-order to submit a new order. The response returns an order_id and client_oid, but the order may still be pending acceptance by the matching engine. Subscribe to user.order or user.order.{instrument_name} to receive real-time order status updates.

Amend Order Call private/amend-order to modify price or quantity on an existing order. Behind the scenes, amend performs a cancel-then-create operation. The new order loses queue priority unless you are only reducing quantity.

Cancel Order Call private/cancel-order to cancel a single order by order_id or client_oid, or private/cancel-all-orders to cancel all orders for a given instrument.

Order Types​

For trigger orders (stop-loss, take-profit) and multi-leg strategies (OCO, OTO, OTOCO), see Advanced Order Management.

Time in Force​

Execution Instructions​

Execution instructions are passed as an array in exec_inst. Multiple instructions can be combined.

Order Statuses​

Querying Orders and Trades​

• private/get-open-orders — retrieve all currently active orders
• private/get-order-detail — fetch detailed information about a single order
• private/get-order-history — retrieve past orders (filled, canceled, or rejected)
• private/get-trades — retrieve executed trades (fills)

Real-Time Order and Trade Updates​

Subscribe to the following WebSocket channels for real-time updates:

These subscriptions require authentication and eliminate the need for polling REST endpoints.