Balance operations

Check SOL and SPL token balances for any Solana wallet address

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

agent · SolanaAgentKit · required

The agent instance containing wallet and connection information

token_address · PublicKey

Optional SPL token mint address. If not provided, returns SOL balance in UI units (not lamports)

Returns

balance · number

The balance in UI units (for SOL: actual SOL amount, not lamports; for tokens: amount based on token decimals)

Example usage

Check SOL balance

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;

For SPL tokens, it retrieves the token account balance directly:

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

agent · SolanaAgentKit · required

The agent instance used for blockchain connection

wallet_address · PublicKey · required

The wallet address to check balance for

token_address · PublicKey

Optional SPL token mint address. If not provided, returns SOL balance

Returns

balance · number

The balance in UI units, or 0 if the account doesn’t exist

Example usage

Check another wallet's SOL

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

agent · SolanaAgentKit · required

The agent instance for blockchain connection

walletAddress · PublicKey

The wallet address to check. Defaults to the agent’s wallet if not provided

Returns

sol · number

The SOL balance in UI units

tokens · array

Array of token balances with metadata. Zero-balance tokens are automatically filtered out.

Show Token object properties

tokenAddress · string

The SPL token mint address

name · string

The token’s full name (e.g., “USD Coin”)

symbol · string

The token’s ticker symbol (e.g., “USDC”)

balance · number

The token balance in UI units

decimals · number

The number of decimals the token uses

Example usage

Get all balances

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:

1. Queries SOL balance and all token accounts in parallel for efficiency
2. Filters out zero-balance token accounts
3. Fetches metadata (name, symbol) for each token mint
4. 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