> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbitflare.com/llms.txt
> Use this file to discover all available pages before exploring further.

# getTokenAccountBalance

> Returns the token balance of an account

## Parameters

<ResponseField name="pubkey" type="string" required>
  Public key of the token account (base-58 encoded)
</ResponseField>

<ResponseField name="config" type="object" optional>
  Configuration object containing:

  <ResponseField name="commitment" type="string" optional>
    Commitment level (processed, confirmed, finalized)
  </ResponseField>
</ResponseField>

## Response

<ResponseField name="result" type="object">
  Object containing:

  <ResponseField name="context" type="object">
    <ResponseField name="slot" type="number">
      The slot the request was processed at
    </ResponseField>
  </ResponseField>

  <ResponseField name="value" type="object">
    <ResponseField name="amount" type="string">
      Raw amount of tokens as a string
    </ResponseField>

    <ResponseField name="decimals" type="number">
      Number of decimals configured for token's mint
    </ResponseField>

    <ResponseField name="uiAmount" type="number" optional>
      Token amount as a float, accounting for decimals
    </ResponseField>

    <ResponseField name="uiAmountString" type="string" optional>
      Token amount as a string, accounting for decimals
    </ResponseField>
  </ResponseField>
</ResponseField>

## Code Examples

### Basic Request

```bash theme={null}
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

```typescript theme={null}
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

| Code   | Message                 | Solution                                     |
| ------ | ----------------------- | -------------------------------------------- |
| -32601 | Method not found        | Verify you're connected to a Solana RPC node |
| -32602 | Invalid params          | Check token account public key               |
| -32007 | Token account not found | Verify the token account exists              |
| -32008 | Invalid token account   | Verify the account is a valid token account  |

## Use Cases

1. **Token Balance Analysis**
   ```typescript theme={null}
   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**
   ```typescript theme={null}
   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**
   ```typescript theme={null}
   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
         }
       };
     }
   }
   ```