Como Usar preconfSubscribe

Use Sender Max (gorjeta mínima: 0.001 SOL) para agir sobre Pré-confirmations. Uma pré-confirmation só vale a pena se você registrar sua transação primeiro — Sender Max é a maneira mais rápida de fazer isso. Construa no Sender Max desde o início para obter todos os benefícios das Pré-confirmations.

O que é `preconfSubscribe`?

preconfSubscribe é um método WebSocket da Helius que transmite Preconfirmations — transações entregues antes de serem coletadas em entradas e fragmentadas em shreds. É o sinal de transação de menor latência oferecido pela Helius. Uma única assinatura entrega tanto as preconfirmações da Helius, emitidas no instante em que o líder executa a transação e contendo o status de execução, quanto as preconfirmações do BAM de validadores que executam o cliente Block Assembly Marketplace da Jito, emitidas quando o validador se compromete a executar a transação. O acesso está disponível em todos os planos pagos — consulte Preços.

A transmissão não é contínua. A cobertura escala com a participação de stake encaminhando para o Helius ou executando BAM, portanto, espere slots sem mensagens — lide com essas lacunas com graça. Veja Cobertura.

preconfSubscribe é servido a partir de wss://beta.helius-rpc.com — o endpoint Gatekeeper da Helius — em vez de mainnet.helius-rpc.com. Autentique-se com sua chave API como um parâmetro de consulta.

wss://beta.helius-rpc.com/?api-key=<API_KEY>

O hostname beta refere-se à implementação do Gatekeeper, não à maturidade das Pré-confirmations. Pré-confirmations são lançadas no endpoint Gatekeeper primeiro; ele se tornará o endpoint padrão à medida que a Helius migrar o tráfego para o Gatekeeper.

Inscrever-se

Envie uma solicitação JSON-RPC com o método preconfSubscribe. O servidor responde com um ID de inscrição e, em seguida, transmite uma notificação para cada transação. Passe um filtro opcional como o primeiro elemento params para receber apenas transações correspondentes; omita params para receber o fluxo completo de ambos, Helius e BAM.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "preconfSubscribe"
}

Resposta da Inscrição

{
  "jsonrpc": "2.0",
  "result": 24040,
  "id": 1
}

Armazene o result — é o ID da inscrição que você usa para cancelar a inscrição. Após essa confirmação, as notificações são transmitidas como quadros binários (veja abaixo).

Filtragem

Por padrão, preconfSubscribe transmite todas as transações de ambas as fontes. Para restringir o fluxo, passe um objeto de filtro como o primeiro elemento de params. A filtragem acontece no lado do servidor, então você só paga e recebe as transações de seu interesse.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "preconfSubscribe",
  "params": [
    {
      "includeSource": ["helius", "bam"],
      "failed": false,
      "regionInclude": ["ewr", "fra"],
      "accountInclude": ["9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"],
      "accountExclude": ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"],
      "accountRequired": ["11111111111111111111111111111111"],
      "signerExclude": ["8qbHbw2BbbTHBW1sbeqakYXVKRQM8Ne7pLK7m6CVfeR"]
    }
  ]
}

Todos os campos são opcionais — um campo ausente significa “sem restrição” para esse predicado, portanto, um filtro vazio (ou sem params) corresponde a todas as transações de ambas as fontes.

Campo	Tipo	Semântica
`includeSource`	`string[]`	Fontes a serem recebidas: `helius` e `bam`. Omita o campo ou passe um array vazio para receber ambas as fontes. Use `["helius"]` ou `["bam"]` para receber uma fonte.
`failed`	`boolean`	`true` retorna apenas transações com falha (revertidas); `false` retorna apenas transações bem-sucedidas. Ambos os valores excluem transações da Helius com status desconhecido. Omita o campo para receber todos os status.
`regionInclude`	`string[]`	Se não estiver vazio, a transação deverá ter origem em uma destas regiões.
`accountInclude`	`string[]`	Se não estiver vazio, a transação deverá referenciar pelo menos uma destas contas.
`accountExclude`	`string[]`	A transação será descartada se referenciar qualquer uma destas contas. Tem precedência sobre `accountInclude`.
`accountRequired`	`string[]`	A transação deverá referenciar todas estas contas.
`signerInclude`	`string[]`	Se não estiver vazio, a transação deverá ser assinada por pelo menos uma destas contas.
`signerExclude`	`string[]`	A transação será descartada se for assinada por qualquer uma destas contas. Tem precedência sobre `signerInclude`.
`signatures`	`string[]`	Se não estiver vazio, a primeira assinatura da transação deverá corresponder a uma destas assinaturas.
`instructions`	`object[]`	Se não estiver vazio, pelo menos uma instrução de nível superior deverá corresponder a um destes filtros de instrução.

