9 min read
Overview
If you are building a wallet monitoring system, you have probably dealt with this: a new wallet needs tracking, so you update a hardcoded address list, redeploy your filter, and wait for everything to reconnect. For a handful of wallets that is manageable, but when the list changes frequently (new users onboarding, addresses rotating, research targets shifting), the process becomes a bottleneck.
This guide walks you through building a live wallet watchlist on Hyperliquid using Webhooks and Key-Value Store. While this example focuses on Hyperliquid, the same pattern applies to any chain supported by Webhooks. KV Store lists also work with Streams for more advanced pipelines (see the HyperCore Order Monitor sample app for an example).
- Quicknode Webhooks can reference a Key-Value Store list instead of hardcoded addresses, making the watchlist dynamic and easily updatable
- Update the address list via dashboard or REST API; the Webhook picks up changes immediately with no restarts
- This guide uses Hyperliquid wallet events as the example, but the pattern works on any supported chain
- Covers both dashboard setup and a fully programmatic approach using Quicknode's REST APIs
What You Will Learn
- How Webhooks and Key-Value Store work together for dynamic address filtering
- How to create a Webhook with the Hyperliquid Wallet Events template
- How to link a KV Store list to your Webhook for dynamic address tracking
- How to manage your watchlist and Webhook programmatically through Quicknode's REST APIs
- How to build a simple server to receive and process Webhook events
What You Will Need
- A Quicknode account
- Node.js v20+ installed
- A Quicknode API key (for the REST API sections)
How Do Webhooks and KV Store Work Together?
Most wallet monitoring setups work with a fixed list of addresses baked into the configuration. When you need to track a new wallet or stop tracking an old one, you modify the configuration and restart the pipeline.
Quicknode Webhooks with Key-Value Store integration changes this by decoupling the address list from the Webhook configuration. Instead of embedding addresses directly, the Webhook references a named list stored in Key-Value Store. At evaluation time, the Webhook looks up the current contents of that list and matches incoming events against it. This means:
- Adding a wallet: Insert an address into the KV Store list. The Webhook picks it up immediately.
- Removing a wallet: Delete the address from the list. The Webhook stops matching it on the next event.
- No Webhook changes needed: The Webhook configuration stays the same. Only the list contents change.
If you are an AI agent or building automated infrastructure, skip ahead to the Programmatic Setup with REST APIs section for a fully API-driven approach.
Creating the Webhook via Dashboard
Navigate to the Webhooks page on your Quicknode dashboard and click Create Webhook. The guided wizard walks you through configuration in a few steps.
Select the Network and Template
- Choose Hyperliquid Hypercore Mainnet as your network.
- Select the Hyperliquid Wallet Events template. This template monitors deposits, withdrawals, transfers, and vault operations for a set of wallet addresses.
Link a Key-Value Store List
After selecting the template, the wizard prompts you to provide the wallet addresses to monitor. You have three options:
- Saved Lists: Select an existing KV Store list. You can edit the list after selecting it.
- Manual Input: Create a new list by adding addresses one by one and setting a list name.
- Import: Upload a text file with one wallet address per line and set a list name.
Choose whichever option fits your workflow. The key point is that all three create (or reference) a KV Store list, so you can update it later without touching the Webhook.
The Hyperliquid Wallet Events template automatically lowercases addresses for case-insensitive matching. You can enter addresses in any case format.
Test the Filter
Set a block number to test your filter against historical data. For example, you can use block 957175080 with the wallet 0x91c65e75f9a869900859ce66bd8719555e66e9c3 to see a sample payload. Click Run to preview the matched events.
Here is an example payload you can expect:
{
"block_number": 957175080,
"block_time": "2026-04-13T12:35:01.639703687",
"matchedEvents": [
{
"hash": "0xbbacbb092cc34605bd2604390d55280202bc00eec7c664d75f75665bebc71ff0",
"inner": {
"LedgerUpdate": {
"delta": {
"amount": "2.291667",
"destination": "0x82cd5683ef2013c30915cd84c940f378ad782d4b",
"fee": "0.0",
"nonce": 1776083700639,
"sourceDex": "spot",
"token": "USDC",
"type": "send",
"usdcValue": "2.291667",
"user": "0x91c65e75f9a869900859ce66bd8719555e66e9c3"
},
"users": [
"0x91c65e75f9a869900859ce66bd8719555e66e9c3",
"0x82cd5683ef2013c30915cd84c940f378ad782d4b"
]
}
},
"time": "2026-04-13T12:35:01.639703687"
}
]
}
The matchedEvents array contains each event triggered by the monitored wallets. The LedgerUpdate type covers most wallet activity, including sends, deposits, withdrawals, and vault operations. See the Hyperliquid Events dataset documentation for the full list of event types.
Example payloads are useful for understanding the data structure and testing your server's event handling logic before going live.
Configure Delivery and Create the Webhook
- Webhook URL: Enter the HTTP endpoint where you want to receive events. If you do not have a server yet, you can use Webhook.site for quick testing, then replace the URL with your production endpoint once your server is ready.
- Security Token: Copy the generated security token. Use it on your server to verify that incoming requests are from Quicknode.
- Compression: Optionally enable gzip compression to reduce payload size. Check the Optimize Streams Bandwidth with Data Compression guide to learn more about compression and how to handle compressed payloads on your server.
- Test Again: After configuring the delivery settings, you can test the Webhook again to see if your endpoint receives the payload correctly. This is especially important if you enabled compression or set up security token verification.
- Name: Give your Webhook a descriptive name (e.g., "Hyperliquid Wallet Watchlist").
- Click Create to activate your Webhook.
Your Webhook is now live and monitoring the wallets in your KV Store list.
For a complete webhook server implementation that processes events and takes action on them, check out the HyperCore Order Monitor sample app. It uses Streams, but the server pattern is the same for Webhooks.
Building a Simple Webhook Server
To receive and process events from your Webhook, you need an HTTP server that accepts POST requests. Here is a minimal example using Express that logs incoming events and verifies the security token:
mkdir hl-watchlist-server && cd hl-watchlist-server
npm init -y
npm install express
Create a file called server.js:
import express from "express";
const app = express();
const PORT = process.env.PORT || 3000;
app.use(express.json());
app.post("/webhook", (req, res) => {
const payload = req.body;
const events = payload.matchedEvents || [];
console.log(`\nBlock #${payload.block_number} | ${events.length} event(s)`);
for (const event of events) {
const inner = event.inner;
if (inner.LedgerUpdate) {
const delta = inner.LedgerUpdate.delta;
console.log(
` ${delta.type} | ${delta.amount} ${delta.token} | ${delta.user} -> ${delta.destination}`
);
}
}
res.status(200).json({ status: "ok" });
});
app.listen(PORT, () => {
console.log(`Webhook server listening on port ${PORT}`);
});
Update package.json to use ES Modules by adding "type": "module" or running npm pkg set type=module in the terminal. Then, start the server:
node server.js
When your Webhook fires, you will see output like:
Block #957175080 | 1 event(s)
send | 2.291667 USDC | 0x91c6...9c3 -> 0x82cd...d4b
To expose this server to the internet during development, use a tool like ngrok:
ngrok http 3000
Copy the generated URL and set it as your Webhook URL (e.g., https://abc123.ngrok.io/webhook). For production, deploy this server to your preferred hosting provider and replace the URL in your Webhook configuration.
Updating Your Watchlist
Once the Webhook is running, you can update the watched addresses at any time, either through the Key-Value Store dashboard or the KV Store REST API. Add or remove addresses, and the Webhook picks up the change on the next incoming event. No restarts needed.
Programmatic Setup with REST APIs
Everything you did through the dashboard can also be done through Quicknode's REST APIs. This is particularly useful for automation, CI/CD pipelines, and AI agents that need to manage Webhooks and watchlists programmatically.
All API requests require your Quicknode API key in the x-api-key header. You can create one from the API Keys page.
Creating a KV Store List
Create a new list with an initial set of wallet addresses using the KV Store REST API:
curl -X POST "https://api.quicknode.com/kv/rest/v1/lists" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"key": "hl-watchlist",
"items": [
"<wallet_address_1>",
"<wallet_address_2>",
"<wallet_address_3>"
]
}'
Replace YOUR_API_KEY with your actual API key and adjust the wallet addresses as needed.
Creating the Webhook
Create a Webhook that references your KV Store list using the Webhooks REST API. The walletsListName parameter links the Webhook to your KV Store list:
curl -X POST "https://api.quicknode.com/webhooks/rest/v1/webhooks/template/hyperliquid-wallets" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"name": "Hyperliquid Wallet Watchlist",
"network": "hyperliquid-hypercore-mainnet",
"url": "https://your-server.com/webhook",
"templateArgs": {
"walletsListName": "hl-watchlist"
}
}'
The walletsListName value must match the key of the KV Store list you created. The Webhook resolves the list contents at evaluation time, so any changes to the hl-watchlist list are picked up automatically.
This example uses the hyperliquid-wallets template on Hyperliquid Hypercore Mainnet, but you can swap the template ID and network for any supported chain. The walletsListName parameter works the same way across all wallet-based templates. See the Webhooks REST API documentation for available templates.
Managing the Watchlist
Add new addresses to your list:
curl -X PATCH "https://api.quicknode.com/kv/rest/v1/lists/hl-watchlist" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"add_items": [
"<wallet_address_4>"
]
}'
Remove addresses:
curl -X PATCH "https://api.quicknode.com/kv/rest/v1/lists/hl-watchlist" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"remove_items": [
"<wallet_address_3>"
]
}'
Retrieve the current list to verify its contents:
curl -X GET "https://api.quicknode.com/kv/rest/v1/lists/hl-watchlist" \
-H "accept: application/json" \
-H "x-api-key: YOUR_API_KEY"
For the full list of operations, see the KV Store REST API documentation.
Conclusion
You now have a live wallet watchlist on Hyperliquid that you can update at any time. The combination of Webhooks and Key-Value Store gives you a monitoring system where the infrastructure stays stable while the data it watches stays flexible.
This pattern is not limited to Hyperliquid. You can apply the same approach to any chain supported by Quicknode Webhooks, referencing a KV Store list for dynamic address filtering on EVM chains, Solana, and more.
Use Streams to build a fully customizable data pipeline with access to historical data, additional destinations, and custom filtering. Streams also supports KV Store list references for the same dynamic filtering pattern.
Next Steps
- Build a production webhook server: Check out the Build a Copy-Trading Bot guide for a complete server implementation that processes events and executes trades. It uses Streams, but the server pattern is the same for Webhooks.
- Explore the Events dataset: See the Hyperliquid Events dataset documentation for the full list of event types and filtering options.
- Learn more about Webhooks: Read the Get Started with Webhooks guide for a deeper look at Webhook configuration, security tokens, and compression.
- Manage data at scale: See the Key-Value Store documentation for advanced list and set operations.
Frequently Asked Questions
Can I use this pattern on chains other than Hyperliquid?
Yes. Quicknode Webhooks supports KV Store list references on any supported chain. The template and event types will differ, but the pattern of linking a Webhook to a KV Store list for dynamic filtering works the same way.
How quickly does the Webhook pick up changes to the KV Store list?
Changes are picked up quickly, typically within about 15 seconds. When you add or remove an address from the KV Store list, the Webhook evaluates the updated list on the next incoming event after the change propagates.
Is there a limit to how many addresses I can put in a KV Store list?
There is no hard limit on the number of items in a KV Store list.
What types of Hyperliquid events does the Webhook capture?
The Hyperliquid Wallet Events template captures LedgerUpdate events (transfers, deposits, withdrawals, vault operations), funding payments, cross-chain bridge operations, and staking-related activities. See the Hyperliquid Events dataset documentation for the full breakdown.
Do I need to restart the Webhook after updating the watchlist?
No. That is the main benefit of this approach. The Webhook references the KV Store list by name, so it always uses the latest version of the list. No restarts or reconfigurations are needed.
Can I reference the same KV Store list from multiple Webhooks?
Yes. Multiple Webhooks can reference the same KV Store list. When you update the list, all Webhooks that reference it will pick up the change. This is useful if you want the same watchlist to trigger different Webhooks for different purposes, like one for alerts and another for analytics.
We ❤️ Feedback!
Let us know if you have any feedback or requests for new topics. We'd love to hear from you.