Cómo obtener los saldos de una billetera

La API de billetera está en fase beta. Los endpoints y los formatos de respuesta pueden cambiar.

Descripción general

El endpoint de saldos de billetera obtiene todas las tenencias de tokens y NFT de una billetera de Solana —SOL, tokens SPL, Token-2022 y NFT— junto con sus precios en USD, logotipos y metadatos. Los resultados se ordenan por valor en USD de forma descendente: primero aparecen los tokens con datos de precios, seguidos de los tokens sin precios. El endpoint devuelve hasta 100 tokens por solicitud, por lo que la paginación es manual. Usa el parámetro page para obtener páginas adicionales y consulta pagination.hasMore para saber si hay más resultados disponibles. Cada solicitud corresponde a una sola llamada a la API y cuesta 100 créditos.

Los precios en USD provienen de DAS y se actualizan cada hora. Cubren los 10 000 tokens principales por capitalización de mercado. pricePerToken y usdValue son null para los tokens no compatibles. Los precios son estimaciones, no cotizaciones de mercado en tiempo real.

Cuándo usar esto

Usa la API de saldos de billetera cuando necesites:

Mostrar las tenencias del portafolio: muestra a los usuarios todas sus tenencias de tokens y NFT.
Calcular valores en USD: obtén valoraciones del portafolio con precios actualizados cada hora.
Crear interfaces de billetera: proporciona datos para paneles de billetera y listas de activos.
Dar seguimiento a las tenencias de tokens: monitorea los saldos de tokens específicos en varias billeteras.
Analizar el portafolio: analiza la distribución y concentración de las tenencias.
Generar informes fiscales: genera instantáneas de las tenencias para fines fiscales.

Inicio rápido

Consulta básica de saldos

Obtén todos los saldos de tokens de una billetera junto con sus valores en 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 NFT en los resultados

Obtén tokens y NFT en una sola solicitud con 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 los resultados

Usa parámetros de consulta para limitar los datos devueltos:

// 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	Valor predeterminado	Descripción
`page`	entero	1	Número de página para la paginación (el índice comienza en 1)
`limit`	entero	100	Número máximo de tokens por página (1-100)
`showZeroBalance`	booleano	false	Incluye tokens con saldo cero
`showNative`	booleano	true	Incluye SOL nativo en los resultados
`showNfts`	booleano	false	Incluye NFT en los resultados (máximo 100, solo en la primera página)

Formato de respuesta

{
  "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 los campos

balance: cantidad legible para personas, ya ajustada según los decimales; 1.5 significa 1.5 SOL y 1000.5 significa 1000.5 USDC. No es necesario convertir lamports. Este endpoint no expone un campo amountRaw sin procesar. Si necesitas el valor entero exacto, calcúlalo como Math.round(balance * 10 ** decimals).
decimals: se proporciona solo como referencia.
pricePerToken / usdValue: null para tokens sin datos de precios de DAS (consulta la nota sobre precios anterior).
totalUsdValue: valor total en USD únicamente para la página de respuesta actual. Para obtener el valor total del portafolio, recorre todas las páginas y suma el valor usdValue de cada saldo.
tokenProgram: indica el estándar que usa cada token: spl-token (token SPL heredado) o token-2022 (extensiones de token). Ambos son totalmente compatibles.

Casos de uso

Crear un panel de portafolio

Muestra las tenencias del usuario junto con sus valores en 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 la concentración de tokens

Analiza la diversificación del portafolio:

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

Dar seguimiento al saldo de un token específico

Monitorea un token específico en varias billeteras:

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 tenencias para informes fiscales

Genera una instantánea de las tenencias:

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

Paginación

Para las billeteras con más de 100 tokens, recorre las páginas de resultados con el parámetro page y 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;
};

Los NFT solo se devuelven en la primera página (hasta 100), independientemente de la paginación de tokens.

Prácticas recomendadas

Filtra los saldos cero para obtener una interfaz más limpia. Usa showZeroBalance=false para ocultar los tokens que la billetera ya no tiene.
Incluye los NFT solo cuando sea necesario. Los NFT se excluyen de forma predeterminada para mejorar el rendimiento. Configura showNfts=true solo cuando necesites mostrarlos.
Gestiona los datos de precios faltantes. Comprueba siempre si pricePerToken y usdValue son null antes de mostrarlos. Son estimaciones por hora de DAS, no cotizaciones de mercado en tiempo real.
Almacena las respuestas en caché. Puedes almacenar los datos de saldos en caché durante varios segundos para reducir las llamadas a la API.
Pagina las billeteras grandes. Algunas billeteras tienen miles de tokens. Implementa la paginación para gestionarlas de forma eficiente.

Errores comunes

Código de error	Descripción	Solución
400	Formato de dirección de billetera no válido	Verifica que la dirección sea una dirección de Solana válida en base58
401	Falta la clave de API o no es válida	Comprueba que la clave de API esté incluida en la solicitud
429	Se superó el límite de solicitudes	Reduce la frecuencia de las solicitudes o mejora tu plan

Próximos pasos

Historical Balance

Obtén el saldo de un token o de SOL en una marca de tiempo, fecha y hora o slot anteriores.

Wallet API Overview

Todos los endpoints y las convenciones compartidas de la API de billetera.

API Reference

Esquemas de solicitud y respuesta para los saldos de billetera.

Primeros pasos

Streaming de datos y escucha de eventos

API de datos y RPC

Trading

Envío de transacciones

Billetera como servicio

Privacidad

Recursos

Cómo obtener los saldos de una billetera

Descripción general

Cuándo usar esto

Inicio rápido

Consulta básica de saldos

Incluir NFT en los resultados

Filtrar los resultados

Parámetros de consulta

Formato de respuesta

Notas sobre los campos

Casos de uso

Crear un panel de portafolio

Calcular la concentración de tokens

Dar seguimiento al saldo de un token específico

Exportar tenencias para informes fiscales

Paginación

Prácticas recomendadas

Errores comunes

Próximos pasos

Historical Balance

Wallet API Overview

API Reference

​Descripción general

​Cuándo usar esto

​Inicio rápido

​Consulta básica de saldos

​Incluir NFT en los resultados

​Filtrar los resultados

​Parámetros de consulta

​Formato de respuesta

​Notas sobre los campos

​Casos de uso

​Crear un panel de portafolio

​Calcular la concentración de tokens

​Dar seguimiento al saldo de un token específico

​Exportar tenencias para informes fiscales

​Paginación

​Prácticas recomendadas

​Errores comunes

​Próximos pasos

Historical Balance

Wallet API Overview

API Reference

Descripción general

Cuándo usar esto

Inicio rápido

Consulta básica de saldos

Incluir NFT en los resultados

Filtrar los resultados

Parámetros de consulta

Formato de respuesta

Notas sobre los campos

Casos de uso

Crear un panel de portafolio

Calcular la concentración de tokens

Dar seguimiento al saldo de un token específico

Exportar tenencias para informes fiscales

Paginación

Prácticas recomendadas

Errores comunes

Próximos pasos