Start Platform Owner Change
Replaces the platform owner address on one setup's diamond with one of the platform owner's own wallets. This is a single on-chain transaction, recorded as a node transaction of type 35 (ChangePlatformOwnerAddress) on the platform owner node; it is asynchronous and answered with status in_progress. Poll List Platform Owner Changes until the change reads done or error. When it is done, the setup's platform owner fee-recipient wallet points at the new wallet.
Only the platform owner's API key may call this endpoint; any other key gets 403. The setup must belong to the node and must have been created while the platform setting platform_owner_can_change_wallet was on: each setup keeps the value it was created with, and that copy is what is checked (see Update Platform Owner Can Change Wallet). Only one change may run on a setup at a time.
Required permission: node:change-platform-owner
Request
POST /v2/admin/nodes/{node_id}/platform-owner-changes
Parameters
| Name | Type | In | Description |
|---|---|---|---|
node_id | string | path | Required. The node that owns the setup |
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 diamond gets the new platform owner. 24-character hex id; must belong to node_id. |
new_wallet_id | string | Yes | The new platform owner wallet. Must be a wallet of the platform owner (root) node, on the chain of the setup's network. |
Example
curl --request POST \
--url '{{baseUrl}}/v2/admin/nodes/6901350deb7ed8c1c38de4e9/platform-owner-changes' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data '{
"setup_id": "6905f1c2a8e4b27d3c9a1f42",
"new_wallet_id": "6907b0d3e2f1a4c5b6d7e8f9"
}'
Response
201 Created
{
"id": "6907b2c4d1e8f93a5b7c0d21",
"node_id": "665ae536a6392b75cfd40352",
"setup_id": "6905f1c2a8e4b27d3c9a1f42",
"status": "in_progress",
"new_owner_address": "0x7De3a0B5C2f4E6d8A1b3C5e7F9a2B4d6E8f0A1c3",
"hash": null,
"error": null,
"created_at": "2026-11-03T13:02:44.190Z",
"updated_at": "2026-11-03T13:02:44.236Z"
}
Response Fields
| Field | Type | Description |
|---|---|---|
id | string | Id of the platform owner change |
node_id | string | The platform owner (root) node the change is attributed to, not the node in the path |
setup_id | string | The setup the change runs on |
status | string | started, in_progress, done or error. A new change is answered in_progress. |
new_owner_address | string | Address of the new platform owner wallet |
hash | string | null | Transaction hash, set once the change is done |
error | string | null | Why the change failed, when error |
created_at | string | ISO 8601 creation time |
updated_at | string | ISO 8601 time of the last change |
Errors
| Status | Code | Description |
|---|---|---|
| 400 | 10015 | Validation failed (missing setup_id or new_wallet_id, setup_id not a 24-character hex id), or the request was refused: the setup is not found on this node, the setup does not allow the platform owner to change its wallet, the root node or the setup's network is not found, the new wallet is not found, is not a platform owner wallet, or is not on the setup's chain. message says which. |
| 400 | 10016 | new_wallet_id is not a valid id |
| 400 | 10001 | Node not found |
| 400 | 21002 | A platform owner change is already started or in_progress on this setup |
| 403 | 10005 | The API key does not belong to the platform owner |
See Errors for the error format and common codes.