如何获取钱包余额

测试版: 钱包API目前处于测试版。API和响应格式可能会更改。

概览

钱包余额端点检索Solana钱包的所有代币和NFT持有。获取SOL、SPL代币、Token-2022和NFT，包括美元定价、标志和元数据，按价值排序。分页是手动的 - 每个请求API返回最多100个代币。结果按美元价值降序排序。带有定价数据的代币优先出现，然后是没有价格的代币。 分页: 使用page参数获取更多页面。响应中包含pagination.hasMore以指示是否有更多结果可用。每个请求进行一次API调用，费用为100积分。

美元定价: 代币价格来源于DAS (数字资产标准)，每小时更新一次。定价覆盖市值前10,000个代币。并非所有代币都有定价数据—pricePerToken和usdValue对于不支持的代币将是null。价格是估计的，不应依赖为实时市场汇率；将来将添加对实时价格的支持。

API参考

查看钱包余额的详细API文档

何时使用

当你需要以下功能时，使用钱包余额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

在单个请求中获取代币和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['tokens'])}")
    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`;

隐藏本地SOL

// Exclude native SOL from results
const url = `https://api.helius.xyz/v1/wallet/${address}/balances?api-key=YOUR_API_KEY&showNative=false`;

限制结果

// Get only 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，仅限第一页）

响应格式

{
  "balances": [
    {
      "mint": "So11111111111111111111111111111111111111112",
      "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。无需进行拉姆波特转换。decimals字段仅供参考。本端点不公开原始amountRaw字段；如果需要确切的整数值，请将其派生为Math.round(balance * 10 ** decimals)。

用例

构建投资组合仪表板

显示用户持有的资产及其美元价值：

const renderPortfolio = async (address) => {
  const { balances, totalUsdValue } = await getWalletBalances(address);

  console.log(`Total Portfolio Value: $${totalUsdValue.toLocaleString()}`);
  console.log(`\nTop Holdings:`);

  // Display top 10 holdings (SOL is first, then other tokens sorted by 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 concentration = (topToken.usdValue / totalUsdValue) * 100;

  console.log(`Largest Position: ${topToken.symbol} (${concentration.toFixed(1)}%)`);

  if (concentration > 50) {
    console.log(`Warning: Portfolio is highly concentrated in ${topToken.symbol}`);
  }

  return { topToken, concentration };
};

跟踪特定代币余额

监控多个钱包中的特定代币：

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,
    totalValueUSD: 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;
};

代币程序支持

钱包API支持两种代币标准：

代币程序	描述	支持
`spl-token`	传统SPL代币标准	完全支持
`token-2022`	新代币扩展标准	完全支持

响应中的tokenProgram字段表示每个代币使用的标准。

分页

对于持有大量代币（>100）的钱包，使用page参数进行手动分页：

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

最佳实践

过滤零余额以优化用户界面

使用 showZeroBalance=false 来隐藏钱包不再持有的代币。这可以防止投资组合视图混乱。

需要时包含NFT

为了性能，NFT默认被排除。仅在需要显示时设置 showNfts=true。

处理缺失的价格数据

美元价格来自DAS，仅涵盖前10,000个每小时更新的代币。显示前始终检查 pricePerToken 和 usdValue 是否为null。这些是估计值，而非实时市场价格。

积极缓存

余额数据可以在数秒内缓存，而不会出现问题。通过缓存响应减少API调用。

为大型钱包使用分页

一些钱包持有数千个代币。实现分页以有效处理大型数据集。

常见错误

错误代码	描述	解决方案
400	无效的钱包地址格式	确保地址是有效的base58 Solana地址
401	缺少或无效的API密钥	检查请求中是否包含API密钥
429	超过速率限制	减少请求频率或升级计划

开始使用

Solana RPC 节点

数据流和事件监听

如何发送交易

获取数据

专用节点

压缩

质押

计费

使用 Orb

资源

如何获取钱包余额

概览

API参考

何时使用

快速开始

基本余额查询

在结果中包含NFTs

过滤选项

隐藏零余额

隐藏本地SOL

限制结果

查询参数

响应格式

用例

构建投资组合仪表板

计算代币集中度

跟踪特定代币余额

导出持有资产以作税务申报

代币程序支持

分页

最佳实践

常见错误

需要帮助？

API参考

联系支持

开始使用

Solana RPC 节点

数据流和事件监听

如何发送交易

获取数据

专用节点

压缩

质押

计费

使用 Orb

资源

​概览

API参考

​何时使用

​快速开始

​基本余额查询

​在结果中包含NFTs

​过滤选项

​隐藏零余额

​隐藏本地SOL

​限制结果

​查询参数

​响应格式

​用例

​构建投资组合仪表板

​计算代币集中度

​跟踪特定代币余额

​导出持有资产以作税务申报

​代币程序支持

​分页

​最佳实践

​常见错误

​需要帮助？

API参考

联系支持

概览

何时使用

快速开始

基本余额查询

在结果中包含NFTs

过滤选项

隐藏零余额

隐藏本地SOL

限制结果

查询参数

响应格式

用例

构建投资组合仪表板

计算代币集中度

跟踪特定代币余额

导出持有资产以作税务申报

代币程序支持

分页

最佳实践

常见错误

需要帮助？