Update User Wallet
Updates wallet information for a specific user by their ID. The user must have no existing token balances — if they hold any token, the endpoint returns 400 Bad Request with the "existing purchases" error.
After the wallet address change is persisted, the handler enqueues a SendKycToken (node transaction type 21) event so the user's KYC token is reissued to the new address. This last step is asynchronous: HTTP 200 means the wallet was updated in the database and the KYC reissue was queued — the on-chain transfer reaches Done later. The signature is verified against the user's _id (Mongo ObjectID hex) — sign that exact bytes payload with the new wallet's private key.
Request
PUT /v2/users/users/{user_id}/wallet
Parameters
| Name | Type | In | Description |
|---|---|---|---|
user_id | string | path | Required. The ID of the user whose wallet to update |
Headers
| Name | Description |
|---|---|
Authorization | Required. Bearer token for authentication |
Content-Type | Required. Must be application/json |
User-Agent | Optional. Client application identifier |
Request Body
| Field | Type | Description |
|---|---|---|
wallet_address | string | Required. The new wallet address |
signature | string | Required. Digital signature for verification |
Example
curl --request PUT \
--url '\{\{baseUrl\}\}/v2/users/users/680c02896d91ca0145cfeb81/wallet' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRJRCI6IjMxYzU4ZGI4LTQ4MmMtNDhiNS04Yzg0LTg4MDBjNzIwMDFhZCIsImV4cGlyYXRpb24iOjE3NTcwNzc0OTksInN1cGVydmlzb3JFbWFpbCI6InViZXJAYXBleC5jb20iLCJzdXBlcnZpc29ySUQiOiI2NjViMzcyZjNhNzJkN2QwNzkxNTk2YmEiLCJzdXBlcnZpc29yTm9kZUlEIjoiNjY1YWU1MzZhNjM5MmI3NWNmZDQwMzUyIiwic3VwZXJ2aXNvck5vZGVJbnRJRCI6MSwic3VwZXJ2aXNvck5vZGVQYXRoIjoiMSIsInN1cGVydmlzb3JSb2xlSUQiOiI2NjVhZTc5NjEwY2UyMTZkYmMzNWM5M2IiLCJzdXBlcnZpc29yUm9sZVByaW9yaXR5IjoxMDB9.BiBDnRfdsP-3MSMYR81sPeFXu7oqG-PtbPcEGGIB8Fo' \
--header 'Content-Type: application/json' \
--header 'User-Agent: insomnia/11.5.0' \
--data '{
"wallet_address": "0x111111111111111",
"signature": "123jfghea"
}'
Response
A successful response returns no content:
Status Code: 200 OK
Response Body: No content
Status Codes
| Status Code | Description |
|---|---|
| 200 | Success - User wallet information updated; KYC token reissue queued |
| 400 | Bad Request - Invalid request body, signature verification failed, or the user still holds tokens (cannot move wallet with non-zero balances) |
| 401 | Unauthorized - Invalid or missing authentication token |
| 404 | Not Found - User ID does not exist |
| 500 | Internal Server Error |
Polling
Track the queued KYC reissue via Get Node Transactions for the user's node — look for the most-recent SendKycToken (type 21) row and wait for status to reach Done (3) before assuming the new wallet is fully KYC-cleared.