Add Token Blacklist Group
Attaches a KYC group to a token's blacklist.
Asynchronous: the attachment is recorded at once and shows up in List Token Blacklist Groups, and the on-chain call is queued. It is recorded as a node transaction of type 53 (AddKycGroupToBlacklist) on the platform owner node, with internal_id set to the attachment's id; see Asynchronous writes.
The chain identifies the group by its numeric group_id on the KYC token of the setup you name, so attach only a group that lives on that KYC token: the API checks that the group exists, not where it lives. Group ids come from List KYC Groups, which only the platform owner node can read.
Pass the token's own setup_id (from Get Token): the call runs on the KYC token that setup is wired to and is signed by that KYC token's owner wallet. Your node must be the token's node or one of its ancestors.
Required permission: kyc:token:blacklist-group:create
Request
POST /v2/admin/tokens/{token_id}/kyc/blacklist/groups/{group_id}
Parameters
| Name | Type | In | Description |
|---|---|---|---|
token_id | string | path | Required. The asset token's id |
group_id | string | path | Required. The KYC group's id (24-character hex), not its numeric group_id |
Headers
| Name | Description |
|---|---|
Authorization | Required. Bearer <access_token> |
Content-Type | Required. application/json |
Body
| Field | Type | Required | Description |
|---|---|---|---|
setup_id | string | Yes | The setup whose KYC token the group is attached on: the token's own setup_id |
Example
curl --request POST \
--url '{{baseUrl}}/v2/admin/tokens/68ae06cfcccf4e8fc19362d1/kyc/blacklist/groups/68d2e7a9c1b4f30045e1a9b2' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data '{
"setup_id": "68b1c2d3e4f5a6b7c8d9e0f1"
}'
Response
Status 201.
{
"requires_approval": false,
"completed": true
}
Response Fields
| Field | Type | Description |
|---|---|---|
requires_approval | boolean | Always false: KYC writes have no approval step |
completed | boolean | true once the request is accepted and the on-chain call is queued. It does not mean the chain has confirmed it |
Errors
| Status | Code | Description |
|---|---|---|
| 400 | 10015 | Validation failed — see details |
| 400 | 10016 | token_id is not a valid id |
| 400 | 10001 (domain 5) | Token not found |
| 403 | 10005 (domain 2) | The token belongs to a node outside your node's subtree |
| 400 | 20001001 | KYC group not found |
| 400 | 10015 | setup_id names no setup, or the setup has no network or no KYC token (message says which) |
| 500 | 10000 | The group is already attached to this list |
See Errors for the error format and common codes.