> ## 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.

# Cómo obtener los saldos de una billetera

> Obtén todos los saldos de tokens y NFT de cualquier billetera de Solana, junto con sus valores en USD, logotipos y metadatos. Se ordenan por valor para facilitar el seguimiento del portafolio.

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

## 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.

<Note>
  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.
</Note>

## 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:

<Tabs>
  <Tab title="JavaScript">
    ```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");
    ```
  </Tab>

  <Tab title="Python">
    ```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")
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={"system"}
    curl "https://api.helius.xyz/v1/wallet/86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY/balances?api-key=YOUR_API_KEY"
    ```
  </Tab>
</Tabs>

### Incluir NFT en los resultados

Obtén tokens y NFT en una sola solicitud con `showNfts=true`:

<Tabs>
  <Tab title="JavaScript">
    ```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");
    ```
  </Tab>

  <Tab title="Python">
    ```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")
    ```
  </Tab>
</Tabs>

### Filtrar los resultados

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

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

## 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

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

### 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:

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

### Calcular la concentración de tokens

Analiza la diversificación del portafolio:

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

### Dar seguimiento al saldo de un token específico

Monitorea un token específico en varias billeteras:

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

### Exportar tenencias para informes fiscales

Genera una instantánea de las tenencias:

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

## 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`:

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

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

<CardGroup cols={3}>
  <Card title="Historical Balance" icon="clock" href="/docs/es/wallet-api/balance-at">
    Obtén el saldo de un token o de SOL en una marca de tiempo, fecha y hora o slot anteriores.
  </Card>

  <Card title="Wallet API Overview" icon="wallet" href="/docs/es/wallet-api/overview">
    Todos los endpoints y las convenciones compartidas de la API de billetera.
  </Card>

  <Card title="API Reference" icon="code" href="/docs/es/api-reference/wallet-api/balances">
    Esquemas de solicitud y respuesta para los saldos de billetera.
  </Card>
</CardGroup>