Trade API Documentation

Welcome to the official Trade API documentation. This API provides programmatic access to our cryptocurrency exchange, enabling you to build trading bots, integrate market data, and manage your account.

Base URL

https://trade-api.darkex.live

General Information

HTTP Return Codes

CodeDescription
200Success - Request processed correctly
400Bad Request - Malformed request, check parameters
401Unauthorized - Invalid API key or signature
403Forbidden - API key lacks required permissions
404Not Found - Endpoint does not exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error
503Service Unavailable - Server under maintenance

Authentication

API requests are authenticated using API keys. Each API key is associated with an account and carries specific permissions.

API Key Setup

  1. Create an API key from your account dashboard.
  2. Each key consists of an API Key (public) and an API Secret (private).
  3. Assign permissions: READ, TRADE, or both.
  4. Optionally restrict to specific IP addresses for enhanced security.
Warning: Never share your API Secret. If compromised, delete the key immediately and create a new one.

Security Types

TypeDescriptionRequired Headers
NONEPublic endpoints, no authentication neededNone
TRADERequires valid API key and signatureX-EX-APIKEY + signature
USER_DATARequires valid API key and signatureX-EX-APIKEY + signature
BROKERRequires valid Broker API key and signatureX-EX-APIKEY + signature

HMAC SHA256 Signing

Signed endpoints require a signature parameter. Follow these steps:

  1. Construct the query string from all request parameters (sorted alphabetically).
  2. Create an HMAC SHA256 signature using your API Secret as the key and the query string as the message.
  3. Append the signature parameter to your request.

Signing Example

Given the following parameters for a new order:

ParameterValue
symbolBTCUSDT
sideBUY
typeLIMIT
timeInForceGTC
quantity1
price50000
timestamp1499827319559

Step 1: Build the query string (sorted):

price=50000&quantity=1&side=BUY&symbol=BTCUSDT&timeInForce=GTC&timestamp=1499827319559&type=LIMIT

Step 2: Sign with HMAC SHA256:

API Secret: NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j
Signature:  c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71

Step 3: Send the request:

curl -H "X-EX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" \
  -X POST 'https://trade-api.darkex.live/api/v1/order?price=50000&quantity=1&side=BUY&symbol=BTCUSDT&timeInForce=GTC&timestamp=1499827319559&type=LIMIT&signature=c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71'

Code Examples

