Update Token Metric
Sets a token's listed supply, purchase bounds, term and rental terms. Every field is applied as sent: an omitted number is read as 0, an omitted term_duration_in_months as null and an omitted rental_income_currency_token_id clears the rental currency, so send the full metric each time.
The change is written to the token at once. It reaches the chain only when the token is in status 6 (Listed) and total_supply, min_purchase_quantity or max_purchase_quantity changed. Then an UpdateToken transaction (type 5) is queued and its id is returned; poll it with Get Token Transaction By ID. Otherwise the response carries "transaction_id": null and a token history snapshot is written immediately. As with Update Token, investors see an on-chain change only after it settles.
Required permission: token:update-metric
Request
PUT /v2/admin/tokens/{token_id}/metric
Parameters
| Name | Type | In | Description |
|---|---|---|---|
token_id | string | path | Required. Token id. |
Headers
| Name | Description |
|---|---|
Authorization | Required. Bearer <access_token> |
Content-Type | Required. application/json |
Body
| Field | Type | Required | Description |
|---|---|---|---|
total_supply | integer | No | Tokens offered for primary sale (value.listed_supply). Must not drop below the tokens already sold, and together with the fee supply must not exceed max_supply. On-chain when the token is listed. |
min_purchase_quantity | integer | No | Minimum tokens per purchase. On-chain when the token is listed. |
max_purchase_quantity | integer | No | Maximum tokens per purchase. On-chain when the token is listed. |
term_duration_in_months | integer | null | No | Term of the asset in months. |
rental_income | string | No | Rental income per distribution, a decimal string with no more decimals than the rental currency. With a category whose rental_income_as_percentage is on, it is a percentage of the total value. |
rental_income_currency_token_id | string | No | Currency token the rental income is paid in. Empty or omitted clears the rental currency. |
rental_payment_period_in_days | integer | No | Days between distributions. |
min_tokens_required_for_rental_income | integer | No | Minimum tokens a holder needs to receive rental income. |
rental_income, rental_income_currency_token_id, rental_payment_period_in_days and min_tokens_required_for_rental_income belong together: set all four, or none of them. The token's category may also fix the payment period, bound the rental income or forbid purchase quantities and the rental minimum (see Errors). Amounts follow Amounts and Percentages.
Example
curl --request PUT \
--url '{{baseUrl}}/v2/admin/tokens/67d8774e903bfcbe7eb5d93e/metric' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data '{
"total_supply": 800,
"term_duration_in_months": 12,
"min_purchase_quantity": 1,
"max_purchase_quantity": 100,
"min_tokens_required_for_rental_income": 5,
"rental_income": "250.5",
"rental_income_currency_token_id": "68fe8c129367fd414b227c7a",
"rental_payment_period_in_days": 30
}'
Response
{
"transaction_id": "6a8b5e13f9129816a6cc7a12"
}
Response Fields
| Field | Type | Description |
|---|---|---|
transaction_id | string | null | The UpdateToken transaction when the change 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 rental_income or one with more decimals than its currency |
| 400 | 10016 | token_id or rental_income_currency_token_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 | 10022 | The four rental fields were not all set or all left empty (token domain 5) |
| 400 | 10002 | total_supply plus the fee supply exceeds max_supply (token domain 5) |
| 400 | 52003 | total_supply is below the tokens already sold (domain 52) |
| 404 | 10001 | Rental currency token not found (currency token domain 15) |
| 400 | 10017 | The category bounds rental_income between 1 and 100 (token domain 5) |
| 400 | 10018 | rental_payment_period_in_days must equal the category's period (token domain 5) |
| 400 | 10019 | The category requires min_purchase_quantity to be 0 (token domain 5) |
| 400 | 10020 | The category requires max_purchase_quantity to be 0 (token domain 5) |
| 400 | 10021 | The category requires min_tokens_required_for_rental_income to be 0 (token domain 5) |
See Errors for the error format and common codes.