Add to Whitelist
Adds one address to a token's whitelist.
Asynchronous: the rule is recorded at once and shows up in Get Token Whitelist, and the on-chain call is queued. It is recorded as a node transaction of type 42 (AddMemberToWhitelist) on the platform owner node, with internal_id set to the new rule's id; see Asynchronous writes.
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:whitelist:create
Request
POST /v2/admin/tokens/{token_id}/kyc/whitelist
Parameters
| Name | Type | In | Description |
|---|---|---|---|
token_id | string | path | Required. The asset token's 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 rule is written to: the token's own setup_id |
user_address | string | Yes | The wallet address to add. Stored exactly as sent; its format is not checked |
Example
curl --request POST \
--url '{{baseUrl}}/v2/admin/tokens/68ae06cfcccf4e8fc19362d1/kyc/whitelist' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data '{
"setup_id": "68b1c2d3e4f5a6b7c8d9e0f1",
"user_address": "0x1234567890123456789012345678901234567890"
}'
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 | 10015 | setup_id names no setup, or the setup has no network or no KYC token (message says which) |
| 500 | 10000 | The address is already on this list |
See Errors for the error format and common codes.