> ## 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余额，包括美元值、标志和元数据。按价值排序，便于投资组合跟踪。 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 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" ``` ### 在结果中包含 NFTs 通过 `showNfts=true` 在一个请求中同时获取代币和 NFTs： ```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` | integer | 1 | 分页的页码（1为起始） | | `limit` | integer | 100 | 每页最多的代币数量（1-100） | | `showZeroBalance` | boolean | false | 包含零余额的代币 | | `showNative` | boolean | true | 结果中包含本机 SOL | | `showNfts` | boolean | false | 结果中包含NFT（最多100，第1页） | ## 响应格式 ```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。无需转换 lamport。此端点不暴露原始 `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终端点和共享约定。 请求和响应架构用于钱包余额。