Presentamos la API Parsed Events Scan

Escanea por instrucciones de programas de Solana

La siguiente solicitud escanea el historial del programa Pump.fun y devuelve transacciones analizadas que contienen una instrucción buy o sell:

curl --request POST \
  --url "https://mainnet.helius-rpc.com/v1/parsed-events/scan?api-key=$HELIUS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "address": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
    "match": {
      "programs": [
        {
          "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
          "instructions": ["buy", "sell"]
        }
      ]
    },
    "limit": 100
  }'

Con esta solicitud, la herramienta de demostración de Parsed Events Scan escaneó 261 registros y encontró 100 coincidencias. Devolvió los 100 eventos más recientes en 182 ms, con un costo total de solo 11 créditos:

Los nombres de instrucciones pueden usar la ortografía de cualquier versión de la IDL del programa o el formato snake_case. La API Parsed Events Scan comprueba tanto las instrucciones de nivel superior como las instrucciones internas invocadas mediante invocaciones entre programas (CPI).

Los programas suelen tener varias versiones de una acción determinada. Por ejemplo, la IDL de Pump.fun tiene instrucciones buy, buy_exact_sol_in, buy_v2, buy_exact_quote_in_v2, sell y sell_v2. La API Scan te permite enumerar todos los nombres de instrucciones que quieres buscar.

Las compras y ventas representan gran parte de la actividad de Pump.fun, por lo que las coincidencias aparecen con bastante rapidez. Scan permite ahorrar más cuando la actividad que necesitas es poco frecuente. Las comisiones de creadores, por ejemplo, representan una pequeña fracción de las transacciones del programa:

curl --request POST \
  --url "https://mainnet.helius-rpc.com/v1/parsed-events/scan?api-key=$HELIUS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "address": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
    "match": {
      "programs": [
        {
          "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
          "instructions": ["collect_creator_fee"]
        }
      ]
    },
    "limit": 10
  }'

Al usar la herramienta de demostración de Parsed Events Scan para encontrar los diez reclamos más recientes, vemos que la herramienta escaneó 3,402 transacciones en 182 ms y que esta solicitud costó 14 créditos:

La llamada equivalente a getTransactionsForAddress costaría 350 créditos, 25 veces más que el endpoint de escaneo.

¿Qué ocurre si un programa de Solana no tiene una IDL con instrucciones nombradas?

Para usar la API Parsed Events Scan con programas de Solana que no tienen una IDL, puedes buscar coincidencias mediante prefijos de datos de instrucciones.

Cada discriminador puede contener de uno a ocho bytes codificados en hexadecimal. Puedes combinar nombres y discriminadores para un mismo programa; una instrucción coincide con cualquiera de los dos. Por ejemplo:

{
  "match": {
    "programs": [
      {
        "programId": "<PROGRAM_ADDRESS>",
        "discriminators": ["0x66063d1201daebea"]
      }
    ]
  }
}

Escanea varios programas de Solana a la vez

Puedes incluir hasta 20 programas en una sola solicitud a la API Parsed Events Scan. Una transacción coincide cuando llama a cualquiera de ellos.

Por ejemplo, esta solicitud escanea las operaciones de una billetera para buscar coincidencias en Jupiter, DFlow y Pump.fun en un solo escaneo:

{
  "address": "<WALLET_ADDRESS>",
  "match": {
    "programs": [
      {
        "programId": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",
        "instructions": ["route", "shared_accounts_route", "route_v2", "shared_accounts_route_v2"]
      },
      { "programId": "DF1ow4tspfHX9JwWJsAb9epbkA8hmpSEAtxXy1V27QBH" },
      {
        "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
        "instructions": ["buy", "buy_exact_sol_in", "buy_v2", "sell", "sell_v2"]
      }
    ]
  }
}

Escanea por mint de token

La API Scan también puede encontrar transacciones que interactuaron con un mint de token determinado. Para ello, comprueba los saldos de tokens anteriores y posteriores a cada transacción para la dirección del mint y, de forma predeterminada, solo cuenta los saldos que pertenecen a la dirección escaneada.

