> ## Documentation Index
> Fetch the complete documentation index at: https://cobo.com/developers/llms.txt
> Use this file to discover all available pages before exploring further.
# Callback request and response formats
> Detailed specifications of the payload formats used in TSS Node callback server interaction
Try [Cobo WaaS Skill](/v2/guides/overview/cobo-waas-skill) in your AI coding assistant (Claude Code, Cursor, etc.). Describe your needs in natural language to auto-generate production-ready SDK code and debug faster 🚀
This document specifies the request and response payload formats used in TSS Node callback server communication.
## Callback request
The callback request is sent from the TSS Node to the callback server.
### Base request structure
| Field | Type | Description |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| request\_id | `string` | The unique ID of the callback request. |
| request\_type | `int` | Type of the callback request:
- `TypePing` (0): Used for heartbeat monitoring
- `TypeKeyGen` (1): Creating new key shares for your MPC Wallets.
- `TypeKeySign` (2): Signing transactions or messages.
- `TypeKeyReshare` (3): Redistributing key shares among participants. |
| request\_detail | `string` | Details specific to the request type. The structure varies depending on the request type. The content is a JSON-serialized string. |
| extra\_info | `string` | Additional contextual information. The structure varies depending on the request type. The content is a JSON-serialized string. |
### TypePing request
Used for heartbeat monitoring of the callback server.
If you have specified the `monitor_interval` parameter when [configuring the TSS Node settings](/v2/guides/mpc-wallets/server-co-signer/callback-server-configure#configure-tss-node-settings), the node will periodically send the request to verify server availability.
```yaml theme={null}
callback:
monitor_interval: 1h # Monitoring interval; if empty, monitoring is disabled
```
For `TypePing` requests, `request_id`, `request_detail` and `extra_info` will be empty objects.
### TypeKeyGen request
Used for key share generation.
#### request\_detail
| Field | Type | Description |
| ------------- | --------------- | ----------------------------------------------------------------------------------------------------------------- |
| threshold | `int` | The number of key share holders required to approve operations in this key share holder group. |
| node\_ids | `array[string]` | The TSS Node IDs of the key share holders in this key share holder group. |
| curve | `int` | The elliptic curve type of the root extended public key. Possible values:
`0`: Secp256k1
`2`: Ed25519. |
| task\_id | `string` | The unique identifier for this key generation task. |
| biz\_task\_id | `string` | For this request type, this field contains the TSS request ID. |
#### extra\_info
| Field | Type | Description |
| --------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| org | `object` | The organization information:
- `org_id`: String. The ID of the organization.
- `name`: String. The organization name.
- `created_timestamp`: Int. The organization's creation time in Unix timestamp format, measured in milliseconds. |
| project | `object` | The project information. For details, see the response of the [Get project information](/v2/api-references/wallets--mpc-wallets/get-project-information) operation. |
| vault | `object` | The vault information. For details, see the response of the [Get vault information](/v2/api-references/wallets--mpc-wallets/get-vault-information) operation. |
| target\_key\_share\_holder\_group | `object` | The key share holder group information. For details, see the response of the [Get key share holder group information](/v2/api-references/wallets--mpc-wallets/get-key-share-holder-group-information) operation. |
| tss\_request | `object` | The TSS request information. For details, see the response of the [Get TSS request](/v2/api-references/wallets--mpc-wallets/get-tss-request) operation. |
### TypeKeySign request
Used for transaction or message signing operations.
#### request\_detail
| Field | Type | Description |
| ----------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| group\_id | `string` | The ID of the TSS key share group. |
| root\_pub\_key | `string` | The root extended public key of the group. |
| used\_node\_ids | `array[string]` | The list of TSS Node IDs participating in signing. |
| bip32\_path\_list | `array[string]` | The BIP32 derivation paths. |
| msg\_hash\_list | `array[string]` | The list of message hashes to sign. |
| tweak\_list | `array[string]` | The list of tweaks to apply. |
| signature\_type | `int` | The type of signature to generate. Possible values:
- `1`: ECDSA signature
- `2`: EdDSA signature
- `3`: Schnorr signature |
| tss\_protocol | `int` | The TSS protocol. Possible values:
- `1`: GG18
- `2`: Lindell
- `3`: EddsaTSS |
| task\_id | `string` | The unique identifier for this signing task. |
| biz\_task\_id | `string` | For this request type, this field contains the transaction ID. |
#### extra\_info
| Field | Type | Description |
| --------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| org | `object` | The organization information:
- `org_id`: String. The ID of the organization.
- `name`: String. The organization name.
- `created_timestamp`: Int. The organization's creation time in Unix timestamp format, measured in milliseconds. |
| project | `object` | The project information. For details, see the response of the [Get project information](/v2/api-references/wallets--mpc-wallets/get-project-information) operation. |
| vault | `object` | The vault information. For details, see the response of the [Get vault information](/v2/api-references/wallets--mpc-wallets/get-vault-information) operation. |
| wallet | `object` | The wallet information. For details, see the response of the [Get wallet information](/v2/api-references/wallets/get-wallet-information) operation. |
| signer\_key\_share\_holder\_group | `object` | The information of the key share holder group that signs the transaction. For details, see the response of the [Get key share holder group information](/v2/api-references/wallets--mpc-wallets/get-key-share-holder-group-information) operation. |
| source\_addresses | `array[object]` | The information of the source addresses of the transaction. For details, see the response of the [List wallet addresses](/v2/api-references/wallets/list-wallet-addresses) operation. |
| transaction | `object` | The information of the transaction to sign. For details, see the response of the [Get transaction information](/v2/api-references/transactions/get-transaction-information) operation. |
### TypeKeyReshare request
Used for [key resharing](https://manuals.cobo.com/en/portal/mpc-wallets/ocw/manage-key-share-groups#manage-recovery-groups) operations. Resharing means to use an existing key share holder group to generate key shares for a new group.
#### request\_detail
| Field | Type | Description |
| --------------- | --------------- | ------------------------------------------------------------------------------------------------ |
| old\_group\_id | `string` | The ID of the existing TSS key share group. |
| root\_pub\_key | `string` | The root extended public key of the vault. |
| curve | `int` | The elliptic curve type of the root extended public key.
`0`: Secp256k1
`2`: Ed25519. |
| used\_node\_ids | `array[string]` | The TSS Node IDs of the existing key share holder group. |
| old\_threshold | `int` | The threshold value of the existing key share holder group used. |
| new\_threshold | `int` | The threshold value of the new key share holder group. |
| new\_node\_ids | `array[string]` | The TSS Node IDs of the new key share holder group. |
| task\_id | `string` | The unique identifier for this resharing task. |
| biz\_task\_id | `string` | For this request type, this field contains the TSS request ID. |
#### extra\_info
| Field | Type | Description |
| --------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| org | `object` | The organization information:
- `org_id`: String. The ID of the organization.
- `name`: String. The organization name.
- `created_timestamp`: Int. The organization's creation time in Unix timestamp format, measured in milliseconds. |
| project | `object` | The project information. For details, see the response of the [Get project information](/v2/api-references/wallets--mpc-wallets/get-project-information) operation. |
| vault | `object` | The vault information. For details, see the response of the [Get vault information](/v2/api-references/wallets--mpc-wallets/get-vault-information) operation. |
| source\_key\_share\_holder\_group | `object` | The information of the existing key share holder group. For details, see the response of the [Get key share holder group information](/v2/api-references/wallets--mpc-wallets/get-key-share-holder-group-information) operation. |
| target\_key\_share\_holder\_group | `object` | The information of the new key share holder group. For details, see the response of the [Get key share holder group information](/v2/api-references/wallets--mpc-wallets/get-key-share-holder-group-information) operation. |
| tss\_request | `object` | The TSS request information. For details, see the response of the [Get TSS request](/v2/api-references/wallets--mpc-wallets/get-tss-request) operation. |
## Callback response
Your callback server must respond to all callback requests with the following structure:
| Field | Type | Description |
| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| status | `int` | The response status code. `0` indicates success. Any other value indicates that an error occurred while processing the request in the callback server. |
| request\_id | `string` | The unique ID of the callback request. |
| action | `string` | Action to take. Possible values:
- `APPROVE`: Approve the request and proceed with the operation
- `REJECT`: Deny the request and stop the operation |
| error | `string` | The error message:
- When `status` is not `0`: Contains internal error messages from the callback server.
- When `status` is `0` and action is `REJECT`: Contains the specific reason for the rejection. |
### Important notes
* If the TSS Node fails to receive an HTTP response, it will retry the callback request.
* After exceeding the maximum retry attempts, the risk control result will be set to `REJECT`.