Início Rápido de Streams Analisados

Novo em Streams Analisados? Leia o modelo mental primeiro — ele explica por que os filtros são como são.

Início Rápido

Get Access

Parsed Streams está disponível em todos os planos por 1 crédito por evento entregue. Obtenha sua chave de API no Painel da Helius e conecte-se ao endpoint do Gatekeeper em wss://beta.helius-rpc.com, o mesmo host usado pelo tráfego de RPC e WebSocket da Helius.Autentique-se com a chave de API do seu projeto, passada como o parâmetro de consulta api-key (ou o cabeçalho x-api-key).

Conectar

wscat

wscat -c "wss://beta.helius-rpc.com/?api-key=YOUR_API_KEY"

Uma chave ausente ou inválida é rejeitada com HTTP 401. Um projeto no limite de conexão recebe HTTP 429.

Inscrever-se com um Filtro

Envie parsedTransactionSubscribe com um filtro e opções opcionais:

{"jsonrpc":"2.0","id":1,"method":"parsedTransactionSubscribe","params":[{"programs":["JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"]}]}

A resposta result é um inteiro id de assinatura:

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

Leia uma Notificação

Cada transação correspondente chega como um parsedTransactionNotification, já decodificado, com matchedIndexes apontando para as instruções que seu filtro atingiu. Veja Notificações para o formato completo.

Cancelar Assinatura

{ "jsonrpc": "2.0", "id": 2, "method": "parsedTransactionUnsubscribe", "params": [23] }

Ou simplesmente feche a conexão — isso remove todas as suas assinaturas.

Guias

Acompanhe Trocas Jupiter

Use describeProgram para construir um filtro confiável antes de assinar.

Acompanhe Mints do Pump.fun

Um ouvinte seguro para reconexões que registra cada novo deploy de token Pump.fun.

Lidando com Reconexões

Sobreviva a timeouts de inatividade e implantações, depois recupere exatamente o que perdeu.

Referência do Protocolo

Streams Analisados usa JSON-RPC 2.0 sobre uma única conexão WebSocket. Cada solicitação recebe uma resposta com o mesmo id. Uma assinatura então envia mensagens parsedTransactionNotification até você cancelar a assinatura ou desconectar.

Método	Finalidade
`parsedTransactionSubscribe`	Iniciar uma assinatura com um filtro
`parsedTransactionUnsubscribe`	Encerrar uma assinatura
`describeProgram`	Listar as instruções, os eventos e as funções de conta de um programa

Inscrever-se

Envie parsedTransactionSubscribe com um filtro e opções opcionais. A resposta result é um inteiro id de assinatura.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "parsedTransactionSubscribe",
  "params": [
    {
      "programs": ["JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"],
      "instructionNames": ["route", "shared_accounts_route"],
      "accounts": {
        "include": ["So11111111111111111111111111111111111111112"],
        "roles": { "user_transfer_authority": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin" }
      },
      "includeFailed": false,
      "includeCpi": true
    },
    { "commitment": "confirmed", "details": "full" }
  ]
}

Response

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

Campos de Filtro

Pelo menos um de programs ou accounts.include é necessário. Os campos que você define se combinam com E: uma instrução deve satisfazer todos eles para corresponder.

string[]

IDs dos Programas para corresponder (endereços base58, não nomes). Uma instrução corresponde se seu programa estiver nesta lista. OU dentro da lista.

string[]

Nomes de instruções decodificadas, como route. Correspondido exatamente primeiro, depois com uma diferença insensível a maiúsculas e separadores, então sharedAccountsRoute também corresponde ao nome da rede shared_accounts_route. OU dentro da lista. Apenas instruções cujo nome o catálogo pôde identificar podem corresponder, então pegue nomes de describeProgram.

string[]

Endereços de contas. Uma instrução corresponde se algum destes aparecer em sua lista de contas. OU dentro da lista. Funciona para todas as instruções, decodificadas ou não. O ID do programa em si não conta como uma conta aqui.

object

Um mapa do nome do papel da conta decodificado para o endereço, como { "user_transfer_authority": "<pubkey>" }. Cada entrada deve ser válida (E entre entradas), e a instrução deve estar decodificada para que isso se aplique. Nomes de papéis correspondem exatamente, sem distinção de maiúsculas, então copie-os de describeProgram em vez de adivinhar.

boolean

padrão:"false"

Incluir instruções de transações falhadas.

boolean

padrão:"true"

Instruções internas (CPI) são elegíveis para corresponder. Defina false para corresponder apenas a instruções de nível superior.