Cuando escanees una billetera en busca de un token, configura tokenAccounts como balanceChanged. En distintos casos, una transferencia de tokens entrante solo interactúa con la cuenta de token de la billetera, no con la billetera en sí. Por eso, el historial de la billetera excluye esas transacciones de forma predeterminada.

Por ejemplo, esta solicitud encuentra la actividad de wSOL de Ansem durante septiembre de 2026:

curl --request POST \
  --url "https://mainnet.helius-rpc.com/v1/parsed-events/scan?api-key=$HELIUS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "address": "<ANSEM_WALLET_ADDRESS>",
    "match": {
      "mints": [{ "mint": "So11111111111111111111111111111111111111112" }]
    },
    "tokenAccounts": "balanceChanged",
    "time": {
      "gte": 1788220800,
      "lte": 1790812800
    }
  }'

La API Scan encontró 53 transacciones coincidentes después de escanear un total de 7,555 transacciones:

Combina programas y mints

Los desarrolladores pueden configurar tanto programs como mints para acotar los resultados. Cuando se combinan, una transacción debe cumplir ambos criterios para coincidir. Sin embargo, para limitar la actividad de un programa a un solo token, la dirección escaneada importa más que los filtros.

Por ejemplo, escanea la dirección del mint de un token en lugar del programa Pump.fun para encontrar todas las operaciones de Pump.fun con un token determinado. Cada compra o venta incluye el mint como una cuenta, por lo que coincide de forma predeterminada:

{
  "address": "<MINT_ADDRESS>",
  "match": {
    "programs": [
      {
        "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
        "instructions": ["buy", "buy_exact_sol_in", "buy_v2", "sell", "sell_v2"]
      }
    ]
  }
}

El historial del mint contiene solo la actividad de ese token, mientras que el historial del programa contiene operaciones de todos los tokens. Por eso, escanearlo desperdiciaría presupuesto en transacciones no relacionadas.

Elige un alcance de coincidencia

De forma predeterminada, las instrucciones de un programa y los saldos de tokens de un mint solo cuentan cuando involucran a la dirección escaneada. Un saldo de token involucra a la dirección cuando esta posee la cuenta de token o cuando la dirección es el mint del saldo. Una instrucción involucra a la dirección cuando:

• Una de sus cuentas es la dirección
• Una de sus cuentas es una cuenta de token que pertenece a la dirección
• La dirección es un mint y una de las cuentas de la instrucción es una cuenta de token de ese mint
• La dirección es el programa llamado

Configura "scope": "transaction" en un programa o mint para contarlo en cualquier parte de la transacción. Úsalo cuando la dirección solo paga la comisión, ejecuta una transacción multifirma o no es una cuenta de la instrucción que buscas.

Por ejemplo, esta solicitud encuentra transacciones de un token que también movieron USDC. Con el alcance predeterminado, los saldos de USDC tendrían que pertenecer a la dirección del mint y no habría coincidencias:

