Cómo obtener los titulares de un token en Solana

Descripción general

Primero, veamos cómo funcionan los tokens, especialmente los tokens no fungibles, en Solana. Cuando un desarrollador crea un token, utiliza el programa de tokens para crear una cuenta de acuñación. Esta cuenta contiene información sobre un token específico, como su nombre, dirección e imagen. Una vez creada la cuenta de acuñación, el token puede acuñarse y almacenarse en una cuenta de token. Una cuenta de token contiene información sobre un token específico que pertenece a una dirección determinada. Incluye datos como la dirección de acuñación, la dirección del propietario y la cantidad de ese token en la cuenta. Por ejemplo, una dirección que tenga USDC (un token SPL) tendrá una cuenta de token para USDC.

Ahora que entendemos cómo funcionan los tokens y las cuentas de token, podemos obtener todos los titulares de un token determinado. Cada billetera que tenga un token específico tendrá una cuenta de token para ese token. Esto significa que el token estará asociado con las cuentas de token de todas las billeteras que lo tengan. Así podremos identificar a todos sus titulares. Si encontramos una forma de obtener todas las cuentas de token asociadas con un token y, luego, los propietarios de esas cuentas, tendremos una lista de todos los titulares. 

Método getTokenAccounts

Por suerte, el método getTokenAccounts de la API de Helius nos permite hacer precisamente eso. Podemos incluir la dirección de acuñación de cualquier token en los parámetros de la llamada a la API y obtendremos una lista de todas las cuentas de token creadas para ese token. Además, la API devuelve el propietario de cada cuenta de token, a quien normalmente llamamos titular del token. Un pequeño detalle que debes tener en cuenta es que una cuenta puede tener varias cuentas de token para el mismo token. Esto no supone un gran problema. Solo debemos implementar una lógica que gestione las cuentas de token que comparten propietario. 

Implementación

Ahora veamos algo de código para entender cómo hacerlo. Para seguir los pasos, necesitarás una clave de API de Helius. Puedes obtener una gratis desde tu panel de Helius al crear una cuenta. Para comenzar, debemos crear un archivo JavaScript llamado getTokenHolders.js. Primero, podemos agregar nuestra URL de Helius e importar la biblioteca fs para guardar los resultados en un archivo JSON.

const url = `https://mainnet.helius-rpc.com/?api-key=`;
const fs = require("fs");

A continuación, crearemos un método para obtener todas las cuentas de token asociadas con el token específico. Podemos comenzar por crear un método llamado findHolders, que utilizará el método getTokenAccounts para obtener los datos necesarios. Puedes obtener más información sobre el método getTokenAccounts aquí.

Es importante tener en cuenta que cada llamada a la API solo puede devolver un máximo de 1000 cuentas de token. La mayoría de los tokens grandes de Solana tienen más de 100 000 cuentas de token. Para solucionar esto, utilizaremos la paginación para recorrer todas las cuentas de token y seguiremos haciendo llamadas a la API hasta obtener los datos de todas las cuentas existentes.

En el método, incluiremos la acuñación del token en los parámetros de la llamada a getTokenAccounts. Mientras recorremos todas las cuentas de token, agregaremos a una lista cada propietario único. Cuando el método termine de ejecutarse, guardaremos esta lista en un archivo JSON que contendrá todos los titulares del token.

