getTokenAccountBalance

​

Parameters

​

Response

​

Code Examples

​

Basic Request

curl https://fra.rpc.orbitflare.com?api_key=YOUR-API-KEY -X POST -H "Content-Type: application/json" -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getTokenAccountBalance",
  "params": [
    "4vJ9JU1bJJE96FWSJKvHsmmFADCg4gpZQff4P3bkLZj"
  ]
}'

​

Using web3.js

import { Connection, PublicKey } from '@solana/web3.js';

const connection = new Connection('https://fra.rpc.orbitflare.com?api_key=YOUR-API-KEY');

// Get token account balance
const tokenAccount = new PublicKey('4vJ9JU1bJJE96FWSJKvHsmmFADCg4gpZQff4P3bkLZj');
const balance = await connection.getTokenAccountBalance(tokenAccount);
console.log('Token balance:', balance);

// Get token account balance with analysis
async function getTokenAccountBalanceWithAnalysis(
  tokenAccount: PublicKey,
  config?: { commitment?: string }
) {
  const balance = await connection.getTokenAccountBalance(tokenAccount, config);
  
  return {
    balance,
    analysis: {
      rawAmount: balance.value.amount,
      uiAmount: balance.value.uiAmount,
      uiAmountString: balance.value.uiAmountString,
      decimals: balance.value.decimals,
      metadata: {
        timestamp: Date.now(),
        commitment: config?.commitment
      }
    }
  };
}

​

Notes

1. Returns the token balance of a token account
2. The balance is returned in both raw and UI-friendly formats
3. The response is immediate as it reads from the current state
4. The balance can change with token transfers and other operations
5. The account must be a valid token account

​

Best Practices

1. Use appropriate commitment level based on your needs
2. Cache results when appropriate to reduce RPC load
3. Monitor for changes in token balances
4. Consider using websocket subscription for real-time updates
5. Handle network errors and retry when appropriate

​

Common Errors

​

Use Cases

1. Token Balance Analysis
   interface TokenBalanceAnalysis {
     account: string;
     balance: {
       raw: string;
       ui: number;
       decimals: number;
     };
     metrics: {
       valueInUSD?: number;
       percentageChange?: number;
       historicalData?: Array<{
         timestamp: number;
         balance: number;
       }>;
     };
     metadata: {
       timestamp: number;
       commitment?: string;
     };
   }
   
   class TokenBalanceAnalyzer {
     private readonly tokenPrice: number = 1; // Replace with actual token price
     private historicalBalances: Array<{
       timestamp: number;
       balance: number;
     }> = [];
     
     async analyzeTokenBalance(
       tokenAccount: PublicKey,
       config?: { commitment?: string }
     ): Promise<TokenBalanceAnalysis> {
       const balance = await connection.getTokenAccountBalance(tokenAccount, config);
       const currentTimestamp = Date.now();
       
       this.historicalBalances.push({
         timestamp: currentTimestamp,
         balance: balance.value.uiAmount || 0
       });
       
       // Keep only last 24 hours of data
       const oneDayAgo = currentTimestamp - 24 * 60 * 60 * 1000;
       this.historicalBalances = this.historicalBalances.filter(
         data => data.timestamp >= oneDayAgo
       );
       
       const metrics = {
         valueInUSD: (balance.value.uiAmount || 0) * this.tokenPrice,
         historicalData: this.historicalBalances
       };
       
       if (this.historicalBalances.length > 1) {
         const oldestBalance = this.historicalBalances[0].balance;
         const newestBalance = this.historicalBalances[this.historicalBalances.length - 1].balance;
         metrics.percentageChange = ((newestBalance - oldestBalance) / oldestBalance) * 100;
       }
       
       return {
         account: tokenAccount.toBase58(),
         balance: {
           raw: balance.value.amount,
           ui: balance.value.uiAmount || 0,
           decimals: balance.value.decimals
         },
         metrics,
         metadata: {
           timestamp: currentTimestamp,
           commitment: config?.commitment
         }
       };
     }
   }
   
2. Token Balance Monitoring
   interface TokenBalanceChange {
     account: string;
     previousBalance: {
       raw: string;
       ui: number;
     };
     currentBalance: {
       raw: string;
       ui: number;
     };
     change: {
       raw: string;
       ui: number;
     };
     metadata: {
       timestamp: number;
     };
   }
   
   class TokenBalanceMonitor {
     private previousBalances: Map<string, {
       raw: string;
       ui: number;
     }> = new Map();
     
     async monitorTokenBalance(
       tokenAccount: PublicKey,
       config?: { commitment?: string }
     ): Promise<TokenBalanceChange | null> {
       const balance = await connection.getTokenAccountBalance(tokenAccount, config);
       const accountKey = tokenAccount.toBase58();
       const previous = this.previousBalances.get(accountKey);
       
       if (!previous) {
         this.previousBalances.set(accountKey, {
           raw: balance.value.amount,
           ui: balance.value.uiAmount || 0
         });
         return null;
       }
       
       if (previous.raw !== balance.value.amount) {
         const change: TokenBalanceChange = {
           account: accountKey,
           previousBalance: previous,
           currentBalance: {
             raw: balance.value.amount,
             ui: balance.value.uiAmount || 0
           },
           change: {
             raw: (BigInt(balance.value.amount) - BigInt(previous.raw)).toString(),
             ui: (balance.value.uiAmount || 0) - previous.ui
           },
           metadata: {
             timestamp: Date.now()
           }
         };
         
         this.previousBalances.set(accountKey, {
           raw: balance.value.amount,
           ui: balance.value.uiAmount || 0
         });
         
         return change;
       }
       
       return null;
     }
   }
   
3. Token Balance Planning
   interface TokenBalancePlan {
     account: string;
     currentBalance: {
       raw: string;
       ui: number;
     };
     projections: Array<{
       days: number;
       balance: number;
       growth: number;
     }>;
     metadata: {
       timestamp: number;
       growthRate: number;
     };
   }
   
   class TokenBalancePlanner {
     private readonly defaultGrowthRate = 0.05; // 5% daily growth
     
     async planTokenBalance(
       tokenAccount: PublicKey,
       config?: { commitment?: string },
       days: number[] = [7, 30, 90]
     ): Promise<TokenBalancePlan> {
       const balance = await connection.getTokenAccountBalance(tokenAccount, config);
       const currentTimestamp = Date.now();
       
       const projections = days.map(daysAhead => {
         const currentBalance = balance.value.uiAmount || 0;
         const projectedBalance = currentBalance * Math.pow(1 + this.defaultGrowthRate, daysAhead);
         
         return {
           days: daysAhead,
           balance: projectedBalance,
           growth: projectedBalance - currentBalance
         };
       });
       
       return {
         account: tokenAccount.toBase58(),
         currentBalance: {
           raw: balance.value.amount,
           ui: balance.value.uiAmount || 0
         },
         projections,
         metadata: {
           timestamp: currentTimestamp,
           growthRate: this.defaultGrowthRate
         }
       };
     }
   }