Authentication
How to authenticate with the ZDEX API
All API requests are authenticated using API Key + HMAC Signature. Create your API keys from the Portfolio > API Keys section in the ZDEX web app.
Signing Requests
Every authenticated request must include:
| Parameter | Location | Description |
|---|---|---|
X-API-KEY | Header | Your API key (zdex_...) |
timestamp | Query param | Current Unix timestamp in milliseconds |
signature | Query param | HMAC-SHA256 signature |
How to Sign
- Build the query string with all parameters (including
timestamp), sorted alphabetically - Compute
HMAC-SHA256(queryString, yourSecretKey) - Append
&signature=<result>to the request
Example (Node.js):
const crypto = require('crypto');
const apiKey = 'zdex_a1b2c3d4e5f6...';
const secret = 'your_secret_key_here';
// Build query string
const params = {
symbol: 'BTCUSDT',
timestamp: Date.now().toString(),
};
const sorted = Object.keys(params).sort();
const qs = sorted.map(k => `${k}=${encodeURIComponent(params[k])}`).join('&');
const signature = crypto.createHmac('sha256', secret).update(qs).digest('hex');
const url = `https://api.zdex.world/v1/positions?${qs}&signature=${signature}`;
const res = await fetch(url, {
headers: { 'X-API-KEY': apiKey },
});Example (Python):
import hmac, hashlib, time, requests
from urllib.parse import urlencode
api_key = 'zdex_a1b2c3d4e5f6...'
secret = 'your_secret_key_here'
params = {
'symbol': 'BTCUSDT',
'timestamp': str(int(time.time() * 1000)),
}
query_string = urlencode(sorted(params.items()))
signature = hmac.new(secret.encode(), query_string.encode(), hashlib.sha256).hexdigest()
url = f'https://api.zdex.world/v1/positions?{query_string}&signature={signature}'
res = requests.get(url, headers={'X-API-KEY': api_key})Timestamp Validation
The server rejects requests where timestamp is more than 30 seconds from the server time. Ensure your system clock is synchronized.
Error Responses
{
"ok": false,
"error": "Invalid or expired token"
}| Status | Error | Meaning |
|---|---|---|
| 401 | Authorization required | No API key provided |
| 401 | Invalid API key | API key not found or revoked |
| 401 | Invalid signature | HMAC signature does not match |
| 401 | Invalid or expired timestamp | Timestamp outside 30s window |
| 403 | IP not whitelisted | Request IP not in key's whitelist |
| 403 | API key does not have TRADE permission | Key lacks required permission |