getTokenAccountBalance RPC 方法返回特定 SPL Token 账户的代币余额。这对于需要显示或验证代币账户持有的特定代币数量的应用程序至关重要。

​
常见用例

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

​
请求参数

  1. 代币账户公钥（字符串，必需）：要查询的 SPL Token 账户的 base-58 编码公钥。
  2. 配置对象（对象，可选）：一个可选对象，可以包含以下字段：
    • commitment（字符串，可选）：指定查询的承诺级别。如果省略，则使用 RPC 节点的默认承诺（通常为 finalized）。

​
响应结构

JSON-RPC 响应中的 result 字段包含一个对象，该对象具有 context 和 value 字段。value 对象包含余额信息：
  • amount（字符串）：代币账户的原始余额，作为字符串表示。这是一个整数，代表代币的最小单位（例如，如果代币有 6 位小数，“1000000” 表示 1 个代币）。
  • decimals（u8）：为此代币类型（由其铸造）定义的小数位数。
  • 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>

​
开发者提示

  • Token Account vs. Mint Account vs. Owner Account: 确保您提供的是 SPL Token Account 的公钥，而不是代币的 mint address 或 owner’s wallet address。您通常可以使用 getTokenAccountsByOwner 获取所有者的代币账户。
  • Decimals: 始终使用 decimals 字段来正确解释 amount。为了避免浮点精度问题，uiAmountString 通常比 uiAmount 更安全用于显示。
  • Non-Existent Accounts: 如果提供的公钥不对应于现有的代币账户，行为可能会因 RPC 提供者或库而略有不同，但通常响应中的 value 将是 null 或会抛出错误。JavaScript 示例中包括对 balance.value 的基本检查。
  • Commitment Levels: 使用不同的承诺级别会影响您看到余额变化的速度，尤其是对于非常近期的交易。finalized 是最安全的，但延迟最大。
本指南应帮助您使用 getTokenAccountBalance 方法准确检索和解释 SPL 代币余额。