签名认证¶
概述¶
每个对 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]}
参数格式规则
- 格式:
{paramName=[paramValue], paramName=[paramValue]} - 排序: 多个参数必须按参数名称的字母顺序排列
发起 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 个请求,否则您的请求将被限流。
需要帮助? 如果您在身份验证方面仍有问题,请联系我们的支持团队并提供您的请求详细信息。