Campos desconhecidos em qualquer lugar no filtro ou opções são rejeitados com -32602 em vez de ignorados silenciosamente, então erros de digitação falham ruidosamente em vez de não corresponder a nada.

Opções

O segundo parâmetro é opcional.

string

padrão:"confirmed"

Apenas confirmed é suportado.

string

padrão:"full"

O que cada notificação carrega. full: a transação inteira, cada instrução, além de matchedIndexes apontando para os acertos do filtro. matched: apenas as instruções que corresponderam, sem lista de índice. raw: apenas instruções correspondidas, cada uma reduzida à sua posição, programId, e blob base58 data, sem campos decodificados e sem matriz accountKeys. Use matched quando a largura de banda for mais importante que o contexto (cargas completas são, em média, aproximadamente três vezes o tamanho), e raw quando você decodificar dados de instrução por conta própria e só precisar dos bytes.

O número de conexões simultâneas por projeto depende do seu plano: 5 no Free, 10 no Developer e 50 no Business e no Professional, compartilhadas entre todas as chaves de API do projeto. Consulte Limites de taxa.

Notificações

Uma notificação por transação correspondente por assinatura. Com o padrão details: "full":

{
  "jsonrpc": "2.0",
  "method": "parsedTransactionNotification",
  "params": {
    "subscription": 23,
    "result": {
      "context": { "slot": 430172053 },
      "value": {
        "transaction": {
          "signature": "3riSYL4HTRxgQjLayt6L2JPaDR3oaEQg1H4v3fnjUxNU...",
          "slot": 430172053,
          "blockTime": null,
          "feePayer": "6jduWNCTQzG91JGBchfGGxd55Vi5FxJCCJEV18RkXzJX",
          "fee": 5000,
          "accountKeys": ["6jduWNCT...", "..."],
          "status": "ok",
          "error": null,
          "summary": {
            "type": "swap",
            "description": "6jduWNCTQzG91JGBchfGGxd55Vi5FxJCCJEV18RkXzJX swapped 0.001 SOL for 0.183985 EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v via Jupiter",
            "parsedData": {
              "type": "swap",
              "protocol": "jupiter",
              "kind": "swap",
              "in_amount": "1000000",
              "actual_out_amount": "183985",
              "input_mint": "So11111111111111111111111111111111111111112",
              "output_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
            }
          },
          "nativeTransfers": [
            { "fromUserAccount": "6jduWNCT...", "toUserAccount": "DfXygSm4...", "amount": 1000000 }
          ],
          "tokenTransfers": [
            {
              "fromUserAccount": "6jduWNCT...",
              "toUserAccount": "AeUfFU6L...",
              "fromTokenAccount": "HLaEoW1s...",
              "toTokenAccount": "G13P9kSY...",
              "rawTokenAmount": 183985,
              "decimals": 6,
              "tokenStandard": "Fungible",
              "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
            }
          ]
        },
        "instructions": [
          {
            "instructionIndex": 4,
            "innerInstructionIndex": null,
            "stackHeight": 1,
            "programId": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",
            "programName": "jupiter",
            "instructionName": "route",
            "summary": {
              "type": "swap",
              "description": "6jduWNCTQzG91JGBchfGGxd55Vi5FxJCCJEV18RkXzJX swapped 0.001 SOL for 0.183985 EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v via Jupiter",
              "parsedData": {
                "type": "swap",
                "protocol": "jupiter",
                "kind": "swap",
                "in_amount": "1000000",
                "actual_out_amount": "183985",
                "input_mint": "So11111111111111111111111111111111111111112",
                "output_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
              }
            },
            "decoded": {
              "args": { "in_amount": "1000000", "slippage_bps": 50 },
              "accounts": [
                { "name": "user_transfer_authority", "pubkey": "9xQe...", "isSigner": true, "isWritable": false }
              ]
            }
          }
        ],
        "matchedIndexes": [8, 13]
      }
    }
  }
}

Lendo-o:

