Inicio rápido de Parsed Streams

¿Es tu primera vez con Parsed Streams? Lee primero el modelo mental. Explica por qué los filtros tienen esa estructura.

Inicio rápido

Get Access

Parsed Streams está disponible en todos los planes a 1 crédito por evento entregado. Obtén tu clave de API en el panel de Helius y conéctate al endpoint de Gatekeeper en wss://beta.helius-rpc.com, el mismo host que usa el tráfico RPC y WebSocket de Helius.Autentícate con la clave de API de tu proyecto. Pásala como parámetro de consulta api-key o como encabezado x-api-key.

Connect

wscat

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

Si falta la clave o no es válida, la solicitud se rechaza con HTTP 401. Si un proyecto alcanza su límite de conexiones, recibe HTTP 429.

Subscribe with a Filter

Envía parsedTransactionSubscribe con un filtro y opciones opcionales:

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

El campo result de la respuesta es un id de suscripción entero:

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

Read a Notification

Cada transacción coincidente llega como parsedTransactionNotification, ya decodificada, con matchedIndexes apuntando a las instrucciones que coincidieron con tu filtro. Consulta Notificaciones para ver la estructura completa.

Unsubscribe

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

O simplemente cierra la conexión. Esto elimina todas sus suscripciones.

Guías

Track Jupiter Swaps

Usa describeProgram para crear un filtro confiable antes de suscribirte.

Track Pump.fun Mints

Un listener seguro frente a reconexiones que registra cada nuevo despliegue de tokens de Pump.fun.

Handling Reconnects

Supera los tiempos de espera por inactividad y los despliegues. Después, recupera exactamente lo que te perdiste.

Referencia del protocolo

Parsed Streams usa JSON-RPC 2.0 mediante una única conexión WebSocket. Cada solicitud recibe una respuesta con el mismo id. Después, una suscripción envía mensajes parsedTransactionNotification hasta que canceles la suscripción o te desconectes.

Método	Propósito
`parsedTransactionSubscribe`	Iniciar una suscripción con un filtro
`parsedTransactionUnsubscribe`	Detener una suscripción
`describeProgram`	Enumerar las instrucciones, los eventos y los roles de cuenta de un programa

{
  "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 del filtro

Se requiere al menos uno de programs o accounts.include. Los campos que configures se combinan con AND: una instrucción debe satisfacerlos todos para coincidir.

string[]

IDs de programa que deben coincidir (direcciones base58, no nombres). Una instrucción coincide si su programa está en esta lista. Se aplica OR dentro de la lista.

string[]

Nombres de instrucciones decodificadas, como route. Primero se busca una coincidencia exacta y, luego, se usa una alternativa que no distingue mayúsculas, minúsculas ni separadores. Por lo tanto, sharedAccountsRoute también coincide con el nombre en el protocolo shared_accounts_route. Se aplica OR dentro de la lista. Solo pueden coincidir las instrucciones cuyo nombre haya identificado el catálogo. Por eso, obtén los nombres de describeProgram.

string[]

Direcciones de cuentas. Una instrucción coincide si alguna de estas aparece en su lista de cuentas. Se aplica OR dentro de la lista. Funciona con todas las instrucciones, estén decodificadas o no. Aquí, el id del programa no cuenta como una cuenta.

object

Un mapa que relaciona el nombre del rol de una cuenta decodificada con una dirección, como { "user_transfer_authority": "<pubkey>" }. Cada entrada debe cumplirse (AND entre entradas) y la instrucción debe estar decodificada para que esto se aplique. Los nombres de roles coinciden exactamente, sin normalizar mayúsculas y minúsculas. Cópialos de describeProgram en lugar de adivinarlos.

boolean

predeterminado:"false"

Incluye instrucciones de transacciones fallidas.

boolean

predeterminado:"true"

Las instrucciones internas (CPI) pueden coincidir. Configura false para que solo coincidan las instrucciones de nivel superior.

Los campos desconocidos en cualquier parte del filtro o de las opciones se rechazan con -32602 en lugar de ignorarse silenciosamente. Así, los errores tipográficos generan un error explícito en vez de no producir coincidencias.

Opciones

El segundo parámetro es opcional.

string

predeterminado:"confirmed"

Solo se admite confirmed.

string

predeterminado:"full"

Define qué contiene cada notificación. full: la transacción completa, todas las instrucciones y matchedIndexes, que apunta a las coincidencias del filtro. matched: solo las instrucciones coincidentes, sin lista de índices. raw: solo las instrucciones coincidentes, cada una reducida a su posición, programId y un blob data en base58, sin campos decodificados ni array accountKeys. Usa matched cuando el ancho de banda sea más importante que el contexto (los payloads completos tienen, en promedio, aproximadamente el triple de tamaño). Usa raw cuando decodifiques tú mismo los datos de las instrucciones y solo necesites los bytes.

Las conexiones simultáneas por proyecto dependen de tu plan: 5 en Free, 10 en Developer y 50 en Business y Professional, compartidas entre todas las claves de API del proyecto. Consulta Límites de frecuencia.

Notificaciones

Se envía una notificación por cada transacción coincidente y por suscripción. Con el valor predeterminado 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]
      }
    }
  }
}

