Start Change Owner Process

Starts a node ownership change on one setup of the node: every tokenized asset deployed under the setup is transferred to the wallet you select, then the owner address on the setup's diamond is changed to it. The call only creates the process; the steps run asynchronously, one on-chain transaction each. Poll Get Change Owner Process to follow it. See the overview for the lifecycle.

Only the platform owner's API key may call this endpoint; any other key gets 403. The setup must belong to the node, and the new wallet must be a wallet of the same node, on the setup's chain, with a different address from the setup's current owner wallet. Only one unfinished process may exist per setup.

Required permission: node:change-owner

Request

POST /v2/admin/nodes/{node_id}/change-owner-processes

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 to change ownership on. 24-character hex id; must belong to `node_id`.
`new_wallet_id`	string	Yes	The node wallet that becomes the new owner. Must be owned by `node_id`, be on the chain of the setup's network, and have a different address from the setup's current owner wallet.

Example

curl --request POST \
  --url '{{baseUrl}}/v2/admin/nodes/6901350deb7ed8c1c38de4e9/change-owner-processes' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "setup_id": "6905f1c2a8e4b27d3c9a1f42",
    "new_wallet_id": "6a89b68e0c46ca4c941271aa"
  }'

Response

201 Created

{
  "id": "6907a4e1b5c83f2d9e6a0b17",
  "node_id": "6901350deb7ed8c1c38de4e9",
  "setup_id": "6905f1c2a8e4b27d3c9a1f42",
  "network_id": "68fe7b31c2d94a5e8b1f0c63",
  "old_owner_address": "0xecE2c86490b1214035cb1bbcC9781aE45d29BB97",
  "new_wallet_id": "6a89b68e0c46ca4c941271aa",
  "new_owner_address": "0xa112983907944387B64ba512daF256B3f28f93f5",
  "status": "started",
  "current_step_order": 0,
  "total_steps": 3,
  "progress": 0,
  "steps": [
    {
      "id": "6907a4e1b5c83f2d9e6a0b18",
      "type": "transfer_tokenized_assets",
      "status": "pending",
      "order": 1,
      "token_id": "67d8774e903bfcbe7eb5d93e",
      "transaction_hash": null,
      "retry_count": 0,
      "max_retries": 3,
      "error": null,
      "started_at": null,
      "completed_at": null
    },
    {
      "id": "6907a4e1b5c83f2d9e6a0b19",
      "type": "transfer_tokenized_assets",
      "status": "pending",
      "order": 2,
      "token_id": "67e1a2b3c4d5e6f708192a3b",
      "transaction_hash": null,
      "retry_count": 0,
      "max_retries": 3,
      "error": null,
      "started_at": null,
      "completed_at": null
    },
    {
      "id": "6907a4e1b5c83f2d9e6a0b1a",
      "type": "change_node_owner",
      "status": "pending",
      "order": 3,
      "token_id": null,
      "transaction_hash": null,
      "retry_count": 0,
      "max_retries": 3,
      "error": null,
      "started_at": null,
      "completed_at": null
    }
  ],
  "error": null,
  "created_at": "2026-11-02T09:14:27.512Z",
  "updated_at": "2026-11-02T09:14:27.512Z",
  "completed_at": null
}

Response Fields

Field	Type	Description
`id`	string	Process id
`node_id`	string	The node that owns the setup
`setup_id`	string	The setup the change runs on
`network_id`	string	The setup's network
`old_owner_address`	string	Address of the setup's current owner wallet, the one being replaced
`new_wallet_id`	string	The wallet selected as new owner
`new_owner_address`	string	Address of the new owner wallet
`status`	string	Process status: `started`, `in_progress`, `paused`, `completed`, `failed`, `cancelled`. See the overview.
`current_step_order`	integer	`order` of the step being executed; `0` before the first step is sent
`total_steps`	integer	Number of steps: one per tokenized asset plus the final owner change
`progress`	number	Percentage (`0`–`100`) of steps that are `completed` or `skipped`
`steps`	array	The steps, in `order`
`steps[].id`	string	Step id
`steps[].type`	string	`transfer_tokenized_assets` or `change_node_owner`
`steps[].status`	string	`pending`, `in_progress`, `completed`, `failed`, `skipped`
`steps[].order`	integer	Position of the step, starting at 1. Pass it as `step_order` to retry.
`steps[].token_id`	string \| null	The token a transfer step moves; `null` for `change_node_owner`
`steps[].transaction_hash`	string \| null	Hash of the confirmed transaction
`steps[].retry_count`	integer	How many times the step was retried
`steps[].max_retries`	integer	Retry limit of the step (`3`)
`steps[].error`	string \| null	Why the step failed
`steps[].started_at`	string \| null	When the step was sent
`steps[].completed_at`	string \| null	When the step completed
`error`	string \| null	Process-level error. Step failures are reported on the step.
`created_at`	string	ISO 8601 creation time
`updated_at`	string	ISO 8601 time of the last change
`completed_at`	string \| null	When the process completed

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's current owner wallet or its network is not found, the new wallet is not found, does not belong to the node, is not on the setup's chain, or is already the setup's owner. `message` says which.
400	`10016`	`new_wallet_id` is not a valid id
400	`10001`	Node not found
400	`20002`	A process that is not finished (`started`, `in_progress` or `paused`) already exists for this setup
403	`10005`	The API key does not belong to the platform owner

See Errors for the error format and common codes.

Request​

Parameters​

Headers​

Body​

Example​

Response​

Response Fields​

Errors​