> ## 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トークンアカウントのトークン残高を返します。これは、トークンアカウントが保持している特定のトークン量を表示または確認する必要があるアプリケーションにとって重要です。

## 一般的な使用例

* **ユーザートークン残高の表示:** ユーザーにウォレット（関連するトークンアカウント）にどれだけの特定トークンを所有しているかを表示します。
* **トークン利用可能性の確認:** トークンアカウントに転送や他の操作を試みる前に十分な残高があるかを確認します。
* **ポートフォリオの追跡:** 異なるトークンアカウントにわたるユーザーのトークン残高を集計します。
* **スマートコントラクトの相互作用:** スマートコントラクトは、そのロジックの一部としてトークン残高をクエリするかもしれません（ただしオンチェーンプログラムは通常アカウント情報から直接このデータにアクセスします）。

## リクエストパラメータ

1. **トークンアカウント公開鍵** (文字列, 必須): クエリしたいSPLトークンアカウントの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): このトークンタイプ（ミントによる）に定義された小数点以下の桁数。
* **`uiAmount`** (number | null): `decimals`を考慮した上での浮動小数点数としてフォーマットされた残高。このフィールドは、あるコンテキストでは`null`かデプリケートされた場合があります。
* **`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>

## 開発者のヒント

* **トークンアカウント対ミントアカウント対所有者アカウント:** 公開鍵を*SPLトークンアカウント*のもの、トークンの*ミントアドレス*または*所有者のウォレットアドレス*ではないことを確認してください。通常、所有者については`getTokenAccountsByOwner`を使ってトークンアカウントを取得します。
* **小数:** 常に`amount`を正しく解釈するために`decimals`フィールドを使用してください。表示にはFLOAT型の誤差を回避するために`uiAmountString`が一般に推奨されます。
* **存在しないアカウント:** 提供された公開鍵が既存のトークンアカウントに対応していない場合、RPCプロバイダやライブラリによって動作が少し異なることがありますが、通常レスポンス内の`value`は`null`かエラーがスローされることがあります。JavaScriptの例には`balance.value`の基本チェックが含まれています。
* **コミットメントレベル:** 異なるコミットメントレベルを使用すると、特に最近のトランザクションに対して、どれだけ早く残高の変更が見られるかに影響を与えることがあります。`finalized`は最も安全ですが、最も遅延があることがあります。

このガイドは、`getTokenAccountBalance`メソッドを使用してSPLトークンの残高を正確に取得し解釈するのに役立つはずです。

## 関連メソッド

<CardGroup cols={2}>
  <Card title="getTokenAccountsByOwner" href="/ja/api-reference/rpc/http/gettokenaccountsbyowner">
    所有者のすべてのトークンアカウントを取得
  </Card>

  <Card title="getTokenSupply" href="/ja/api-reference/rpc/http/gettokensupply">
    トークンの総供給量を取得
  </Card>
</CardGroup>