Como Obter Saldos de Carteira

A Wallet API está em Beta. Endpoints e formatos de resposta podem mudar.

Visão Geral

O endpoint Wallet Balances recupera todas as participações de tokens e NFTs para uma carteira Solana — SOL, tokens SPL, Token-2022 e NFTs — com preços em USD, logotipos e metadados. Os resultados são ordenados por valor em USD em ordem decrescente: tokens com dados de preços aparecem primeiro, seguidos por tokens sem preços. O endpoint retorna até 100 tokens por solicitação, então a paginação é manual. Use o parâmetro page para buscar páginas adicionais e leia pagination.hasMore para saber quando mais resultados estão disponíveis. Cada solicitação é uma única chamada de API e custa 100 créditos.

Os preços em USD são originários do DAS e atualizados a cada hora, cobrindo os 10.000 principais tokens por capitalização de mercado. pricePerToken e usdValue são null para tokens não suportados. Os preços são estimativas, não taxas de mercado em tempo real.

Quando usar isso

Use a Wallet Balances API quando precisar:

Exibir participações de portfólio: mostrar aos usuários suas reservas completas de tokens e NFTs.
Calcular valores em USD: obter avaliações de portfólio com preços atualizados por hora.
Construir interfaces de carteira: alimentar painéis de carteira e listas de ativos.
Acompanhar participações de tokens: monitorar saldos específicos de tokens em carteiras.
Análise de portfólio: analisar distribuição e concentração de participações.
Relatório fiscal: gerar instantâneos de participações para fins fiscais.

Início Rápido

Consulta básica de saldo

Obtenha todos os saldos de tokens para uma carteira com valores em 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"

Incluir NFTs nos resultados

Obtenha tokens e NFTs em uma única solicitação com showNfts=true:

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

Filtrar os resultados

Use parâmetros de consulta para restringir o que é retornado:

// 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`;

Parâmetros de consulta

Parâmetro	Tipo	Padrão	Descrição
`page`	inteiro	1	Número da página para paginação (baseado em 1)
`limit`	inteiro	100	Número máximo de tokens por página (1-100)
`showZeroBalance`	booleano	false	Incluir tokens com saldo zero
`showNative`	booleano	true	Incluir SOL nativo nos resultados
`showNfts`	booleano	false	Incluir NFTs nos resultados (máx. 100, apenas na primeira página)

Formato de resposta

{
  "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
  }
}

Notas sobre os campos

balance: quantidade legível por humanos, já ajustada para decimais — 1.5 significa 1.5 SOL e 1000.5 significa 1000.5 USDC. Não é necessária conversão de lamports. Este endpoint não expõe um campo bruto amountRaw; se precisar do valor exato, derive-o como Math.round(balance * 10 ** decimals).
decimals: fornecido apenas para referência.
pricePerToken / usdValue: null para tokens sem dados de preços do DAS (veja a nota sobre preços acima).
totalUsdValue: valor total em USD apenas para a página de resposta atual. Para o valor total do portfólio, pagine por todas as páginas e some o usdValue de cada saldo.
tokenProgram: qual padrão de token cada token usa — spl-token (Token SPL legado) ou token-2022 (Extensões de Token). Ambos são totalmente suportados.

Casos de uso

Construir um painel de portfólio

Exibir participações do usuário com valores em 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)})`);
    }
  });
};

Calcular a concentração de tokens

Analisar a diversificação do portfólio:

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

Acompanhar um saldo específico de token

Monitorar um token específico em várias carteiras:

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

Exportar participações para relatório fiscal

Gerar um instantâneo de participações:

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

Paginação

Para carteiras com mais de 100 tokens, percorra os resultados com o parâmetro page e 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;
};

NFTs são retornados apenas na primeira página (até 100), independentemente da paginação de tokens.

Melhores práticas

Filtrar saldos zero para uma interface mais limpa. Use showZeroBalance=false para ocultar tokens que a carteira não possui mais.
Incluir NFTs apenas quando necessário. NFTs são excluídos por padrão para desempenho; defina showNfts=true apenas ao exibi-los.
Lidar com dados de preço ausentes. Sempre verifique se pricePerToken e usdValue são null antes de exibir. Esses são estimativas horárias do DAS, não taxas de mercado em tempo real.
Armazenar respostas em cache. Dados de saldo podem ser armazenados em cache por vários segundos para reduzir chamadas à API.
Paginar carteiras grandes. Algumas carteiras possuem milhares de tokens; implemente paginação para lidar com elas eficientemente.

Erros comuns

Código de Erro	Descrição	Solução
400	Formato inválido de endereço de carteira	Verifique se o endereço é um endereço Solana base58 válido
401	Chave de API ausente ou inválida	Verifique se sua chave de API está incluída na solicitação
429	Limite de taxa excedido	Reduza a frequência das solicitações ou atualize seu plano

Próximos passos

Saldo Histórico

Obtenha um saldo de token ou SOL em um horário passado, data ou slot.

Visão Geral da Wallet API

Todos os endpoints da Wallet API e convenções compartilhadas.

Referência da API

Esquemas de solicitação e resposta para saldos de carteira.

Primeiros Passos

Transmissão de Dados & Escuta de Eventos

APIs de Dados & RPCs

Negociação

Envio de Transações

Carteira como Serviço

Guias

Recursos

Como Obter Saldos de Carteira

Visão Geral

Quando usar isso

Início Rápido

Consulta básica de saldo

Incluir NFTs nos resultados

Filtrar os resultados

Parâmetros de consulta

Formato de resposta

Notas sobre os campos

Casos de uso

Construir um painel de portfólio

Calcular a concentração de tokens

Acompanhar um saldo específico de token

Exportar participações para relatório fiscal

Paginação

Melhores práticas

Erros comuns

Próximos passos

Saldo Histórico

Visão Geral da Wallet API

Referência da API

​Visão Geral

​Quando usar isso

​Início Rápido

​Consulta básica de saldo

​Incluir NFTs nos resultados

​Filtrar os resultados

​Parâmetros de consulta

​Formato de resposta

​Notas sobre os campos

​Casos de uso

​Construir um painel de portfólio

​Calcular a concentração de tokens

​Acompanhar um saldo específico de token

​Exportar participações para relatório fiscal

​Paginação

​Melhores práticas

​Erros comuns

​Próximos passos

Saldo Histórico

Visão Geral da Wallet API

Referência da API

Visão Geral

Quando usar isso

Início Rápido

Consulta básica de saldo

Incluir NFTs nos resultados

Filtrar os resultados

Parâmetros de consulta

Formato de resposta

Notas sobre os campos

Casos de uso

Construir um painel de portfólio

Calcular a concentração de tokens

Acompanhar um saldo específico de token

Exportar participações para relatório fiscal

Paginação

Melhores práticas

Erros comuns

Próximos passos