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 Helius que transmite Pré-confirmations — transações entregues na fase de transação programada, antes de serem fragmentadas. É o sinal de transação de menor latência que a Helius oferece. O acesso requer um plano Professional ou superior — veja Preços.

O fluxo não é contínuo. A cobertura escala com a participação de stake encaminhada para a Helius, portanto, espere slots sem mensagens — lide com essas lacunas graciosamente. 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, em seguida transmite uma notificação para cada transação programada. Passe um filtro opcional como o primeiro elemento params para receber apenas transações correspondentes; omita params para receber o fluxo completo.

{
  "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 cada transação programada. Para restringir o fluxo, passe um objeto de filtro como o primeiro elemento de params. A filtragem acontece do lado do servidor, então você só paga e recebe pelas transações que lhe interessam.

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

Cada campo é opcional — um campo ausente significa “sem restrição” para esse predicado, então um filtro vazio (ou nenhum params) corresponde a todas as transações.

Campo	Tipo	Semântica
`failed`	`boolean`	`false` descarta transações falhas (revertidas); transações de sucesso e de status desconhecido ainda passam. `true` — como omitir o campo — mantém todos os status.
`regionInclude`	`string[]`	Se não estiver vazio, a transação deve se originar de uma das regiões.
`accountInclude`	`string[]`	Se não estiver vazio, a transação deve referenciar pelo menos uma dessas contas.
`accountExclude`	`string[]`	A transação é descartada se referenciar qualquer uma dessas contas. Tem precedência sobre `accountInclude`.
`accountRequired`	`string[]`	A transação deve referenciar todas essas contas.

Regras de filtro:

Todos os predicados são combinados com AND, avaliados na ordem regionInclude → accountExclude → accountRequired → accountInclude.
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 é limitada a 500 entradas.

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

Filtros de conta correspondem a mais do que apenas as chaves de conta estáticas da transação — Helius resolve v0 tabelas de consulta de endereços no lado do servidor, então accountInclude, accountExclude e accountRequired também correspondem às contas que uma transação carrega por meio de uma ALT. Isso significa que você pode filtrar qualquer conta que uma transação toca, mesmo quando ela aparece apenas por meio de uma tabela de consulta — não há necessidade de manter mapeamentos ALT ou resolver tabelas você mesmo. Basta passar a chave pública da conta e a Helius fará a resolução antes que o filtro seja aplicado.

Filtragem de localização

Use regionInclude para receber apenas transações que se originam de regiões específicas da Helius. Passe um ou mais códigos de região; uma transação passa quando sua região de origem corresponde a qualquer um deles.

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

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

Quando regionInclude é definido, transações que não carregam 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 de notificação

As notificações são entregues como quadros binários WebSocket (não JSON). Cada quadro é um layout de bytes compactado carregando uma única transação programada:

Bytes	Campo	Tipo	Descrição
0	`version`	`u8`	Versão do esquema de payload. Atualmente `1`.
1–8	`slot`	`u64` (little-endian)	O slot em que a transação está programada.
9–16	`tx_index`	`u64` (little-endian)	Índice da transação dentro do slot.
17	`status`	`u8`	Status da transação: `0` = falha, `1` = sucesso, `2` = desconhecido. O status de execução é relatado por validadores com base no melhor esforço — `2` quando não está disponível.
18+	`transaction`	`bincode(VersionedTransaction)`	A transação programada, serializada em bincode.

Leia os campos na ordem, depois bincode-desserialize os bytes restantes em um VersionedTransaction para ler instruções, contas e a assinatura.

Sempre leia e verifique o byte version primeiro. Atualmente é 1. Se a Helius precisar atualizar o formato do payload, a versão será incrementada — faça ramificações nela para que seu decodificador continue funcionando em mudanças de esquema.

Uma pré-confirmation é 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 através de verificações padrão de compromisso antes de tratá-la como final.

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'
    // Optional: only successful txs from EWR/FRA touching a given account
    // params: [{ failed: false, regionInclude: ['ewr', 'fra'], accountInclude: ['9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM'] }]
  }));

  // 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) | bincode(VersionedTransaction)
  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);
  const status = buf.readUInt8(17); // 0 = failed, 1 = success, 2 = unknown
  const txBytes = buf.subarray(18); // bincode-serialized VersionedTransaction

  console.log('Scheduled transaction:', { version, slot, txIndex, status, bytes: txBytes.length });
  // Deserialize txBytes (bincode) into a VersionedTransaction with your Solana tooling
});

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

Cancelar inscrição

Para parar de receber notificações, chame preconfUnsubscribe com o ID de inscrição retornado de preconfSubscribe.

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

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

Preços

Pré-confirmations requerem um plano Professional ou superior e custam 10 créditos por mensagem — uma mensagem por transação transmitida — cobrados do seu plano. Veja Créditos para detalhes.

Pré-confirmations é um novo produto e o preço está sujeito a alterações.

Relacionados

Visão Geral das Pré-confirmações

O que são Pré-confirmações e onde elas se situam no pipeline do validador.

transactionSubscribe

Transmita transações com confirmação confirmada usando filtragem rica.

referência da API preconfSubscribe

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

Primeiros Passos

Transmissão de Dados e Audição de Eventos

APIs de Dados & RPCs

Negociação

Enviando Transações

Carteira como Serviço

Privacidade

Recursos

Como Usar preconfSubscribe

O que é `preconfSubscribe`?

Inscrever-se

Resposta da Inscrição

Filtragem

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

Filtragem de localização

Payload de notificação

Exemplo

Cancelar inscrição

Preços

Relacionados

Visão Geral das Pré-confirmações

transactionSubscribe

referência da API preconfSubscribe

​O que é preconfSubscribe?

​Inscrever-se

​Resposta da Inscrição

​Filtragem

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

​Filtragem de localização

​Payload de notificação

​Exemplo

​Cancelar inscrição

​Preços

​Relacionados

Visão Geral das Pré-confirmações

transactionSubscribe

referência da API preconfSubscribe

O que é `preconfSubscribe`?

Inscrever-se

Resposta da Inscrição

Filtragem

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

Filtragem de localização

Payload de notificação

Exemplo

Cancelar inscrição

Preços

Relacionados