API Access and Usage#

Before using the DEX API, you need to create a project and generate an API key in the developer portal. For step-by-step instructions and additional resources, please refer to the guide available here.

Authentication#

All API requests must include the following headers:

OK-ACCESS-KEY: Your API key.
OK-ACCESS-TIMESTAMP: Request timestamp in UTC (ISO format, e.g., 2020-12-08T09:08:57.715Z).
OK-ACCESS-PASSPHRASE: The passphrase specified when creating the API key.
OK-ACCESS-SIGN: Request signature.

Signature steps:

Step 1: Concatenate the timestamp, HTTP method (e.g., GET/POST), requestPath, and body (if applicable) into a string.
Step 2: Sign the pre-hashed string (from Step 1) using the HMAC SHA256 algorithm with your secret key (generated during API key creation).
Step 3: Encode the signature using Base64.

Explanation

For example, sign = CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(timestamp + 'GET' + '/api/v5/dex/aggregator/swap', SecretKey))
Timestamp and OK-ACCESS-TIMESTAMP must be the same
GET is the method (HTTP request method, all letters are uppercase)
/api/v5/dex/aggregator/swap is the requestPath (request interface path)
Body is empty. If the request has no request body (usually a GET request), body can be omitted

Note

The time difference between the timestamp and the server must not exceed 30 seconds
The POST request must include the original request in the signature
The secret key is only visible during its creation. Please store it in a safe place that is accessible only by you

Postman example#

Postman 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/

Note

This example requires you to have a basic understanding of Postman.

Add parameters#

This typically applies to GET requests.
If your request requires query parameters, you can add them under the Params tab. Here, you can add key-value pairs for your query parameters.

Set headers#

Under the Headers tab, add the following key-value pairs:

OK-ACCESS-KEY
OK-ACCESS-PASSPHRASE

Add body#

This typically applies to POST requests.
If your request requires a request body, you can add them under the Body tab.
Select raw and JSON under the dropdown menu.
Input your request body in JSON format.

Set pre-request script#

This is used to generate the necessary signature (OK-ACCESS-SIGN) and timestamp (OK-ACCESS-TIMESTAMP)
Under the Pre-request Script tab, insert the script which corresponds to the request type.
Exclude the request body when generating the prehash string for GET requests.
Edit the secret key accordingly.

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

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
const api_config = {
  "api_key": '',
  "secret_key": '',
  "passphrase": '',
};

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'],
    'Content-Type': 'application/json'
  };

  const options = {
    hostname: 'web3.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'],
    'Content-Type': 'application/json' 
  };

  const options = {
    hostname: 'web3.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);

Legacy API#

The Wallet API, Marketplace API, and DeFi API will no longer be updated. If you are using these APIs, please visit here for more information.

Table of contents