Update Token

Updates an existing token's value/metadata. The integration splits updates into two branches based on which fields changed:

• On-chain branch — fires only when the token's status = listed and a value field that the deployed contract owns (total_value) has changed. The handler enqueues a blockchain update_token transaction and returns 200 immediately. The change is not reflected on user-facing reads until the chain confirms — at confirm time the consumer writes a token_histories row and the user overlay surfaces the new value.
• Off-chain branch — fires for everything else (or when the token is not in listed status). The token document is updated in MongoDB and a token_histories snapshot is written synchronously so the user overlay sees the change on the very next read.

This split is intentional: user-facing reads always overlay Value / Metric from the latest token_histories row, so blockchain-pending updates stay invisible until the chain settles. See Get Token By User for the read side.

Request

PUT /v2/admin/tokens/{token_id}

Path Parameters

Name	Type	In	Description
token_id	string	path	Required. The ID of the token to update.

Form Body

Name	Type	Branch	Description
name	string	off-chain	Required. Display name.
description	string	off-chain	Required. Description.
total_value	number	on-chain (when status = listed)	The total value of the token. Changing this on a listed token enqueues a blockchain update.
currency_token_id	string	off-chain	Currency token ID for the value object. Re-attaching metadata only — does not trigger a chain update on its own.
salable_percentage	number	off-chain	Percentage of tokens that are salable (0-100).
images	file	off-chain	Optional. New image file(s).
documents	file	off-chain	Optional. New supporting document(s). Documents are also queued separately when the token is listed.
remove_image_ids	string	off-chain	Comma-separated list of image IDs to remove.
remove_document_ids	string	off-chain	Comma-separated list of document IDs to remove.
oracle_id	string	off-chain	Oracle ID for price reference.
oracle_code	string	off-chain	Oracle code for price reference.

External tokens (origin = external) bypass both branches — the handler updates name/description and exits early without writing history.

Headers

Name	Description
Authorization	Required. Bearer token for authentication.
Content-Type	Required. Must be multipart/form-data.

Example

curl --request PUT \
  --url '\{\{baseUrl\}\}/v2/admin/tokens/67d8774e903bfcbe7eb5d93e' \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  --header 'Content-Type: multipart/form-data' \
  --form 'name=TKN Token Name Updated' \
  --form 'description=Token Description' \
  --form total_value=12000 \
  --form currency_token_id=68fe8c129367fd414b227c7a \
  --form salable_percentage=80 \
  --form images=@/path/to/image.png \
  --form documents=@/path/to/document.pdf \
  --form remove_image_ids= \
  --form remove_document_ids= \
  --form oracle_id=677ed6e3cc111aea14a3dfc3 \
  --form oracle_code=IOG

Response

A successful request returns HTTP 200 with an empty body. The response is identical for the on-chain and off-chain branches — the caller cannot distinguish them from the HTTP envelope alone.

To observe the on-chain branch settling, poll POST /v2/admin/tokens/{token_id}/transactions/search for a new update_token transaction and wait for its status to reach Completed. Once the consumer confirms the transaction it writes the new Value/Metric snapshot into token_histories and user reads will start surfacing the updated values.

History Behaviour

Branch	Writes token_histories row?	Change Reason
Off-chain (or non-listed token)	Yes — synchronously on success	offchain_update
On-chain (listed token, total_value changed)	Yes — but only after the blockchain confirm consumer (CompleteUpdateToken) settles the transaction	contract_confirm

Document add/remove events flow through a separate event stream (AddDocumentEvent) when the token is listed; they do not change the value snapshot.

Status Codes

Status	Description
200	Success.
400	Bad Request — invalid parameters, category rules violated (e.g. salable_percentage_must_be_100, total_value_must_match_max_supply).
401	Unauthorized — invalid or missing authentication token.
404	Not Found — token ID does not exist.
413	Payload Too Large — file size exceeds the per-image / per-document limit.
415	Unsupported Media Type — file format not allowed.
500	Internal Server Error.