Regras de filtro:

Todos os predicados são combinados com AND e avaliados na ordem includeSource → failed → regionInclude → signatures → accountExclude → accountRequired → accountInclude → signerExclude → signerInclude → instructions.
As pré-confirmações do BAM com status desconhecido ignoram o filtro failed. As pré-confirmações da Helius com status desconhecido não correspondem a um filtro failed explícito.
includeSource deve ser um array contendo apenas helius e bam. Um valor inválido retorna o erro JSON-RPC -32602 (parâmetros inválidos).
As contas são chaves públicas codificadas em base58. Um valor inválido retorna o erro JSON-RPC -32602 (parâmetros inválidos).
Cada lista de contas ou signatários é limitada a 10.000 entradas. signatures é limitado a 1.000 entradas.

O filtro obsoleto includeBam continua disponível para compatibilidade com versões anteriores. includeBam: false equivale a includeSource: ["helius"]. includeBam: true ou um campo omitido seleciona ambas as fontes. Não envie includeBam e includeSource juntos.

Para receber apenas pré-confirmações da Helius:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "preconfSubscribe",
  "params": [{ "includeSource": ["helius"] }]
}

Filtragem por signatário e assinatura

Use signerInclude para encontrar transações assinadas por uma conta específica. Use signerExclude para remover transações assinadas por qualquer conta listada. Uma conta referenciada não é considerada um signatário. Use signatures quando você já souber quais transações deseja rastrear. O filtro corresponde à primeira assinatura da transação, que é a assinatura usada pelos métodos RPC da Solana. O filtro não pode ser alterado após a assinatura do fluxo, portanto, crie uma nova assinatura para rastrear novas assinaturas de transação.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "preconfSubscribe",
  "params": [
    {
      "signerInclude": ["9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"],
      "signerExclude": ["8qbHbw2BbbTHBW1sbeqakYXVKRQM8Ne7pLK7m6CVfeR"]
    }
  ]
}

Filtragem de instruções

Use instructions para encontrar instruções de nível superior por programa e dados da instrução. Cada filtro de instrução aceita estes campos:

Campo	Tipo	Semântica
`programId`	`string`	Obrigatório. O programa invocado pela instrução.
`memcmp`	`object[]`	Opcional. Cada entrada compara o `bytes` decodificado em um `offset`. Todas as entradas devem corresponder.
`dataSize`	`number`	Opcional. Os dados da instrução devem ter exatamente esse comprimento em bytes.

Cada entrada memcmp aceita codificação base58, base64 ou hex. O padrão é base58. Uma transação corresponde quando uma instrução de nível superior atende a todas as condições de qualquer filtro de instrução. A solicitação a seguir encontra instruções buy da pump.fun pelo discriminador Anchor correspondente:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "preconfSubscribe",
  "params": [
    {
      "instructions": [
        {
          "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
          "memcmp": [
            {
              "offset": 0,
              "bytes": "66063d1201daebea",
              "encoding": "hex"
            }
          ]
        }
      ]
    }
  ]
}

O filtro verifica apenas instruções de nível superior. Ele não pode encontrar instruções invocadas por meio de uma invocação entre programas (CPI), pois essas instruções não existem antes da execução. Você pode fornecer até 16 filtros de instrução e quatro entradas memcmp por filtro de instrução. Cada valor memcmp deve ser decodificado em 1–128 bytes. Um deslocamento final de memcmp e dataSize não podem exceder 4.096 bytes.

Resolução da tabela de pesquisa de endereços (ALT)

