Check a Balance

Faucet Service

You can use the faucet service to send test tokens to any Chrysalis devnet address.

Java

Client.getBalance(seed: String)

Combines Client.getAddresses() and Client.getAddressBalance() api calls. It returns a combined balance for the provided seed.

Client.getAddressBalance(address: String)

Expects a single address in Bech32 format and returns dict with a balance for the address.

Client.getAddressBalances(addresses: String[])

A convenient function that expects list of addresses in Bech32 format and returns list of dict with balances for all given addresses.

Client.getAddress().balance(address: String)

You can use the GetAdressBuilder on a Client instance and query for and addresses' balances by chaining a call to the balance(address: String) function.

Client.getAddress().outputs(address: String, options: OutputOptions)

You can use the GetAdressBuilder on a Client instance and query for and addresses' balances by chaining a call to the outputs(address: String) function.

bindings/java/examples/java-app/src/main/java/org/iota/client/example/ExampleApp.java

public static void getBalance() {
    try {
        Client iota = node();

        String seed = "NONSECURE_USE_OF_DEVELOPMENT_SEED_1";

        long seed_balance = iota.getBalance(seed).finish();
        System.out.println("Account balance: " + seed_balance);

        String address = "atoi1qzt0nhsf38nh6rs4p6zs5knqp6psgha9wsv74uajqgjmwc75ugupx3y7x0r";

        BalanceAddressResponse response = iota.getAddress().balance(address);
        System.out.println("The balance of " + address + " is " + response.balance());

        UtxoInput[] outputs = iota.getAddress().outputs(address, new OutputsOptions());
        System.out.println("The outputs of address " + address + " are: " + Arrays.toString(outputs));
    } catch (ClientException e) {
        System.out.println("Error: " + e.getMessage());
    }
}

See full example on GitHub

Example output:

Account balance: 1096055332i

The balance of "atoi1qzt0nhsf38nh6rs4p6zs5knqp6psgha9wsv74uajqgjmwc75ugupx3y7x0r" is 451055332i

The outputs of address "atoi1qzt0nhsf38nh6rs4p6zs5knqp6psgha9wsv74uajqgjmwc75ugupx3y7x0r" are: [
  UtxoInput(741673db85f78ebd95d04b572d1bf32e9207bbd265d90dbbe499a6d32f2b25470000),
  UtxoInput(ed33089c623c67eb06dbc1c10b0c1c0424b0ace04a2e44070702668b3de440c80000),
  UtxoInput(0af84c860dc461730064e7c4c88152ed8bea1ae72b1d6f5e4ab0c3e51ed185b70100),
  ...]

• dustAllowed indicates whether the given address is allowed to accept a dust. You can learn more about dust protection in the Chrysalis documentation.

Nodejs

There are three common API calls you can use to get a balance:

Client.getAddressBalance(address: string)

It expects a single address in Bech32 format and returns dict with a balance for the address.

Client.getAddressBalances(AddressBalance[]: string[])

A convenient function that expects list of addresses in Bech32 format and returns list of dict with balances for all given addresses.

Client.getBalance(seed: string)

A convenient helper BalanceGetter class that combines Client.getAddresses() and Client.getAddressBalance() api calls. It returns a combined balance for the provided seed and optional chaining calls .accountIndex(index: number), .initialAddressIndex(index: number) and .gapLimit(amount: number).

Client.getBalance(seed) performs several tasks under the hood. It starts by generating addresses for the provided seed and .accountIndex from .initialAddressIndex(index), and checks for a balance of each of the generated addresses. Since it does not know how many addresses are used in fact, there is a condition set by the .gapLimit(amount) argument to know when to stop searching. If the .gapLimit amount of addresses in a row have no balance, the function returns results and searching does not continue.

bindings/nodejs/examples/04_get_balance.js

async function run() {
    const { ClientBuilder } = require('@iota/client');

    // Get the seed from environment variable
    const IOTA_SEED_SECRET = process.env.IOTA_SEED_SECRET;

    // client will connect to testnet by default
    const client = new ClientBuilder().build();

    // Get the balance of a single known address
    console.log(
        await client.getAddressBalance("atoi1qp9427varyc05py79ajku89xarfgkj74tpel5egr9y7xu3wpfc4lkpx0l86")
    );

    // Get the balance of addresses from an account
    const balance = await client.getBalance(IOTA_SEED_SECRET)
        .accountIndex(0)
        .initialAddressIndex(0)
        .get();

    console.log("Account balance: " + balance);
}

