> ## 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

> 返回账户的代币余额

## 参数

<ResponseField name="pubkey" type="string" required>
  代币账户的公钥（base-58 编码）
</ResponseField>

<ResponseField name="config" type="object" optional>
  包含以下内容的配置对象：

  <ResponseField name="commitment" type="string" optional>
    Commitment 级别（processed、confirmed、finalized）
  </ResponseField>
</ResponseField>

## 响应

<ResponseField name="result" type="object">
  包含以下内容的对象：

  <ResponseField name="context" type="object">
    <ResponseField name="slot" type="number">
      处理请求时的 slot
    </ResponseField>
  </ResponseField>

  <ResponseField name="value" type="object">
    <ResponseField name="amount" type="string">
      代币的原始数量（字符串格式）
    </ResponseField>

    <ResponseField name="decimals" type="number">
      代币铸造配置的小数位数
    </ResponseField>

    <ResponseField name="uiAmount" type="number" optional>
      考虑小数位数后的代币数量（浮点数）
    </ResponseField>

    <ResponseField name="uiAmountString" type="string" optional>
      考虑小数位数后的代币数量（字符串）
    </ResponseField>
  </ResponseField>
</ResponseField>

## 代码示例

### 基本请求

```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"
  ]
}'
```

### 使用 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
      }
    }
  };
}
```

## 注意事项

1. 返回代币账户的代币余额
2. 余额以原始格式和用户友好格式返回
3. 响应是即时的，因为它从当前状态读取
4. 余额可能随代币转账和其他操作而变化
5. 账户必须是有效的代币账户

## 最佳实践

1. 根据需求使用适当的 commitment 级别
2. 在适当时缓存结果以减少 RPC 负载
3. 监控代币余额的变化
4. 考虑使用 WebSocket 订阅获取实时更新
5. 适当处理网络错误并重试

## 常见错误

| 错误码    | 消息                      | 解决方案                  |
| ------ | ----------------------- | --------------------- |
| -32601 | Method not found        | 验证是否连接到 Solana RPC 节点 |
| -32602 | Invalid params          | 检查代币账户公钥              |
| -32007 | Token account not found | 验证代币账户是否存在            |
| -32008 | Invalid token account   | 验证账户是否是有效的代币账户        |

## 用例

1. **代币余额分析**
   ```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. **代币余额监控**
   ```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. **代币余额规划**
   ```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
         }
       };
     }
   }
   ```