Apresentamos a Parsed Events Scan API

Escaneie por instruções de programas da Solana

A solicitação a seguir escaneia o histórico do programa Pump.fun e retorna transações analisadas que contêm uma instrução buy ou 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
  }'

Com essa solicitação, a ferramenta de demonstração da Parsed Events Scan escaneou 261 registros e encontrou 100 correspondências. Ela retornou os 100 eventos mais recentes em 182 ms, com um custo total de apenas 11 créditos:

Os nomes das instruções podem usar a grafia de qualquer versão da IDL do programa ou o formato snake_case. A Parsed Events Scan API verifica tanto as instruções de nível superior quanto as instruções internas invocadas por meio de invocações entre programas (CPI).

Os programas costumam ter várias versões de uma determinada ação. Por exemplo, a IDL da Pump.fun tem as instruções buy, buy_exact_sol_in, buy_v2, buy_exact_quote_in_v2, sell e sell_v2. A Scan API permite listar todos os nomes de instruções que você deseja usar na correspondência.

Compras e vendas representam grande parte da atividade da Pump.fun, então as correspondências são encontradas rapidamente. A Scan gera mais economia quando a atividade de que você precisa é rara. As taxas de criador, por exemplo, representam uma pequena fração das transações do 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
  }'

Ao usar a ferramenta de demonstração da Parsed Events Scan para encontrar as dez reivindicações mais recentes, podemos ver que ela escaneou 3.402 transações em 182 ms e cobrou 14 créditos por essa solicitação:

A chamada equivalente a getTransactionsForAddress custaria 350 créditos, um valor 25 vezes maior em comparação com o endpoint de escaneamento.

E se um programa da Solana não tiver uma IDL com instruções nomeadas?

Para usar a Parsed Events Scan API com programas da Solana que não têm uma IDL, você pode fazer a correspondência usando prefixos dos dados das instruções.

Cada discriminador pode conter de um a oito bytes codificados em hexadecimal. Você pode combinar nomes e discriminadores para um único programa; uma instrução corresponde a qualquer um deles. Por exemplo:

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

Escaneie vários programas da Solana de uma só vez

Você pode listar até 20 programas em uma única solicitação à Parsed Events Scan API, e uma transação corresponde aos critérios quando chama qualquer um deles.

Por exemplo, esta solicitação escaneia as negociações de uma carteira para encontrar correspondências na Jupiter, DFlow e Pump.fun em um único escaneamento:

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

Escaneie por mint de token

A Scan API também pode encontrar transações que envolveram determinado mint de token verificando os saldos de tokens anteriores e posteriores a cada transação para o endereço do mint. Por padrão, ela conta apenas os saldos que pertencem ao endereço escaneado.

Ao escanear uma carteira em busca de um token, defina tokenAccounts como balanceChanged. Há vários casos em que uma transferência de token recebida envolve apenas a conta de token da carteira, não a carteira em si. Por isso, o histórico da carteira exclui essas transações por padrão.

Por exemplo, esta solicitação encontra a atividade de wSOL de Ansem durante setembro 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
    }
  }'

A Scan API encontrou 53 transações correspondentes após escanear um total de 7.555 transações:

Combine programas e mints

Os desenvolvedores podem definir programs e mints para restringir os resultados. Quando combinados, uma transação precisa satisfazer ambos os critérios para corresponder. No entanto, para restringir a atividade de um programa a um único token, o endereço escaneado é mais importante do que os filtros.

Por exemplo, escaneie o endereço do mint de um token, em vez do programa Pump.fun, para encontrar todas as negociações de determinado token na Pump.fun. Cada compra ou venda lista o mint como uma conta, por isso corresponde aos critérios por padrão:

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

O histórico do mint contém apenas a atividade desse token, enquanto o histórico do programa contém negociações de todos os tokens. Portanto, escanear o programa desperdiçaria o orçamento com transações não relacionadas.

