> ## 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. # ウォレット残高の取得方法 > SolanaウォレットのすべてのトークンとNFT残高をUSD値、ロゴ、メタデータとともに取得します。価値に応じて並べ替えられているため、ポートフォリオの追跡が簡単です。 ウォレットAPIはベータ版です。エンドポイントやレスポンス形式は変更される可能性があります。 ## 概要 ウォレット残高エンドポイントは、SolanaウォレットのすべてのトークンとNFT保有物—SOL、SPLトークン、Token-2022、およびNFT—をUSD価格、ロゴ、およびメタデータ付きで取得します。結果はUSD価値の高い順に並べ替えられます。価格データのあるトークンが最初に表示され、価格のないトークンがその後に続きます。 このエンドポイントは1リクエストあたり最大100トークンを返すため、ページネーションは手動です。追加ページを取得するには`page`パラメータを使用し、さらなる結果が利用可能かどうかを判断するために`pagination.hasMore`を参照してください。各リクエストは1回のAPIコールで、100クレジットがかかります。 USD価格はDASから取得され、時価総額トップ10,000トークンに対応しています。`pricePerToken`と`usdValue`は、未対応トークンの場合は`null`です。価格は推定値であり、リアルタイムの市場レートではありません。 ## 使用する場合 ウォレット残高APIを使用する必要がある場合： * **ポートフォリオ保有物を表示する**: ユーザーに完全なトークンとNFT保有物を表示します。 * **USD値を計算する**: ポートフォリオ評価を毎時更新された価格で取得します。 * **ウォレットUIを構築する**: ウォレットダッシュボードと資産リストを提供します。 * **トークン保有を追跡する**: ウォレット間で特定のトークン残高を監視します。 * **ポートフォリオ分析**: 保有物の分布と集中を分析します。 * **税務報告**: 税務目的で保有物のスナップショットを生成します。 ## クイックスタート ### 基本的な残高クエリ ウォレットのすべてのトークン残高をUSD値で取得します。 ```javascript theme={"system"} const getWalletBalances = async (address) => { const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY`; const response = await fetch(url); if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } const data = await response.json(); const solBalance = data.balances[0]; // SOL is always first when showNative=true console.log(`SOL Balance: ${solBalance.balance} SOL ($${solBalance.usdValue})`); console.log(`Page ${data.pagination.page} Total Value: $${data.totalUsdValue}`); console.log(`Token Count (this page): ${data.balances.length}`); // Display top holdings data.balances.slice(0, 5).forEach(token => { console.log(`${token.symbol}: ${token.balance} ($${token.usdValue || 'N/A'})`); }); return data; }; getWalletBalances("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY"); ``` ```python theme={"system"} import requests def get_wallet_balances(address: str): url = f"https://api.helius.xyz/v1/wallet/{address}/balances" headers = {"X-Api-Key": "YOUR_API_KEY"} response = requests.get(url, headers=headers) response.raise_for_status() data = response.json() sol_balance = data['balances'][0] # SOL is always first when showNative=true print(f"SOL Balance: {sol_balance['balance']} SOL (${sol_balance['usdValue']})") print(f"Page {data['pagination']['page']} Total Value: ${data['totalUsdValue']}") print(f"Token Count (this page): {len(data['balances'])}") # Display top holdings for token in data['balances'][:5]: usd_value = token.get('usdValue', 'N/A') print(f"{token['symbol']}: {token['balance']} (${usd_value})") return data get_wallet_balances("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY") ``` ```bash theme={"system"} curl "https://api.helius.xyz/v1/wallet/86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY/balances?api-key=YOUR_API_KEY" ``` ### NFTを結果に含める トークンとNFTの両方を1つのリクエストで取得します： ```javascript theme={"system"} const getWalletWithNfts = async (address) => { const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY&showNfts=true`; const response = await fetch(url); const data = await response.json(); console.log(`Tokens: ${data.balances.length}`); console.log(`NFTs: ${data.nfts?.length || 0}`); // Display NFTs data.nfts?.forEach(nft => { console.log(`NFT: ${nft.name || 'Unnamed'} (${nft.collectionName || 'Unknown Collection'})`); }); return data; }; getWalletWithNfts("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY"); ``` ```python theme={"system"} def get_wallet_with_nfts(address: str): url = f"https://api.helius.xyz/v1/wallet/{address}/balances" params = { "api-key": "YOUR_API_KEY", "showNfts": "true" } response = requests.get(url, params=params) response.raise_for_status() data = response.json() print(f"Tokens: {len(data['balances'])}") print(f"NFTs: {len(data.get('nfts', []))}") # Display NFTs for nft in data.get('nfts', []): name = nft.get('name', 'Unnamed') collection = nft.get('collectionName', 'Unknown Collection') print(f"NFT: {name} ({collection})") return data get_wallet_with_nfts("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY") ``` ### 結果をフィルタリングする クエリパラメータを使用して返される内容を絞り込みます： ```javascript theme={"system"} // Only show tokens with non-zero balances const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY&showZeroBalance=false`; // Exclude native SOL from results const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY&showNative=false`; // Get only the top 50 tokens by value const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY&limit=50`; ``` ## クエリパラメータ | パラメータ | 型 | デフォルト | 説明 | | ----------------- | --- | ----- | --------------------------- | | `page` | 整数 | 1 | ページネーションのためのページ番号（1から始まる） | | `limit` | 整数 | 100 | 1ページあたりのトークンの最大数（1-100） | | `showZeroBalance` | ブール | false | ゼロ残高のトークンを含めます | | `showNative` | ブール | true | ネイティブSOLを結果に含めます | | `showNfts` | ブール | false | 結果にNFTを含めます（最大100、最初のページのみ） | ## レスポンス形式 ```json theme={"system"} { "balances": [ { "mint": "So11111111111111111111111111111111111111111", "symbol": "SOL", "name": "Solana", "balance": 1.5, "decimals": 9, "pricePerToken": 145.32, "usdValue": 217.98, "logoUri": "https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/So11111111111111111111111111111111111111112/logo.png", "tokenProgram": "spl-token" }, { "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "symbol": "USDC", "name": "USD Coin", "balance": 1000.5, "decimals": 6, "pricePerToken": 1.0, "usdValue": 1000.5, "logoUri": "https://example.com/usdc-logo.png", "tokenProgram": "spl-token" } ], "nfts": [ { "mint": "7Xq8wXyXVqfBPPqVJjPDwG9zN5wCVxBYZ6z7vPYBzr6F", "name": "Degen Ape #1234", "imageUri": "https://example.com/nft.png", "collectionName": "Degen Ape Academy", "collectionAddress": "DegN1dXmU2uYa4n7U9qTh7YNYpK4u8L9qXx7XqYqJfGH", "compressed": false } ], "totalUsdValue": 1218.48, "pagination": { "page": 1, "limit": 100, "hasMore": true } } ``` ### フィールドノート * **`balance`**: 十分に調整された人間が読み取れる量—`1.5`は1.5 SOLを意味し、`1000.5`は1000.5 USDCを意味します。ラメポート変換は不要です。このエンドポイントは生の`amountRaw`フィールドを公開しませんが、必要に応じて`Math.round(balance * 10 ** decimals)`として正確な整数値を導出します。 * **`decimals`**: 参照用にのみ提供されます。 * **`pricePerToken` / `usdValue`**: DAS価格データのないトークンの場合は`null`です（上記の価格ノートを参照してください）。 * **`totalUsdValue`**: 現在のレスポンスページのみの総USD価値です。フルポートフォリオの値を取得するには、すべてのページをページングし、各バランスの`usdValue`を合計します。 * **`tokenProgram`**: 各トークンが使用するトークンスタンダード—`spl-token`（レガシーSPLトークン）または`token-2022`（トークン拡張）。両方とも完全にサポートされています。 ## 使用例 ### ポートフォリオダッシュボードを構築する USD値でユーザーの保有を表示します。 ```javascript theme={"system"} const renderPortfolio = async (address) => { const { balances, totalUsdValue } = await getWalletBalances(address); console.log(`Current Page Value: $${totalUsdValue.toLocaleString()}`); console.log(`\nTop Holdings:`); // totalUsdValue is page-scoped; paginate before computing full portfolio value. balances.slice(0, 10).forEach((token, i) => { if (token.usdValue) { console.log(`${i + 1}. ${token.symbol}: ${token.balance.toFixed(4)} ($${token.usdValue.toFixed(2)})`); } }); }; ``` ### トークン集中度を計算する ポートフォリオの多様性を分析します。 ```javascript theme={"system"} const analyzeConcentration = async (address) => { const { balances, totalUsdValue } = await getWalletBalances(address); const tokensWithValue = balances.filter(t => t.usdValue); if (tokensWithValue.length === 0) { console.log('No tokens with USD pricing data available'); return null; } const topToken = tokensWithValue[0]; const pageConcentration = (topToken.usdValue / totalUsdValue) * 100; console.log(`Largest Position on Current Page: ${topToken.symbol} (${pageConcentration.toFixed(1)}%)`); if (pageConcentration > 50) { console.log(`Warning: Current page is highly concentrated in ${topToken.symbol}`); } return { topToken, pageConcentration }; }; ``` ### 特定のトークン残高を追跡する 複数のウォレット間で特定のトークンを監視します。 ```javascript theme={"system"} const getTokenBalance = async (address, tokenMint) => { const { balances } = await getWalletBalances(address); const token = balances.find(t => t.mint === tokenMint); if (!token) { console.log(`Token not found in wallet`); return null; } console.log(`${token.symbol} Balance: ${token.balance}`); console.log(`USD Value: $${token.usdValue || 'N/A'}`); return token; }; // Example: Check USDC balance getTokenBalance( "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" // USDC mint ); ``` ### 税務報告のために保有をエクスポートする 保有のスナップショットを生成します。 ```javascript theme={"system"} const exportHoldingsSnapshot = async (address) => { const { balances, totalUsdValue } = await getWalletBalances(address); const snapshot = { date: new Date().toISOString(), address, pageValueUSD: totalUsdValue, holdings: balances .filter(t => t.usdValue) .map(t => ({ symbol: t.symbol, mint: t.mint, balance: t.balance, pricePerToken: t.pricePerToken, usdValue: t.usdValue })) }; console.log(JSON.stringify(snapshot, null, 2)); return snapshot; }; ``` ## ページネーション 100トークンを超えるウォレットの場合、`page`パラメータと`pagination.hasMore`を使用して結果をページングします。 ```javascript theme={"system"} const getAllBalances = async (address) => { let allBalances = []; let page = 1; let hasMore = true; while (hasMore) { const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY&page=${page}&limit=100`; const response = await fetch(url); const data = await response.json(); allBalances = allBalances.concat(data.balances); hasMore = data.pagination.hasMore; page++; console.log(`Fetched page ${data.pagination.page}, total tokens so far: ${allBalances.length}`); } console.log(`Total tokens: ${allBalances.length}`); return allBalances; }; ``` NFTはトークンページネーションに関係なく、最初のページでのみ返されます（最大100）。 ## ベストプラクティス * **ゼロ残高をフィルタリングしてUIをクリーンにする。** `showZeroBalance=false`を使用して、ウォレットがもはや保持しないトークンを隠します。 * **NFTは必要に応じてのみ含めます。** NFTはデフォルトでパフォーマンスのために除外されており、表示する際にのみ`showNfts=true`を設定します。 * **価格データの不足に対処します。** `pricePerToken`と`usdValue`が`null`であるかどうかを常に確認してください。これらはDASからの毎時の推定値であり、リアルタイムの市場レートではありません。 * **レスポンスをキャッシュします。** バランスデータは、APIコールの回数を減らすために数秒間キャッシュできます。 * **大規模なウォレットをページングします。** 一部のウォレットは何千ものトークンを保持しています。効率的に処理するためにページングを実装します。 ## 一般的なエラー | エラーコード | 説明 | 解決策 | | ------ | -------------- | ------------------------------------ | | 400 | 無効なウォレットアドレス形式 | アドレスが有効なbase58 Solanaアドレスであることを確認します | | 401 | APIキーがないか無効です | リクエストにAPIキーが含まれていることを確認します | | 429 | レート制限超過 | リクエストの頻度を減らすかプランをアップグレードします | ## 次のステップ 過去のタイムスタンプ、日付時刻、またはスロットでのトークンまたはSOLの残高を取得します。 すべてのウォレットAPIエンドポイントと共有の規約。 ウォレット残高のリクエストおよびレスポンススキーマ。