REST API authentication#

Initiate a request#

All REST private request headers must contain the following:

OK-ACCESS-KEY string APIKey (follow this guide to generate an API key
OK-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.715Z
OK-ACCESS-PASSPHRASE represents the Passphrase you specified when creating the API key

Some endpoints, such as WaaS, 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.

Signature#

OK-ACCESS-SIGNrequest header：

is a combination of timestamp + method + requestPath + body strings (+ indicates string connection) and SecretKey, which is encrypted using the HMAC SHA256 method and output through Base-64 encoding.
Prepare the Secret Key (generated when the API key is created).
Use HMAC SHA256 to sign the pre-hash string with a key.
Encodes the signature in Base64 format.

Example: sign=CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(timestamp + 'GET' + '/api/v5/account/balance?ccy=BTC', SecretKey))

The value of 'timestamp' is the same as the request header of 'OK-ACCESS-TIMESTAMP' and is in ISO format
- For example：2020-12-08T09:08:57.715Z
method indicates the request method. All letters are uppercase
- For example：GET/POST
requestPath specifies the request interface path
- For example：/api/v5/account/balance
body is the string that requests the body. If the request does not have a body (usually a GET request), the body can be omitted
- For example：{"instId":"BTC-USDT","lever":"5","mgnMode":"isolated"}
- GETthe request parameter is counted as requestPath, not body

Javascript example#

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 WaaS 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);

Introduction

Use the developer portal

Introduction

Node.js environment Settings

Table of contents

Initiate a request

Signature

Javascript example