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

# 如何使用 getTokenAccountBalance

> 了解 getTokenAccountBalance 的使用案例、代码示例、请求参数、响应结构和提示。

[`getTokenAccountBalance`](https://www.helius.dev/docs/api-reference/rpc/http/gettokenaccountbalance) RPC 方法返回特定 SPL Token 帐户的代币余额。这对于需要显示或验证代币帐户持有的特定代币数量的应用程序至关重要。

## 常见用例

* **显示用户代币余额：** 向用户展示他们在钱包（关联代币账户）中拥有多少特定代币。
* **验证代币可用性：** 在尝试转账或其他操作之前，检查代币账户是否有足够的余额。
* **投资组合跟踪：** 汇总用户在不同代币账户中的代币余额。
* **智能合约交互：** 智能合约可能会查询代币余额作为其逻辑的一部分（尽管链上程序通常直接从账户信息中访问此数据）。

## 请求参数

1. **代币账户公钥**（字符串，必填）：要查询的 SPL Token 账户的 base-58 编码公钥。
2. **配置对象**（对象，可选）：一个可选对象，可以包含以下字段：

* **`commitment`**（字符串，可选）：指定查询的[承诺级别](https://www.helius.dev/blog/solana-commitment-levels)。如果省略，则使用 RPC 节点的默认承诺（通常是 `finalized`）。

## 响应结构

JSON-RPC 响应中的 `result` 字段包含一个具有 `context` 和 `value` 字段的对象。`value` 对象持有余额信息：

* **`amount`**（字符串）：代币账户的原始余额，作为字符串表示。这是表示代币最小单位的整数（例如，如果代币有 6 位小数，则“1000000”表示 1 个代币）。
* **`decimals`**（u8）：为此代币类型定义的小数位数（由其 mint 决定）。
* **`uiAmount`**（数字 | null）：根据 `decimals` 计算的浮点数格式的余额。在某些情况下，此字段可能为 `null` 或者在某些上下文中被弃用，优先于 `uiAmountString`。
* **`uiAmountString`**（字符串）：根据 `decimals` 计算的字符串格式的余额。为了避免潜在的浮点不准确，这通常是优先用于显示的。

**示例响应：**

```json theme={"system"}
{
  "jsonrpc": "2.0",
  "result": {
    "context": {
      "slot": 183457201
    },
    "value": {
      "amount": "500000000",
      "decimals": 9,
      "uiAmount": 0.5,
      "uiAmountString": "0.5"
    }
  },
  "id": 1
}
```

## 代码示例

<CodeGroup>
  ```bash cURL theme={"system"}
  # Basic Request (replace <TOKEN_ACCOUNT_PUBKEY>):
  curl -X POST -H "Content-Type: application/json" -d \
    '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "getTokenAccountBalance",
      "params": [
        "<TOKEN_ACCOUNT_PUBKEY>"
      ]
    }' \
    <YOUR_RPC_URL>

  # Request with commitment (replace <TOKEN_ACCOUNT_PUBKEY>):
  curl -X POST -H "Content-Type: application/json" -d \
    '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "getTokenAccountBalance",
      "params": [
        "<TOKEN_ACCOUNT_PUBKEY>",
        {
          "commitment": "confirmed"
        }
      ]
    }' \
    <YOUR_RPC_URL>
  ```

  ```javascript JavaScript (using @solana/web3.js) theme={"system"}
  const { Connection, PublicKey } = require('@solana/web3.js');

  async function checkTokenBalance(tokenAccountPublicKey) {
    // Replace with your RPC endpoint
    const connection = new Connection('https://mainnet.helius-rpc.com/?api-key=<api-key>');
    
    try {
      const tokenAccountPubKey = new PublicKey(tokenAccountPublicKey);
      const balance = await connection.getTokenAccountBalance(tokenAccountPubKey);

      if (!balance.value) {
          console.log(`Could not find token account: ${tokenAccountPublicKey}`);
          return;
      }

      console.log(`Token Account: ${tokenAccountPublicKey}`);
      console.log(`Raw Amount: ${balance.value.amount}`);
      console.log(`Decimals: ${balance.value.decimals}`);
      console.log(`UI Amount (string): ${balance.value.uiAmountString}`);
      // console.log(JSON.stringify(balance, null, 2)); // For full response details

    } catch (error) {
      console.error(`Error fetching token account balance for ${tokenAccountPublicKey}:`, error);
    }
  }

  // Replace with an actual SPL Token Account Public Key
  const exampleTokenAccount = 'HHisAGTT6ADDd52jY1g65Akn3N2f4jSdQS2rTiyDEw5c'; // Example: An account holding some USDC on mainnet
  checkTokenBalance(exampleTokenAccount);

  // Example for a token account that might not exist or have 0 balance
  // const nonExistentAccount = '11111111111111111111111111111111'; 
  // checkTokenBalance(nonExistentAccount);
  ```
</CodeGroup>

## 开发者提示

* **代币账户 vs. 铸造账户 vs. 拥有者账户：** 确保您提供的是*SPL代币账户*的公钥，而不是代币的*铸造地址*或*拥有者的钱包地址*。通常，您可以使用 `getTokenAccountsByOwner` 获取拥有者的代币账户。
* **小数位：** 始终使用 `decimals` 字段来正确解释 `amount`。为了避免浮点精度问题，显示时一般更安全的是使用 `uiAmountString` 而非 `uiAmount`。
* **不存在的账户：** 如果提供的公钥未对应到现有的代币账户，行为可能会根据RPC提供商或库稍有不同，但通常响应中的 `value` 会是 `null` 或抛出错误。JavaScript示例中包含对 `balance.value` 的基本检查。
* **承诺水平：** 使用不同的承诺水平可能影响您看到余额变动的速度，尤其是对于非常近期的交易。`finalized` 是最安全的，但延迟最大。

本指南应能帮助您使用 `getTokenAccountBalance` 方法准确获取并解释 SPL 代币余额。

## 相关方法

<CardGroup cols={2}>
  <Card title="getTokenAccountsByOwner" href="/docs/zh/api-reference/rpc/http/gettokenaccountsbyowner">
    获取拥有者的所有代币账户
  </Card>

  <Card title="getTokenSupply" href="/docs/zh/api-reference/rpc/http/gettokensupply">
    获取代币铸造的总供应量
  </Card>
</CardGroup>