Os filtros de conta correspondem a mais do que as chaves de conta estáticas da transação — a Helius resolve as tabelas de pesquisa de endereços v0 no lado do servidor. Portanto, accountInclude, accountExclude e accountRequired também correspondem a contas que uma transação carrega por meio de uma ALT. Isso significa que você pode filtrar por qualquer conta acessada por uma transação, mesmo quando ela aparece apenas por trás de uma tabela de pesquisa — não é necessário manter mapeamentos de ALT nem resolver tabelas por conta própria. Basta passar a chave pública da conta, e a Helius fará a resolução antes de aplicar o filtro.

Filtragem por localização

Use regionInclude para receber apenas transações originadas em regiões específicas. Passe um ou mais códigos de região; uma transação passa pelo filtro quando sua região de origem corresponde a qualquer um deles.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "preconfSubscribe",
  "params": [{ "regionInclude": ["ewr", "fra"] }]
}

A região de origem depende da fonte. Para pré-confirmações da Helius, é a região da Helius que recebeu a transação. Para pré-confirmações do BAM, é o endpoint regional do BAM que emitiu a pré-confirmação, não o local em que a Helius a recebeu. Os endpoints do BAM em Singapura e Dallas são mapeados para sgp e dal. Códigos de região válidos:

Código	Localização
`slc`	Salt Lake City
`fra`	Frankfurt
`lon`	Londres
`pit`	Pittsburgh
`sgp`	Singapura
`ewr`	Newark
`tyo`	Tóquio
`ams`	Amsterdã
`dal`	Dallas
`dub`	Dublin
`mia`	Miami
`lax`	Los Angeles
`iad`	Ashburn
`sea`	Seattle
`hkg`	Hong Kong
`sqq`	Šiauliai, Lituânia

Quando regionInclude está definido, as transações que não contêm informações de região são descartadas. Um código de região não reconhecido retorna o erro JSON-RPC -32602 (parâmetros inválidos).

Payload da notificação

As notificações são entregues como quadros WebSocket binários (não como JSON). As pré-confirmações da Helius e do BAM compartilham o mesmo layout. Cada quadro é um layout de bytes compactado que transporta uma única transação:

Bytes	Campo	Tipo	Descrição
0	`version`	`u8`	Versão do esquema do payload. Atualmente, `1`.
1–8	`slot`	`u64` (little-endian)	O slot ao qual a transação pertence.
9–16	`tx_index`	`u64` (little-endian)	Índice da transação no slot, quando disponível. As pré-confirmações do BAM sempre informam `0`; outras fontes também podem informar `0` quando nenhum índice de transação estiver disponível.
17	`status`	`u8`	Status da transação: `0` = falha, `1` = sucesso, `2` = desconhecido.
18+	`transaction`	`bytes`	A transação no formato de transmissão da Solana. Consulte Como decodificar a transação.

O payload não tem um campo de fonte. Não deduza uma origem no BAM com base em tx_index = 0, pois outras fontes também podem informar 0.

Como distinguir as duas fontes

Como não há um campo de fonte, você não pode classificar uma mensagem arbitrária como Helius ou BAM. O byte status fornece um classificador unidirecional:

status é 0 ou 1 — a mensagem é uma pré-confirmação da Helius, e a transação foi executada. O BAM nunca informa esses valores.
status é 2 — a fonte é ambígua: pode ser uma pré-confirmação do BAM ou uma pré-confirmação da Helius cujo status de execução estava indisponível.

Nenhum outro campo permite fazer essa distinção. O ID de sequência e a posição no pacote do BAM não são transportados neste fluxo. Portanto, não há metadados de ordenação do BAM que possam ser usados como chave. Além disso, regionInclude é um filtro de assinatura do fluxo, não um campo do payload, e não pode ser lido em cada mensagem. Se você precisar que todas as mensagens em um fluxo contenham o mesmo tipo de evidência, defina includeSource: ["helius"] ou includeSource: ["bam"]. Um fluxo exclusivo da Helius contém pré-confirmações emitidas durante a execução pelo líder.

Sempre leia e verifique primeiro o byte version. Atualmente, ele é 1. Se a Helius precisar atualizar o formato do payload, a versão será incrementada — crie uma ramificação com base nela para que seu decodificador continue funcionando após alterações no esquema.

