Create KYC Token
Creates a platform KYC token on a network and starts its deploy. The answer is the new token in status deploying.
Asynchronous: the deploy runs in two on-chain steps, the UUPS implementation and then the ERC1967 proxy. Poll List KYC Tokens with the same network_id until the token appears with its address. The catalog lists deployed tokens only, so a token whose deploy fails never appears there.
The wallet is chosen by the caller and never resolved: it must be one of the platform owner node's wallets on the network's chain. It signs both deploy steps and becomes the token's owner wallet, which signs every later group change and token rule on this KYC token. A custody provider must be active. Only the platform owner (root) node may call it.
Required permission: kyc:token:create
Request
POST /v2/admin/kyc-tokens
Headers
| Name | Description |
|---|---|
Authorization | Required. Bearer <access_token> |
Content-Type | Required. application/json |
Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Display name, shown wherever KYC tokens are listed. Surrounding spaces are trimmed |
network_id | string | Yes | The network to deploy on |
wallet_id | string | Yes | One of the platform owner node's wallets on the network's chain. It signs the deploy and becomes the token's owner wallet |
Example
curl --request POST \
--url '{{baseUrl}}/v2/admin/kyc-tokens' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data '{
"name": "Apex KYC Polygon",
"network_id": "68a1f0c2d4e5f60718293a4b",
"wallet_id": "68a2b3c4d5e6f708192a3b4c"
}'
Response
Status 201.
{
"id": "68c4a1f2b9e3d70012a5c3e8",
"name": "Apex KYC Polygon",
"network_id": "68a1f0c2d4e5f60718293a4b",
"wallet_id": "68a2b3c4d5e6f708192a3b4c",
"status": "deploying",
"address": "",
"impl_address": "",
"version": "",
"proxy_version": "",
"created_at": "2026-10-02T09:14:31.512Z"
}
Response Fields
| Field | Type | Description |
|---|---|---|
id | string | The KYC token's id: the kyc_token_id used by setups and KYC groups |
name | string | Display name |
network_id | string | The network the token is deployed on |
wallet_id | string | The token's owner wallet |
status | string | deploying, done or error; always deploying in this response |
address | string | The KYC token's address (its proxy). Empty until the proxy step confirms |
impl_address | string | The implementation's address. Empty until the implementation step confirms |
version | string | KYC token implementation version. Empty until the implementation step confirms |
proxy_version | string | Proxy contract version. Empty until the proxy step confirms |
deployed_at | string | When the deploy completed (ISO 8601). Absent until then |
created_at | string | When the token was created (ISO 8601) |
Errors
| Status | Code | Description |
|---|---|---|
| 400 | 10015 | Validation failed — see details. Also network not found when network_id names no network |
| 400 | 10016 | network_id or wallet_id is not a valid id |
| 403 | 10005 (domain 2) | Your node is not the platform owner (root) node |
| 400 | 10021 (domain 2) | wallet_id is not one of the platform owner node's wallets on the network's chain |
| 400 | 10028 (domain 2) | No custody provider is active, so the deploy cannot run |
See Errors for the error format and common codes.