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

{% stepper %}
{% step %}

### Choose a Token

This is the token whose balance is being modified.

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

{% endstep %}

{% step %}

### Choose a Target Account

This is the account receiving or sending the tokens: `userAccount`
{% endstep %}

{% step %}

### 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`.

```typescript
// 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
```

{% endstep %}

{% step %}

### Call `modifyTokenBalance()`

Add the balance operation to the builder.

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

{% endstep %}

{% step %}

### Publish the Builder

Finalize the changes by sending them to the network.

```typescript
await userClient.publishBuilder(builder)
```

{% endstep %}
{% endstepper %}

## Method

```typescript
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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.keeta.com/components/blocks/operations/modifytokenbalance.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.