run()

See full example on GitHub

Example of output:

{
   "address":"atoi1qp9427varyc05py79ajku89xarfgkj74tpel5egr9y7xu3wpfc4lkpx0l86",
   "balance":10000000,
   "dustAllowed":false
}
Account balance: 0

• dustAllowed indicates whether the given address is allowed to accept a dust. You can learn more about dust protection in the Chrysalis documentation.

Python

There are three common API calls you can use to get a balance:

Client.get_address_balance(address: str)

Expects a single address in Bech32 format and returns dict with a balance for the address.

Client.get_address_balances(addresses: list[str]):

A convenient function that expects list of addresses in Bech32 format and returns list of dict with balances for all given addresses

Client.get_balance(seed, account_index (optional), initial_address_index(optional), gap_limit(optional))

A convenient function that combines Client.get_addresses() and Client.get_address_balances() api calls. It returns a combined balance for the provided seed and optional chaining calls .accountIndex(index), .initialAddressIndex(index) and .gapLimit(amount)

Client.get_balance(seed) performs several tasks under the hood. It starts by generating addresses for the provided seed and account_index from initial_address_index, and checks for a balance of each of the generated addresses. Since it does not know how many addresses are used in fact, there is a condition set by the gap_limit argument to know when to stop searching. If the gap_limit amount of addresses in a row have no balance, the function returns results and stops searching.

bindings/python/examples/04_get_balance.py

import os
import iota_client

# Get the seed from environment variable
IOTA_SEED_SECRET = os.getenv('IOTA_SEED_SECRET')
if not IOTA_SEED_SECRET:
    raise Exception("Please define environment variable called `IOTA_SEED_SECRET`")

client = iota_client.Client()

print("Return a balance for a single address:")
print(
    client.get_address_balance("atoi1qp9427varyc05py79ajku89xarfgkj74tpel5egr9y7xu3wpfc4lkpx0l86")
)

print("Return a balance for the given seed and account_index:")
print(
    client.get_balance(
        seed=IOTA_SEED_SECRET,
        account_index=0,
        initial_address_index=0
    )
)

See full example on GitHub

Example of output:

{
   "address":"atoi1qp9427varyc05py79ajku89xarfgkj74tpel5egr9y7xu3wpfc4lkpx0l86",
   "balance":10000000,
   "dustAllowed":false
}
Account balance: 0

• dustAllowed indicates whether the given address is allowed to accept a dust due to dust protection mechanism.

Rust

There are several API calls you can use to get a balance:

Client. get_address_balances(addresses: &[String])

Aconvenient function that expects list of addresses in Bech32 format and returns list of dict with balances for all given addresses.

