What is Key-Value Store?

Key-Value Store is Quicknode's account-level store for the small pieces of state a data pipeline depends on, organized as lists and values. Streams filters, Webhooks, and external applications all read and write the same data, through qnLib functions inside filters and a REST API everywhere else. A list such as watched_wallets drives membership checks. A value such as lastProcessedBlock holds one data point a pipeline updates over time.

How do I update a Streams filter's address list without redeploying the filter?

Store the list in Key-Value Store instead of hardcoding it in filter code. The filter checks membership with qnLib.qnContainsListItems, and an update through the REST API, or with qnLib.qnUpsertList, changes what that check sees. The running filter reads the current version of the list, so the pipeline keeps processing while the watchlist changes.

Can Webhooks read the same list as my Streams filter?

Yes. A list in Key-Value Store is account-scoped, so the same watched_wallets list a Streams filter checks with qnLib.qnContainsListItems is available to every Webhook on the account. There is no per-product copy to create or keep in sync. Update the list once through the REST API, and both surfaces read the current version.

What is the difference between a list and a value?

A list is a named collection of string items stored under one key, built for membership checks, like matching senders against watched_wallets with qnLib.qnContainsListItems. A value stores one data point under one key, tracked over time, like lastProcessedBlock. Lists answer whether an item belongs to a collection. Values answer what one tracked data point currently holds.

Is there a cost for lookups inside Streams filters and Webhooks?

qnLib.qnContainsListItems usage inside your Streams filter, and using your list in Webhooks are included at no cost, on every Quicknode plan. That applies to those lookups, not to writes or storage, so a Streams filter can check a large list as often as it runs. For current terms on everything else, check the Quicknode pricing page.

What does Key-Value Store cost?

Key-Value Store is available on every Quicknode plan with nothing separate to buy or provision. qnLib.qnContainsListItems usage inside your Streams filter, and using your list in Webhooks are included at no cost. For current terms on writes and storage, check the Quicknode pricing page.

How do the REST API and the qnLib functions relate?

The REST API and the qnLib functions are two ways into the same underlying data. A Streams filter calls functions like qnLib.qnGetValue natively while it runs. A backend, script, or agent calls the REST API with the same Quicknode API key. Update a list through either surface, and anything reading it, filter or application, reads the current version.

Is Key-Value Store data shared across my whole account?

Yes. Key-Value Store data is account-scoped: it lives at the Quicknode account level, not inside one project or endpoint. Every Streams filter and every Webhook on the account reads the same lists and values, and the REST API reaches the same data with the account's API key. Create watched_wallets once, and each pipeline checks one current copy instead of maintaining its own.

Is there a limit on how much Key-Value Store holds?

Key-Value Store can hold millions of items, so a large watchlist fits in one list like watched_wallets. No need to shard it across systems. Membership checks with qnLib.qnContainsListItems read that same list from inside Streams filters. For current specifics on storage and item counts, check the Key-Value Store docs before sizing a workload.

Are Key-Value Store items case-sensitive?

Yes, items in Key-Value Store are case-sensitive, so 0xAbC1 and 0xabc1 are two different entries. This matters most with blockchain addresses. Store an address in the same case a Streams filter uses when it calls qnLib.qnContainsListItems, or a checksummed entry will not match its lowercase twin. Consistent casing at write time keeps membership checks accurate.

Are there working examples of Key-Value Store with Streams?

Yes. Two sample apps in the Quicknode Sample App Library are built on the dynamic-watchlist pattern this page describes. Wallet Tracking monitors wallet addresses on Solana and Ethereum, with the watchlist held in Key-Value Store and updated through a simple UI. HyperCore Order Monitor tracks trading orders on Hyperliquid Core, with watched addresses and order statuses in Key-Value Store lists. Both ship with source code you can clone.

Base de données clé-valeur : mise à jour des listes de filtres d'Streams , sans redéploiement

Chargement du contenu...

// FAQ

Foire aux questions

Coût, limites, portée et mode d'interaction entre les surfaces. La documentation relative au magasin clé-valeur couvre toutes les « endpoint s » et toutes les fonctions.

Le « Key-Value Store » est le magasin de données au niveau du compte d’ Quicknode, destiné aux petits éléments d’état dont dépend un pipeline de données, organisés sous forme de listes et de valeurs. Les filtres Streams , Webhooks et les applications externes lisent et écrivent toutes les mêmes données, via les fonctions qnLib au sein des filtres et une API REST partout ailleurs. Une liste telle que « watched_wallets » permet de vérifier l’appartenance à un groupe. Une valeur telle que « lastProcessedBlock » contient un point de données qu’un pipeline met à jour au fil du temps.

Enregistrez la liste dans un magasin clé-valeur plutôt que de l'intégrer en dur dans le code du filtre. Le filtre vérifie l'appartenance à la liste à l'aide de la fonction `qnLib.qnContainsListItems`, et toute mise à jour effectuée via l'API REST ou à l'aide de la fonction `qnLib.qnUpsertList` modifie les éléments pris en compte par cette vérification. Le filtre en cours d'exécution lit la version actuelle de la liste, ce qui permet au pipeline de poursuivre son traitement même lorsque la liste de surveillance évolue.