Cómo interpretarla:

transaction es el contexto completo. fee está en lamports. accountKeys es la lista completa de claves, incluidas las claves cargadas desde tablas de búsqueda de direcciones, en el mismo orden en que la cadena las reporta. feePayer siempre es accountKeys[0]. error contiene el error de la transacción como JSON estructurado, por ejemplo, {"InstructionError": [2, {"Custom": 6001}]}, cuando status es "error".
summary tiene la misma estructura dondequiera que aparece: un type (como swap o transfer), un description legible para humanos y una carga útil parsedData estructurada cuando el analizador reconoce la acción; para un intercambio: el protocolo, los montos y los mints. transaction.summary identifica la acción principal de la transacción; cada instrucción reconocida incluye su propio summary con la misma estructura. Para recopilar todos los intercambios de una transacción, recorre instructions y lee summary.parsedData donde summary.type sea "swap".
Los montos de los intercambios son los reportados por la plataforma. in_amount, actual_out_amount y los montos de intercambios internos en parsedData son los que reportó la plataforma, no los que la billetera del usuario realmente envió o recibió. No tienen en cuenta las comisiones de transferencia de Token-2022 ni otras deducciones aplicadas fuera del intercambio. Para obtener el monto exacto recibido, compara los saldos de la cuenta de tokens del usuario antes y después de la transacción.
nativeTransfers y tokenTransfers enumeran los movimientos de SOL y tokens que el analizador extrajo de toda la transacción, con la misma estructura que devuelve la API de eventos analizados, de modo que los consumidores del flujo y de la API puedan compartir el código de procesamiento. Ambos están siempre presentes, aunque pueden estar vacíos.
instructions contiene todas las instrucciones de la transacción en orden de ejecución: cada instrucción de nivel superior seguida de sus instrucciones internas. Cada entrada incluye su propia posición: instructionIndex indica a qué instrucción de nivel superior pertenece (comenzando en 0), innerInstructionIndex indica su posición entre las llamadas internas de esa instrucción (null significa que es la propia instrucción de nivel superior) e stackHeight indica la profundidad de la llamada (1 para el nivel superior). Usa estos valores, no la posición en el arreglo.
matchedIndexes son índices de instructions que indican cuáles coincidieron realmente con tu filtro. El resto está ahí para aportar contexto. Con details: "matched", el arreglo contiene solo las coincidencias e matchedIndexes no está presente.
Los nombres de decoded usan snake_case (in_amount, user_transfer_authority), tal como se publican en el IDL del programa. Los argumentos enteros suelen ser cadenas ("1000000") porque los valores u64 no caben en los números de JavaScript.
blockTime actualmente siempre es null. No dependas de él.
Espera una combinación de instrucciones decodificadas y sin decodificar dentro de una misma transacción: un intercambio completamente decodificado puede aparecer junto a un memo no reconocido. Bifurca según decoded: cuando sea null, la instrucción incluirá en su lugar rawData (bytes en base58) e rawAccounts (lista simple de claves públicas), por lo que siempre tendrás algo con lo que trabajar.