{
  "address": "<MINT_ADDRESS>",
  "match": {
    "mints": [
      { "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "scope": "transaction" }
    ]
  },
  "returnShape": "signatures"
}

Los programas también admiten el mismo alcance de coincidencia. Esta solicitud encuentra los swaps de Jupiter cuyas comisiones pagó un retransmisor.

El retransmisor solo firma las transacciones como pagador de comisiones, por lo que no es una de las cuentas de la instrucción de ruta. Ninguna de estas transacciones coincidiría con el alcance predeterminado:

{
  "address": "<RELAYER_ADDRESS>",
  "match": {
    "programs": [
      {
        "programId": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",
        "instructions": ["route", "shared_accounts_route", "route_v2", "shared_accounts_route_v2"],
        "scope": "transaction"
      }
    ]
  },
  "returnShape": "signatures"
}

La misma lógica se aplica a un miembro de una cuenta multifirma que ejecuta una propuesta. La instrucción que ejecuta la cuenta multifirma actúa sobre las cuentas de la bóveda, no sobre las del miembro. Por eso, para encontrarlas en el historial del miembro, se necesita el alcance transaction.

Haz seguimiento del SOL nativo

El SOL nativo no tiene saldos de tokens, por lo que el escaneo busca coincidencias en lamports.

Pasa el mint de SOL nativo (So11111111111111111111111111111111111111111), que es diferente del SOL envuelto. Una transacción coincide cuando cambia el saldo de SOL de la dirección escaneada, sin contar la comisión que pagó:

{
  "address": "<WALLET_ADDRESS>",
  "match": {
    "mints": [{ "mint": "So11111111111111111111111111111111111111111" }]
  },
  "time": { "gte": 1788220800, "lt": 1790812800 }
}

Esto detecta el SOL que paga un programa sin una instrucción de transferencia, como una venta en Pump.fun. También detecta movimientos incidentales, como propinas de Jito y rentas pagadas o reembolsadas desde cuentas.

Obtén transacciones analizadas, firmas o un conteo

returnShape define lo que incluye la respuesta para las coincidencias:

Por ejemplo, esta solicitud cuenta las compras de Pump.fun de un trader en septiembre de 2026 sin devolver transacciones:

{
  "address": "<WALLET_ADDRESS>",
  "match": {
    "programs": [
      {
        "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
        "instructions": ["buy", "buy_exact_sol_in", "buy_v2"]
      }
    ]
  },
  "returnShape": "count",
  "time": { "gte": 1788220800, "lt": 1790812800 }
}

Para hacer el conteo, signatures e count ignoran limit y abarcan todas las coincidencias del rango que escanea una solicitud. Para contar un historial largo, sigue paginando y suma scan.matchedTransactions.

Los tres formatos tienen el mismo costo.

Controla cuánto historial escanea cada solicitud

Un escaneo puede inspeccionar hasta 10,000 transacciones por solicitud y devolver hasta 100 coincidencias.

El campo budget.maxScannedTransactions controla ese límite y su valor predeterminado es 10,000. El campo limit controla cuántas coincidencias devuelve el endpoint; acepta valores de 1 a 100 y su valor predeterminado es 100.

Los dos controles están separados porque las coincidencias pueden ser poco frecuentes. Es decir, una solicitud puede escanear miles de transacciones y devolver solo unas pocas coincidencias.

De forma predeterminada, las solicitudes de escaneo solo incluyen transacciones exitosas.

Configura status como failed o any para incluir transacciones fallidas. Las transacciones fallidas incluyen errores de programa decodificados cuando la IDL del programa los define.

Resúmenes de escaneo

Cada respuesta incluye un resumen scan:

{
  "data": [],
  "paginationToken": "460903064:422",
  "scan": {
    "stoppedOn": "budget",
    "scannedTransactions": 2000,
    "matchedTransactions": 0,
    "scannedThrough": {
      "slot": 460903064,
      "blockTime": 1792856105
    },
    "creditsCharged": 12
  }
}

El resumen te indica:

• Por qué se detuvo el escaneo
• Cuántas transacciones escaneó
• Cuántas transacciones coincidieron
• El último slot y tiempo de bloque que escaneó
• Cuántos créditos usó la solicitud

Cómo funciona la paginación de Scan

Cuando se detiene un escaneo, el campo scan.stoppedOn indica el motivo:

• windowEnd: el escaneo llegó al final del historial o del intervalo
• limit: la respuesta contiene el número solicitado de coincidencias
• budget: la solicitud alcanzó su presupuesto de escaneo de transacciones
• deadline: la solicitud alcanzó su límite de tiempo

Cuando la respuesta incluya un paginationToken, envía ese token en la siguiente solicitud y continúa incluso si el array data actual está vacío. Un resultado vacío puede significar que la solicitud agotó su presupuesto antes de encontrar una coincidencia, no que no existan coincidencias posteriores.

Por ejemplo, este bucle recopila las operaciones de Pump.fun de la última hora.

Ten en cuenta que el límite time y el límite de solicitudes evitan que recorra todo el historial:

const PUMP_PROGRAM = "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P";
const ONE_HOUR_AGO = Math.floor(Date.now() / 1000) - 3600;
const MAX_REQUESTS = 50;

let paginationToken;
let requests = 0;

async function scanHistory() {
  const response = await fetch(
    `https://mainnet.helius-rpc.com/v1/parsed-events/scan?api-key=${process.env.HELIUS_API_KEY}`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        address: PUMP_PROGRAM,
        match: {
          programs: [{ programId: PUMP_PROGRAM, instructions: ["buy", "sell"] }],
        },
        time: { gte: ONE_HOUR_AGO },
        limit: 100,
        ...(paginationToken && { paginationToken }),
      }),
    }
  );

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  }

  return response.json();
}