Uma pré-confirmação é um sinal antecipado, não uma garantia. A transação ainda não foi registrada on-chain e pode ser descartada — e o status de execução de uma pré-confirmação da Helius reflete o resultado local do líder, que não é definitivo até que o bloco seja confirmado. Confirme o registro por meio das verificações de compromisso padrão antes de tratá-lo como definitivo.

Como decodificar a transação

Os bytes da transação são encaminhados exatamente como o validador os serializou, na codificação de transmissão padrão da versão da transação. As transações legadas e v0 usam o layout com assinaturas primeiro produzido por bincode. A transação v1 (SIMD-0385) usa um layout com a mensagem primeiro e as assinaturas no final. Por isso, bincode falha em payloads v1. Use um decodificador compatível com todas as versões:

Rust: agave-transaction-view analisa transações legadas, v0 e v1 no local, sem uma cópia intermediária. Esta é a opção recomendada. wincode, o serializador compatível com bincode usado pelos SDKs atuais da Solana, também decodifica v1 em VersionedTransaction.
JavaScript / TypeScript: verifique se a versão da sua biblioteca é compatível com a transação v1. Implementações mais antigas de VersionedTransaction.deserialize aceitam apenas transações legadas e v0. Use @solana/kit 8.0+ ou @solana/web3.js v3. Consulte Compatibilidade com a transação v1.

use agave_transaction_view::transaction_view::TransactionView;

// `frame` is the full binary WebSocket message
let tx_bytes = &frame[18..];
let tx = TransactionView::try_new_unsanitized(tx_bytes)?;

println!("version: {:?}", tx.version()); // Legacy, V0, or V1
println!("signature: {}", tx.signatures()[0]);
for ix in tx.instructions_iter() {
    println!("program index {}: {} bytes", ix.program_id_index, ix.data.len());
}

Notificações duplicadas

As pré-confirmações da Helius e do BAM são desduplicadas por fonte, não entre fontes. Uma pequena parcela das transações chega à Helius por ambas, portanto, você pode receber a mesma assinatura duas vezes, e as duas cópias podem informar slots diferentes. Faça a desduplicação por assinatura no cliente e torne idempotentes as ações acionadas por transações, para que uma segunda notificação não dispare a mesma ação duas vezes. Confirme a execução e o registro por meio das verificações de compromisso padrão.

Exemplo

const WebSocket = require('ws');

const ws = new WebSocket('wss://beta.helius-rpc.com/?api-key=<API_KEY>');

ws.on('open', () => {
  ws.send(JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'preconfSubscribe' // Helius and BAM preconfirmations by default
    // Optional: txs from EWR/FRA touching a given account; Helius txs must be successful.
    // BAM ignores the status filter; region and account filters still apply.
    // params: [{ failed: false, regionInclude: ['ewr', 'fra'], accountInclude: ['9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM'] }]
    // Optional: Helius preconfirmations only
    // params: [{ includeSource: ['helius'] }]
  }));

  // Keep the connection alive
  setInterval(() => ws.ping(), 30_000);
});

ws.on('message', (data, isBinary) => {
  // The subscribe acknowledgement arrives as a JSON text frame
  if (!isBinary) {
    const msg = JSON.parse(data.toString());
    if (msg.id === 1) console.log('Subscribed, ID:', msg.result);
    return;
  }

  // Notifications arrive as binary frames:
  // version (u8) | slot (u64 LE) | tx_index (u64 LE) | status (u8) | transaction bytes
  const buf = Buffer.from(data);
  const version = buf.readUInt8(0); // currently 1 — branch on this if it changes
  if (version !== 1) return; // unknown schema version; update your decoder
  const slot = buf.readBigUInt64LE(1);
  const txIndex = buf.readBigUInt64LE(9); // always 0 for BAM; may be 0 for other sources
  const status = buf.readUInt8(17); // 0 = failed, 1 = success, 2 = unknown
  const txBytes = buf.subarray(18); // transaction in Solana wire format (legacy, v0, or v1)

  console.log('Preconfirmation:', { version, slot, txIndex, status, bytes: txBytes.length });
  // Decode txBytes with a decoder that supports transaction v1 (see "Decoding the transaction")
});