Client.get_balance(seed: seed: &'a Seed)

A convenient GetBalanceBuilder class that combines Client.get_addresses(seed: &'a Seed) and Client.get_address_balances(addresses: &[String]) api calls. It returns a combined balance for the provided seed and optional chaining calls .with_account_index(account_index: usize), .with_initial_address_index(initial_address_index: usize) and .with_gap_limit(gap_limit: usize).

Client.get_balance(seed) performs several tasks under the hood. It starts by generating addresses for the provided seed and .account_index from .with_initial_address_index(account_index), and checks for a balance of each of the generated addresses. Since it does not know how many addresses are used in fact, there is a condition set by the .with_gap_limit(gap_limit) argument to know when to stop searching. If the .gap_limit amount of addresses in a row have no balance, the function returns results and searching does not continue.

Client.get_address().balance(address: &str)

You can use the GetAdressBuilder on a Client instance and query for an addresses' balances by chaining a call to the balance(address: String) function.

Client.get_address().outputs(address: &str, options: OutputOptions)

You can use the GetAdressBuilder on a Client instance and query for an addresses' balances by chaining a call to the outputs(address: String) function.

examples/04_get_balance.rs

// Copyright 2021 IOTA Stiftung
// SPDX-License-Identifier: Apache-2.0

//! cargo run --example 04_get_balance --release

use iota_client::{Client, Seed};
extern crate dotenv;
use dotenv::dotenv;
use std::env;

/// In this example we will get the account balance of a known seed and the balance and outputs of a known address

#[tokio::main]
async fn main() {
    // Create a client instance
    let iota = Client::builder()
        .with_node("https://api.lb-0.h.chrysalis-devnet.iota.cafe") // Insert your node URL here
        .unwrap()
        .with_node_sync_disabled()
        .finish()
        .await
        .unwrap();

    // This example uses dotenv, which is not safe for use in production
    dotenv().ok();

    let seed = Seed::from_bytes(&hex::decode(env::var("NONSECURE_USE_OF_DEVELOPMENT_SEED_1").unwrap()).unwrap());

    let seed_balance = iota.get_balance(&seed).finish().await.unwrap();
    println!("Account balance: {seed_balance:?}i\n");

    let address = "atoi1qzt0nhsf38nh6rs4p6zs5knqp6psgha9wsv74uajqgjmwc75ugupx3y7x0r";

    let response = iota.get_address().balance(address).await.unwrap();
    println!("The balance of {:?} is {:?}i\n", address, response.balance);

    let outputs = iota.get_address().outputs(address, Default::default()).await.unwrap();

    println!("The outputs of address {address:?} are: {outputs:?}");
}

See full example on GitHub

Example of output:

Account balance: 1096055332i

The balance of "atoi1qzt0nhsf38nh6rs4p6zs5knqp6psgha9wsv74uajqgjmwc75ugupx3y7x0r" is 451055332i

The outputs of address "atoi1qzt0nhsf38nh6rs4p6zs5knqp6psgha9wsv74uajqgjmwc75ugupx3y7x0r" are: [
  UtxoInput(741673db85f78ebd95d04b572d1bf32e9207bbd265d90dbbe499a6d32f2b25470000),
  UtxoInput(ed33089c623c67eb06dbc1c10b0c1c0424b0ace04a2e44070702668b3de440c80000),
  UtxoInput(0af84c860dc461730064e7c4c88152ed8bea1ae72b1d6f5e4ab0c3e51ed185b70100),
  ...]

• dustAllowed indicates whether the given address is allowed to accept a dust due to dust protection mechanism.

Wasm

There are two API calls you can use to get a balance:

Client.getAddressBalances(addresses: any)

A convenient function that expects list of addresses in Bech32 format and returns list of dict with balances for all given addresses.

Client.getBalance(seed: string)

A convenient helper BalanceGetter class that combines Client.getAddresses(seed: string) and Client.getAddressBalances() api calls. It returns a combined balance for the provided seed and optional chaining calls .accountIndex(index), .initialAddressIndex(initial_address_index: number) and .gap_limit(amount: number)

Client.getBalance(seed: string) performs several tasks under the hood. It starts by generating addresses for the provided seed and .accountIndex from .initialAddressIndex(initial_address_index: number), and checks for a balance of each of the generated addresses. Since it does not know how many addresses are used in fact, there is a condition set by the .gap_limit(amount: number) argument to know when to stop searching. If the .gap_limit amount of addresses in a row have no balance, the function returns results and searching does not continue.

bindings/wasm/examples/04_get_balance.js

async function run() {
    const { ClientBuilder } = require('../node')

    // Get the seed from environment variable
    const IOTA_SEED_SECRET = process.env.IOTA_SEED_SECRET;

    // client will connect to testnet by default
    const client = await new ClientBuilder().build();

    // Get the balance of a known address
    console.log(
        await client.getAddressBalances(["atoi1qp9427varyc05py79ajku89xarfgkj74tpel5egr9y7xu3wpfc4lkpx0l86"])
    );

    // Get the balance of addresses from an account
    const balance = await client.getBalance(IOTA_SEED_SECRET)
        .accountIndex(0)
        .initialAddressIndex(0)
        .get();

    console.log("Account balance: " + balance);
}

run()

See full example on GitHub

Example of output:

{
   "address":"atoi1qp9427varyc05py79ajku89xarfgkj74tpel5egr9y7xu3wpfc4lkpx0l86",
   "balance":10000000,
   "dustAllowed":false,
   "ledgerIndex": 2338924
}
Account balance: 0

• dustAllowed indicates whether the given address is allowed to accept a dust. You can learn more about dust protection in the Chrysalis documentation.