Escolha um escopo de correspondência

Por padrão, as instruções de um programa e os saldos de tokens de um mint contam apenas quando envolvem o endereço escaneado. Um saldo de token envolve o endereço quando esse endereço é proprietário da conta de token ou quando é o mint do saldo. Uma instrução envolve o endereço quando:

• Uma de suas contas é o endereço
• Uma de suas contas é uma conta de token pertencente ao endereço
• O endereço é um mint, e uma das contas da instrução é uma conta de token desse mint
• O endereço é o programa chamado

Defina "scope": "transaction" em um programa ou mint para considerá-lo em qualquer parte da transação. Use essa opção quando o endereço apenas pagar a taxa, executar uma transação multisig ou não for uma conta da instrução usada na correspondência.

Por exemplo, esta solicitação encontra transações de um token que também movimentaram USDC. No escopo padrão, os saldos de USDC precisariam pertencer ao endereço do mint, e nada corresponderia aos critérios:

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

Os programas também aceitam o mesmo escopo de correspondência. Esta solicitação encontra os swaps da Jupiter cujas taxas foram pagas por um retransmissor.

O retransmissor apenas assina as transações como pagador da taxa, portanto não é uma das contas da instrução de rota, e nenhuma dessas transações corresponderia aos critérios no escopo padrão:

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

A mesma lógica se aplica a um membro de multisig que executa uma proposta. A instrução executada pelo multisig atua nas contas do cofre, não nas contas do membro. Portanto, escanear o histórico do membro em busca delas exige o escopo transaction.

Rastreie SOL nativo

O SOL nativo não tem saldos de tokens, então o escaneamento faz a correspondência com base em lamports.

Informe o mint de SOL nativo (So11111111111111111111111111111111111111111), que é diferente do SOL encapsulado. Uma transação corresponde aos critérios quando o saldo de SOL do endereço escaneado muda, sem contar a taxa paga:

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

Isso captura o SOL pago por um programa sem uma instrução de transferência, como em uma venda na Pump.fun. Também captura movimentações incidentais, como gorjetas da Jito e aluguel pago ou reembolsado por contas.

Obtenha transações analisadas, assinaturas ou uma contagem

returnShape define o que a resposta inclui para as correspondências:

Por exemplo, esta solicitação conta as compras de um trader na Pump.fun em setembro de 2026 sem retornar as transações:

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

Para fazer a contagem, signatures e count ignoram limit e cobrem todas as correspondências no intervalo escaneado por uma solicitação. Para contar um histórico longo, continue paginando e some scan.matchedTransactions.

Os três formatos têm o mesmo custo.

Controle quanto do histórico cada solicitação escaneia

Um escaneamento pode inspecionar até 10.000 transações por solicitação e retornar até 100 correspondências.

O campo budget.maxScannedTransactions controla esse limite, cujo padrão é 10.000. O campo limit controla quantas correspondências o endpoint retorna; ele aceita valores de 1 a 100, com padrão de 100.

Os dois controles são separados porque as correspondências podem ser esparsas. Ou seja, uma solicitação pode escanear milhares de transações e retornar apenas algumas correspondências.

Por padrão, as solicitações de escaneamento incluem apenas transações bem-sucedidas.

Defina status como failed ou any para incluir transações com falha. As transações com falha incluem os erros decodificados do programa quando eles estão definidos na IDL do programa.

Resumos de escaneamento

Toda resposta inclui um resumo scan:

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

O resumo informa:

• Por que o escaneamento foi interrompido
• Quantas transações foram escaneadas
• Quantas transações corresponderam aos critérios
• O último slot e horário de bloco escaneados
• Quantos créditos a solicitação usou

Como funciona a paginação do escaneamento

Quando um escaneamento é interrompido, o campo scan.stoppedOn informa o motivo:

• windowEnd: o escaneamento chegou ao fim do histórico ou da janela
• limit: a resposta contém o número solicitado de correspondências
• budget: a solicitação atingiu seu orçamento de escaneamento de transações
• deadline: a solicitação atingiu seu limite de tempo