do {
  const page = await scanHistory();
  requests++;

  for (const transaction of page.data) {
    console.log(transaction.signature);
  }

  paginationToken = page.paginationToken;
} while (paginationToken && requests < MAX_REQUESTS);

Resultados analizados sin un pipeline del lado del cliente

Cada elemento de data usa el mismo formato TransactionResult que el endpoint Parse Transactions de Parsed Events. Los resultados pueden incluir instrucciones decodificadas, transferencias, cambios en cuentas, eventos, resúmenes de transacciones y datos analizados específicos del protocolo cuando estén disponibles. Si tu aplicación también necesita el payload original de la transacción de Solana, configura rawTransaction como "json", "jsonParsed" o "base64".

La principal diferencia es dónde se ejecuta el flujo de trabajo del historial.

Tu aplicación define la búsqueda una vez, mientras que la API Parsed Events Scan gestiona la paginación del historial, las coincidencias y el análisis antes de devolver las transacciones relevantes.

Usa los SDK más recientes de Helius

Tanto nuestro SDK de TypeScript como el de Rust admiten nuestra API Parsed Events y el nuevo endpoint de escaneo.

El SDK de TypeScript expone los escaneos como helius.parsedEvents.scan(). El tipo de respuesta sigue el valor returnShape proporcionado:

const { scan } = await helius.parsedEvents.scan({
  address: "<WALLET_ADDRESS>",
  match: {
    programs: [{ programId: "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P", instructions: ["buy", "sell"] }],
  },
  returnShape: "count",
});

console.log(scan.matchedTransactions, scan.stoppedOn);

El SDK de Rust también ofrece scan, scan_signatures e scan_count en helius.parsed_events(). Todos aceptan el mismo ScanRequest.

Precios de la API Parsed Events Scan

Cada solicitud a la API Parsed Events Scan cuesta 10 créditos más 1 crédito por cada página del historial escaneada. Una página del historial contiene hasta 1,000 transacciones.

Por ejemplo, una solicitud que usa el presupuesto predeterminado de 10,000 transacciones cuesta como máximo 20 créditos. La respuesta informa el cargo exacto en scan.creditsCharged.

En comparación, escanear cuesta una décima parte que paginar el mismo historial con getTransactionsForAddress, que cuesta 100 créditos por página (hasta 1,000 transacciones).

Controla el uso

Para controlar el uso, utiliza la dirección más específica posible y agrega límites de slot o tiempo cuando puedas. Menos transacciones no relacionadas significan más coincidencias útiles en cada solicitud.

Reemplaza la API Enhanced Transactions por la API Parsed Events

La API Enhanced Transactions sigue disponible en modo de mantenimiento, pero no recibe nuevos tipos de analizadores ni nuevas funciones. Parsed Events es su sucesora y usa el catálogo de IDL de Helius para decodificar instrucciones de miles de programas de Solana. Si aún no lo has hecho, migra a la API Parsed Events.

¿Cuál es la diferencia?

La API Enhanced Transactions organiza la actividad en un conjunto fijo de tipos de transacciones, como swaps, transferencias y ventas de NFT. En cambio, la API Parsed Events Scan permite realizar búsquedas más precisas por instrucción de programa, discriminador sin procesar, mint de token o una combinación de estos criterios. Helius aplica esos filtros mientras escanea el historial de la dirección y solo analiza las transacciones coincidentes.

La API Parsed Events ofrece a los desarrolladores una cobertura de programas más amplia y más control sobre las consultas históricas, sin tener que mantener un escáner del lado del cliente.

Comienza ahora

Usa la API Parsed Events Scan cuando sepas qué actividad onchain necesitas, pero no quieras crear y mantener un escáner de historial del lado del cliente. Lee la referencia de la API Scan Transaction History para consultar el esquema completo de solicitudes, los campos de respuesta, los límites, los errores y más ejemplos.

Para seguir explorando lo que puede hacer la API Scan, prueba la nueva herramienta Scan en tu panel de Helius. Intenta escanear direcciones por programa y mints, y aplica filtros.