Skip to main content

Wallet Balance

swapper.Utils exposes fee-aware balance helpers for both smart chain wallets and Bitcoin wallets.

These helpers are meant for swap UIs and "Max" buttons. Unlike a raw RPC balance, they estimate how much can actually be used in a swap without leaving too little for network fees. This is especially important for the exact-input flows described in Creating Quotes and Executing Swaps.

The returned balances use the TokenAmount object type which makes it easy to show the balance in human-readable format, get the raw token amount or estimate the USD value of the amount.

Use SwapperUtils.getSpendableBalance() to get the spendable balance of a smart chain (i.e. Solana, Starknet, etc.) wallet, as is the case in the Smart Chain → BTC/Lightning flow. For native tokens such as SOL, STRK or the native token of an EVM chain, the SDK automatically deducts the estimated fee required to initiate the swap. The returned amount is therefore safe to use as a "Max" amount for exact-input swaps.

const strkBalance = await swapper.Utils.getSpendableBalance(
  starknetSigner,
  Tokens.STARKNET.STRK,
  {
    feeMultiplier: 1.1 // Optionally keep an extra 10% fee buffer
  }
);

console.log("Spendable balance:", strkBalance.toString());

For non-native tokens such as WBTC, transaction fees are paid in the native token of the chain, so the token balance itself is usually fully spendable. You can use the hasEnoughForTxFees() function to check if the source wallet has enough native token balance to cover the transaction fees for initiating the swap.

// Check if a ToBTCSwap or ToBTCLNSwap can be initiated
const {enoughBalance, balance, required} = await swap.hasEnoughForTxFees();
if (!enoughBalance) {
  console.log(`The source wallet has insufficient balance to execute the swap, required: ${required.toString()}, balance: ${balance.toString()}`);
}
warning

A large non-native token balance does not guarantee that the swap can be initiated. The wallet still needs enough native gas token balance. This matters even more in the legacy Solana flows, where even the destination side requires SOL for deposits or transaction fees. See Bitcoin → Solana and Lightning → Solana.

Swaps Using Max Balance​

Spendable balance helpers are most useful for estimating maximum amount of a swap source token that can be used for EXACT_IN-mode swaps. To create a swap spending the full balance of a wallet you can use the following:

import {SwapAmountType} from "@atomiqlabs/sdk";

// Get the spendable balance of the signer
const maxSpendable = await swapper.Utils.getSpendableBalance(
  starknetSigner,
  Tokens.STARKNET.STRK
);

// Create an EXACT_IN swap spending the full wallet balance
const swap = await swapper.swap(
  Tokens.STARKNET.STRK,
  Tokens.BITCOIN.BTC,
  maxSpendable.amount,
  SwapAmountType.EXACT_IN,
  starknetSigner.getAddress(),
  btcAddress
);
info

In your UI you can hook the getBitcoinSpendableBalance() and getSpendableBalance functions to recompute on state changes, i.e. if the source/destination chain types change or gas drop request is toggled.

API Reference​