Python
JavaScript
C#

    import hmac
    import hashlib
    import time
    import requests
    from urllib.parse import urlencode

    API_KEY = "your_api_key"
    API_SECRET = "your_api_secret"
    BASE_URL = "trade-api.darkex.live"

    def create_signature(params, secret):
    query_string = urlencode(sorted(params.items()))
    signature = hmac.new(
    secret.encode("utf-8"),
    query_string.encode("utf-8"),
    hashlib.sha256
    ).hexdigest()
    return query_string + "&signature=" + signature

    def send_signed_request(method, endpoint, params):
    params["timestamp"] = int(time.time() * 1000)
    query = create_signature(params, API_SECRET)
    url = f"{BASE_URL}{endpoint}?{query}"
    headers = {"X-EX-APIKEY": API_KEY}
    response = requests.request(method, url, headers=headers)
    return response.json()

    # Example: Place a limit order
    result = send_signed_request("POST", "/api/v1/order", {
    "symbol": "BTCUSDT",
    "side": "BUY",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "0.001",
    "price": "50000"
    })
    print(result)

    const crypto = require("crypto");
    const axios = require("axios");

    const API_KEY = "your_api_key";
    const API_SECRET = "your_api_secret";
    const BASE_URL = "https://trade-api.darkex.live";

    function createSignature(params, secret) {
    const sortedKeys = Object.keys(params).sort();
    const queryString = sortedKeys
    .map(key => `${key}=${params[key]}`)
    .join("&");
    const signature = crypto
    .createHmac("sha256", secret)
    .update(queryString)
    .digest("hex");
    return queryString + "&signature=" + signature;
    }

    async function signedRequest(method, endpoint, params) {
    params.timestamp = Date.now();
    const query = createSignature(params, API_SECRET);
    const url = `${BASE_URL}${endpoint}?${query}`;
    const { data } = await axios({
    method,
    url,
    headers: { "X-EX-APIKEY": API_KEY }
    });
    return data;
    }

    // Example: Get account info
    signedRequest("GET", "/api/v1/account", {})
    .then(console.log)
    .catch(console.error);

    using System.Security.Cryptography;
    using System.Text;

    public class TradingApiClient
    {
    private readonly string _apiKey;
    private readonly string _apiSecret;
    private readonly HttpClient _http;
    private const string BaseUrl = "https://trade-api.darkex.live";

    public TradingApiClient(string apiKey, string apiSecret)
    {
    _apiKey = apiKey;
    _apiSecret = apiSecret;
    _http = new HttpClient();
    _http.DefaultRequestHeaders.Add("X-EX-APIKEY", _apiKey);
    }

    private string CreateSignature(SortedDictionary<string, string> parameters)
    {
    var queryString = string.Join("&",
    parameters.Select(p => $"{p.Key}={p.Value}"));

    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(_apiSecret));
    var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(queryString));
    var signature = BitConverter.ToString(hash).Replace("-", "").ToLower();

    return queryString + "&signature=" + signature;
    }

    public async Task<string> PlaceOrderAsync(string symbol, string side,
    string type, decimal quantity, decimal price)
    {
    var parameters = new SortedDictionary<string, string>
    {
    ["symbol"] = symbol,
    ["side"] = side,
    ["type"] = type,
    ["timeInForce"] = "GTC",
    ["quantity"] = quantity.ToString(),
    ["price"] = price.ToString(),
    ["timestamp"] = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds().ToString()
    };

    var query = CreateSignature(parameters);
    var response = await _http.PostAsync($"{BaseUrl}/api/v1/order?{query}", null);
    return await response.Content.ReadAsStringAsync();
    }
    }

Timing Security

Signed endpoints require a timestamp parameter (Unix time in milliseconds). The server compares it against the current server time. If the difference exceeds recvWindow (default: 5000ms), the request is rejected.

Tip: Use the GET /api/v1/time endpoint to synchronize your local clock with the server time. Adjust your recvWindow if you experience latency issues (max: 60000ms).

Rate Limits

The API employs multiple rate limit types to ensure fair usage. Exceeding rate limits results in a 429 HTTP status code.

Limit Types

TypeLimitWindow
Request Weight (IP)60001 minute
Orders (Account)101 second
Orders (Account)200,00024 hours

Each endpoint has a weight value. Most endpoints cost weight 1, but some (like deep order book queries) cost more.

Response Headers

HeaderDescription
X-MBX-USED-WEIGHT-1mCurrent used weight for the IP in the 1-minute window
X-MBX-ORDER-COUNT-10sCurrent order count for the account in the 10-second window
X-MBX-ORDER-COUNT-1dCurrent order count for the account in the 24-hour window
Retry-AfterSeconds to wait before retrying (only on 429 responses)
Important: When you receive HTTP 429, stop sending requests and wait for the duration specified in the Retry-After header. Repeated violations may result in an IP ban.

Error Codes

When an API request fails, the response contains a JSON object with a code and msg field:

{
  "code": -1000,
  "msg": "An unknown error occurred while processing the request."
}

General Errors (1xxx)

CodeMessageDescription
-1000UNKNOWNAn unknown error occurred while processing the request
-1001DISCONNECTEDInternal error; unable to process your request
-1002UNAUTHORIZEDYou are not authorized to execute this request
-1003TOO_MANY_REQUESTSRate limit exceeded
-1006UNEXPECTED_RESPUnexpected response from internal service
-1007TIMEOUTRequest timed out waiting for backend response
-1014UNKNOWN_ORDER_COMPOSITIONUnsupported order combination
-1015TOO_MANY_ORDERSToo many new orders
-1016SERVICE_SHUTTING_DOWNService is shutting down
-1020UNSUPPORTED_OPERATIONThis operation is not supported
-1021INVALID_TIMESTAMPTimestamp is outside of recvWindow
-1022INVALID_SIGNATURESignature for this request is not valid

