回调请求和响应格式

即刻安装 Cobo WaaS Skill，在 Claude Code、Cursor 等 AI 开发环境中使用自然语言集成 WaaS API，显著提升开发效率 🚀

本文档规定了 TSS Node Callback服务器通信中使用的请求和响应 Payload 格式。

回调请求

回调请求由 TSS Node发送到回调服务器。

基本请求结构

字段	类型	描述
request_id	`string`	回调请求的唯一 ID。
request_type	`int`	回调请求的类型： - `TypePing` (0)：用于心跳监控 - `TypeKeyGen` (1)：为您的 MPC 钱包创建新的私钥分片 - `TypeKeySign` (2)：签署交易或消息 - `TypeKeyReshare` (3)：在参与者之间重新分配私钥分片。
request_detail	`string`	特定于请求类型的详细信息。结构根据请求类型而变化。内容是 JSON 序列化的字符串。
extra_info	`string`	额外的上下文信息。结构根据请求类型而变化。内容是 JSON 序列化的字符串。

TypePing 请求

用于回调服务器的心跳监控。如果您在配置 TSS Node设置时指定了 monitor_interval 参数，节点将定期发送请求以验证服务器可用性。

callback:
  monitor_interval: 1h # 监控间隔；如果为空，则禁用监控

对于 TypePing 请求，request_id、request_detail 和 extra_info 将是空对象。

TypeKeyGen 请求

用于私钥分片生成。

request_detail

字段	类型	描述
threshold	`int`	此私钥分片持有者组中需要批准操作的私钥分片持有者数量。
node_ids	`array[string]`	此私钥分片持有者组中私钥分片持有者的 TSS Node ID。
curve	`int`	根扩展公钥的椭圆曲线类型。可能的值： `0`：Secp256k1 `2`：Ed25519。
task_id	`string`	此密钥生成任务的唯一标识符。
biz_task_id	`string`	对于此请求类型，此字段包含 TSS 请求 ID。

extra_info

字段	类型	描述
org	`object`	组织信息： - `org_id`：字符串。组织的 ID。 - `name`：字符串。组织名称。 - `created_timestamp`：整数。组织的创建时间，以毫秒为单位的 Unix 时间戳格式。
project	`object`	项目信息。详情请参阅获取项目信息操作的响应。
vault	`object`	Vault信息。详情请参阅获取Vault信息操作的响应。
target_key_share_holder_group	`object`	私钥分片持有者组信息。详情请参阅获取私钥分片持有者组信息操作的响应。
tss_request	`object`	TSS 请求信息。详情请参阅获取 TSS 请求操作的响应。

TypeKeySign 请求

用于交易或消息签名操作。

request_detail

字段	类型	描述
group_id	`string`	TSS 私钥分片组 ID。
root_pub_key	`string`	该组的根扩展公钥。
used_node_ids	`array[string]`	参与签名的 TSS Node ID 列表。
bip32_path_list	`array[string]`	BIP32 派生路径。
msg_hash_list	`array[string]`	要签名的消息哈希列表。
tweak_list	`array[string]`	要应用的调整列表。
signature_type	`int`	要生成的签名类型。可能的值： - `1`：ECDSA 签名 - `2`：EdDSA 签名 - `3`：Schnorr 签名
tss_protocol	`int`	TSS 协议。可能的值： - `1`：GG18 - `2`：Lindell - `3`：EddsaTSS
task_id	`string`	此签名任务的唯一标识符。
biz_task_id	`string`	对于此请求类型，此字段包含交易 ID。

extra_info

字段	类型	描述
org	`object`	组织信息： - `org_id`：字符串。组织的 ID。 - `name`：字符串。组织名称。 - `created_timestamp`：整数。组织的创建时间，以毫秒为单位的 Unix 时间戳格式。
project	`object`	项目信息。详情请参阅获取项目信息操作的响应。
vault	`object`	Vault信息。详情请参阅获取Vault信息操作的响应。
wallet	`object`	钱包信息。详情请参阅获取钱包信息操作的响应。
signer_key_share_holder_group	`object`	签署交易的私钥分片持有者组的信息。详情请参阅获取私钥分片持有者组信息操作的响应。
source_addresses	`array[object]`	交易源地址的信息。详情请参阅列出钱包地址操作的响应。
transaction	`object`	要签名的交易信息。详情请参阅获取交易信息操作的响应。

transaction 对象包含一个 initiator_type 字段，用于标识交易的发起方式，因此您的回调服务器可以区分交易，例如区分通过 API 发起的交易和通过 App 发起的交易。可能的值为 API（通过 WaaS API 发起）、Web（通过 Cobo Portal 发起）、App（通过 Cobo Portal Apps 发起）和 External（在 Cobo 之外发起）。有关完整的交易结构，请参阅获取交易信息操作的响应。