Oui. Une liste dans Key-Value Store est associée au compte ; ainsi, la même liste « watched_wallets » qu’un filtre « Streams » vérifie à l’aide de la fonction `qnLib.qnContainsListItems` est accessible à tous les webhooks du compte. Il n’est pas nécessaire de créer ni de synchroniser une copie distincte pour chaque produit. Il suffit de mettre à jour la liste une seule fois via l’API REST pour que les deux interfaces affichent la version actuelle.

Une liste est un ensemble nommé d'éléments de type chaîne de caractères stockés sous une clé, conçue pour vérifier l'appartenance à un ensemble, par exemple pour comparer des expéditeurs à des portefeuilles surveillés (watched_wallets) à l'aide de la fonction `qnLib.qnContainsListItems`. Une valeur stocke un point de données sous une clé, suivi au fil du temps, comme `lastProcessedBlock`. Les listes permettent de déterminer si un élément appartient à un ensemble. Les valeurs indiquent la valeur actuelle d'un point de données suivi.

L'utilisation de qnLib.qnContainsListItems dans votre filtre Streams et l'utilisation de votre liste dans Webhooks sont incluses gratuitement dans tous les forfaits Quicknode . Cela s'applique à ces requêtes de recherche, et non aux écritures ni au stockage ; ainsi, un filtre Streams peut vérifier une liste volumineuse à chaque exécution. Pour connaître les conditions actuelles concernant tous les autres éléments, consultez la page de tarification Quicknode .

Le service de stockage clé-valeur est disponible dans tous les forfaits « Quicknode », sans achat ni configuration supplémentaire. L'utilisation de `qnLib.qnContainsListItems` dans votre filtre ` Streams `, ainsi que l'utilisation de votre liste dans ` Webhooks `, sont incluses sans frais supplémentaires. Pour connaître les conditions actuelles relatives aux écritures et au stockage, consultez la page des tarifs sur Quicknode .

L'API REST et les fonctions qnLib constituent deux moyens d'accéder aux mêmes données sous-jacentes. Un filtre « Streams » appelle nativement des fonctions telles que qnLib.qnGetValue lors de son exécution. Un backend, un script ou une « agent » appelle l'API REST à l'aide de la même clé API « Quicknode ». Quelle que soit l'interface utilisée pour mettre à jour une liste, tout élément qui la consulte (filtre ou application) accède à la version actuelle.

Oui. Les données du magasin clé-valeur sont associées au compte : elles se trouvent au niveau du compte Quicknode , et non au sein d’un projet ou d’ endpoint. Chaque filtre Streams et chaque webhook du compte lit les mêmes listes et les mêmes valeurs, et l’API REST accède aux mêmes données à l’aide de la clé API du compte. Créez des « watched_wallets » une seule fois, et chaque pipeline vérifiera une copie à jour au lieu d’en gérer une lui-même.

Le Key-Value Store peut contenir des millions d'éléments ; ainsi, une liste de surveillance volumineuse peut tenir dans une seule liste, telle que `watched_wallets`. Il n'est donc pas nécessaire de la répartir entre plusieurs systèmes. Les vérifications d'appartenance effectuées à l'aide de `qnLib.qnContainsListItems` lisent cette même liste à partir des filtres ` Streams `. Pour obtenir des informations détaillées sur le stockage et le nombre d'éléments, consultez la documentation du Key-Value Store avant de dimensionner une charge de travail.

Oui, les éléments du magasin clé-valeur sont sensibles à la casse ; ainsi, 0xAbC1 et 0xabc1 sont deux entrées différentes. Cela revêt une importance particulière pour les adresses de blockchain. Enregistrez une adresse en respectant la casse utilisée par le filtre « Streams » lorsqu’il appelle la fonction `qnLib.qnContainsListItems`, sinon une entrée avec somme de contrôle ne correspondra pas à son équivalent en minuscules. Le respect d’une casse cohérente lors de l’écriture garantit la précision des vérifications d’appartenance.

Oui. Deux exemples d’applications de la bibliothèque d’exemples « Quicknode » s’appuient sur le modèle de liste de surveillance dynamique décrit sur cette page. « Wallet Tracking » surveille les adresses de portefeuilles sur Solana et Ethereum; la liste de surveillance est stockée dans un magasin clé-valeur et mise à jour via une interface utilisateur simple. « HyperCore Order Monitor » suit les ordres de trading sur Hyperliquid Core ; les adresses surveillées et les statuts des ordres sont répertoriés dans des listes du magasin clé-valeur. Ces deux exemples sont fournis avec leur code source, que vous pouvez cloner.

Il n'y a rien de nouveau à faire.Ça fonctionne avec le programme que vous avez.

Créez une liste.

Lisez-le dans votre pipeline.

Mettez-le à jour où que vous soyez.

Modifiez les éléments surveillés par votre pipeline.Ignorez le redéploiement.

La liste a encore changé. Votre filtre, lui, n'a pas changé.

Des modifications à chaque PATCH.

Ça ne change jamais.

Grandes listes dynamiques et valeurs globales.Sélection par tâche.

Les listes et valeurs disponibles à l'échelle mondiale permettent de synchroniser vos Streams, Webhooks et applications .

Deux applications fonctionnent déjà selon ce modèle. Clonez-en une.

Suivi du portefeuille

Moniteur de commandes HyperCore

Documentation sur les bases de données clé-valeur

Tarifs

Mettez votre première liste à profit.

Foire aux questions

Vous souhaitez rester informé ?

Outils de développement

Documents et guides