Update Token Metric

Updates a token's metric configuration (supply, purchase bounds, rental terms). Like Update Token, the integration splits this call into two branches:

• On-chain branch — total_supply, min_purchase_quantity, or max_purchase_quantity changed and status = listed. The handler enqueues a blockchain update_token transaction and the new values are not visible to users until the chain confirms.
• Off-chain branch — every other change (or the token is not listed). The metric is updated in MongoDB and a token_histories snapshot is written synchronously, so user reads pick it up on the very next call.

User-facing reads always overlay Value / Metric from the latest token_histories row (see Get Token By User), which is what hides blockchain-pending updates from end users.

Request

PUT /v2/admin/tokens/{token_id}/metric

Path Parameters

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

Headers

Name	Description
Authorization	Required. Bearer token for authentication.
Content-Type	Required. Must be application/json.

Request Body

Name	Type	Branch	Description
total_supply	number	on-chain (when status = listed)	Total listed supply. Must satisfy supply invariants (<= max_supply, >= purchased_supply + sold_supply).
term_duration_in_months	number	off-chain	Duration of the term in months. null allowed.
min_purchase_quantity	number	on-chain (when status = listed)	Minimum tokens per purchase.
max_purchase_quantity	number	on-chain (when status = listed)	Maximum tokens per purchase.
min_tokens_required_for_rental_income	number	off-chain	Minimum tokens a holder must own to receive rental income.
rental_income	number	off-chain	Amount of rental income per period.
rental_income_currency_token_id	string	off-chain	Currency for rental_income. Pass an empty string to clear rental configuration.
rental_payment_period_in_days	number	off-chain	Period between rental payments in days.

Rental-Field Invariant

rental_income, rental_payment_period_in_days, and min_tokens_required_for_rental_income must all be set together or all left empty. Partial configurations are rejected with rental_config_incomplete (HTTP 400).

Example

curl --request PUT \
  --url '\{\{baseUrl\}\}/v2/admin/tokens/67d8774e903bfcbe7eb5d93e/metric' \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  --header 'Content-Type: application/json' \
  --data '{
  "total_supply": 100,
  "term_duration_in_months": 12,
  "min_purchase_quantity": 1,
  "max_purchase_quantity": 100,
  "min_tokens_required_for_rental_income": 5,
  "rental_income": 250.50,
  "rental_income_currency_token_id": "68fe8c129367fd414b227c7a",
  "rental_payment_period_in_days": 30
}'

Response

A successful request returns HTTP 200 with an empty body. The response shape is identical for the on-chain and off-chain branches.

For the on-chain branch, poll POST /v2/admin/tokens/{token_id}/transactions/search for the new update_token transaction; the change becomes visible on user reads once that transaction reaches Completed and the consumer writes the confirming token_histories row.

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, supply/quantity bounds changed)	Yes — after the blockchain confirm consumer settles	contract_confirm

Status Codes

Status	Description
200	Success.
400	Bad Request — invalid parameters, supply invariant violation (error_total_supply), incomplete rental config, category rule violation.
401	Unauthorized — invalid or missing authentication token.
404	Not Found — token ID does not exist.
500	Internal Server Error.