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.liveGeneral Information
- All endpoints return JSON objects or arrays.
- All time and timestamp related fields are in milliseconds.
- All data is returned in ascending order (oldest first, newest last).
- HTTP
4XXreturn codes are used for malformed requests; the issue is on the client side. - HTTP
429return code indicates rate limit has been exceeded. - HTTP
5XXreturn codes are used for internal server errors. - For
GETendpoints, parameters must be sent as a query string. - For
POST,PUT, andDELETEendpoints, parameters may be sent as a query string or in the request body with content typeapplication/x-www-form-urlencoded. - Parameters may be sent in any order.
HTTP Return Codes
| Code | Description |
|---|---|
200 | Success - Request processed correctly |
400 | Bad Request - Malformed request, check parameters |
401 | Unauthorized - Invalid API key or signature |
403 | Forbidden - API key lacks required permissions |
404 | Not Found - Endpoint does not exist |
429 | Too Many Requests - Rate limit exceeded |
500 | Internal Server Error |
503 | Service 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
- Create an API key from your account dashboard.
- Each key consists of an API Key (public) and an API Secret (private).
- Assign permissions:
READ,TRADE, or both. - Optionally restrict to specific IP addresses for enhanced security.
Security Types
| Type | Description | Required Headers |
|---|---|---|
| NONE | Public endpoints, no authentication needed | None |
| TRADE | Requires valid API key and signature | X-EX-APIKEY + signature |
| USER_DATA | Requires valid API key and signature | X-EX-APIKEY + signature |
| BROKER | Requires valid Broker API key and signature | X-EX-APIKEY + signature |
HMAC SHA256 Signing
Signed endpoints require a signature parameter. Follow these steps:
- Construct the query string from all request parameters (sorted alphabetically).
- Create an HMAC SHA256 signature using your API Secret as the key and the query string as the message.
- Append the
signatureparameter to your request.
Signing Example
Given the following parameters for a new order:
| Parameter | Value |
|---|---|
| symbol | BTCUSDT |
| side | BUY |
| type | LIMIT |
| timeInForce | GTC |
| quantity | 1 |
| price | 50000 |
| timestamp | 1499827319559 |
Step 1: Build the query string (sorted):
price=50000&quantity=1&side=BUY&symbol=BTCUSDT&timeInForce=GTC×tamp=1499827319559&type=LIMITStep 2: Sign with HMAC SHA256:
API Secret: NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j
Signature: c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71Step 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×tamp=1499827319559&type=LIMIT&signature=c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71'Code Examples
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.
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
| Type | Limit | Window |
|---|---|---|
| Request Weight (IP) | 6000 | 1 minute |
| Orders (Account) | 10 | 1 second |
| Orders (Account) | 200,000 | 24 hours |
Each endpoint has a weight value. Most endpoints cost weight 1, but some (like deep order book queries) cost more.
Response Headers
| Header | Description |
|---|---|
X-MBX-USED-WEIGHT-1m | Current used weight for the IP in the 1-minute window |
X-MBX-ORDER-COUNT-10s | Current order count for the account in the 10-second window |
X-MBX-ORDER-COUNT-1d | Current order count for the account in the 24-hour window |
Retry-After | Seconds to wait before retrying (only on 429 responses) |
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)
| Code | Message | Description |
|---|---|---|
-1000 | UNKNOWN | An unknown error occurred while processing the request |
-1001 | DISCONNECTED | Internal error; unable to process your request |
-1002 | UNAUTHORIZED | You are not authorized to execute this request |
-1003 | TOO_MANY_REQUESTS | Rate limit exceeded |
-1006 | UNEXPECTED_RESP | Unexpected response from internal service |
-1007 | TIMEOUT | Request timed out waiting for backend response |
-1014 | UNKNOWN_ORDER_COMPOSITION | Unsupported order combination |
-1015 | TOO_MANY_ORDERS | Too many new orders |
-1016 | SERVICE_SHUTTING_DOWN | Service is shutting down |
-1020 | UNSUPPORTED_OPERATION | This operation is not supported |
-1021 | INVALID_TIMESTAMP | Timestamp is outside of recvWindow |
-1022 | INVALID_SIGNATURE | Signature for this request is not valid |
Request Errors (11xx)
| Code | Message | Description |
|---|---|---|
-1100 | ILLEGAL_CHARS | Illegal characters found in a parameter |
-1101 | TOO_MANY_PARAMETERS | Too many parameters sent for this endpoint |
-1102 | MANDATORY_PARAM_EMPTY_OR_MALFORMED | A mandatory parameter was not sent or was empty/malformed |
-1103 | UNKNOWN_PARAM | An unknown parameter was sent |
-1104 | UNREAD_PARAMETERS | Not all sent parameters were read |
-1105 | PARAM_EMPTY | A parameter was empty |
-1106 | PARAM_NOT_REQUIRED | A parameter was sent when not required |
-1111 | BAD_PRECISION | Precision is over the maximum defined for this asset |
-1112 | NO_DEPTH | No orders on book for symbol |
-1114 | TIF_NOT_REQUIRED | TimeInForce parameter sent when not required |
-1115 | INVALID_TIF | Invalid timeInForce |
-1116 | INVALID_ORDER_TYPE | Invalid orderType |
-1117 | INVALID_SIDE | Invalid side |
-1118 | EMPTY_NEW_CL_ORD_ID | New client order ID was empty |
-1119 | EMPTY_ORG_CL_ORD_ID | Original client order ID was empty |
-1120 | BAD_INTERVAL | Invalid interval |
-1121 | BAD_SYMBOL | Invalid symbol |
-1125 | INVALID_LISTEN_KEY | This listenKey does not exist |
-1127 | MORE_THAN_XX_HOURS | Lookup interval is too big |
-1128 | BAD_COMBO | Combination of optional parameters invalid |
-1130 | INVALID_PARAMETER | Data sent for a parameter is not valid |
Trading Errors (2xxx)
| Code | Message | Description |
|---|---|---|
-2010 | NEW_ORDER_REJECTED | New order was rejected |
-2011 | CANCEL_REJECTED | Cancel request was rejected |
-2013 | NO_SUCH_ORDER | Order does not exist |
-2014 | BAD_API_KEY_FMT | API key format is invalid |
-2015 | REJECTED_MBX_KEY | Invalid API key, IP, or permissions for action |
Filter Errors (4xxx)
| Code | Message | Description |
|---|---|---|
-4000 | INVALID_ORDER_STATUS | Invalid order status |
-4001 | PRICE_LESS_THAN_ZERO | Price must be greater than 0 |
-4002 | PRICE_GREATER_THAN_MAX | Price is greater than maximum allowed |
-4003 | QTY_LESS_THAN_ZERO | Quantity must be greater than 0 |
-4004 | QTY_LESS_THAN_MIN_QTY | Quantity is less than minimum allowed |
-4005 | QTY_GREATER_THAN_MAX_QTY | Quantity is greater than maximum allowed |
-4010 | PRICE_NOT_INCREASED | Price is not within the tick size |
-4011 | MIN_NOTIONAL | Price * Quantity is too low (notional) |
-4013 | LOT_SIZE | Quantity does not conform to lot size step |
-4015 | MAX_NUM_ORDERS | Too many open orders on symbol |
Broker Errors (3xxx)
| Code | Message | Description |
|---|---|---|
-3001 | BROKER_NOT_AUTHORIZED | Broker account is not authorized for this operation |
-3002 | BROKER_SUB_ACCOUNT_NOT_FOUND | Sub-account not found |
-3003 | BROKER_OWNERSHIP_VIOLATION | Sub-account does not belong to this broker |
-3004 | BROKER_SUB_ACCOUNT_FROZEN | Sub-account is frozen |
-3005 | BROKER_TRANSFER_FAILED | Transfer operation failed |
-3006 | BROKER_INSUFFICIENT_BALANCE | Insufficient balance for transfer |
-3007 | BROKER_API_KEY_LIMIT_EXCEEDED | Maximum number of API keys reached |
-3008 | BROKER_PERMISSION_DENIED | Insufficient broker permissions |
-3009 | BROKER_DUPLICATE_SUB_ACCOUNT | Duplicate sub-account label |
-3010 | BROKER_API_KEY_OPERATION_FAILED | API key create/modify/delete operation failed |