Skip to main content
本文介绍如何对 Cobo 支付服务的 API 请求进行身份验证。 为确保您加密资产的安全访问，Cobo 支付服务要求您使用 EdDSA 签名对每个 API 请求进行签名（可公开访问的 API 操作除外）。 您需要在请求头中提供 API Key、随机数和 API 签名： 
headers = {
  "Biz-Api-Key": {YOUR_API_KEY}.hex(),
  "Biz-Api-Nonce": {Nonce},
  "Biz-Api-Signature": {YOUR_API_SIGNATURE}.hex(),
}
  • Biz-Api-Key：用于请求的 API Key。更多详情，请参阅 API Key。
  • Biz-Api-Nonce：随机数。随机数是以毫秒为单位的当前 Unix 时间戳。
  • Biz-Api-Signature：API 签名。要了解如何计算 API 签名，请参阅计算 API 签名。
如果您使用 Cobo 的 Payments API SDK，您只需提供 API Secret，因为 SDK 会为您处理其余步骤。

​
API Key 和 API Secret

为了实现客户端与 Cobo 支付服务之间的安全通信和身份认证，我们使用了 API Key 和 API Secret 机制。该机制依赖于加密密钥对来验证客户端的身份和请求的完整性。

​
API Key

API Key 是加密密钥对中的公钥。它用于识别发起 API 请求的客户端。

​
API Secret

API Secret 是密钥对中的私钥。它用于签署 API 请求，保证其真实性和完整性。API Secret 是高度敏感的数据，请务必妥善保管并采取严格的安全措施。 API Key 和 API Secret 共同确保了客户端与 Cobo 支付服务端的通信安全：
  • API Key 包含在 API 请求中，使 Cobo 支付服务能够识别客户端。使用前您需要在 Cobo Portal 上注册 API Key。
  • API Secret 用于生成每个 API 请求的签名。Cobo 支付服务验证签名以确认请求的真实性和防止篡改。

​
生成 API Key 和 API Secret

本节介绍如何使用 Ed25519 算法生成 API Key 和 API Secret。您也可以使用其他支持 Ed25519 算法的工具进行生成。 公钥将用作 API Key，私钥将用作 API Secret。

​
使用 OpenSSL

在终端窗口中，运行以下 OpenSSL 命令生成 Ed25519 算法的密钥对： 
openssl genpkey -algorithm ed25519 -out private_key.pem

openssl pkey -in private_key.pem -pubout -out public_key.pem

echo "Private Key (Hex):"
openssl pkey -in private_key.pem -text | grep 'priv:' -A 3 | tail -n +2 | tr -d ':\n ' && echo

echo "Public Key (Hex):"
openssl pkey -pubin -in public_key.pem -text | grep 'pub:' -A 3 | tail -n +2 | tr -d ':\n ' && echo
您将看到类似以下示例的输出： 
Private Key (Hex):
06f78882576ec0e05b1e51a33548da7e8cf958c190ba96be77b1c671f98a2b5f
Public Key (Hex):
5987dedc180167b7ab1d27e6009e5065d10d764cd85d7b64f8c968ca40326e28
使用 Private Key (Hex) 作为您的 API Secret，使用 Public Key (Hex) 作为您的 API Key。

​
使用 Python 库

  1. 安装 PyNaCl Python 库。 在终端窗口中，运行以下命令： 
    pip install PyNaCl
  2. 生成密钥对。 从 Python 库导入函数生成基于 Ed25519 算法的密钥对，如下所示： 
    from nacl.signing import SigningKey
# 创建密钥对。
sk = SigningKey.generate()
# 打印十六进制格式的私钥
print("私钥:", sk.encode().hex())
# 打印十六进制格式的公钥
print("公钥:", sk.verify_key.encode().hex())

​
注册 API Key

生成 API Key 后，您需要在 Cobo Portal 上注册密钥。要了解如何注册 API Key，请参阅发送您的第一个 API 请求。

​
随机数

随机数为 Unix 时间戳格式的当前时间，以毫秒为单位。

​
计算 API 签名

以下步骤介绍如何计算 API 签名。
  1. 首先，基于您的请求拼接出一个字符串，如下所示： str_to_sign = {METHOD}|{PATH}|{TIMESTAMP}|{PARAMS}|{BODY}
    字段描述示例
    METHODHTTP 方法。GET
    PATHAPI 端点。/v2/payments/topup/address
    TIMESTAMP以毫秒为单位的当前 Unix 时间戳。该值必须与请求头中的随机数相同。1718587017026
    PARAMS（如有）查询参数。chain_id=ETH&limit=10
    BODY（如有）原始请求包体的字符串格式。{"name":"Default","wallet_subtype":"Asset","wallet_type":"Custodial"}
  2. 使用 hashlib 库对字符串进行两次 SHA-256 哈希，如下所示： 
    import hashlib
content_hash = hashlib.sha256(hashlib.sha256(str_to_sign.encode()).digest()).digest()
  3. 使用 API Secret 对字符串进行签名，如下所示： 
    from nacl.signing import SigningKey

# 创建 Ed25519 签名密钥。将 `api_secret` 替换为您的 API Secret
sk = SigningKey(bytes.fromhex(api_secret))
# 签署哈希后的消息
signature = sk.sign(content_hash).signature.hex()
现在您已经计算出了一个 API 签名。