跳转至

签名认证

概述

每个对 Cactus Custody 的 API 请求都必须使用 SHA256 with ECDSA 签名进行身份验证。本指南将逐步指导您完成身份验证过程。

API 请求频率限制: 每秒 30 个请求

获取您的 API 凭证

生成密钥对

生成公私钥 ECDSA 密钥对(参考生成公私钥对)。

提交您的公钥

  • 以管理员身份登录
  • 导航至:人员管理 → 人员 → 公钥
  • 上传 PEM 格式的公钥文件
  • 您将通过电子邮件收到 AKID

获取您的 API Key

如需获取 API Key,请联系我们的团队。

准备您的 API 请求

在发出请求之前,请准备以下组件:

组件 描述 示例
请求方法 大写的 HTTP 方法 GET、POST、PUT
URI API 端点路径 /custody/v1/api/wallets
参数 查询字符串参数(如有) ?coin=BTC
x-api-nonce 唯一请求标识符 生成一个 UUID。可以使用您所用编程语言提供的内置库生成 UUID。
Date 时间戳必须反映 GMT 格式的当前时间;否则会发生错误 Tue, 03 Mar 2020 12:26:57 GMT

日期格式: 日期必须采用精确格式:EEE, dd MMM yyyy HH:mm:ss zzz 并使用 GMT+0 时区;否则将返回错误代码 10380002。

构建待签名内容

这是您将使用私钥签名的字符串。GET 和 POST 请求的格式有所不同。

格式

GET\n
application/json\n
\n
application/json\n
[GMT 日期]\n
x-api-key:[您的 API Key]\n
x-api-nonce:[您的 Nonce]\n
[URI]?{[排序后的参数]}

注意第二个 application/json 之后有一个空行(第 3 行为空)

示例

GET\n
application/json\n
\n
application/json\n
Tue, 03 Mar 2020 12:26:57 GMT\n
x-api-key:X5SGmgTAoYaVw1t7oD2p82pHgf0eNNVw3wxYGgM2\n
x-api-nonce:36dbe33ed529455cb0638eef0f5f59e3\n
/custody/v1/api/wallets?{b_id=[4a3e2fb40faa4b9d94480559ac01e8de], coin_names=[BTC,LTC], hide_no_coin_wallet=[false], total_market_order=[0]}

格式

POST\n
application/json\n
[请求体哈希]\n
application/json\n
[GMT 日期]\n
x-api-key:[您的 API 密钥]\n
x-api-nonce:[您的 Nonce]\n
[URI]

请求体哈希计算: Base64(SHA256(request_body))

示例

POST\n
application/json\n
3cLLd5MmUAMM2BneR7eT0NV9AZ4TUJ2F7xy31krmInQ=\n
application/json\n
Tue, 03 Mar 2020 13:26:57 GMT\n
x-api-key:X5SGmgTAoYaVw1t7oD2p82pHgf0eNNVw3wxYGgM2\n
x-api-nonce:36dbe33ed529455cb0638eef0f5f59e3\n
/custody/v1/api/projects/4a3e2fb40faa4b9d94480559ac01e8de/order/create

参数格式规则

  • 格式: {paramName=[paramValue], paramName=[paramValue]}
  • 排序: 多个参数必须按参数名称的字母顺序排列

生成签名

签名内容

使用您的私钥对"待签名内容"字符串进行签名:

签名 = Base64(SHA256withECDSA(ContentToSign))

构建授权标头

按以下格式组合您的凭证:

api [AKId]:[签名]

示例:

api e4c9f9024bff472cba51cb2a9fe0f974:MEUCIQCOWdpspTVI0KlkZNPwHTr8JAdo0tBtLeg6I9aeqRr4+QIgeXfCgrqhLkyXAjh21NcP1AHXH9V4a3bTl+GaevmbQyo=

发起 API 请求

GET 请求头

{
    "x-api-key": "H12q1kJRfa341wajqyZ6ya6cm9ZtOJaq3DXWJTb4",
    "x-api-nonce": "59ae8151fb5949d5ac3e35e919e26265",
    "Accept": "application/json",
    "Date": "Tue, 03 Mar 2020 12:26:57 GMT",
    "Content-type": "application/json",
    "Authorization": "api e4c9f9024bff472cba51cb2a9fe0f974:MEUCIQCOWdpspTVI0KlkZNPwHTr8JAdo0tBtLeg6I9aeqRr4+QIgeXfCgrqhLkyXAjh21NcP1AHXH9V4a3bTl+GaevmbQyo="
}

POST 请求头

{
    "x-api-key": "H12q1kJRfa341wajqyZ6ya6cm9ZtOJaq3DXWJTb4",
    "x-api-nonce": "59ae8151fb5949d5ac3e35e919e26265",
    "Accept": "application/json",
    "Content-SHA256": "l5lLhZ9tlS/bnbPa2LUTkki5cFVQ3n9+4Imtkmaoz6U=",
    "Date": "Tue, 03 Mar 2020 12:26:57 GMT",
    "Content-type": "application/json",
    "Authorization": "api e4c9f9024bff472cba51cb2a9fe0f974:MEUCIQCOWdpspTVI0KlkZNPwHTr8JAdo0tBtLeg6I9aeqRr4+QIgeXfCgrqhLkyXAjh21NcP1AHXH9V4a3bTl+GaevmbQyo="
}

请求头字段参考

请求头 必需用于 描述
x-api-key 所有请求 您的 API Key
x-api-nonce 所有请求 唯一请求 ID(使用 UUID)
Accept 所有请求 始终为 "application/json"
Date 所有请求 GMT 时间戳
Content-type 所有请求 始终为 "application/json"
Content-SHA256 仅 POST/PUT Base64(SHA256(请求体))
Authorization 所有请求 api [AKId]:[签名]

常见错误

注意这些常见错误:

换行符是真实的换行符

"待签名内容"中的 \n 是实际的换行符,而不是字面字符串 "\n"。确保您的代码正确解释它们。

参数必须按字母顺序排序

URL 参数必须按参数名称的字母顺序排序。顺序对签名验证很重要!

GET 请求有一个空行

注意 GET 请求中 "application/json" 后面的空行(第 3 行)。POST 请求在该位置使用请求体哈希。

日期格式必须完全匹配

日期必须遵循格式:EEE, dd MMM yyyy HH:mm:ss zzz。即使是微小的变化也会导致身份验证失败。请注意,时间格式必须为 GMT +0。

请求频率限制

不要超过每秒 30 个请求,否则您的请求将被限流。

需要帮助? 如果您在身份验证方面仍有问题,请联系我们的支持团队并提供您的请求详细信息。