Wallet balances

In this brief step-by-step guide we will use the Checkout SDK to fetch the tokens (ERC20) balances in a wallet. This list will contain tokens such as IMX, USDC, etc.

Sections

• Supported tokens
• Get all balances
  • ERC20 Token details
• Get balance for a token

---

Supported tokens

The list of supported tokens per network and feature can be programmatically fetched using the getTokenAllowList() function.

The getTokenAllowList() function allows to filter the list of tokens based on type and chainId which can be found in the GetTokenAllowListParams interface.

// Import the checkout module from the Immutable SDK package
import { checkout } from '@imtbl/sdk';

// Instantiate the Checkout SDKs with the default configurations
const checkoutSDK = new checkout.Checkout();

// Get the list of default supported tokens
const type = checkout.TokenFilterTypes.ALL;
const chainId = checkout.ChainId.IMTBL_ZKEVM_TESTNET;
checkoutSDK.getTokenAllowList({ type, chainId }).then((resp) => console.log(resp));

The GetTokenAllowListResult result provides list of allowed networks with additional information (e.g. nativeCurrency) that can be used while building your application.

Get all balances

This can be easily done using the getAllBalances() function. This function returns the native token balance as well as balances for all the ERC20 tokens held by the wallet associated to the provider.

Networks	Native Token	Layer
IMTBL_ZKEVM_MAINNET	IMX	Layer 2
IMTBL_ZKEVM_TESTNET	IMX	Layer 2
IMTBL_ZKEVM_DEVNET	IMX	Layer 2
ETHEREUM	ETH	Layer 1
SEPOLIA	ETH	Layer 1

// Import the checkout module from the Immutable SDK package
import { checkout } from '@imtbl/sdk';

// Import utility type for casting the sample provider
import { Web3Provider } from '@ethersproject/providers';

// Instantiate the Checkout SDKs with the default configurations
const checkoutSDK = new checkout.Checkout();

// The previous provider; here set as an empty object for sample purposes.
const provider = {} as Web3Provider;

// Get the wallet address from the provider and then get all its balances
// on zkEVM testnet.
provider
  .getSigner()
  .getAddress()
  .then((walletAddress) => {
    const chainId = checkout.ChainId.IMTBL_ZKEVM_TESTNET;
    checkoutSDK
      .getAllBalances({ provider, walletAddress, chainId })
      .then((resp) => console.log(resp));
  });

The GetAllBalancesResult result provides the list of tokens held by the wallet on target network and their balances.

The formattedBalance property is the balance value formatted using the token decimal property; this value should be used when showing the value to the application user.

ERC20 Token details

The Checkout SDK exposes the getTokenInfo() function that can be used to fetch the (ERC20) token details (e.g. symbol).

// Import the checkout module from the Immutable SDK package
import { checkout } from '@imtbl/sdk';

// Import utility type for casting the sample provider
import { Web3Provider } from '@ethersproject/providers';

// Instantiate the Checkout SDKs with the default configurations
const checkoutSDK = new checkout.Checkout();

// The provider connected to the chain with the token contract to query
// here set as an empty object for sample purposes.
const provider = {} as Web3Provider; // or JsonRpcProvider

// Get the wallet address from the provider and then get all its balances
// on zkEVM testnet.
const tokenAddress = "0xD61ffaece032CA6E0C469820707d677Feb4BEDD5"
checkoutSDK
  .getTokenInfo({ provider, tokenAddress })
  .then((resp) => console.log(resp));

The TokenInfo result provides an object containing the token details.

Get balance for a token

The SDK also offers the ability to get the balance of a token. This should be preferred above fetching all the balances if network latency is important and the need for the whole list of balances is optional.

In the example below, the getBalance() function is used to fetch the native token balance of the wallet associated to the provider.

// Import the checkout module from the Immutable SDK package
import { checkout } from '@imtbl/sdk';

// Import utility type for casting the sample provider
import { Web3Provider } from '@ethersproject/providers';

// Instantiate the Checkout SDKs with the default configurations
const checkoutSDK = new checkout.Checkout();

// The previous provider; here set as an empty object for sample purposes.
const provider = {} as Web3Provider;

// Get the wallet address from the provider and then get all its balances
// on zkEVM testnet.
provider
  .getSigner()
  .getAddress()
  .then((walletAddress) => {
    // Current wallet native balance. This is based on the connected network.
    // If the provider is connected to zkEVM then this value is the IMX
    // balance held by the wallet associated to the provider.
    // If the provider is connected to L1 (ethereum) this value is the amount
    // of ETH held by the wallet associated to the provider.
    checkoutSDK
      .getBalance({ provider, walletAddress })
      .then((resp) => console.log(resp));
  });

However, by providing the ERC token address as an input parameter, the getBalance() function will get the ERC20 token balance of the wallet associated to the provider.

// Import the checkout module from the Immutable SDK package
import { checkout } from '@imtbl/sdk';

// Import utility type for casting the sample provider
import { Web3Provider } from '@ethersproject/providers';

// Instantiate the Checkout SDKs with the default configurations
const checkoutSDK = new checkout.Checkout();

// The previous provider; here set as an empty object for sample purposes.
const provider = {} as Web3Provider;

// Get the wallet address from the provider and then get all its balances
// on zkEVM testnet.
provider
  .getSigner()
  .getAddress()
  .then((walletAddress) => {
    // Fetch the balance of a specific ERC20.
    const tokenAddress = '0x12345...';
    checkoutSDK
      .getBalance({ provider, walletAddress, tokenAddress })
      .then((resp) => console.log(resp));
  });

In both cases, the function returns the GetBalanceResult interface.