Cómo usar getTokenAccountsByOwner

​

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

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

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

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

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

​

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

​

Paginación para portafolios de tokens grandes

• 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

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