preconfSubscribe

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "preconfSubscribe",
  "params": [
    {
      "failed": false,
      "regionInclude": ["ewr", "fra"],
      "accountInclude": ["9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"]
    }
  ]
}

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

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

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 filter:
    // params: [{ failed: false, accountInclude: ['9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM'] }]
    // Helius preconfirmations only:
    // params: [{ includeSource: ['helius'] }]
  }));

  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);
  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:', { slot, txIndex, status, bytes: txBytes.length });
});

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

version   u8              payload schema version, currently 1
slot      u64 (LE)        slot the transaction is scheduled in
tx_index  u64 (LE)        transaction index when available (always 0 for BAM)
status    u8              0 = failed, 1 = success, 2 = unknown
tx        bytes           transaction in Solana wire format (legacy, v0, or v1)

Inicie uma assinatura de Preconfirmations — transações entregues antes de serem agrupadas em entradas e convertidas em shreds. Esse é o sinal de transação com a menor latência oferecido pela Helius. Uma única assinatura transmite tanto as pré-confirmações da Helius, emitidas no instante em que o líder executa a transação e contendo o status de execução, quanto as pré-confirmações BAM, emitidas quando o validador se compromete a executá-la. Use includeSource para selecionar qualquer uma das fontes.

Endpoints

preconfSubscribe é servido a partir do endpoint Helius Gatekeeper:

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

O hostname beta refere-se à implantação do Gatekeeper, não à maturidade das Pré-confirmações — ele se tornará o endpoint padrão à medida que o tráfego migrar para o Gatekeeper.

O fluxo não é contínuo. A cobertura escala com a participação da rede enviando para Helius ou executando BAM, então espere slots sem mensagens — lide com essas lacunas de maneira adequada. Veja Cobertura.

Autorizações

string

obrigatório

Sua chave de API da Helius, transmitida como o parâmetro de consulta api-key. As pré-confirmações estão disponíveis em todos os planos pagos.

Corpo

array

Opcional. Omitir params para receber todas as transações tanto da Helius quanto do BAM. Para restringir o fluxo, passe um objeto de filtro como o primeiro elemento — o filtragem acontece no lado do servidor, então você só paga e recebe as transações que lhe interessam.

Ocultar Filter

Todos os campos são opcionais — um campo ausente significa “sem restrição” para esse predicado. Portanto, um filtro vazio corresponde a todas as transações das duas fontes. Os campos definidos são combinados com AND, avaliados na ordem includeSource → failed → regionInclude → signatures → accountExclude → accountRequired → accountInclude → signerExclude → signerInclude → instructions.

string[]

padrão:"[]"

Fontes a serem recebidas. Os valores compatíveis são helius e bam. Omita o campo ou passe um array vazio para receber as duas fontes. Use ["helius"] ou ["bam"] para receber uma única fonte. Valores desconhecidos e valores que não sejam arrays retornam -32602 (parâmetros inválidos).

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 as duas fontes. Não envie includeBam e includeSource juntos.

boolean

true retorna somente transações com falha (revertidas); false retorna somente transações bem-sucedidas. Ambos os valores excluem transações da Helius com status desconhecido. Omita o campo para receber todos os status. Pré-confirmações com status desconhecido ainda serão entregues se corresponderem aos filtros de fonte, região, conta e signatário.

string[]

Se não estiver vazio, a transação deverá ter origem em uma destas regiões. Quando essa opção está definida, as transações sem informações de região são descartadas.

string[]

Se não estiver vazio, a transação deverá referenciar pelo menos uma destas contas (chaves públicas em base58). Limitado a 10.000 entradas.

string[]

A transação será descartada se referenciar qualquer uma destas contas. Tem precedência sobre accountInclude. Limitado a 10.000 entradas.

string[]

A transação deverá referenciar todas estas contas. Limitado a 10.000 entradas.

string[]

Se não estiver vazio, a transação deverá ser assinada por pelo menos uma destas contas. Limitado a 10.000 entradas.

string[]

A transação será descartada se for assinada por qualquer uma destas contas. Tem precedência sobre signerInclude. Limitado a 10.000 entradas.

string[]

Se não estiver vazio, a primeira assinatura da transação deverá corresponder a uma destas assinaturas em base58. Limitado a 1.000 entradas.

object[]

Se não estiver vazio, pelo menos uma instrução de nível superior deverá corresponder a um destes filtros de instrução. Limitado a 16 entradas.

Mostrar Instruction filter

string

obrigatório

A chave pública em base58 do programa invocado pela instrução.

object[]

Compara os bytes decodificados em um deslocamento nos dados da instrução. Todas as entradas devem corresponder. Limitado a quatro entradas.Cada entrada exige um offset não negativo e uma string bytes. O encoding opcional pode ser base58, base64 ou hex, e o padrão é base58. Cada valor deve ser decodificado para 1–128 bytes.

number

O tamanho exato dos dados da instrução em bytes. O máximo é 4.096 bytes.

Uma fonte, chave pública, assinatura, filtro de instrução ou código de região inválido retorna o erro JSON-RPC -32602 (parâmetros inválidos). Combinar includeSource com o campo obsoleto includeBam também retorna -32602. Os filtros de instrução inspecionam somente instruções de nível superior. Eles não correspondem a instruções invocadas por meio de invocação entre programas (CPI). Um deslocamento final memcmp e dataSize não deve exceder 4.096 bytes. Os filtros de conta correspondem a mais do que as chaves de conta estáticas da transação — a Helius resolve as tabelas de consulta de endereços v0 no servidor. Portanto, accountInclude, accountExclude e accountRequired também correspondem às contas carregadas por uma transação por meio de uma ALT.