const findHolders = async () => {
  // Pagination logic
  let page = 1;
 	// allOwners will store all the addresses that hold the token
  let allOwners = new Set();

  while (true) {
    const response = await fetch(url, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        jsonrpc: "2.0",
        method: "getTokenAccounts",
        id: "helius-test",
        params: {
          page: page,
          limit: 1000,
          displayOptions: {},
					//mint address for the token we are interested in
          mint: "CKfatsPMUf8SkiURsDXs7eK6GWb4Jsd6UDbs7twMCWxo",
        },
      }),
    });

		// Check if any error in the response
      if (!response.ok) {
        console.log(
          `Error: ${response.status}, ${response.statusText}`
        );
        break;
      }

    const data = await response.json();
  	// Pagination logic.
    if (!data.result || data.result.token_accounts.length === 0) {
      console.log(`No more results. Total pages: ${page - 1}`);
      break;
    }
    console.log(`Processing results from page ${page}`);
 		// Adding unique owners to a list of token owners.
    data.result.token_accounts.forEach((account) =>
      allOwners.add(account.owner)
    );
    page++;
  }

  fs.writeFileSync(
    "output.json",
    JSON.stringify(Array.from(allOwners), null, 2)
  );
};

‍En el ejemplo anterior, se llama varias veces al método getTokenAccounts mientras se recorren todas las cuentas de token mediante paginación. La respuesta de la API proporcionará los siguientes datos para cada cuenta de token: 

{
"address": "CVMR1nbxTcQ7Jpa1p137t5TyKFii3Y7Vazt9fFct3tk9",
"mint": "SHDWyBxihqiCj6YekG2GUr7wqKLeLAMK1gHZck9pL6y",
"owner": "CckxW6C1CjsxYcXSiDbk7NYfPLhfqAm3kSB5LEZunnSE",
"amount": 100000000,
"delegated_amount": 0,
"frozen": false
},

Extrajimos el propietario de estas cuentas de token y lo agregamos a nuestra lista. Si quisiéramos, también podríamos almacenar la cantidad de tokens que contiene cada cuenta para identificar a los mayores titulares. 

Una vez hecho esto, solo debemos llamar al método:

findHolders();

El código completo de nuestro archivo getTokenHolders.js debería verse así:

const url = `https://mainnet.helius-rpc.com/?api-key=`;
const fs = require("fs");

const findHolders = async () => {
  let page = 1;
  let allOwners = new Set();

  while (true) {
    const response = await fetch(url, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        jsonrpc: "2.0",
        method: "getTokenAccounts",
        id: "helius-test",
        params: {
          page: page,
          limit: 1000,
          displayOptions: {},
          mint: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
        },
      }),
    });

		// Check if any error in the response
      if (!response.ok) {
        console.log(
          `Error: ${response.status}, ${response.statusText}`
        );
        break;
      }

    const data = await response.json();

    if (!data.result || data.result.token_accounts.length === 0) {
      console.log(`No more results. Total pages: ${page - 1}`);

      break;
    }
    console.log(`Processing results from page ${page}`);
    data.result.token_accounts.forEach((account) =>
      allOwners.add(account.owner)
    );
    page++;
  }

  fs.writeFileSync(
    "output.json",
    JSON.stringify(Array.from(allOwners), null, 2)
  );
};

findHolders();

Resultado

El resultado de nuestro código será una lista de todos los titulares y se verá así:

[
  "111An9SVxuPpgjnuXW9Ub7hcVmZpYNrYZF4edsGwJEW",
  "11Mmng3DoMsq2Roq8LBcqdz6d4kw9oSD8oka9Pwfbj",
  "112uNfcC8iwX9P2TkRdJKyPatg6a4GNcr9NC5mTc2z3",
  "113uswn5HNgEfBUKfK4gVBmd2GpZYbxd1N6h1uUWReg",
  "11CyvpdYTqFmCVWbJJeKFNX8F8RSjNSYW5VVUi8eX4P",
  "11MANeaiHEy9S9pRQNu3nqKa2gpajzX2wrRJqWrf8dQ",
…
]

Puedes probarlo con nuestro ejemplo en Replit.

Conclusión

Para concluir esta guía, explicamos correctamente el proceso para identificar a los titulares de un token de Solana mediante el método getTokenAccounts de la API de Helius. Este tutorial te dará las habilidades necesarias para interactuar directamente con la comunidad de tu token, ya sea mediante airdrops, análisis u otras interacciones. Si tienes alguna pregunta, contáctanos a través de Twitter o Discord. ‍