Overview

Key-Value Store is a robust data storage solution that enables you to manage extensive lists of datapoints, such as hundreds (or millions) of wallet addresses, and individual values. With Key-Value Store, you can update your lists and values on demand, manage and use them at any time via REST API or seamlessly within your Streams filter.

Why Key-Value Store?

When you are dealing with large volumes of data, efficient storage and quick retrieval are critical. Key-Value Store seamlessly integrates with Streams, enabling you to easily evaluate your lists and values against streaming real-time and historical data with ease, manage your lists and values, and track datapoints block-over-block with high efficiency.

This solution is particularly useful for use cases that require tracking, updating and evaluating large datasets in real-time, such as:

• Wallet and portfolio applications that want to track the activity of a large, dynamic list of wallet addresses
• Tracking and checking token holdings
• Applications that track and alert on changes in values over time

Key-Value Store Features

• Scalable Data Management - Manage, access, and evaluate large lists of data, such as millions of addresses or other data points, with ease.
• Real-Time Updates - Update your data on demand and access it instantly.
• API Access - Interact with your lists and values via REST API.
• Streams Integration - Use Key-Value Store seamlessly within Streams filters for enhanced data processing capabilities.
• High Performance - Key-Value Store features ultra-fast access time for efficient data lookup and updates.

Example Use Cases

• Wallet Address Management: Manage lists of wallet addresses to evaluate against streaming data.
• Historical Data Tracking: Track values over time for various metrics.
• Data Analysis: Calculate deltas and other statistics over large datasets.

By leveraging the Key-Value Store, you can enhance and customize Streams, enabling you to create more sophisticated, efficient, and responsive streaming datasets based on your specifications.

Lists vs. Values: Choosing the Right Data Type

	Lists	Values
What it stores	A named collection of string items under a single key	A single key-value pair
Best for	Membership checks (e.g., "is this address in my watchlist?")	Storing and retrieving individual data points
Example	A list called watched_wallets containing thousands of wallet addresses	A key called lastProcessedBlock with value 19271294
Streams function	qnContainsListItems, qnUpsertList, qnAddListItem	qnGetValue, qnAddValue, qnBulkValues

Use lists when you need to manage and evaluate a dynamic collection of items (e.g., wallet addresses, token contracts, account IDs) against streaming data. Use values when you need to store and retrieve individual data points that may change over time (e.g., tracking a running total, storing the last processed block number, caching a computed value between blocks).

Feature Availability & Costs

Key-Value Store is available to users on all Quicknode plans. Limits are the same across all plan tiers. For more details, check out the pricing page.

Limits

There is no limit on the number of items you can store in a list. The following per-item size limits apply:

Item	Maximum size
List item	128 characters
List name (key)	256 characters
Value key	255 characters
Value	800,000 characters

Performance

List size does not impact lookup performance. qnContainsListItems maintains consistent performance even for very large lists (100k+ items). For best results, batch all membership checks into as few qnContainsListItems calls as possible to minimize round trips.

Access

Access Key-Value Store within Streams in the Quicknode Developer Portal, and via Key-Value Store REST API.

Using Key-Value Store with Streams filters

Note

Key-Value Store items are case-sensitive. This is particularly important to remember when working with blockchain addresses, as they must be entered exactly as they appear onchain.

Key-Value Store can be accessed and managed seamlessly within a Streams filter. You can create new lists and values, add and remove items from your lists, update values, and evaluate your Key-Value Store data against streaming blockchain data.

Terminology

In Key-Value Store, a value refers to a single key-value pair. A list is a named collection of string items associated with a single key.

Use lists when you want to associate many values to one key, for instance you could manage and evaluate a large list of wallet addresses by adding them as items to a list called addresses.

Use values when you want to store datapoints for easy retrieval and updating, for instance you could calculate the average gas price in a block and store the value with the key gasPrice, and then retrieve it in the next block to calculate the delta.

Available Key-Value Store Functions inside your Streams Filter

The functions below are the Go methods available on the qn filter context. For the JavaScript equivalents (the qnLib.* API), see the Streams Filters documentation.

Lists

• qn.ContainsListItem(listName, item): Checks whether a single item is in a list. Returns bool.
• qn.ContainsListItems(listName, items): Batch membership check for many items; returns a []bool aligned with items. Batch all lookups into as few calls as possible to reduce round trips and improve performance.
• qn.AddListItem(listName, item): Adds an item to a list. Returns error.
• qn.RemoveListItem(listName, item): Removes an item from a list. Returns error.
• qn.GetList(listName): Retrieves every item in a list. Returns ([]string, error).
• qn.GetAllLists(): Lists every list name for the account. Returns ([]string, error).
• qn.DeleteList(listName): Deletes a list. Returns error.

Example Filter Code for Lists

For a complete working example demonstrating all list operations (qn.ContainsListItem, qn.ContainsListItems, qn.AddListItem, qn.RemoveListItem, qn.GetList, qn.GetAllLists, qn.DeleteList), see the Streams Filters documentation.

Values

• qn.GetValue(key): Retrieves the value for a key. Returns (string, error).
• qn.AddValue(key, value): Creates or updates a key-value pair. Returns error.
• qn.DeleteValue(key): Deletes a key-value pair. Returns error.
• qn.GetAllKeys(): Lists all keys for the account. Returns ([]string, error).

Example Filter Code for Key-Value Store Values

For a complete working example demonstrating all value operations (qn.GetValue, qn.AddValue, qn.DeleteValue, qn.GetAllKeys), see the Streams Filters documentation.

---

Have feedback on Key-Value Store? Let us know.