getTokenAccountBalance RPCメソッドは、特定のSPLトークンアカウントのトークン残高を返します。これは、トークンアカウントが保持している特定のトークン量を表示または確認する必要があるアプリケーションにとって重要です。
一般的な使用例
- ユーザートークン残高の表示: ユーザーにウォレット(関連するトークンアカウント)にどれだけの特定トークンを所有しているかを表示します。
- トークン利用可能性の確認: トークンアカウントに転送や他の操作を試みる前に十分な残高があるかを確認します。
- ポートフォリオの追跡: 異なるトークンアカウントにわたるユーザーのトークン残高を集計します。
- スマートコントラクトの相互作用: スマートコントラクトは、そのロジックの一部としてトークン残高をクエリするかもしれません(ただしオンチェーンプログラムは通常アカウント情報から直接このデータにアクセスします)。
リクエストパラメータ
- トークンアカウント公開鍵 (文字列, 必須): クエリしたいSPLトークンアカウントのbase-58エンコードされた公開鍵。
- 設定オブジェクト (オブジェクト, オプション): 以下のフィールドを含むことができるオプションのオブジェクト:
commitment(文字列, オプション): クエリのコミットメントレベルを指定します。省略された場合、RPCノードのデフォルトのコミットメントが使用されます(通常finalized)。
レスポンス構造
JSON-RPCレスポンスのresultフィールドには、contextとvalueフィールドを持つオブジェクトが含まれています。valueオブジェクトは残高情報を保持します:
amount(文字列): トークンアカウントの生の残高を文字列として示します。これはトークンの最小単位を表す整数です(例えば、トークンが6桁の小数を持つ場合、“1000000”は1トークンを意味します)。decimals(u8): このトークンタイプ(ミントによる)に定義された小数点以下の桁数。uiAmount(number | null):decimalsを考慮した上での浮動小数点数としてフォーマットされた残高。このフィールドは、あるコンテキストではnullかデプリケートされた場合があります。uiAmountString(文字列):decimalsを考慮した上での文字列としてフォーマットされた残高。表示にはこれが望ましいことが多く、浮動小数点の不正確さを避けるためにも使用されます。
コード例
開発者のヒント
- トークンアカウント対ミントアカウント対所有者アカウント: 公開鍵をSPLトークンアカウントのもの、トークンのミントアドレスまたは所有者のウォレットアドレスではないことを確認してください。通常、所有者については
getTokenAccountsByOwnerを使ってトークンアカウントを取得します。 - 小数: 常に
amountを正しく解釈するためにdecimalsフィールドを使用してください。表示にはFLOAT型の誤差を回避するためにuiAmountStringが一般に推奨されます。 - 存在しないアカウント: 提供された公開鍵が既存のトークンアカウントに対応していない場合、RPCプロバイダやライブラリによって動作が少し異なることがありますが、通常レスポンス内の
valueはnullかエラーがスローされることがあります。JavaScriptの例にはbalance.valueの基本チェックが含まれています。 - コミットメントレベル: 異なるコミットメントレベルを使用すると、特に最近のトランザクションに対して、どれだけ早く残高の変更が見られるかに影響を与えることがあります。
finalizedは最も安全ですが、最も遅延があることがあります。
getTokenAccountBalanceメソッドを使用してSPLトークンの残高を正確に取得し解釈するのに役立つはずです。
関連メソッド
getTokenAccountsByOwner
所有者のすべてのトークンアカウントを取得
getTokenSupply
トークンの総供給量を取得