useGetTokenBalancesDetails

複数チェーンに対応した、メタデータを含むトークン残高の詳細を取得するためのフック

​

インポート

import { useGetTokenBalancesDetails } from '@0xsequence/hooks'

​

使い方

import React from 'react'
import { useGetTokenBalancesDetails } from '@0xsequence/hooks'
import { ContractVerificationStatus } from '@0xsequence/connect'
import { useAccount } from 'wagmi'

function TokenPortfolio() {
  const { address } = useAccount()
  
  const {
    data: tokens,
    isLoading,
    isError
  } = useGetTokenBalancesDetails({
    chainIds: [1, 137], // Ethereum and Polygon
    filter: {
      accountAddresses: [address || ''],
      omitNativeBalances: false,
      contractStatus: ContractVerificationStatus.VERIFIED,
      // Optional: include only specific tokens
      contractWhitelist: [
        '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', // USDC
        '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2'  // WETH
      ]
    }
  })

  if (isLoading) return <div>Loading portfolio...</div>
  if (isError) return <div>Error loading portfolio</div>

  return (
    <div>
      {tokens?.map(token => (
        <div key={`${token.chainId}-${token.contractAddress}-${token.tokenID}`}>
          {token.contractType === 'ERC721' || token.contractType === 'ERC1155' ? (
            // NFT display
            <div className="nft-card">
              <img 
                src={token.tokenMetadata?.image} 
                alt={token.tokenMetadata?.name}
                width={200}
              />
              <h3>{token.tokenMetadata?.name}</h3>
              <p>{token.tokenMetadata?.description}</p>
              <div className="attributes">
                {token.tokenMetadata?.attributes?.map(attr => (
                  <span key={attr.trait_type}>
                    {attr.trait_type}: {attr.value}
                  </span>
                ))}
              </div>
            </div>
          ) : (
            // Fungible token display
            <div className="token-row">
              {token.contractInfo?.logoURI && (
                <img 
                  src={token.contractInfo.logoURI}
                  alt={token.contractInfo.symbol}
                  width={24}
                  height={24}
                />
              )}
              <span>{token.contractInfo?.symbol || 'Unknown Token'}</span>
              <span>Balance: {token.balance}</span>
              <span>Chain: {token.chainId}</span>
            </div>
          )}
        </div>
      ))}
    </div>
  )
}

​

返却型：UseQueryResult<TokenBalance[]>

このフックはReact QueryのUseQueryResultの全プロパティと、メタデータを含むトークン残高データを返します。詳細な構造は以下の通りです:

interface TokenBalance {
  contractType: ContractType
  contractAddress: string
  accountAddress: string
  tokenID?: string
  balance: string
  blockHash: string
  blockNumber: number
  chainId: number
  uniqueCollectibles: string
  isSummary: boolean
  contractInfo?: ContractInfo
  tokenMetadata?: TokenMetadata
}

​

プロパティ

​

data

TokenBalance[] | undefined

以下を含むトークン残高オブジェクトの配列：

• contractType: トークンコントラクトの種類（NATIVE、ERC20、ERC721、ERC1155）
• contractAddress: トークンコントラクトのアドレス
• accountAddress: トークンを保有するアカウントのアドレス
• balance: トークン残高（最小単位での文字列）
• chainId: トークンが存在するチェーンID
• blockHash: 残高が最後に更新されたブロックのハッシュ
• blockNumber: 残高が最後に更新されたブロック番号
• tokenID: （NFTの場合）トークンID
• contractInfo: トークンコントラクトの名前、シンボル、小数点、ロゴURLの情報
• tokenMetadata: （NFTの場合）トークンの詳細なメタデータ（名前、説明、画像URL、属性など）
• uniqueCollectibles: ユニークコレクティブルの数
• isSummary: 残高がサマリーかどうか

​

isLoading

boolean

データ取得時のローディング状態。

​

isError

boolean

クエリが失敗した場合のエラー状態。

​

エラー

Error | null

データ取得中に発生したエラー内容。

​

パラメータ

このフックは2つのパラメータを受け取ります：

​

引数: GetTokenBalancesDetailsArgs

interface GetTokenBalancesDetailsArgs {
  chainIds: number[]
  filter: {
    accountAddresses: string[]
    contractWhitelist?: string[]
    contractBlacklist?: string[]
    omitNativeBalances?: boolean
    contractStatus?: ContractVerificationStatus
  }
}

パラメータ	型	説明
chainIds	number[]	残高を取得するチェーンIDの配列
filter.accountAddresses	string[]	残高を取得するアカウントアドレスの配列
filter.contractWhitelist	string[]	（オプション）取得対象とするコントラクトアドレスの配列
filter.contractBlacklist	string[]	（オプション）除外するコントラクトアドレスの配列
filter.omitNativeBalances	boolean	（オプション）trueの場合、ネイティブトークン残高を除外
filter.contractStatus	ContractVerificationStatus	（オプション）コントラクトの認証ステータスで絞り込み

​

options: BalanceHookOptions

interface BalanceHookOptions {
  disabled?: boolean
  retry?: boolean
  hideCollectibles?: boolean
}

パラメータ	型	説明
disabled	boolean	（オプション）クエリの自動実行を無効にします
retry	boolean	（オプション）失敗したクエリを再試行するかどうか
hideCollectibles	boolean	（オプション）trueの場合、ERC721およびERC1155トークンを除外します