Update Token

Updates a token's name, description, value, images, documents and oracle. The change is written to the token at once. Only one change reaches the chain: a new total_value on a token in status 6 (Listed). Then an UpdateToken transaction (type 5) is queued and its id is returned; poll it with Get Token Transaction By ID. Any other update answers "transaction_id": null and is complete when the call returns.

User-facing token reads show the latest token history snapshot. An off-chain update writes that snapshot immediately (change_reason: "offchain_update"); an on-chain one writes it only when the transaction settles ("contract_confirm"), so investors keep seeing the previous value until then.

Required permission: token:update

Request

PUT /v2/admin/tokens/{token_id}

Parameters

Name	Type	In	Description
token_id	string	path	Required. Token id.

Headers

Name	Description
Authorization	Required. Bearer <access_token>
Content-Type	Required. multipart/form-data. A JSON body is refused.

Body

Field	Type	Required	Description
name	string	Yes	Display name.
description	string	Yes	Description.
total_value	string	Yes, for a platform token	Value of the whole asset. The value fields are applied as sent: an omitted total_value is read as "0". Send the current value to keep it.
currency_token_id	string	Yes, for a platform token	Currency token of the value. An omitted one is refused (10016). On a change the amount is kept and expressed in the new currency; the change does not reach the chain on its own.
salable_percentage	string	Yes, for a platform token	Share offered for sale, "0" to "100", one decimal at most. An omitted one is read as "0".
images	file	No	New images to add. Up to 10, PNG, JPEG or GIF, each under 2 MB.
documents	file	No	New PDF documents to add. Up to 10, each under 2 MB. On a listed token with a deployed contract, each new document is also anchored on chain by its own AddDocumentToToken transaction (type 16); find them with List Token Transactions.
remove_image_ids	string	No	Id of an image to remove. Repeat the field for several. The token reads do not return image ids; take them from the latest token history snapshot (meta.images[].id).
remove_document_ids	string	No	Id of a document to remove (meta.documents[].id). Repeat the field for several.
oracle_id	string	No	Oracle to attach, together with oracle_code. Send it empty (oracle_id=) to detach the current oracle. Omit both to leave the oracle unchanged.
oracle_code	string	No	One of the oracle's integration codes.

For an external token (origin: 1) the value fields are ignored: only name, description, images, documents and oracle change, nothing reaches the chain and no history row is written.

The value is checked against the category's tokenization rules and against the token's current metric (see Errors). Amounts follow Amounts and Percentages.

Example

curl --request PUT \
  --url '{{baseUrl}}/v2/admin/tokens/67d8774e903bfcbe7eb5d93e' \
  --header 'Authorization: Bearer <access_token>' \
  --form 'name=TKN Token Name Updated' \
  --form 'description=Token Description' \
  --form total_value=15000 \
  --form currency_token_id=68fe8c129367fd414b227c7a \
  --form salable_percentage=80 \
  --form documents=@/path/to/valuation-report.pdf \
  --form remove_document_ids=67d8774e903bfcbe7eb5d940

Response

On-chain update (listed token, total_value changed):

{
  "transaction_id": "6a8b5e13f9129816a6cc7a12"
}

Off-chain update:

{
  "transaction_id": null
}

Response Fields

Field	Type	Description
transaction_id	string | null	The UpdateToken transaction when the update reaches the chain; null when it was applied off-chain only.

Errors

Status	Code	Description
400	10015	Validation failed — see details. Also returned for a malformed amount or percentage, a total_value with more decimals than the currency token, an oracle_code that is not one of the oracle's codes, an upload of 2 MB or more, or a body that is not multipart
400	10016	token_id, currency_token_id or oracle_id is not a valid id
400	10001	Token not found (token domain 5)
403	10005	The caller's node does not cover the token's node (node domain 2)
400	10015	The category requires salable_percentage to be 100 (token domain 5)
400	10016	The category requires max_supply to match total_value (token domain 5)
400	10017–10021	The token's current metric breaks a category rule (rental income range, payment period, purchase quantities, rental minimum) (token domain 5)
404	10001	Currency token not found (currency token domain 15)
400	10001	Oracle not found (oracle domain 5, message oracle not found)
400	10040	An uploaded file's type is not allowed (images: PNG, JPEG, GIF; documents: PDF)

See Errors for the error format and common codes.