API 访问和用法#

在开始使用 DEX API 之前，你需要先在开发者管理平台创建项目并生成 API key。详细的步骤和相关资源请参考这里。

鉴权#

所有对 API 发起访问的请求都需要包括下面信息来进行身份认证。

OK-ACCESS-KEY ： API key
OK-ACCESS-TIMESTAMP ：发起请求的时间 (UTC) 。ISO 格式，如：2020-12-08T09:08:57.715Z
OK-ACCESS-PASSPHRASE ：创建 API key 时指定的 passphrase
OK-ACCESS-SIGN ：签名

签名步骤：

第一步：将 timestamp 、 method 、requestPath 、 body 拼接成一个字符串
第二步：以 HMAC SHA256 算法和 secret key (在创建 API key 时生成) 对预哈希字符串 (第一步产生的结果) 进行签名
第三步：以 Base64 算法对签名进行编码

解释

例如，sign=CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(timestamp + 'GET' + '/api/v5/dex/aggregator/swap', SecretKey))
其中，timestamp 与 OK-ACCESS-TIMESTAMP 必须相同
其中，GET 是 method （HTTP请求方法，字母全部大写）
其中，/api/v5/dex/aggregator/swap 是requestPath （请求接口路径）
其中 body 为空。如果请求没有请求体（通常为 GET 请求），那 body 可省略

注意

时间戳与服务端时差不得超过 30 秒
POST 请求需包含原始请求体参与签名计算
Secret key 仅创建时可见，请通过安全渠道存储

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

添加正文#

这通常适用于 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 凭证
const api_config = {
  "api_key": '',
  "secret_key": '',
  "passphrase": '',
};

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'],
  };

  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) {
  // 生成签名
  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'],
    '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 请求示例
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);

遗留 API#

钱包 API、市场 API 和 DeFi API 已经被归档，我们将不再提供更新。如果你正在使用相关服务并需要查看有关的文档内容，请前往这里。