Quando a resposta incluir um paginationToken, envie esse token na próxima solicitação e continue mesmo quando o array data atual estiver vazio. Um resultado vazio pode significar que a solicitação esgotou o orçamento antes de encontrar uma correspondência, não que não existam correspondências posteriores.

Por exemplo, este loop coleta as negociações da última hora na Pump.fun.

Observe que o limite time e o limite máximo de solicitações impedem que ele percorra todo o histórico:

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 analisados sem o pipeline no cliente

Cada item em data usa o mesmo formato TransactionResult do endpoint Parse Transactions da Parsed Events. Os resultados podem incluir instruções decodificadas, transferências, alterações em contas, eventos, resumos de transações e dados analisados específicos de protocolos, quando disponíveis. Se seu aplicativo também precisar do payload original da transação da Solana, defina rawTransaction como "json", "jsonParsed" ou "base64".

A principal diferença está em onde o fluxo de trabalho do histórico é executado.

Seu aplicativo define a pesquisa uma vez, enquanto a Parsed Events Scan API gerencia a paginação do histórico, a correspondência e a análise antes de retornar as transações relevantes.

Use os SDKs mais recentes da Helius

Nossos SDKs de TypeScript e Rust oferecem suporte à Parsed Events API e ao novo endpoint de escaneamento.

O SDK de TypeScript disponibiliza os escaneamentos como helius.parsedEvents.scan(). O tipo da resposta segue o returnShape informado:

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

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

O SDK de Rust também disponibiliza scan, scan_signatures e scan_count em helius.parsed_events(), todos aceitando o mesmo ScanRequest.

Preços da Parsed Events Scan API

Cada solicitação à Parsed Events Scan API custa 10 créditos, mais 1 crédito para cada página de histórico escaneada. Uma página de histórico contém até 1.000 transações.

Por exemplo, uma solicitação que usa o orçamento padrão de 10.000 transações custa no máximo 20 créditos. A resposta informa a cobrança exata em scan.creditsCharged.

Para comparar, o escaneamento custa um décimo do valor da paginação do mesmo histórico com getTransactionsForAddress, que custa 100 créditos por página (até 1.000 transações).

Controle de uso

Para controlar o uso, use o endereço mais específico possível e adicione limites de slot ou tempo quando puder. Menos transações não relacionadas significam mais correspondências úteis em cada solicitação.

Substitua a Enhanced Transactions API pela Parsed Events API

A Enhanced Transactions API continua disponível em modo de manutenção, mas não recebe novos tipos de parser nem novos recursos. A Parsed Events é sua sucessora e usa o catálogo de IDLs da Helius para decodificar instruções em milhares de programas da Solana. Se ainda não fez isso, migre para a Parsed Events API.

Qual é a diferença?

A Enhanced Transactions API organiza as atividades em um conjunto fixo de tipos de transação, como swaps, transferências e vendas de NFT, enquanto a Parsed Events Scan API permite pesquisas mais precisas por instrução de programa, discriminador bruto, mint de token ou uma combinação desses critérios. A Helius aplica esses filtros ao escanear o histórico do endereço e analisa apenas as transações correspondentes.

A Parsed Events API oferece aos desenvolvedores uma cobertura mais ampla de programas e mais controle sobre consultas de histórico, sem a necessidade de manter um scanner no cliente.

Comece agora

Use a Parsed Events Scan API quando souber qual atividade onchain precisa encontrar, mas não quiser criar e manter um scanner de histórico no cliente. Leia a referência da API Scan Transaction History para conferir o esquema completo da solicitação, os campos da resposta, os limites, os erros e mais exemplos.

Para continuar explorando o que a Scan API pode fazer, confira a nova ferramenta Scan no seu painel da Helius. Experimente escanear endereços por programa, mints e filtros.