suix_getBalance - Query Coin Balances
Get coin balances for any address on Sui blockchain. Query SUI tokens and custom coins with Dwellir's high-performance Sui RPC infrastructure.
Returns the total balance of a specific coin type for a given address on the Sui network.
Overview
The suix_getBalance method provides a simple way to query the total balance of any coin type owned by an address. This includes native SUI tokens and any custom fungible tokens created on the Sui blockchain. The method aggregates all coin objects of the specified type and returns the total balance.
Code Examples
Practical Examples
Portfolio Balance Tracker
async function getPortfolioBalances(address) {
const tokens = [
{
type: '0x2::sui::SUI',
symbol: 'SUI',
decimals: 9
},
{
type: '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC',
symbol: 'USDC',
decimals: 6
},
{
type: '0x549e8b69270defbfafd4f94e17ec44cdbdd99820b33bda2278dea3b9a32d3f55::cert::CERT',
symbol: 'wUSDT',
decimals: 6
}
];
const balances = {};
for (const token of tokens) {
try {
const balance = await client.getBalance({
owner: address,
coinType: token.type
});
balances[token.symbol] = {
raw: balance.totalBalance,
formatted: Number(balance.totalBalance) / Math.pow(10, token.decimals),
coinCount: balance.coinObjectCount
};
} catch (error) {
balances[token.symbol] = {
raw: '0',
formatted: 0,
coinCount: 0
};
}
}
return balances;
}Balance Monitoring with Threshold Alerts
async function monitorBalance(address, threshold, coinType = '0x2::sui::SUI') {
const balance = await client.getBalance({
owner: address,
coinType: coinType
});
const balanceInSUI = Number(balance.totalBalance) / 1_000_000_000;
if (balanceInSUI < threshold) {
console.warn(`⚠️ Low balance alert!`);
console.warn(`Current balance: ${balanceInSUI} SUI`);
console.warn(`Threshold: ${threshold} SUI`);
// Send notification
await sendLowBalanceNotification(address, balanceInSUI, threshold);
}
return {
isLow: balanceInSUI < threshold,
current: balanceInSUI,
threshold: threshold
};
}Multi-Address Balance Aggregation
async function getAggregatedBalance(addresses, coinType = '0x2::sui::SUI') {
let totalBalance = BigInt(0);
let totalCoinCount = 0;
const addressBalances = [];
for (const address of addresses) {
const balance = await client.getBalance({
owner: address,
coinType: coinType
});
totalBalance += BigInt(balance.totalBalance);
totalCoinCount += balance.coinObjectCount;
addressBalances.push({
address: address,
balance: balance.totalBalance,
coinCount: balance.coinObjectCount
});
}
return {
totalBalance: totalBalance.toString(),
totalCoinCount: totalCoinCount,
addressBalances: addressBalances,
averageBalance: (totalBalance / BigInt(addresses.length)).toString()
};
}Working with Different Coin Types
Discovering Coin Types
// First get all coins owned by address
const coins = await client.getAllCoins({
owner: address
});
// Extract unique coin types
const coinTypes = [...new Set(coins.data.map(coin => coin.coinType))];
// Get balance for each type
for (const coinType of coinTypes) {
const balance = await client.getBalance({
owner: address,
coinType: coinType
});
console.log(`${coinType}: ${balance.totalBalance}`);
}Handling Coin Metadata
async function getBalanceWithMetadata(address, coinType) {
// Get balance
const balance = await client.getBalance({
owner: address,
coinType: coinType
});
// Get coin metadata for decimals and symbol
const metadata = await client.getCoinMetadata({
coinType: coinType
});
// Calculate formatted balance
const formatted = Number(balance.totalBalance) /
Math.pow(10, metadata.decimals);
return {
...balance,
metadata: metadata,
formattedBalance: formatted,
displayString: `${formatted} ${metadata.symbol}`
};
}Locked Balance Information
The lockedBalance field appears when tokens are locked (e.g., in staking):
const balance = await client.getBalance({
owner: address,
coinType: '0x2::sui::SUI'
});
if (balance.lockedBalance) {
console.log('Locked Balance:', {
amount: balance.lockedBalance.number,
epochId: balance.lockedBalance.epochId,
unlockEpoch: balance.lockedBalance.epochId + 1
});
const availableBalance =
BigInt(balance.totalBalance) - BigInt(balance.lockedBalance.number);
console.log('Available balance:', availableBalance.toString());
}Performance Optimization
Batch Balance Queries
async function batchGetBalances(address, coinTypes) {
// Use Promise.all for parallel queries
const balancePromises = coinTypes.map(coinType =>
client.getBalance({ owner: address, coinType })
.catch(err => ({
coinType: coinType,
totalBalance: '0',
coinObjectCount: 0,
error: err.message
}))
);
const balances = await Promise.all(balancePromises);
return balances.reduce((acc, balance, index) => {
acc[coinTypes[index]] = balance;
return acc;
}, {});
}Related Methods
- sui_executeTransactionBlock - Execute transactions with coins
- sui_getObject - Get detailed object information
Best Practices
- Cache coin metadata to avoid repeated calls for decimals and symbols
- Handle zero balances gracefully for non-existent coin types
- Use BigInt for arithmetic operations to avoid precision loss
- Implement retry logic for network failures
- Batch queries when checking multiple coin types
Need help? Contact our support team or check the Sui documentation.
suix_getAllBalances - Get All Coin Balan...
Retrieve all coin balances for any Sui address using suix_getAllBalances RPC method. Get comprehensive portfolio overview with native SUI and custom tokens using Dwellir's high-performance Sui infrastructure.
suix_getCoinMetadata - Get Coin Metadata
Get comprehensive metadata for any coin type on Sui blockchain including decimals, symbol, name, and icon URL using Dwellir's high-performance Sui RPC infrastructure.