WaaS Web3 API 接口鉴权全流程：REST 认证与签名示例

REST API、Web3、数字资产、WaaS、密钥签名、Postman、JavaScript、UTC 时间戳

如果你有在 Web3 场景中对接托管钱包或资产管理后台的需求，REST API 鉴权 是绕不开的第一步。本文将以 OKX Web3 WaaS API 为例，给出最精简又最完整的实践指南，涵盖密钥生成、签名算法、Postman 调试及一句话 JavaScript 代码，助你 10 分钟跑通第一笔链上数据查询。

发起一次带签名的私有请求

所有需要身份鉴权的 REST 接口都必须在请求头加入四组固定字段：

OK-ACCESS-KEY
由开发者门户生成的 API 密钥（不是私钥）。
OK-ACCESS-SIGN
通过 HMAC-SHA256 + Base64 计算出的签名值。
OK-ACCESS-TIMESTAMP
UTC 时间戳，格式形如：2020-12-08T09:08:57.715Z。
OK-ACCESS-PASSPHRASE
创建密钥时自定义的「口令」。

部分接口（如项目级数据）还须提供：

OK-ACCESS-PROJECT
项目 ID，可在「项目详情」中复制。

请求体的 Content-Type 必须为 application/json，并保证是标准 JSON 字符串。

签名原理与伪代码拆解

1. 构造 `pre-hash` 字符串

规则：timestamp + method + requestPath + body 顺序拼接，区分大小写。

字段	要求示例
method	全大写：GET / POST
requestPath	含查询串，`/api/v5/account/balance?ccy=BTC`
body	POST 时放 JSON 字符串；GET 时留空串

2. 计算签名

signature = Base64(
              HMAC_SHA256(
                  prehashString, 待加密
                  secretKey       密钥
              )
            )

示例 JavaScript 片段：

const crypto = require('crypto');
const sign = crypto
  .createHmac('sha256', secretKey)
  .update(prehashString)
  .digest('base64');

FAQ #1：时间戳有效期多久？

服务器一般容忍前后 30 秒 的偏差。建议校准时钟后再发起请求。

FAQ #2：body 什么时候需要？

仅有 PUT/POST 等写操作含 JSON 时才拼接。GET 参数别误塞进 body 字段！

用 Postman 直线调试

Postman 几乎零门槛，适用于 API 初学者 与 测试协同场景。

步骤一：填入公共请求头

键	值示例
OK-ACCESS-KEY	`afa1b2c3…`
OK-ACCESS-PASSPHRASE	`myPassphrase`
OK-ACCESS-PROJECT	`proj-123`（如有）

步骤二：GET 请求附加查询参数

在 Params 标签页填好 key / value，Headers 中即可省略 ?ccy=BTC 缀在 path 后面。

步骤三：POST 请求设置 JSON body

选 Body → raw → JSON

粘贴示例：

{"instId":"BTC-USDT","lever":"5","mgnMode":"isolated"}

步骤四：Pre-request Script 自动生成签名

在 Pre-request Script 加入如下模板，一键计算 OK-ACCESS-SIGN 与 OK-ACCESS-TIMESTAMP：

const crypto = require('crypto');
const timestamp = new Date().toISOString();
let body = pm.request.body ? pm.request.body.raw : "";
let method = pm.request.method.toUpperCase();
let path = pm.request.url.getPath() + (pm.request.url.query ? '?' + pm.request.url.query.toString() : "");

const prehashStr = [timestamp, method, path, body].join('');
const signature = CryptoJS.enc.Base64.stringify(
                    CryptoJS.HmacSHA256(prehashStr, pm.environment.get("SecretKey"))
                 );

pm.request.headers.upsert({key: 'OK-ACCESS-TIMESTAMP', value: timestamp});
pm.request.headers.upsert({key: 'OK-ACCESS-SIGN', value: signature});

👉 这里一次性给出 Postman 全环境配置 JSON，快速导入即可体验。

JavaScript 环境 30 秒调用

将以下脚本复制到 Node.js 即可直接打印账户余额：

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

const API_KEY = '你的APIKey';
const SECRET = '你的SecretKey';
const PASSPHRASE = '你的Passphrase';

function genSign(method, path, body = '') {
  const time = new Date().toISOString();
  const pre = `${time}${method}${path}${body}`;
  const sign = crypto.createHmac('sha256', SECRET).update(pre).digest('base64');
  return { sign, time };
}

const path = '/api/v5/account/balance';
const { sign, time } = genSign('GET', path);

const headers = {
  'OK-ACCESS-KEY': API_KEY,
  'OK-ACCESS-SIGN': sign,
  'OK-ACCESS-TIMESTAMP': time,
  'OK-ACCESS-PASSPHRASE': PASSPHRASE,
  'Content-Type': 'application/json'
};

const req = https.request({
  host: 'www.okx.com',
  path,
  headers,
  method: 'GET'
}, res => {
  let chunk = '';
  res.on('data', d => (chunk += d));
  res.on('end', () => console.log(chunk));
});
req.end();

运行 node index.js，首次看到 JSON 余额返回即宣告调通。

FAQ #3：报文提示「TIME_ERROR」怎么办？

核对本机时间，并在 Response Header 中读 Date 字段，反向验证本地 NTP 同步。

FAQ #4：能否用 Java / Python？

思路完全一样，只需本地实现 HMAC-SHA256 + Base64。👉 查看各语言 SDK 代码合集，无品牌限制。

防盗指南与安全最佳实践

为保证你的 数字资产 与 业务数据 不被滥用：

务必给不同环境（测试、正式）配置不同密钥。
将 secretKey 写入 .env 或云端凭据管理，绝不进代码仓库。
最小权限原则：只勾选需要的接口权限。
定期轮换密钥并检视访问日志。

FAQ #5：正式环境应关闭哪些权限？

除必要的查询与转账权限外，撤销提币接口可降低风险。

结语

打通 REST API 鉴权 是 Web3 世界的第一步。跟着本文的时间戳计算、签名生成、Postman 调试和 JavaScript 单文件，你就能丝滑完成接入。下一步，就去挑战更酷的智能合约交互吧！祝你链上无阻，代码常青。