Presentamos el almacén de clave-valor: cómo modificar una lista de seguimiento sin necesidad de volver a implementar

Quicknode

14 de septiembre de 2026 — 6 minutos de lectura

Compartir

Añadir como fuente preferida

Las listas de seguimiento cambian. Un gestor de carteras incorpora una dirección cada vez que alguien se registra. Un proceso de cumplimiento normativo sigue una lista de sanciones que se actualiza según el calendario de otra persona.

Si esa lista se encuentra dentro de tu filtro « Streams », cada cambio se convierte en una modificación del código. Alguien edita un array y actualiza el filtro. O bien, guardas los datos en una base de datos independiente y los consultas en cada bloque, lo que te supone otro sistema que gestionar y sincronizar.

El almacén de clave-valor elimina ese cambio de estado del filtro.

Te ofrece dos tipos de datos:

• Las listas contienen conjuntos con nombre de elementos de tipo cadena, como direcciones de monedero, listas de permitidos o criterios de filtrado.

• Los valores contienen un único dato de estado que se desea seguir a lo largo del tiempo, como, por ejemplo, el último bloque procesado.

Streams Los filtros pueden leer y escribir ambos. Las plantillas de webhook compatibles pueden hacer referencia a las listas del almacén de clave-valor por su nombre. Un backend, un script o Agente puede acceder a los mismos datos a través de la API REST.

En el caso de una lista de seguimiento, esto significa que una sola llamada a la API puede modificar los resultados que devuelve un filtro en ejecución sin necesidad de modificar ni volver a implementar el filtro en sí.

Evitar los cambios de filtro es solo una de las ventajas. Y lo que es más importante, el responsable de la lista de seguimiento ya no tiene que modificar la lógica de filtrado cada vez que cambian los datos. Se puede actualizar directamente desde la interfaz de usuario, el backend o mediante un script.

El almacén de clave-valor está disponible en todos los planes de « Quicknode ».

Lee la documentación sobre el almacén de clave-valor

Actualizar la lista de seguimiento sin modificar el filtro

Dentro de un filtro « Streams », puedes comprobar si varios elementos coinciden con una lista mediante qnLib.qnContainsListItems:

async function main(payload) {
  const addresses = payload.data.flatMap(block =>
    block.transactions.flatMap(tx => [tx.from, tx.to])
  );
  const hits = await qnLib.qnContainsListItems(
    "watched_wallets",
    addresses
  );
  return hits.some(Boolean) ? payload.data : null;
}

El método toma una matriz de elementos y devuelve un valor booleano para cada uno de ellos, alineado con la matriz de entrada. Los filtros también se pueden escribir en Go, donde el método equivalente es `qn.ContainsListItems` y se ejecuta de forma sincrónica, sin necesidad de utilizar `await`.

Lo importante es dónde se encuentra «watched_wallets»: fuera del filtro.

Añade o elimina una dirección de la lista, y el filtro en ejecución utilizará la lista de seguimiento actualizada sin necesidad de volver a implementarlo.

Ese patrón funciona siempre que la lógica de filtrado se mantenga igual, aunque cambien los datos sobre los que actúa.

Los criterios de filtrado también pueden encontrarse fuera del filtro

Las listas no tienen por qué contener direcciones de monedero.

También pueden incluir los criterios que determinan qué eventos son relevantes. Por ejemplo, una aplicación de seguimiento de pedidos podría permitir a los usuarios elegir qué estados de los pedidos desean supervisar.

En lugar de introducir esos estados de forma fija en el filtro, puedes guardarlos en una lista. Cuando un usuario cambie su selección, actualiza la lista y el filtro activo comenzará a aplicar los nuevos criterios.

Lo mismo se aplica a las listas de permitidos, las listas de bloqueados, los criterios de enrutamiento, los contratos supervisados u otros conjuntos de valores que cambian independientemente de tu lógica de filtrado.

Si para modificar algo no es necesario modificar el propio filtro, es un buen candidato para un almacén de clave-valor.

Los valores gestionan un estado que no es una lista

Los valores representan la otra cara de la misma idea.

Por ejemplo, un filtro que necesite recordar dónde se quedó podría escribir un valor «lastProcessedBlock» al final de una ejecución y volver a leerlo cuando se reanude el procesamiento.

En lugar de integrar el estado cambiante en la lógica de la aplicación, el filtro puede leerlo y actualizarlo a través de un almacén de clave-valor.

Antes de incorporarlo a la ruta de acceso

Hay algunas cosas que conviene saber antes de utilizar el almacén clave-valor dentro de un filtro.

La búsqueda distingue entre mayúsculas y minúsculas

Los elementos del almacén de clave-valor distinguen entre mayúsculas y minúsculas.