TypeKeyReshare 请求

用于密钥reshare操作。reshare意味着使用现有的私钥分片持有者组为新组生成私钥分片。

request_detail

字段	类型	描述
old_group_id	`string`	现有 TSS 私钥分片组的 ID。
root_pub_key	`string`	Vault的根扩展公钥。
curve	`int`	根扩展公钥的椭圆曲线类型。 `0`：Secp256k1 `2`：Ed25519。
used_node_ids	`array[string]`	现有私钥分片持有者组的 TSS Node ID。
old_threshold	`int`	使用的现有私钥分片持有者组的阈值。
new_threshold	`int`	新私钥分片持有者组的阈值。
new_node_ids	`array[string]`	新私钥分片持有者组的 TSS Node ID。
task_id	`string`	此reshare任务的唯一标识符。
biz_task_id	`string`	对于此请求类型，此字段包含 TSS 请求 ID。

extra_info

字段	类型	描述
org	`object`	组织信息： - `org_id`：字符串。组织的 ID。 - `name`：字符串。组织名称。 - `created_timestamp`：整数。组织的创建时间，以毫秒为单位的 Unix 时间戳格式。
project	`object`	项目信息。详情请参阅获取项目信息操作的响应。
vault	`object`	Vault信息。详情请参阅获取Vault信息操作的响应。
source_key_share_holder_group	`object`	现有私钥分片持有者组的信息。详情请参阅获取私钥分片持有者组信息操作的响应。
target_key_share_holder_group	`object`	新私钥分片持有者组的信息。详情请参阅获取私钥分片持有者组信息操作的响应。
tss_request	`object`	TSS 请求信息。详情请参阅获取 TSS 请求操作的响应。

回调响应

您的回调服务器必须使用以下结构响应所有回调请求：

字段	类型	描述
status	`int`	响应状态码。`0` 表示成功。任何其他值表示在回调服务器处理请求时发生错误。
request_id	`string`	回调请求的唯一 ID。
action	`string`	要采取的操作。可能的值： - `APPROVE`：批准请求并继续操作 - `REJECT`：拒绝请求并停止操作
error	`string`	错误消息： - 当 `status` 不为 `0` 时：包含回调服务器的内部错误消息。 - 当 `status` 为 `0` 且 action 为 `REJECT` 时：包含拒绝的具体原因。

HTTP 响应要求

上述回调响应是 HTTP 响应的 JSON 包体。请使用 HTTP 200（OK）状态码返回您的响应，并将包体中的 status 字段设置为 0，以表明您的回调服务器已成功处理该回调。 HTTP 状态码和包体中的 status 字段是不同的：HTTP 状态码表示 HTTP 请求是否到达并由您的回调服务器处理，而包体中的 status 字段表示回调的处理结果——值为 0 表示成功，任何其他值表示回调服务器在处理请求时发生了错误。

示例

// 来自 TSS Node 的回调请求（TypeKeySign）
{
  "request_id": "f1e2d3c4b5a6",
  "request_type": 2,
  "request_detail": "{...}",
  "extra_info": "{...}"
}

// 回调响应（HTTP 状态码 200）
{
  "status": 0,
  "request_id": "f1e2d3c4b5a6",
  "action": "APPROVE",
  "error": ""
}

重要说明

如果 TSS Node未能收到 HTTP 响应，它将重试回调请求。
超过最大重试次数后，风险控制结果将被设置为 REJECT。
对于 TypePing 请求，需要成功响应（status = 0）以表明服务器可用。

概述

快速开始

Webhooks 和 Callbacks

交易

MPC 钱包

资源文档

回调请求和响应格式

回调请求

基本请求结构

TypePing 请求

TypeKeyGen 请求

request_detail

extra_info

TypeKeySign 请求

request_detail

extra_info

TypeKeyReshare 请求

request_detail

extra_info

回调响应

HTTP 响应要求

示例

重要说明

​回调请求

​基本请求结构

​TypePing 请求

​TypeKeyGen 请求

​request_detail

​extra_info

​TypeKeySign 请求

​request_detail

​extra_info

​TypeKeyReshare 请求

​request_detail

​extra_info

​回调响应

​HTTP 响应要求

​示例

​重要说明

回调请求

基本请求结构

TypePing 请求

TypeKeyGen 请求

request_detail

extra_info

TypeKeySign 请求

request_detail

extra_info

TypeKeyReshare 请求

request_detail

extra_info

回调响应

HTTP 响应要求

示例

重要说明