---
title: Scaled UI Amount Issuer Guide
description:
  Learn how to use the Scaled UI Amount extension to scale the UI amount of a
  token.
---

## 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:

<CodeTabs>

```terminal !! title="create-token.sh"
$ spl-token --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb create-token --ui-amount-multiplier 1.5
Creating token 66EV4CaihdqyQ1fbsr51wBsoqKLgAG5KiYz7r5XNrxUM under program TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb

Address:  66EV4CaihdqyQ1fbsr51wBsoqKLgAG5KiYz7r5XNrxUM
Decimals:  9

Signature: 2sPziXu9M3duTCvsDvxQE9UKC9nBiLayi8muDvnjhA2qYvfXSZuaUieoq39MFjg4kf8xFrw6crmYSkPyV59dvudF
```

```ts !! title="create-token.ts"
import {
  Connection,
  Keypair,
  PublicKey,
  Signer,
  SystemProgram,
  Transaction,
  sendAndConfirmTransaction
} from "@solana/web3.js";
import {
  TOKEN_2022_PROGRAM_ID,
  createInitializeMintInstruction,
  createInitializeScaledUiAmountConfigInstruction,
  ExtensionType,
  getMintLen
} from "@solana/spl-token";

/**
 * Creates a new SPL-Token 2022 mint with the Scaled UI extension enabled
 * and a UI multiplier of 1.1.
 *
 * @param connection – An initialized Solana Connection.
 * @param payer      – Signer paying for fees and rent.
 * @returns The newly created mint PublicKey.
 */
export async function createScaledUiMint(
  connection: Connection,
  payer: Signer
): Promise<PublicKey> {
  // 1) Generate a new mint Keypair
  const mint = Keypair.generate();
  const MINT_EXTENSIONS = [ExtensionType.ScaledUiAmountConfig];
  const mintLen = getMintLen(MINT_EXTENSIONS);
  const mintLamports =
    await connection.getMinimumBalanceForRentExemption(mintLen);
  const mintTransaction = new Transaction().add(
    SystemProgram.createAccount({
      fromPubkey: payer.publicKey,
      newAccountPubkey: mint.publicKey,
      space: mintLen,
      lamports: mintLamports,
      programId: TOKEN_2022_PROGRAM_ID
    }),
    createInitializeScaledUiAmountConfigInstruction(
      mint.publicKey,
      payer.publicKey,
      1.1,
      TOKEN_2022_PROGRAM_ID
    ),
    createInitializeMintInstruction(
      mint.publicKey,
      0,
      payer.publicKey,
      null,
      TOKEN_2022_PROGRAM_ID
    )
  );
  await sendAndConfirmTransaction(
    connection,
    mintTransaction,
    [payer, mint],
    undefined
  );

  console.log(
    "✅ Created mint w/ scaled-UI extension:",
    mint.publicKey.toBase58()
  );
  return mint.publicKey;
}
(async () => {
  // 1) Establish a connection to the Solana devnet
  const connection = new Connection(
    "https://api.devnet.solana.com",
    "confirmed"
  );

  // 2) Generate a new fee-payer Keypair
  const payer = Keypair.generate();

  // 3) Airdrop 1 SOL to the fee-payer so it has funds for transactions
  const airdropSignature = await connection.requestAirdrop(
    payer.publicKey,
    1_000_000_000 // 1 SOL in lamports
  );

  // 4) Create the scaled-UI mint using our helper
  const mintPubkey = await createScaledUiMint(connection, payer);
})().catch((err) => {
  console.error("Error running example:", err);
});
```

</CodeTabs>

### 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](https://github.com/solana-program/token-2022/pull/522)
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

<CodeTabs>

```terminal !! title="update-ui-amount-multiplier.sh"
$ 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
```

```ts !! title="update-ui-amount-multiplier.ts"
/**
 * Updates the scaled UI multiplier for an existing SPL-Token 2022 mint.
 *
 * @param connection – An initialized Solana Connection.
 * @param payer      – Signer paying for fees and rent.
 * @param mint       – PublicKey of the mint to update.
 * @param multiplier – New multiplier value to set.
 * @returns The transaction signature.
 */
export async function updateScaledUiMultiplier(
  connection: Connection,
  payer: Signer,
  mint: PublicKey,
  multiplier: number,
  effectiveTimestamp: bigint,
  previousMultiplier: number,
  previousEffectiveTimestamp: bigint
): Promise<string> {
  const transaction = new Transaction()
    .add(
      // Set the previous multiplier to the current multiplier
      // This is temporarily needed until PR 522 is deployed to mainnet
      createUpdateMultiplierDataInstruction(
        mint,
        payer.publicKey,
        previousMultiplier,
        previousEffectiveTimestamp,
        [],
        TOKEN_2022_PROGRAM_ID
      )
    )
    .add(
      createUpdateMultiplierDataInstruction(
        mint,
        payer.publicKey,
        multiplier,
        effectiveTimestamp,
        [],
        TOKEN_2022_PROGRAM_ID
      )
    );

  const signature = await sendAndConfirmTransaction(
    connection,
    transaction,
    [payer],
    undefined
  );

  console.log(
    `✅ Updated scaled-UI multiplier to ${multiplier} for mint:`,
    mint.toBase58()
  );
  return signature;
}
const multiplier = 1.5;
const effectiveTimestamp = BigInt(Math.floor(Date.now() / 1000));
const previousMultiplier = 1.2;
const previousEffectiveTimestamp = BigInt(1746470000);
const updateSignature = await updateScaledUiMultiplier(
  connection,
  payer,
  mintPubkey,
  multiplier,
  effectiveTimestamp,
  previousMultiplier,
  previousEffectiveTimestamp
);
console.log("Update signature:", updateSignature);
```

</CodeTabs>

### Fetch the Balance

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

<CodeTabs>

```terminal !! title="balance.sh"
$ spl-token balance 66EV4CaihdqyQ1fbsr51wBsoqKLgAG5KiYz7r5XNrxUM
```

```ts !! title="balance.ts"
/**
 * Gets the scaled UI amount balance for a token holder.
 *
 * @param connection – An initialized Solana Connection.
 * @param mint       – PublicKey of the mint to check.
 * @param owner      – PublicKey of the token holder.
 * @returns The scaled UI amount balance.
 */
export async function getScaledUiAmountBalance(
  connection: Connection,
  mint: PublicKey,
  owner: PublicKey
): Promise<number> {
  // Get the token account for this mint/owner pair
  const tokenAccount = getAssociatedTokenAddressSync(
    mint,
    owner,
    false,
    TOKEN_2022_PROGRAM_ID
  );

  // Get the token account info
  const accountInfo = await connection.getAccountInfo(tokenAccount);
  if (!accountInfo) {
    throw new Error("Token account not found");
  }

  const info = await connection.getTokenAccountBalance(tokenAccount);
  if (info.value.uiAmount == null) throw new Error("No balance found");
  console.log("Balance: ", info.value.uiAmount);
  return info.value.uiAmount;
}
const balance = await getScaledUiAmountBalance(connection, mint, owner);
```

</CodeTabs>