En el caso de las direcciones de blockchain, asegúrate de que los valores se almacenen y se comprueben de forma coherente. De lo contrario, es posible que las direcciones que utilicen mayúsculas y minúsculas diferentes no coincidan como se espera.

El estado actual está disponible a nivel global en Streams, Webhooks y la API REST.

El almacén de clave-valor permite a tus filtros acceder al contenido actual de una lista, lo que lo convierte en una opción ideal cuando lo que importa es el estado actual, como ocurre con muchas listas de seguimiento y reglas de filtrado dinámicas.

Cuando actualizas una lista, los filtros en ejecución leen el contenido actualizado.

Para acceder a la API REST se necesita una clave de API

Streams Los filtros pueden acceder al almacén de clave-valor a través del entorno de ejecución de « Streams ».

Las solicitudes realizadas directamente a través de la API REST, ya sean de lectura o de escritura, requieren una clave de API de Quicknode .

Infórmate sobre cómo se utiliza antes de enviarlo

Las lecturas y comparaciones en el almacén de clave-valor dentro de los filtros de « Streams » no consumen créditos de API. El uso de una lista del almacén de clave-valor con un webhook también es gratuito.

Las operaciones de escritura son diferentes. Añadir un elemento a una lista o crear un valor consume créditos de API, tanto si la escritura se realiza desde un filtro de Streams como a través de la API REST.

Los siguientes usos consumen créditos de la API:

• 20 créditos API por cada elemento añadido a la lista o valor creado

• 10 créditos de API por artículo almacenado al mes

• 5 créditos de API por cada solicitud a la API REST del almacén de clave-valor

Los límites de tamaño actuales son de 128 caracteres por elemento de la lista y 800 000 caracteres por valor.

Consulta la documentación de Key-Value Store para conocer los precios y límites más recientes antes de determinar el volumen de uso en producción.

Consulta los precios y límites actuales del almacén de clave-valor

Elaborar una lista y mantenerla actualizada

Para trasladar un array existente al almacén de clave-valor es necesario realizar un cambio en el filtro.

En primer lugar, crea la lista e introduce los primeros elementos:

curl -X POST "https://api.quicknode.com/kv/rest/v1/lists" \
 -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"key":"watched_wallets","items":["0x8f3c...","0x41be..."]}'

Puedes crear la lista e introducir los datos iniciales en una sola solicitud.

A continuación, configura el filtro para que lea esa lista y actualízalo una vez.

A partir de ese momento, los cambios en la lista de seguimiento se realizan a través del almacén de clave-valor, en lugar de a través del filtro.

Tanto para cambios continuos como por lotes, la lista de actualizaciones endpoint permite añadir y eliminar varios elementos en una sola solicitud PATCH. Esto facilita que una interfaz de usuario, un backend, un script o una tarea de integración continua (CI) mantengan la lista actualizada sin necesidad de modificar el filtro.

Lee la documentación de la API de la lista de actualizaciones

Los datos de Key-Value Store se limitan a la cuenta de Quicknode , en lugar de a un único proyecto o a endpoint, por lo que los filtros de Streams , Webhooks y las aplicaciones pueden funcionar a partir de los mismos datos subyacentes.

Dos aplicaciones que puedes clonar

La función «Wallet Tracking» muestra la tendencia mediante listas de seguimiento de monederos en tiempo real en Solana y Ethereum. Las direcciones se gestionan al margen del filtro y pueden actualizarse a través de la interfaz de usuario de la aplicación sin necesidad de volver a implementar el Stream.

Aplicación de ejemplo «Wallet Tracking», que se muestra aquí en la interfaz de usuario de demostración de UserStream.

Ver la aplicación de ejemplo «Wallet Tracking»

HyperCore Order Monitor aplica el mismo concepto a las órdenes de « Hyperliquid » Core, utilizando listas de almacenamiento clave-valor para filtrar dinámicamente las direcciones y el estado de las órdenes.

Ver la aplicación de ejemplo «HyperCore Order Monitor»

Ambos son puntos de partida útiles si quieres ver cómo funciona el patrón en una aplicación completa.

¿Qué más se considera ya «datos»?

Cualquier cambio que se produzca porque un usuario haya cambiado de opinión o porque otro sistema haya publicado algo nuevo merece la pena ser analizado.

Las direcciones de monedero son el ejemplo más evidente. Pero las listas de permitidos, las listas de bloqueados, los contratos supervisados, los criterios de enrutamiento, los tipos de eventos seleccionados por el usuario y otras configuraciones similares pueden seguir el mismo patrón.

La diferencia es sencilla:

Si cambia la lógica, cambia el filtro.

Si solo cambian los datos, plantéate almacenarlos en un almacén de clave-valor.

Extraje esos datos una sola vez, actualice el filtro y deje que se modifique de forma independiente a partir de ese momento.

Primeros pasos con el almacén de clave-valor