Scaled UI Amount Issuer Guide

How to use the Scaled UI Amount extension

To use the Scaled UI Amount extension, you need to enable it on a token mint or token account. Note that once a token is created, you cannot modify which extensions are enabled.

Enable the Scaled UI Amount extension on a token mint

To enable the Scaled UI Amount extension on a token mint, you need to set the scaled_ui_amount_extension field to true in the Mint account. Here is an example of how to create a token with the Scaled UI Amount extension enabled using the spl-token CLI:

$ spl-token --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb create-token --ui-amount-multiplier 1.5
Creating token 66EV4CaihdqyQ1fbsr51wBsoqKLgAG5KiYz7r5XNrxUM under program TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb

Address:  66EV4CaihdqyQ1fbsr51wBsoqKLgAG5KiYz7r5XNrxUM
Decimals:  9

Signature: 2sPziXu9M3duTCvsDvxQE9UKC9nBiLayi8muDvnjhA2qYvfXSZuaUieoq39MFjg4kf8xFrw6crmYSkPyV59dvudF

Update the UI amount multiplier

To update the UI amount multiplier, you need to use the update-ui-amount-multiplier command. A timestamp, in seconds since the Unix epoch, is optional and can be used to set a custom start time for the new multiplier. If no timestamp is provided, the current timestamp will be used.

Important Note: There is currently an idiosyncrasy in the process to update the scaled ui multiplier. Right now if you do the following:

1. Set a scaled ui multiplier for the future
2. Time passes beyond this update time
3. Set another scaled ui multiplier for the future
4. Then the previous scaled ui multiplier is overridden and by the new one effectively removing it.

There is a merged PR to fix this so the multiplier properly updates to the current multiplier instead of being overridden, but this is not live yet.

Until this time it is necessary to do 2 multiplier updates during step 3 above:

1. Set the previous multiplier again with the timestamp to the same timestamp is originally set in step 1 (this will properly set the multiplier as the current multiplier)
2. Set the new multiplier as described in step 3 above

$ spl-token update-ui-amount-multiplier 66EV4CaihdqyQ1fbsr51wBsoqKLgAG5KiYz7r5XNrxUM 1.2 -- 1746470000 # 1.2 is the current multiplier as described in step 1 above
$ spl-token update-ui-amount-multiplier 66EV4CaihdqyQ1fbsr51wBsoqKLgAG5KiYz7r5XNrxUM 1.5 -- 1746471400

Fetch the Balance

To fetch the balance, you need to use the balance command.

$ spl-token balance 66EV4CaihdqyQ1fbsr51wBsoqKLgAG5KiYz7r5XNrxUM