The Token Plugin provides three functions for checking balances, each optimized for different use cases.
get_balance
Get the balance of SOL or an SPL token for the agent’s wallet.
Function signature
function get_balance(
agent: SolanaAgentKit,
token_address?: PublicKey
): Promise<number>
Parameters
The agent instance containing wallet and connection information
Optional SPL token mint address. If not provided, returns SOL balance in UI units (not lamports)
Returns
The balance in UI units (for SOL: actual SOL amount, not lamports; for tokens: amount based on token decimals)
Example usage
import { get_balance } from '@/utils/syntoUtils/agent/plugins/plugin-token/solana/tools';
const solBalance = await get_balance(agent);
console.log(`SOL Balance: ${solBalance}`);
// Output: SOL Balance: 2.5
Implementation details
For SOL balances, the function queries the network and converts lamports to SOL:
const lamports = await agent.connection.getBalance(agent.wallet.publicKey);
return lamports / LAMPORTS_PER_SOL;
const tokenAccount = await agent.connection.getTokenAccountBalance(token_address);
return tokenAccount.value.uiAmount || 0;
The function returns 0 if a token account doesn’t exist, rather than throwing an error.
get_balance_other
Get the balance of SOL or an SPL token for any wallet address (not just the agent’s wallet).
Function signature
function get_balance_other(
agent: SolanaAgentKit,
wallet_address: PublicKey,
token_address?: PublicKey
): Promise<number>
Parameters
The agent instance used for blockchain connection
The wallet address to check balance for
Optional SPL token mint address. If not provided, returns SOL balance
Returns
The balance in UI units, or 0 if the account doesn’t exist
Example usage
import { get_balance_other } from '@/utils/syntoUtils/agent/plugins/plugin-token/solana/tools';
import { PublicKey } from '@solana/web3.js';
const otherWallet = new PublicKey('8x2dR8Mpzuz2YqyZyZjUbYWKSWesBo5jMx2Q9Y86udVk');
const balance = await get_balance_other(agent, otherWallet);
console.log(`Wallet ${otherWallet.toBase58()} has ${balance} SOL`);
Error handling
The function throws descriptive errors if the balance check fails:
try {
const balance = await get_balance_other(agent, walletAddress, tokenMint);
} catch (error) {
console.error(`Error fetching balance: ${error.message}`);
}
If no token accounts are found for the specified mint, the function logs a warning and returns 0 instead of throwing an error.
get_token_balance
Get comprehensive token balances for a wallet, including SOL and all SPL tokens with metadata.
Function signature
function get_token_balance(
agent: SolanaAgentKit,
walletAddress?: PublicKey
): Promise<{
sol: number;
tokens: Array<{
tokenAddress: string;
name: string;
symbol: string;
balance: number;
decimals: number;
}>;
}>
Parameters
The agent instance for blockchain connection
The wallet address to check. Defaults to the agent’s wallet if not provided
Returns
The SOL balance in UI units
Array of token balances with metadata. Zero-balance tokens are automatically filtered out.Show Token object properties
The SPL token mint address
The token’s full name (e.g., “USD Coin”)
The token’s ticker symbol (e.g., “USDC”)
The token balance in UI units
The number of decimals the token uses
Example usage
import { get_token_balance } from '@/utils/syntoUtils/agent/plugins/plugin-token/solana/tools';
const balances = await get_token_balance(agent);
console.log(`SOL: ${balances.sol}`);
console.log('\nTokens:');
balances.tokens.forEach(token => {
console.log(`${token.symbol}: ${token.balance}`);
});
Implementation details
The function performs the following steps:
- Queries SOL balance and all token accounts in parallel for efficiency
- Filters out zero-balance token accounts
- Fetches metadata (name, symbol) for each token mint
- Returns a structured object with all balances and metadata
const [lamportsBalance, tokenAccountData] = await Promise.all([
agent.connection.getBalance(walletAddress ?? agent.wallet.publicKey),
agent.connection.getParsedTokenAccountsByOwner(
walletAddress ?? agent.wallet.publicKey,
{ programId: TOKEN_PROGRAM_ID }
)
]);
This function is ideal for building portfolio views or wallet dashboards, as it returns all necessary information in a single call.
Additional utilities
getWalletAddress
Get the agent’s wallet address as a base58-encoded string.
import { getWalletAddress } from '@/utils/syntoUtils/agent/plugins/plugin-token/solana/tools';
const address = getWalletAddress(agent);
console.log(`Wallet address: ${address}`);
// Output: Wallet address: 8x2dR8Mpzuz2YqyZyZjUbYWKSWesBo5jMx2Q9Y86udVk
getTPS
Get the current Solana network transactions per second.
import { getTPS } from '@/utils/syntoUtils/agent/plugins/plugin-token/solana/tools';
const tps = await getTPS(agent);
console.log(`Network TPS: ${tps.toFixed(2)}`);
// Output: Network TPS: 3456.78
getTPS throws an error if no performance samples are available from the network.
request_faucet_funds
Request 5 SOL from the Solana faucet (devnet/testnet only).
import { request_faucet_funds } from '@/utils/syntoUtils/agent/plugins/plugin-token/solana/tools';
const signature = await request_faucet_funds(agent);
console.log(`Airdrop signature: ${signature}`);
This function only works on devnet and testnet. It will fail on mainnet-beta.
Best practices
Use the right function for your use case
- Use
get_balance() for quick checks of the agent’s own balance
- Use
get_balance_other() when you need to check other wallets
- Use
get_token_balance() when building portfolio views or dashboards
Handle zero balances gracefully
All balance functions return 0 for non-existent accounts instead of throwing errors. Always check for zero balances in your UI:const balance = await get_balance(agent, tokenMint);
if (balance === 0) {
console.log('No balance or account does not exist');
}
Cache balance data when appropriate
Balance queries require network calls. Consider caching results for a few seconds if you’re displaying balances in a frequently-updated UI:let cachedBalance: number | null = null;
let cacheTime: number = 0;
const CACHE_DURATION = 5000; // 5 seconds
async function getCachedBalance() {
if (cachedBalance && Date.now() - cacheTime < CACHE_DURATION) {
return cachedBalance;
}
cachedBalance = await get_balance(agent);
cacheTime = Date.now();
return cachedBalance;
}
Next steps
Transfer functions
Learn how to transfer SOL and SPL tokens
Jupiter integration
Swap tokens using Jupiter Exchange