ws.on('error', console.error);
ws.on('close', () => process.exit(1));

Como cancelar a assinatura

Para parar de receber notificações, chame preconfUnsubscribe com o ID da assinatura retornado por preconfSubscribe.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "preconfUnsubscribe",
  "params": [24040]
}

{
  "jsonrpc": "2.0",
  "result": true,
  "id": 2
}

Preços

As Preconfirmations estão disponíveis em todos os planos pagos: Developer, Business, Professional e Enterprise. Planos gratuitos não são elegíveis. Consulte Créditos para obter detalhes. Slots sem nenhuma mensagem entregue custam zero crédito, mesmo quando o slot tem cobertura de preconfirmação. Quando um slot entrega pelo menos uma mensagem, cada assinatura preconfSubscribe aberta é cobrada pelo maior valor entre 300 créditos ou 10 créditos por mensagem entregue. Slots sem cobertura têm custo zero. Consulte Preços para conhecer os critérios de cobrança por origem e região.

Mensagens entregues em um slot coberto	Créditos cobrados
0	0
10	300
30	300
100	1.000

Cada assinatura simultânea é cobrada de forma independente quando recebe pelo menos uma mensagem. Feche as assinaturas de que você não precisa mais com preconfUnsubscribe. Com includeSource: ["helius"], slots cobertos somente pelo BAM são excluídos da cobrança. Quando regionInclude está definido, slots cobertos fora das regiões selecionadas têm custo zero para essa assinatura; slots correspondentes são cobrados somente quando a assinatura recebe pelo menos uma mensagem. A cobrança é feita por mensagem, não por assinatura de transação única. Uma transação entregue pela Helius e pelo BAM é contabilizada duas vezes. Defina includeSource: ["helius"] se você quiser apenas pré-confirmações da Helius.

Para controlar os custos, consolide os filtros de contas em uma única assinatura quando possível, use regionInclude para limitar a cobrança às regiões necessárias, defina includeSource: ["helius"] quando não precisar do BAM e monitore os créditos no painel da Helius.

Preconfirmations é um produto novo, e os preços estão sujeitos a alterações.

Relacionados

Preconfirmations Overview

O que são Preconfirmations e onde elas se encontram no pipeline do validador.

transactionSubscribe

Transmita transações com compromisso confirmado usando filtros avançados.

preconfSubscribe API reference

Parâmetros da solicitação, campos de filtro e estrutura da notificação binária.

Primeiros passos

Streaming de dados e escuta de eventos

APIs de dados e RPCs

Negociação

Envio de transações

Carteira como serviço

Privacidade

Recursos

Como Usar preconfSubscribe

O que é `preconfSubscribe`?

Inscrever-se

Resposta da Inscrição

Filtragem

Filtragem por signatário e assinatura

Filtragem de instruções

Resolução da tabela de pesquisa de endereços (ALT)

Filtragem por localização

Payload da notificação

Como distinguir as duas fontes

Como decodificar a transação

Notificações duplicadas

Exemplo

Como cancelar a assinatura

Preços

Relacionados

Preconfirmations Overview

transactionSubscribe

preconfSubscribe API reference

​O que é preconfSubscribe?

​Inscrever-se

​Resposta da Inscrição

​Filtragem

​Filtragem por signatário e assinatura

​Filtragem de instruções

​Resolução da tabela de pesquisa de endereços (ALT)

​Filtragem por localização

​Payload da notificação

​Como distinguir as duas fontes

​Como decodificar a transação

​Notificações duplicadas

​Exemplo

​Como cancelar a assinatura

​Preços

​Relacionados

Preconfirmations Overview

transactionSubscribe

preconfSubscribe API reference

O que é `preconfSubscribe`?

Inscrever-se

Resposta da Inscrição

Filtragem

Filtragem por signatário e assinatura

Filtragem de instruções

Resolução da tabela de pesquisa de endereços (ALT)

Filtragem por localização

Payload da notificação

Como distinguir as duas fontes

Como decodificar a transação

Notificações duplicadas

Exemplo

Como cancelar a assinatura

Preços

Relacionados