ウォレット残高の取得方法

ウォレット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
Python
cURL

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");

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")

curl "https://api.helius.xyz/v1/wallet/86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY/balances?api-key=YOUR_API_KEY"

NFTを結果に含める

トークンとNFTの両方を1つのリクエストで取得します：

JavaScript
Python

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");

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")

結果をフィルタリングする

クエリパラメータを使用して返される内容を絞り込みます：

// 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、最初のページのみ）

レスポンス形式

{
  "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値でユーザーの保有を表示します。

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)})`);
    }
  });
};

トークン集中度を計算する

ポートフォリオの多様性を分析します。

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 };
};

特定のトークン残高を追跡する

複数のウォレット間で特定のトークンを監視します。

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
);

税務報告のために保有をエクスポートする

保有のスナップショットを生成します。

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を使用して結果をページングします。

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概要

すべてのウォレットAPIエンドポイントと共有の規約。

APIリファレンス

ウォレット残高のリクエストおよびレスポンススキーマ。

はじめに

データストリーミングとイベントリスニング

データ API & RPC

トレーディング

トランザクションの送信

ウォレット・アズ・ア・サービス

ガイド

リソース

ウォレット残高の取得方法

概要

使用する場合

クイックスタート

基本的な残高クエリ

NFTを結果に含める

結果をフィルタリングする

クエリパラメータ

レスポンス形式

フィールドノート

使用例

ポートフォリオダッシュボードを構築する

トークン集中度を計算する

特定のトークン残高を追跡する

税務報告のために保有をエクスポートする

ページネーション

ベストプラクティス

一般的なエラー

次のステップ

履歴残高

ウォレットAPI概要

APIリファレンス

​概要

​使用する場合

​クイックスタート

​基本的な残高クエリ

​NFTを結果に含める

​結果をフィルタリングする

​クエリパラメータ

​レスポンス形式

​フィールドノート

​使用例

​ポートフォリオダッシュボードを構築する

​トークン集中度を計算する

​特定のトークン残高を追跡する

​税務報告のために保有をエクスポートする

​ページネーション

​ベストプラクティス

​一般的なエラー

​次のステップ

履歴残高

ウォレットAPI概要

APIリファレンス

概要

使用する場合

クイックスタート

基本的な残高クエリ

NFTを結果に含める

結果をフィルタリングする

クエリパラメータ

レスポンス形式

フィールドノート

使用例

ポートフォリオダッシュボードを構築する

トークン集中度を計算する

特定のトークン残高を追跡する

税務報告のために保有をエクスポートする

ページネーション

ベストプラクティス

一般的なエラー

次のステップ