介绍
REST API 鉴权

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 选项卡下添加它们。
  • 在下拉菜单中选择 rawJSON
  • 使用 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);