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

> Conoce los casos de uso, ejemplos de código, parámetros de solicitud, estructura de respuesta y consejos de getTokenAccountsByOwner.

El método RPC [`getTokenAccountsByOwner`](https://www.helius.dev/docs/api-reference/rpc/http/gettokenaccountsbyowner) se usa para recuperar todas las [cuentas de tokens](https://www.helius.dev/blog/how-to-get-token-holders-on-solana) SPL que pertenecen a una clave pública específica. Es un método fundamental para las billeteras y aplicaciones que necesitan mostrar los tokens de un usuario o interactuar con sus distintas cuentas de tokens.

Debes filtrar la consulta por un `mint` de token específico o un `programId` (por ejemplo, el programa de tokens SPL o el programa Token-2022).

Para billeteras con portafolios de tokens extensos, considera usar [`getTokenAccountsByOwnerV2`](/docs/es/api-reference/rpc/http/gettokenaccountsbyownerv2), que admite paginación basada en cursor con tamaños de página configurables de hasta 10,000 cuentas por solicitud.

## Casos de uso comunes

* **Mostrar el portafolio del usuario:** Obtén todas las cuentas de tokens (y, por lo tanto, sus saldos) de la dirección de billetera de un usuario para mostrar su portafolio completo de tokens.
* **Lógica de la aplicación:** Identifica la cuenta de un token específico del usuario para un mint determinado antes de iniciar una transferencia u otra interacción.
* **Verificación:** Comprueba qué cuentas de tokens posee un propietario para un tipo de token determinado.
* **Indexación de titulares de tokens:** Aunque es menos eficiente para la indexación global que otros métodos, puede usarse para encontrar cuentas de un conjunto conocido de propietarios.

## Parámetros de la solicitud

1. **`ownerPubkey`** (string, obligatorio): La clave pública codificada en base 58 del propietario cuyas cuentas de tokens quieres recuperar.

2. **`filter`** (object, obligatorio): Un objeto JSON que **debe** especificar `mint` o `programId`:
   * **`mint`** (string): La clave pública codificada en base 58 de un mint de token específico. Si se proporciona, solo se devolverán las cuentas de este mint que pertenezcan a `ownerPubkey`.
   * **`programId`** (string): La clave pública codificada en base 58 del programa de tokens que controla las cuentas. Los valores comunes son:
     * Programa de tokens SPL: `TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA`
     * Programa Token-2022: `TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`

3. **`options`** (object, opcional): Un objeto de configuración opcional que puede incluir:
   * **`commitment`** (string, opcional): Especifica el [nivel de compromiso](https://www.helius.dev/blog/solana-commitment-levels).
   * **`encoding`** (string, opcional): La codificación de los datos de la cuenta. Se recomienda ampliamente `"jsonParsed"`. Otras opciones: `"base64"`, `"base64+zstd"`. El valor predeterminado es `"base64"`.
   * **`dataSlice`** (object, opcional): Permite recuperar una sección específica de los datos de la cuenta (`offset`: usize, `length`: usize). Solo está disponible para las codificaciones `base58`, `base64` o `base64+zstd`.
   * **`minContextSlot`** (u64, opcional): El slot mínimo para la consulta.

## Estructura de la respuesta

El campo `result.value` de la respuesta JSON-RPC es un arreglo de objetos. Cada objeto corresponde a una cuenta de tokens SPL que pertenece a `ownerPubkey` y coincide con `filter`.

Cada objeto del arreglo `value` contiene:

* **`pubkey`** (string): La clave pública codificada en base 58 de la propia cuenta de tokens.
* **`account`** (object): Información detallada sobre la cuenta de tokens:
  * **`lamports`** (u64): Saldo en lamports para la exención del alquiler.
  * **`owner`** (string): El programa propietario (por ejemplo, la clave pública del programa de tokens).
  * **`data`**: Datos de la cuenta. Si se usa la codificación `"jsonParsed"`, contiene:
    * **`program`** (string): Por ejemplo, `"spl-token"`.
    * **`parsed`**: Un objeto con información estructurada:
      * **`info`**: Detalles como:
        * **`mint`** (string): La dirección del mint del token.
        * **`owner`** (string): El propietario de la cuenta de tokens (debe coincidir con `ownerPubkey` de la solicitud).
        * **`tokenAmount`** (object): El saldo de tokens (`amount`, `decimals`, `uiAmount`, `uiAmountString`).
        * **`state`** (string): Estado de la cuenta de tokens (por ejemplo, `"initialized"`).
        * **`isNative`** (boolean): Indica si la cuenta contiene SOL envuelto.
        * **`delegate`** (string, opcional): La dirección del delegado, si se configuró uno.
        * **`delegatedAmount`** (object, opcional): La cantidad delegada, si se configuró un delegado.
      * **`type`** (string): Por ejemplo, `"account"`.
  * **`executable`** (boolean): Indica si la cuenta es ejecutable.
  * **`rentEpoch`** (u64): Próxima época en la que vence el alquiler.
  * **`space`** (u64, si no es `jsonParsed`): Longitud de los datos sin procesar de la cuenta, en bytes.

**Ejemplo de respuesta (con codificación `jsonParsed` y filtrada por `programId`):**

```json theme={"system"}
{
  "jsonrpc": "2.0",
  "result": {
    "context": {
      "slot": 183459000
    },
    "value": [
      {
        "pubkey": "AssociatedTokenAccountPubkey1...",
        "account": {
          "data": {
            "program": "spl-token",
            "parsed": {
              "info": {
                "isNative": false,
                "mint": "SomeTokenMintPubkey...",
                "owner": "OwnerPubkeyProvidedInRequest...",
                "state": "initialized",
                "tokenAmount": {
                  "amount": "1000000000", // 1 token if decimals is 9
                  "decimals": 9,
                  "uiAmount": 1.0,
                  "uiAmountString": "1.0"
                }
              },
              "type": "account"
            },
            "space": 165
          },
          "executable": false,
          "lamports": 2039280,
          "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
          "rentEpoch": 380
        }
      },
      {
        "pubkey": "AnotherAssociatedTokenAccountPubkey...",
        "account": {
          // ... similar structure for another token owned by the same owner
        }
      }
    ]
  },
  "id": 1
}
```

## Ejemplos de código

<CodeGroup>
  ```bash cURL theme={"system"}
  # Replace <OWNER_PUBKEY> and <TOKEN_MINT_PUBKEY> or <TOKEN_PROGRAM_ID>

  # Example filtering by programId (SPL Token Program)
  curl -X POST -H "Content-Type: application/json" -d \
    '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "getTokenAccountsByOwner",
      "params": [
        "<OWNER_PUBKEY>",
        { "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" },
        { "encoding": "jsonParsed" }
      ]
    }' \
    <YOUR_RPC_URL>

  # Example filtering by a specific mint
  curl -X POST -H "Content-Type: application/json" -d \
    '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "getTokenAccountsByOwner",
      "params": [
        "<OWNER_PUBKEY>",
        { "mint": "<SPECIFIC_TOKEN_MINT_PUBKEY>" },
        { "encoding": "jsonParsed", "commitment": "confirmed" }
      ]
    }' \
    <YOUR_RPC_URL>
  ```

  ```javascript JavaScript (using @solana/web3.js) theme={"system"}
  const { Connection, PublicKey } = require('@solana/web3.js');

  async function findOwnerTokenAccounts(ownerAddress, filter, encoding = 'jsonParsed') {
    // Replace with your RPC endpoint
    const connection = new Connection('https://mainnet.helius-rpc.com/?api-key=<api-key>');
    const ownerPubKey = new PublicKey(ownerAddress);

    try {
      let actualFilter;
      if (filter.mint) {
        actualFilter = { mint: new PublicKey(filter.mint) };
      } else if (filter.programId) {
        actualFilter = { programId: new PublicKey(filter.programId) };
      } else {
        console.error("Filter must contain either 'mint' or 'programId'");
        return;
      }

      const accounts = await connection.getTokenAccountsByOwner(
        ownerPubKey,
        actualFilter,
        { encoding }
      );

      console.log(`Found ${accounts.value.length} token accounts for owner ${ownerAddress}:`);
      accounts.value.forEach(accInfo => {
        console.log(`  Token Account: ${accInfo.pubkey.toBase58()}`);
        if (encoding === 'jsonParsed' && accInfo.account.data.parsed) {
          console.log(`    Mint: ${accInfo.account.data.parsed.info.mint}`);
          console.log(`    Balance: ${accInfo.account.data.parsed.info.tokenAmount.uiAmountString}`);
        }
        // console.log(JSON.stringify(accInfo, null, 2)); // For full details
      });

    } catch (error) {
      console.error(`Error fetching token accounts for owner ${ownerAddress}:`, error);
    }
  }

  // Replace with an actual owner's public key
  const exampleOwner = 'HXtBm8XZbxaTt41uqaKhwUAa6Z1aPyvJdsZVENiWsetg'; // Example wallet address

  // Example 1: Find all SPL Token Program accounts owned by `exampleOwner`
  findOwnerTokenAccounts(exampleOwner, { programId: 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA' });

  // Example 2: Find USDC token accounts owned by `exampleOwner`
  // const usdcMint = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
  // findOwnerTokenAccounts(exampleOwner, { mint: usdcMint });

  // Example 3: Find Token-2022 Program accounts owned by `exampleOwner`
  // findOwnerTokenAccounts(exampleOwner, { programId: 'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb' });
  ```
</CodeGroup>

## Consejos para desarrolladores

* **Requisito del filtro:** *Debes* proporcionar `mint` o `programId` en el filtro. No es posible consultar todas las cuentas de tokens de un propietario para todos los tipos de tokens sin uno de estos filtros principales.
* **Cuentas de tokens asociadas:** Este método devolverá todas las cuentas de tokens que pertenezcan a la clave pública, incluidas las cuentas de tokens asociadas (ATA) estándar y cualquier otra cuenta de tokens SPL que pueda poseer (por ejemplo, de implementaciones de billeteras antiguas o configuraciones personalizadas).
* **Codificación:** Se recomienda ampliamente usar `"jsonParsed"` para la opción `encoding`. Esta codificación decodifica los datos binarios de la cuenta en una estructura JSON más fácil de usar.
* **Rendimiento:** Si un propietario tiene una cantidad muy grande de cuentas de tokens (en especial cuando solo se filtra por `programId`), la respuesta puede ser grande. En esos casos, usa [`getTokenAccountsByOwnerV2`](/docs/es/api-reference/rpc/http/gettokenaccountsbyownerv2), que ofrece paginación integrada.
* **Token-2022 (extensiones de tokens):** Si trabajas con tokens creados mediante el programa Token-2022 (que admite extensiones como comisiones por transferencia, intereses, etc.), asegúrate de usar el `programId` correcto: `TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`.

Esta guía proporciona una comprensión completa del método RPC `getTokenAccountsByOwner` para que puedas recuperar de forma eficiente la información de las cuentas de tokens de cualquier dirección de Solana.

## Paginación para portafolios de tokens grandes

Para billeteras con una gran cantidad de tokens, usa [`getTokenAccountsByOwnerV2`](/docs/es/api-reference/rpc/http/gettokenaccountsbyownerv2), que ofrece:

* **Paginación basada en cursor**: Define `limit` (1-10,000) y usa `paginationKey` para navegar por los resultados
* **Actualizaciones incrementales**: Usa `changedSinceSlot` para obtener solo las cuentas de tokens modificadas desde un slot específico
* **Mejor rendimiento**: Evita tiempos de espera agotados y permite rastrear portafolios en tiempo real
* **Comportamiento de la paginación**: El final de la paginación solo se indica cuando no se devuelve ninguna cuenta de tokens. Es posible que se devuelvan menos cuentas que el límite debido al filtrado; continúa con la paginación hasta que `paginationKey` sea null

```typescript theme={"system"}
// Example: Paginated query for all token accounts
const response = await fetch("https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "1",
    method: "getTokenAccountsByOwnerV2",
    params: [
      "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
      { "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" },
      {
        encoding: "jsonParsed",
        limit: 1000
      }
    ]
  })
});

const data = await response.json();
console.log(`Found ${data.result.value.length} token accounts`);
if (data.result.paginationKey) {
  console.log("More results available, use paginationKey for next page");
  // Continue pagination even if fewer than limit accounts were returned
} else {
  console.log("End of pagination - no more token accounts available");
}
```

## Métodos relacionados

<CardGroup cols={2}>
  <Card title="getTokenAccountsByOwnerV2" href="/docs/es/api-reference/rpc/http/gettokenaccountsbyownerv2">
    Versión paginada con navegación basada en cursor para portafolios grandes
  </Card>

  <Card title="getTokenAccountBalance" href="/docs/es/api-reference/rpc/http/gettokenaccountbalance">
    Obtén el saldo de una cuenta de tokens específica
  </Card>
</CardGroup>