Balances

Calls

forceTransfer

Exactly as transfer, except the origin must be root and the source account may be specified.

Namespace

api.tx.balances.forceTransfer

Type

function forceTransfer(
  source: SeedPrimitivesSignatureAccountId20,
  dest: SeedPrimitivesSignatureAccountId20,
  value: Compact<u128>
)

forceUnreserve

Unreserve some balance from a user by force.

Can only be called by ROOT.

Namespace

api.tx.balances.forceUnreserve

Type

function forceUnreserve(
  who: SeedPrimitivesSignatureAccountId20,
  amount: u128
)

setBalance

Set the balances of a given account.

This will alter FreeBalance and ReservedBalance in storage. it will also alter the total issuance of the system (TotalIssuance) appropriately. If the new free or reserved balance is below the existential deposit, it will reset the account nonce (frame_system::AccountNonce).

The dispatch origin for this call is root.

Namespace

api.tx.balances.setBalance

Type

function setBalance(
  who: SeedPrimitivesSignatureAccountId20,
  new_free: Compact<u128>,
  new_reserved: Compact<u128>
)

transfer

Transfer some liquid-free balance to another account.

transfer will set the FreeBalance of the sender and receiver. If the sender's account is below the existential deposit as a result of the transfer, the account will be reaped.

The dispatch origin for this call must be Signed by the transactor.

Namespace

api.tx.balances.transfer

Type

function transfer(
  dest: SeedPrimitivesSignatureAccountId20,
  value: Compact<u128>
)

transferAll

Transfer the entire transferable balance from the caller account.

NOTE: This function only attempts to transfer transferable balances. This means that any locked, reserved, or existential deposits (when keep_alive is true), will not be transferred by this function. To ensure that this function results in a killed account, you might need to prepare the account by removing any reference counters, storage deposits, etc.

The dispatch origin of this call must be Signed.

• dest: The recipient of the transfer.

• keep_alive: A boolean to determine if the transfer_all operation should send all of the funds the account has, causing the sender account to be killed (false), or transfer everything except at least the existential deposit, which will guarantee to keep the sender account alive (true). #

Namespace

api.tx.balances.transferAll

Type

function transferAll(
  dest: SeedPrimitivesSignatureAccountId20,
  keep_alive: bool
)

transferKeepAlive

Same as the transfer call, but with a check that the transfer will not kill the origin account.

99% of the time you want transfer instead.

Namespace

api.tx.balances.transferKeepAlive

Type

function transferKeepAlive(
  dest: SeedPrimitivesSignatureAccountId20,
  value: Compact<u128>
)

Storage

account

The Balances pallet example of storing the balance of an account.

Example

nocompile impl pallet_balances::Config for Runtime { type AccountStore = StorageMapShim<Self::Account<Runtime>, frame_system::Provider<Runtime>, AccountId, Self::AccountData<Balance>> }

You can also store the balance of an account in the System pallet.

Example

nocompile impl pallet_balances::Config for Runtime { type AccountStore = System }

But this comes with tradeoffs, storing account balances in the system pallet stores frame_system data alongside the account data contrary to storing account balances in the Balances pallet, which uses a StorageMap to store balances data only. NOTE: This is only used in the case that this pallet is used to store balances.

Namespace

api.query.balances.account

Type

function account(
  SeedPrimitivesSignatureAccountId20
): PalletBalancesAccountData

locks

Any liquidity locks on some account balances. NOTE: Should only be accessed when setting, changing and freeing a lock.

Namespace

api.query.balances.locks

Type

function locks(
  SeedPrimitivesSignatureAccountId20
): Vec<PalletBalancesBalanceLock>

reserves

Named reserves on some account balances.

Namespace

api.query.balances.reserves

Type

function reserves(
  SeedPrimitivesSignatureAccountId20
): Vec<PalletBalancesReserveData>

storageVersion

Storage version of the pallet.

This is set to v2.0.0 for new networks.

Namespace

api.query.balances.storageVersion

Type

function storageVersion(

): PalletBalancesReleases

totalIssuance

The total units issued in the system.

Namespace