transaction é o contexto completo. fee está em lamports. accountKeys é a lista completa de chaves, incluindo as chaves carregadas de tabelas de consulta de endereços, na mesma ordem em que a cadeia as informa. feePayer é sempre accountKeys[0]. error contém o erro da transação como JSON estruturado, por exemplo, {"InstructionError": [2, {"Custom": 6001}]}, quando status é "error".
summary tem o mesmo formato em todos os lugares em que aparece: um type (como swap ou transfer), um description legível por humanos e um payload parsedData estruturado quando o parser reconhece a ação — para um swap: o protocolo, os valores e os mints. transaction.summary identifica a ação principal da transação; cada instrução reconhecida contém seu próprio summary com o mesmo formato. Para coletar todos os swaps de uma transação, percorra instructions e leia summary.parsedData quando summary.type for "swap".
Os valores dos swaps são informados pela plataforma. in_amount, actual_out_amount e os valores dos swaps internos em parsedData são os valores informados pela plataforma, não o que a carteira do usuário realmente enviou ou recebeu. Eles não consideram taxas de transferência do Token-2022 nem outras deduções aplicadas fora do swap. Para saber o valor exato recebido, compare os saldos da conta de tokens do usuário antes e depois da transação.
nativeTransfers e tokenTransfers listam as movimentações de SOL e tokens que o parser extraiu de toda a transação, no mesmo formato retornado pela Parsed Events API. Assim, os consumidores do stream e da API podem compartilhar o código de processamento. Ambos estão sempre presentes, mas podem estar vazios.
instructions contém todas as instruções da transação na ordem de execução: cada instrução de nível superior seguida por suas instruções internas. Cada entrada contém sua própria posição: instructionIndex indica a qual instrução de nível superior ela pertence (começando em 0), innerInstructionIndex indica sua posição entre as chamadas internas dessa instrução (null significa que é a própria instrução de nível superior) e stackHeight indica a profundidade da chamada (1 para o nível superior). Use esses valores, não a posição no array.
matchedIndexes são índices em instructions que indicam quais instruções realmente corresponderam ao seu filtro. As demais estão presentes para fornecer contexto. Com details: "matched", o array contém apenas as correspondências, e matchedIndexes não está presente.
Os nomes de decoded usam snake_case (in_amount, user_transfer_authority), conforme publicados na IDL do programa. Os argumentos inteiros geralmente são strings ("1000000"), pois valores u64 não cabem nos números do JavaScript.
blockTime atualmente é sempre null. Não dependa dele.
Espere uma combinação de instruções decodificadas e não decodificadas em uma mesma transação: um swap totalmente decodificado pode aparecer ao lado de um memo não reconhecido. Faça a ramificação com base em decoded: quando ele for null, a instrução conterá rawData (bytes em base58) e rawAccounts (lista simples de chaves públicas), de modo que você sempre tenha algo com que trabalhar.

Com details: "raw" o value reduz-se a meta da transação e blobs. accountKeys, nativeTransfers, tokenTransfers, matchedIndexes, e todos os campos decodificados estão ausentes (a transação summary ainda está incluída); cada instrução correspondida é sua posição, seu programa e seus bytes data em base58, exatamente como aparecem na cadeia (presentes mesmo para instruções que o catálogo poderia ter decodificado):