Request Errors (11xx)

CodeMessageDescription
-1100ILLEGAL_CHARSIllegal characters found in a parameter
-1101TOO_MANY_PARAMETERSToo many parameters sent for this endpoint
-1102MANDATORY_PARAM_EMPTY_OR_MALFORMEDA mandatory parameter was not sent or was empty/malformed
-1103UNKNOWN_PARAMAn unknown parameter was sent
-1104UNREAD_PARAMETERSNot all sent parameters were read
-1105PARAM_EMPTYA parameter was empty
-1106PARAM_NOT_REQUIREDA parameter was sent when not required
-1111BAD_PRECISIONPrecision is over the maximum defined for this asset
-1112NO_DEPTHNo orders on book for symbol
-1114TIF_NOT_REQUIREDTimeInForce parameter sent when not required
-1115INVALID_TIFInvalid timeInForce
-1116INVALID_ORDER_TYPEInvalid orderType
-1117INVALID_SIDEInvalid side
-1118EMPTY_NEW_CL_ORD_IDNew client order ID was empty
-1119EMPTY_ORG_CL_ORD_IDOriginal client order ID was empty
-1120BAD_INTERVALInvalid interval
-1121BAD_SYMBOLInvalid symbol
-1125INVALID_LISTEN_KEYThis listenKey does not exist
-1127MORE_THAN_XX_HOURSLookup interval is too big
-1128BAD_COMBOCombination of optional parameters invalid
-1130INVALID_PARAMETERData sent for a parameter is not valid

Trading Errors (2xxx)

CodeMessageDescription
-2010NEW_ORDER_REJECTEDNew order was rejected
-2011CANCEL_REJECTEDCancel request was rejected
-2013NO_SUCH_ORDEROrder does not exist
-2014BAD_API_KEY_FMTAPI key format is invalid
-2015REJECTED_MBX_KEYInvalid API key, IP, or permissions for action

Filter Errors (4xxx)

CodeMessageDescription
-4000INVALID_ORDER_STATUSInvalid order status
-4001PRICE_LESS_THAN_ZEROPrice must be greater than 0
-4002PRICE_GREATER_THAN_MAXPrice is greater than maximum allowed
-4003QTY_LESS_THAN_ZEROQuantity must be greater than 0
-4004QTY_LESS_THAN_MIN_QTYQuantity is less than minimum allowed
-4005QTY_GREATER_THAN_MAX_QTYQuantity is greater than maximum allowed
-4010PRICE_NOT_INCREASEDPrice is not within the tick size
-4011MIN_NOTIONALPrice * Quantity is too low (notional)
-4013LOT_SIZEQuantity does not conform to lot size step
-4015MAX_NUM_ORDERSToo many open orders on symbol

Broker Errors (3xxx)

CodeMessageDescription
-3001BROKER_NOT_AUTHORIZEDBroker account is not authorized for this operation
-3002BROKER_SUB_ACCOUNT_NOT_FOUNDSub-account not found
-3003BROKER_OWNERSHIP_VIOLATIONSub-account does not belong to this broker
-3004BROKER_SUB_ACCOUNT_FROZENSub-account is frozen
-3005BROKER_TRANSFER_FAILEDTransfer operation failed
-3006BROKER_INSUFFICIENT_BALANCEInsufficient balance for transfer
-3007BROKER_API_KEY_LIMIT_EXCEEDEDMaximum number of API keys reached
-3008BROKER_PERMISSION_DENIEDInsufficient broker permissions
-3009BROKER_DUPLICATE_SUB_ACCOUNTDuplicate sub-account label
-3010BROKER_API_KEY_OPERATION_FAILEDAPI key create/modify/delete operation failed