如何使用 getTokenAccountBalance

​

常见用例

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

​

请求参数

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

• commitment（字符串，可选）：指定查询的承诺级别。如果省略，则使用 RPC 节点的默认承诺（通常是 finalized）。

​

响应结构

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

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

​

代码示例

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

​

开发者提示

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

​

相关方法