modifyTokenBalance

The modifyTokenBalance() function lets you directly adjust a specific account’s balance for a token, either by adding to or subtracting from it. This is done from or to the token's "unallocated balance", not another user.

Think of it like minting or burning — but instead of affecting total supply, you're just updating who holds what.

When to Use

• Mint tokens to an account (from unallocated token balance)

• Burn tokens from an account (to unallocated token balance)

• Adjust balance after supply changes

• Pre-fill or wipe account balances during setup/testing

How It Works (Step-by-Step)

1

Choose a Token

This is the token whose balance is being modified.

const tokenAccount = Client.lib.Account.fromPublicKeyString("TOKEN_PUBLIC_KEY")

2

Choose a Target Account

This is the account receiving or sending the tokens: userAccount

3

Determine Amount

• Use a positive amount to credit (add tokens).

• Use a negative amount to debit (remove tokens).

• You can also overwrite the balance using isSet: true.

// Add 1000 tokens
const amount = 1000n

// OR remove 500 tokens
const amount = -500n

// OR set balance exactly to 0
const amount = 0n
const isSet = true

4

Call modifyTokenBalance()

Add the balance operation to the builder.

builder.modifyTokenBalance(
  tokenAccount,
  amount,
  isSet ?? false, // optional: true if you want to overwrite balance
  { account: userAccount }
)

5

Publish the Builder

Finalize the changes by sending them to the network.

await userClient.publishBuilder(builder)

Method

modifyTokenBalance(
  token: TokenOrPending,
  amount: bigint,
  isSet?: boolean,
  options?: { account: Account }
): void

• amount: Can be positive (add) or negative (remove)

• isSet: Default is false. If true, sets the exact balance. Otherwise, adds/subtracts from current balance.

• account: The target account to modify.