如何获取钱包余额

Wallet API 处于 Beta 阶段。端点和响应格式可能会改变。

概览

Wallet Balances 端点检索 Solana 钱包中所有代币和 NFT 持有量 — 包括 SOL、SPL 代币、Token-2022 和 NFT — 提供美元定价、标志和元数据。结果按美元价值以降序排序：具有定价数据的代币先出现，然后是没有价格的代币。该端点每次请求返回最多 100 个代币，因此分页是手动的。使用 page 参数获取更多页面，并阅读 pagination.hasMore 以了解何时有更多结果可用。每次请求是一次单一的 API 调用，消耗 100 积分。

美元价格来源于 DAS，每小时更新，涵盖市值排名前 10,000 的代币。pricePerToken 和 usdValue 是对于不支持代币的 null。价格为估值，不是实时市场价格。

何时使用

在需要以下功能时使用 Wallet Balances API：

显示投资组合持有量：向用户展示其完整的代币和 NFT 持有量。
计算美元价值：通过每小时更新的定价获取投资组合估值。
构建钱包 UI：支持钱包仪表板和资产列表。
跟踪代币持有量：监控跨钱包的特定代币余额。
投资组合分析：分析持有分布和集中度。
税务报告：生成用于税务目的的持有量快照。

快速开始

基本余额查询

获取钱包的所有代币余额和美元价值：

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"

在结果中包含 NFTs

通过 showNfts=true 在一个请求中同时获取代币和 NFTs：

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`	integer	1	分页的页码（1为起始）
`limit`	integer	100	每页最多的代币数量（1-100）
`showZeroBalance`	boolean	false	包含零余额的代币
`showNative`	boolean	true	结果中包含本机 SOL
`showNfts`	boolean	false	结果中包含NFT（最多100，第1页）

响应格式

{
  "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。无需转换 lamport。此端点不暴露原始 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

交易

发送交易

Wallet-as-a-Service

指南

资源

如何获取钱包余额

概览

何时使用

快速开始

基本余额查询

在结果中包含 NFTs

过滤结果

查询参数

响应格式

字段说明

使用案例

构建投资组合仪表板

计算代币集中度

跟踪特定代币余额

导出持有信息用于税务报告

分页

最佳实践

常见错误

下一步

历史余额

钱包API概述

API参考

​概览

​何时使用

​快速开始

​基本余额查询

​在结果中包含 NFTs

​过滤结果

​查询参数

​响应格式

​字段说明

​使用案例

​构建投资组合仪表板

​计算代币集中度

​跟踪特定代币余额

​导出持有信息用于税务报告

​分页

​最佳实践

​常见错误

​下一步

历史余额

钱包API概述

API参考

概览

何时使用

快速开始

基本余额查询

在结果中包含 NFTs

过滤结果

查询参数

响应格式

字段说明

使用案例

构建投资组合仪表板

计算代币集中度

跟踪特定代币余额

导出持有信息用于税务报告

分页

最佳实践

常见错误

下一步