api.query.balances.totalIssuance

Type

function totalIssuance(

): u128

Events

BalanceSet

A balance was set by root.

Namespace

api.events.balances.BalanceSet

Type

type BalanceSet = {
  who: SeedPrimitivesSignatureAccountId20,
  free: u128,
  reserved: u128
}

Deposit

Some amount was deposited (e.g. for transaction fees).

Namespace

api.events.balances.Deposit

Type

type Deposit = {
  who: SeedPrimitivesSignatureAccountId20,
  amount: u128
}

DustLost

An account was removed whose balance was non-zero but below ExistentialDeposit, resulting in an outright loss.

Namespace

api.events.balances.DustLost

Type

type DustLost = {
  account: SeedPrimitivesSignatureAccountId20,
  amount: u128
}

Endowed

An account was created with some free balance.

Namespace

api.events.balances.Endowed

Type

type Endowed = {
  account: SeedPrimitivesSignatureAccountId20,
  free_balance: u128
}

Reserved

Some balance was reserved (moved from free to reserved).

Namespace

api.events.balances.Reserved

Type

type Reserved = {
  who: SeedPrimitivesSignatureAccountId20,
  amount: u128
}

ReserveRepatriated

Some balance was moved from the reserve of the first account to the second account. Final argument indicates the destination balance type.

Namespace

api.events.balances.ReserveRepatriated

Type

type ReserveRepatriated = {
  from: SeedPrimitivesSignatureAccountId20,
  to: SeedPrimitivesSignatureAccountId20,
  amount: u128,
  destination_status: FrameSupportTokensMiscBalanceStatus
}

Slashed

Some amount was removed from the account (e.g. for misbehavior).

Namespace

api.events.balances.Slashed

Type

type Slashed = {
  who: SeedPrimitivesSignatureAccountId20,
  amount: u128
}

Transfer

Transfer succeeded.

Namespace

api.events.balances.Transfer

Type

type Transfer = {
  from: SeedPrimitivesSignatureAccountId20,
  to: SeedPrimitivesSignatureAccountId20,
  amount: u128
}

Unreserved

Some balance was unreserved (moved from reserved to free).

Namespace

api.events.balances.Unreserved

Type

type Unreserved = {
  who: SeedPrimitivesSignatureAccountId20,
  amount: u128
}

Withdraw

Some amount was withdrawn from the account (e.g. for transaction fees).

Namespace

api.events.balances.Withdraw

Type

type Withdraw = {
  who: SeedPrimitivesSignatureAccountId20,
  amount: u128
}

Errors

DeadAccount

Beneficiary account must pre-exist

Namespace

api.errors.balances.DeadAccount

ExistentialDeposit

Value too low to create account due to existential deposit

Namespace

api.errors.balances.ExistentialDeposit

ExistingVestingSchedule

A vesting schedule already exists for this account

Namespace

api.errors.balances.ExistingVestingSchedule

InsufficientBalance

Balance too low to send value

Namespace

api.errors.balances.InsufficientBalance

KeepAlive

Transfer/payment would kill account

Namespace

api.errors.balances.KeepAlive

LiquidityRestrictions

Account liquidity restrictions prevent withdrawal

Namespace

api.errors.balances.LiquidityRestrictions

TooManyReserves

Number of named reserves exceed MaxReserves

Namespace

api.errors.balances.TooManyReserves

VestingBalance

Vesting balance too high to send value

Namespace

api.errors.balances.VestingBalance

Constants

existentialDeposit

The minimum amount required to keep an account open.

Namespace

api.consts.balances.existentialDeposit

Type

type existentialDeposit = u128

maxLocks

The maximum number of locks that should exist on an account. Not strictly enforced, but used for weight estimation.

Namespace

api.consts.balances.maxLocks

Type

type maxLocks = u32

maxReserves

The maximum number of named reserves that can exist on an account.

Namespace

api.consts.balances.maxReserves

Type

type maxReserves = u32

Source: https://docs.therootnetwork.com/build/substrate/api-reference/runtime-pallets/balances · captured 2026-05-02 · part of TRN Docs source map