Con details: "raw", value se reduce a los metadatos y blobs de la transacción. accountKeys, nativeTransfers, tokenTransfers, matchedIndexes y todos los campos decodificados desaparecen (el summary de la transacción sigue incluido). Cada instrucción coincidente contiene su posición, su programa y sus bytes data en base58, exactamente como aparecen en la cadena. Esto también se aplica a las instrucciones que el catálogo podría haber 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 la suscripción

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

Devuelve true si la suscripción existía y te pertenecía. Las notificaciones se detienen de inmediato. Al cerrar la conexión, se eliminan todas sus suscripciones.

Descubrimiento

El error más común con este tipo de API es usar un filtro válido que no coincide con nada, por lo general debido a un nombre de instrucción o rol elegido por suposición. describeProgram evita esto al devolver los nombres exactos con los que compara el sistema de coincidencias. Actualmente, solo está disponible en wss://fs-beta.helius-rpc.com/?api-key=<API_KEY>, así que envíalo mediante una conexión separada de tus suscripciones:

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

Puedes pasar la dirección de un programa o un nombre del catálogo, pero es preferible usar la dirección. Los nombres pueden ser ambiguos entre versiones del programa (más de una entrada del catálogo se llama jupiter y una búsqueda por nombre puede devolver la versión más antigua). Si buscas por nombre, comprueba que result.id sea el programa al que quieres suscribirte. Flujo recomendado: usa describeProgram para obtener los nombres exactos de las instrucciones y los roles, crea el filtro con esos nombres y, luego, suscríbete. La guía Rastrear swaps de Jupiter explica todo el proceso de principio a fin.

Límites

Límite	Valor
Conexiones simultáneas por proyecto	5 (Free), 10 (Developer), 50 (Business y Professional)
Suscripciones por conexión	25
Mensajes del cliente	10 por segundo, ráfaga de 20
Tamaño de los mensajes del cliente	64 KiB
`programs` por filtro	10
`instructionNames` por filtro	50, cada uno de hasta 64 caracteres
`accounts.include` por filtro	100
`accounts.roles` por filtro	20, cada nombre de hasta 64 caracteres
Búfer de salida por conexión	2048 notificaciones; después, se cierra la conexión

Errores

Los errores siguen JSON-RPC 2.0: { "error": { "code": <int>, "message": "<text>" }, "id": <id> }. Los mensajes indican exactamente qué salió mal y dónde.

Código	Significado
`-32700`	Error de análisis (JSON no válido)
`-32600`	Solicitud no válida
`-32601`	Método no encontrado
`-32602`	Parámetros no válidos: clave pública incorrecta, campo desconocido o valor de commitment o details no compatible
`-32000`	Se superó el límite del filtro
`-32001`	El servidor no está listo; vuelve a intentarlo con espera incremental
`-32002`	Límite de frecuencia alcanzado (10 mensajes por segundo)
`-32006`	Demasiadas suscripciones (25 por conexión)

Las conexiones también pueden cerrarse con un código de cierre de WebSocket. Consulta Manejo de reconexiones para saber qué significa cada código y cómo recuperarte.

Ejemplos de clientes

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())

Primeros pasos

Transmisión de datos y escucha de eventos

API de datos y RPC

Trading

Envío de transacciones

Billetera como servicio

Privacidad

Recursos

Inicio rápido de Parsed Streams

Inicio rápido

Guías

Track Jupiter Swaps

Track Pump.fun Mints

Handling Reconnects

Referencia del protocolo

Suscribirse

Campos del filtro

Opciones

Notificaciones

Cancelar la suscripción

Descubrimiento

Límites

Errores

Ejemplos de clientes

​Inicio rápido

​Guías

Track Jupiter Swaps

Track Pump.fun Mints

Handling Reconnects

​Referencia del protocolo

​Suscribirse

​Campos del filtro

​Opciones

​Notificaciones

​Cancelar la suscripción

​Descubrimiento

​Límites

​Errores

​Ejemplos de clientes

Inicio rápido

Guías

Referencia del protocolo

Suscribirse

Campos del filtro

Opciones

Notificaciones

Cancelar la suscripción

Descubrimiento

Límites

Errores

Ejemplos de clientes