Códigos de região

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

Para as pré-confirmações da Helius, a região é o local onde a Helius recebeu a transação. Para as pré-confirmações BAM, é o endpoint BAM regional que emitiu a pré-confirmação, não o local onde a Helius a recebeu. Os endpoints de Singapura e Dallas da BAM são mapeados para sgp e dal.

Resposta

integer

ID da assinatura (necessário para cancelar a assinatura)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "preconfSubscribe",
  "params": [
    {
      "failed": false,
      "regionInclude": ["ewr", "fra"],
      "accountInclude": ["9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"]
    }
  ]
}

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

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

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 filter:
    // params: [{ failed: false, accountInclude: ['9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM'] }]
    // Helius preconfirmations only:
    // params: [{ includeSource: ['helius'] }]
  }));

  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);
  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:', { slot, txIndex, status, bytes: txBytes.length });
});

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

version   u8              payload schema version, currently 1
slot      u64 (LE)        slot the transaction is scheduled in
tx_index  u64 (LE)        transaction index when available (always 0 for BAM)
status    u8              0 = failed, 1 = success, 2 = unknown
tx        bytes           transaction in Solana wire format (legacy, v0, or v1)

Notificações

Após a confirmação JSON, as notificações são entregues como frames WebSocket binários (não JSON). As pré-confirmações da Helius e da BAM usam o mesmo layout. Cada frame é uma estrutura compactada de bytes que contém 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 no qual a transação está programada.
9–16	`tx_index`	`u64` (little-endian)	Índice da transação no slot, quando disponível. As pré-confirmações BAM sempre informam `0`; outras fontes também podem informar `0` quando nenhum índice de transação está 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 BAM com base em tx_index = 0, pois outras fontes também podem informar 0.

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 ainda pode falhar ou ser descartada. Confirme o registro por meio das verificações padrão de compromisso antes de tratá-la como final.

Como decodificar a transação

Os bytes da transação são encaminhados exatamente como foram serializados pelo validador, na codificação de transmissão padrão da versão da transação. As transações legadas e v0 usam o layout com as assinaturas primeiro produzido por bincode. A transação v1 (SIMD-0385) usa um layout com a mensagem primeiro e as assinaturas no final. Portanto, bincode falha em payloads v1. Use um decodificador compatível com todas as versões. Em Rust, agave-transaction-view analisa transações legadas, v0 e v1 no próprio local e é a opção recomendada; wincode com um VersionedTransaction de um SDK atual da Solana também funciona. Em JavaScript, verifique se a versão da sua biblioteca é compatível com a transação v1. Consulte o guia para ver um exemplo em Rust.

Notificações duplicadas

As pré-confirmações da Helius e da BAM são desduplicadas por fonte, não entre fontes. Uma pequena parcela das transações chega à Helius por ambas, então 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. Consulte o guia.

Preços

As Preconfirmations estão disponíveis em todos os planos pagos: Developer, Business, Professional e Enterprise. Os 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 pré-confirmação. Quando um slot entrega pelo menos uma mensagem, cada assinatura preconfSubscribe ativa é cobrada pelo maior valor entre 300 créditos e 10 créditos por mensagem entregue. Slots sem cobertura não geram custos. Consulte Preços para verificar a elegibilidade 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 que você não precisa mais com preconfUnsubscribe. Com includeSource: ["helius"], os slots cobertos somente pelo BAM são excluídos da cobrança. Quando regionInclude está definido, os slots cobertos fora das regiões selecionadas não geram custos para essa assinatura; os slots correspondentes são cobrados somente quando a assinatura recebe pelo menos uma mensagem. A cobrança é feita por mensagem, não por assinatura única. Uma transação entregue tanto pela Helius quanto pelo BAM conta duas vezes. Defina includeSource: ["helius"] se você quiser apenas pré-confirmações da Helius.

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

Relacionados

Preconfirmations Overview

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

preconfUnsubscribe

Interrompa uma assinatura pelo ID.

⌘I

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "preconfSubscribe",
  "params": [
    {
      "failed": false,
      "regionInclude": ["ewr", "fra"],
      "accountInclude": ["9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"]
    }
  ]
}

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

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

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 filter:
    // params: [{ failed: false, accountInclude: ['9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM'] }]
    // Helius preconfirmations only:
    // params: [{ includeSource: ['helius'] }]
  }));

  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);
  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:', { slot, txIndex, status, bytes: txBytes.length });
});

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

version   u8              payload schema version, currently 1
slot      u64 (LE)        slot the transaction is scheduled in
tx_index  u64 (LE)        transaction index when available (always 0 for BAM)
status    u8              0 = failed, 1 = success, 2 = unknown
tx        bytes           transaction in Solana wire format (legacy, v0, or v1)

Primeiros passos

Negociação

Envio de transações

Gerenciamento de contas

Endpoints

Autorizações

Corpo

Códigos de região

Resposta

Notificações

Como decodificar a transação

Notificações duplicadas

Preços

Relacionados

Preconfirmations Overview

preconfUnsubscribe

​Endpoints

​Autorizações

​Corpo

​Códigos de região

​Resposta

​Notificações

​Como decodificar a transação

​Notificações duplicadas

​Preços

​Relacionados

Preconfirmations Overview

preconfUnsubscribe

Endpoints

Autorizações

Corpo

Códigos de região

Resposta

Notificações

Como decodificar a transação

Notificações duplicadas

Preços

Relacionados