REST API 鉴权#

发起请求#

所有 REST 私有请求头都必须包含以下内容：

OK-ACCESS-KEY 字符串类型的 API key (遵循这个指南来生成一个 API key)
OK-ACCESS-SIGN 使用 HMAC SHA256 哈希函数获得哈希值，再使用 Base-64 编码 (请参阅签名)
OK-ACCESS-TIMESTAMP 发起请求的时间 (UTC) ，如：2020-12-08T09:08:57.715Z
OK-ACCESS-PASSPHRASE 你在创建 API key 时指定的 Passphrase

一些端点，例如 WaaS，需要额外的请求头：

OK-ACCESS-PROJECT 你的项目的项目 ID (可在项目详细信息下找到)

所有请求都应该含有application/json类型内容，并且是有效的 JSON。

签名#

OK-ACCESS-SIGN的请求头：

是对timestamp + method + requestPath + body字符串 (+ 表示字符串连接)，以及 Secret key，使用 HMAC SHA256 方法加密，通过 Base-64 编码输出而得到的。
准备 Secret key (在创建 API key 时生成)。
使用 HMAC SHA256 使用密钥对预哈希字符串进行签名。
以 Base64 格式对签名进行编码。

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

其中，timestamp的值与OK-ACCESS-TIMESTAMP请求头相同，为 ISO 格式
- 如：2020-12-08T09:08:57.715Z
method 是请求方法，字母全部大写
- 如：GET/POST
requestPath 是请求接口路径
- 如：/api/v5/account/balance
body 是指请求主体的字符串，如果请求没有主体（通常为 GET 请求）则 body 可省略
- 如：{"instId":"BTC-USDT","lever":"5","mgnMode":"isolated"}
- GET请求参数是算作 requestPath，不算 body

Postman 示例#

Postman 是一款流行的 API 开发和测试工具，允许开发人员设计、测试和记录 API。它提供了对用户友好的图形界面，用于向 API 发送 HTTP 请求。

如果你还没有安装 Postman，你可以免费从 Postman 网站下载它：https://www.postman.com/

提示

这个示例需要你具备对 Postman 的基础理解。

添加参数#

这通常适用于 GET 请求。
如果你的请求需要查询参数，你可以在 Params 选项卡下添加它们。在这里，你可以添加查询参数的 key-value pair。

设置标题#

在 Headers 选项卡下，添加以下键-值对：

OK-ACCESS-KEY
OK-ACCESS-PASSPHRASE
OK-ACCESS-PROJECT(如果需要)

添加正文#

这通常适用于 POST 请求。
如果你的请求需要一个请求主体，你可以在 Body 选项卡下添加它们。
在下拉菜单中选择 raw 和 JSON。
使用 JSON 格式输入你的请求主体。

设置预请求脚本#

用于生成所需的签名 (OK-ACCESS-SIGN) 和时间戳 (OK-ACCESS-TIMESTAMP)。
在 Pre-request Script 选项卡下，插入与请求类型相对应的脚本。
在生成预哈希字符串时，GET 请求会排除请求主体。
根据需要编辑密钥。

GET 请求：

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 请求:

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 示例#

若要通过 Javascript 脚本调用 API，请参考以下代码示例：

const https = require('https');
const crypto = require('crypto');
const querystring = require('querystring');

// 定义 API 凭证和项目 ID
const api_config = {
  "api_key": '',
  "secret_key": '',
  "passphrase": '',
  "project": '' // 此处仅适用于 WaaS APIs
};

function preHash(timestamp, method, request_path, params) {
  // 根据字符串和参数创建预签名
  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) {
  // 使用 HMAC-SHA256 对预签名字符串进行签名
  const hmac = crypto.createHmac('sha256', secret_key);
  hmac.update(message);
  return hmac.digest('base64');
}

function createSignature(method, request_path, params) {
  // 获取 ISO 8601 格式时间戳
  const timestamp = new Date().toISOString().slice(0, -5) + 'Z';
  // 生成签名
  const message = preHash(timestamp, method, request_path, params);
  const signature = sign(message, api_config['secret_key']);
  return { signature, timestamp };
}

function sendGetRequest(request_path, params) {
  // 生成签名
  const { signature, timestamp } = createSignature("GET", request_path, params);

  // 生成请求头
  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'] // 这仅适用于 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) {
  // 生成签名
  const { signature, timestamp } = createSignature("POST", request_path, params);

  // 生成请求头
  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'], // 这仅适用于 WaaS APIs
    'Content-Type': 'application/json' // POST 请求需要加上这个头部
  };

  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 请求示例
const getRequestPath = '/api/v5/dex/aggregator/quote';
const getParams = {
  'chainId': 42161,
  'amount': 1000000000000,
  'toTokenAddress': '0xff970a61a04b1ca14834a43f5de4533ebddb5cc8',
  'fromTokenAddress': '0x82aF49447D8a07e3bd95BD0d56f35241523fBab1'
};
sendGetRequest(getRequestPath, getParams);

// POST 请求示例
const postRequestPath = '/api/v5/mktplace/nft/ordinals/listings';
const postParams = {
  'slug': 'sats'
};
sendPostRequest(postRequestPath, postParams);