"value": {
  "transaction": {
    "signature": "3riSYL4HTRxgQjLayt6L2JPaDR3oaEQg1H4v3fnjUxNU...",
    "slot": 430172053,
    "blockTime": null,
    "feePayer": "6jduWNCTQzG91JGBchfGGxd55Vi5FxJCCJEV18RkXzJX",
    "fee": 5000,
    "status": "ok",
    "error": null,
    "summary": {
      "type": "swap",
      "description": "6jduWNCTQzG91JGBchfGGxd55Vi5FxJCCJEV18RkXzJX swapped 0.001 SOL for 0.183985 EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v via Jupiter",
      "parsedData": {
        "type": "swap",
        "protocol": "jupiter",
        "kind": "swap",
        "in_amount": "1000000",
        "actual_out_amount": "183985",
        "input_mint": "So11111111111111111111111111111111111111112",
        "output_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
      }
    }
  },
  "instructions": [
    { "instructionIndex": 4, "innerInstructionIndex": null, "stackHeight": 1, "programId": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4", "data": "3Bxs4h24hBtQy9rw" }
  ]
}

Cancelar Assinatura

{ "jsonrpc": "2.0", "id": 2, "method": "parsedTransactionUnsubscribe", "params": [23] }

Retorna true se a assinatura existia e era sua. As notificações param imediatamente. Fechar a conexão remove todas as suas assinaturas.

Descoberta

A falha mais comum com esse tipo de API é um filtro válido que não corresponde a nada, geralmente por usar um nome de instrução ou função presumido. describeProgram evita isso retornando os nomes exatos usados pelo mecanismo de correspondência. No momento, ele está disponível apenas em wss://fs-beta.helius-rpc.com/?api-key=<API_KEY>. Portanto, envie-o por uma conexão separada das suas assinaturas:

Request

{ "jsonrpc": "2.0", "id": 1, "method": "describeProgram", "params": [{ "program": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4" }] }

Response

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "id": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",
    "name": "jupiter",
    "instructions": ["route", "shared_accounts_route", "exact_out_route"],
    "events": ["SwapEvent"],
    "roles": ["user_transfer_authority", "destination_token_account"]
  }
}

Você pode passar um endereço de programa ou um nome de catálogo, mas prefira o endereço: nomes podem ser ambíguos entre versões de programas (mais de uma entrada de catálogo é nomeada jupiter, e uma busca por nome pode resolver para a mais antiga). Se você fizer a busca por nome, verifique se result.id é o programa que você pretende assinar. Fluxo recomendado: describeProgram para obter os nomes exatos de instrução e papel, construa o filtro com esses nomes, depois assine. O guia Acompanhe Trocas Jupiter percorre isso do início ao fim.

Limites

Limite	Valor
Conexões simultâneas por projeto	5 (Free), 10 (Developer), 50 (Business e Professional)
Assinaturas por conexão	25
Mensagens do cliente	10 por segundo, pico de 20
Tamanho da mensagem do cliente	64 KiB
`programs` por filtro	10
`instructionNames` por filtro	50, cada um com até 64 caracteres
`accounts.include` por filtro	100
`accounts.roles` por filtro	20, cada nome com até 64 caracteres
Buffer de saída por conexão	2.048 notificações; depois disso, a conexão é encerrada

Erros

Erros seguem JSON-RPC 2.0: { "error": { "code": <int>, "message": "<text>" }, "id": <id> }. Mensagens dizem exatamente o que estava errado e onde.

Código	Significado
`-32700`	Erro de parse (JSON inválido)
`-32600`	Solicitação inválida
`-32601`	Método não encontrado
`-32602`	Parâmetros inválidos: chave pública ruim, campo desconhecido, valor de compromisso ou detalhes não suportado
`-32000`	Limite de filtro excedido
`-32001`	Servidor não pronto; tente novamente com backoff
`-32002`	Limitado por taxa (10 mensagens por segundo)
`-32006`	Muitas assinaturas (25 por conexão)

Conexões também podem fechar com um código de fechamento WebSocket — veja Lidando com Reconexões para o que cada um significa e como se recuperar.

Exemplos de Cliente

wscat -c "wss://beta.helius-rpc.com/?api-key=<API_KEY>"
# then send:
{"jsonrpc":"2.0","id":1,"method":"parsedTransactionSubscribe","params":[{"programs":["JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"]}]}

import WebSocket from "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: "parsedTransactionSubscribe",
    params: [{ programs: ["JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"] }],
  }));
});

ws.on("message", (data) => {
  const msg = JSON.parse(data.toString());
  if (msg.method === "parsedTransactionNotification") {
    const { transaction, instructions, matchedIndexes } = msg.params.result.value;
    for (const i of matchedIndexes ?? instructions.keys()) {
      const ix = instructions[i];
      console.log(transaction.signature, ix.programName, ix.instructionName, ix.decoded?.args);
    }
  }
});

import asyncio, json, websockets

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

async def main():
    async with websockets.connect(URL) as ws:
        await ws.send(json.dumps({
            "jsonrpc": "2.0", "id": 1, "method": "parsedTransactionSubscribe",
            "params": [{"programs": ["JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"]}],
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("method") == "parsedTransactionNotification":
                value = msg["params"]["result"]["value"]
                for i in value.get("matchedIndexes") or range(len(value["instructions"])):
                    ix = value["instructions"][i]
                    print(ix.get("programName"), ix.get("instructionName"), (ix.get("decoded") or {}).get("args"))

asyncio.run(main())

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

Início Rápido de Streams Analisados

Início Rápido

Guias

Acompanhe Trocas Jupiter

Acompanhe Mints do Pump.fun

Lidando com Reconexões

Referência do Protocolo

Inscrever-se

Campos de Filtro

Opções

Notificações

Cancelar Assinatura

Descoberta

Limites

Erros

Exemplos de Cliente

​Início Rápido

​Guias

Acompanhe Trocas Jupiter

Acompanhe Mints do Pump.fun

Lidando com Reconexões

​Referência do Protocolo

​Inscrever-se

​Campos de Filtro

​Opções

​Notificações

​Cancelar Assinatura

​Descoberta

​Limites

​Erros

​Exemplos de Cliente

Início Rápido

Guias

Referência do Protocolo

Inscrever-se

Campos de Filtro

Opções

Notificações

Cancelar Assinatura

Descoberta

Limites

Erros

Exemplos de Cliente