All REST private request headers must contain the following:
OK-ACCESS-KEY
string APIKey(follow [this guide])(./introduction-to-developer-portal-interface#generate-api-keys) to generate an API keyOK-ACCESS-SIGN
uses the HMAC SHA256 hash function to get the hash value, then uses Base-64 encoding (see signature)OK-ACCESS-TIMESTAMP
specifies the time (UTC) when the request is initiated, for example, 2020-12-08T09:08:57.715ZOK-ACCESS-PASSPHRASE
represents the Passphrase you specified when creating the API keySome endpoints, require additional headers:
OK-ACCESS-PROJECT
The project ID of your project (found under Project Details)All requests should have content of type 'application/json' and be valid JSON.
OK-ACCESS-SIGN
request header:
Example:
sign=CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(timestamp + 'GET' + '/api/v5/account/balance?ccy=BTC', SecretKey))
2020-12-08T09:08:57.715Z
GET/POST
/api/v5/account/balance
{"instId":"BTC-USDT","lever":"5","mgnMode":"isolated"}
GET
the request parameter is counted as requestPath, not bodyPostman is a popular API development and testing tool that allows developers to design, test, and document APIs. It provides a user-friendly graphical interface for making HTTP requests to APIs.
If you have not installed Postman, you can download it for free from the Postman website: https://www.postman.com/
Under the Headers tab, add the following key-value pairs:
OK-ACCESS-KEY
OK-ACCESS-PASSPHRASE
OK-ACCESS-PROJECT
(if required)OK-ACCESS-SIGN
) and timestamp (OK-ACCESS-TIMESTAMP
)GET requests:
var method = pm.request.method;
var now = new Date();
var isoString = now.toISOString();
var path = pm.request.url.getPathWithQuery();
var sign=CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(isoString + method + path, pm.variables.replaceIn('{{secret_key}}')));
pm.request.headers.add({
key: 'OK-ACCESS-SIGN',
value: sign
});
pm.request.headers.add({
key: 'OK-ACCESS-TIMESTAMP',
value: isoString
});
POST requests:
var method = pm.request.method;
var now = new Date();
var isoString = now.toISOString();
var path = pm.request.url.getPathWithQuery();
var bodyStr = pm.request.body.raw;
var sign=CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(isoString + method + path + bodyStr, pm.variables.replaceIn('{{secret_key}}')))
pm.request.headers.add({
key: 'OK-ACCESS-SIGN',
value: sign
});
pm.request.headers.add({
key: 'OK-ACCESS-TIMESTAMP',
value: isoString
});
To invoke the API through a Javascript script, refer to the following code example:
const https = require('https');
const crypto = require('crypto');
const querystring = require('querystring');
// Define API credentials and project ids
const api_config = {
"api_key": '',
"secret_key": '',
"passphrase": '',
"project": '' // This applies only to onchainOS APIs
};
function preHash(timestamp, method, request_path, params) {
// Create a pre-signature based on strings and parameters
let query_string = '';
if (method === 'GET' && params) {
query_string = '?' + querystring.stringify(params);
}
if (method === 'POST' && params) {
query_string = JSON.stringify(params);
}
return timestamp + method + request_path + query_string;
}
function sign(message, secret_key) {
// Use HMAC-SHA256 to sign the pre-signed string
const hmac = crypto.createHmac('sha256', secret_key);
hmac.update(message);
return hmac.digest('base64');
}
function createSignature(method, request_path, params) {
// Get the timestamp in ISO 8601 format
const timestamp = new Date().toISOString().slice(0, -5) + 'Z';
// Generate a signature
const message = preHash(timestamp, method, request_path, params);
const signature = sign(message, api_config['secret_key']);
return { signature, timestamp };
}
function sendGetRequest(request_path, params) {
// Generate a signature
const { signature, timestamp } = createSignature("GET", request_path, params);
// Generate the request header
const headers = {
'OK-ACCESS-KEY': api_config['api_key'],
'OK-ACCESS-SIGN': signature,
'OK-ACCESS-TIMESTAMP': timestamp,
'OK-ACCESS-PASSPHRASE': api_config['passphrase'],
'OK-ACCESS-PROJECT': api_config['project'] // This applies only to WaaS APIs
};
const options = {
hostname: 'www.okx.com',
path: request_path + (params ? `?${querystring.stringify(params)}` : ''),
method: 'GET',
headers: headers
};
const req = https.request(options, (res) => {
let data = '';
res.on('data', (chunk) => {
data += chunk;
});
res.on('end', () => {
console.log(data);
});
});
req.end();
}
function sendPostRequest(request_path, params) {
// Generate a signature
const { signature, timestamp } = createSignature("POST", request_path, params);
// Generate the request header
const headers = {
'OK-ACCESS-KEY': api_config['api_key'],
'OK-ACCESS-SIGN': signature,
'OK-ACCESS-TIMESTAMP': timestamp,
'OK-ACCESS-PASSPHRASE': api_config['passphrase'],
'OK-ACCESS-PROJECT': api_config['project'], // This applies only to WaaS APIs
'Content-Type': 'application/json' // POST requests need this header
};
const options = {
hostname: 'www.okx.com',
path: request_path,
method: 'POST',
headers: headers
};
const req = https.request(options, (res) => {
let data = '';
res.on('data', (chunk) => {
data += chunk;
});
res.on('end', () => {
console.log(data);
});
});
if (params) {
req.write(JSON.stringify(params));
}
req.end();
}
// GET request example
const getRequestPath = '/api/v5/dex/aggregator/quote';
const getParams = {
'chainId': 42161,
'amount': 1000000000000,
'toTokenAddress': '0xff970a61a04b1ca14834a43f5de4533ebddb5cc8',
'fromTokenAddress': '0x82aF49447D8a07e3bd95BD0d56f35241523fBab1'
};
sendGetRequest(getRequestPath, getParams);
// POST request example
const postRequestPath = '/api/v5/mktplace/nft/ordinals/listings';
const postParams = {
'slug': 'sats'
};
sendPostRequest(postRequestPath, postParams);