Skip to main content
Back to Sample Apps

HyperCore Order Monitor

Track trading orders on Hyperliquid Core (L1) in real-time with Quicknode Streams and KV Store for dynamic filtering.

Deploy Icon
Deploy App
Github Icon
View Repo
Frontend Framework/Library:
React
Language:
TypeScript
Build Tool/Development Server:
Next.js
Sample app preview

Overview

This sample app enables real-time tracking of trading orders on Hyperliquid Core (L1). It leverages Quicknode Streams + Key-Value Store (KV Store) for intelligent, dynamic filtering without requiring stream restarts. Monitor whale traders, track order statuses, and receive live updates through a modern UI.

Architecture​

Hyperliquid Core (L1)
  -> Quicknode Streams + KV
    -> POST /api/webhook/streams (signature verified)
      -> OrderLog upsert + SSE emit
        -> Live UI order feed

Features​


  • Real-time address filtering via KV Store lists
  • Dynamic status filtering (open, filled, cancelled, rejected, triggered)
  • Blockchain-native filtering at the stream level
  • Server-Sent Events (SSE) for live UI updates
  • Quicknode Streams setup scripts (create + activate)
  • Bulk add trader addresses
  • Webhook signature verification and timestamp checks
  • ENS resolution for Ethereum addresses (optional)
  • Prisma + SQLite local storage

Prerequisites​


  • Node.js 20+ and a package manager (pnpm, yarn, npm).
  • Quicknode account with Streams and KV Store access: Create an account, and get your Console API key for QN_API_KEY.
  • Public webhook URL: Use a tunnel like ngrok or deploy the app so APP_URL is reachable by Quicknode.
  • Optional: Ethereum mainnet RPC endpoint for ENS name resolution (QN_EVM_ENDPOINT).

Project Structure​

filters/
  hl-orders-filter.js     # Quicknode Streams filter (HyperCore)
scripts/
  setup-streams.ts        # Creates KV lists + stream (paused)
  activate-streams.ts     # Activates stream by id
src/
  app/api/                # API routes (webhooks, users, SSE)
  lib/                    # Quicknode, webhook, SSE helpers
  types/                  # TypeScript definitions
prisma/
  schema.prisma           # SQLite schema

Environment Variables​

Copy .env.example to .env and fill in:

QN_API_KEY=""                  # Quicknode API key with Streams + KV permissions
QN_STREAM_SECURITY_TOKEN=""    # Stream security token (from setup script)
APP_URL="http://localhost:3000" # Public app URL (ngrok for local webhooks)
DATABASE_URL="file:./dev.db"   # SQLite DB
QN_EVM_ENDPOINT=""             # Optional: Ethereum RPC for ENS resolution
ADMIN_API_KEY=""               # Optional for local dev, required for production

Notes:

  • QN_STREAM_SECURITY_TOKEN is returned by setup:streams.
  • APP_URL must be reachable by Quicknode (use ngrok or a deployed URL).
  • Ensure your API key has both Streams and KV Store permissions enabled.

Getting Started​

1. Install dependencies​

pnpm install
# npm install
# yarn install

2. Create your env file​

cp .env.example .env

3. Add required variables​

Fill in .env (see Prerequisites). For local webhooks, expose your app with ngrok and copy the HTTPS URL into APP_URL:

ngrok http 3000

4. Initialize the database​

pnpm prisma migrate dev --name hypercore-order-monitor
pnpm db:seed

The seed script creates status filters (enabling open, filled, triggered by default) and adds a sample trader address.

5. Create Quicknode Streams + KV lists​

pnpm run setup:streams

Copy the printed security token into .env (QN_STREAM_SECURITY_TOKEN).

6. Start the app​

pnpm dev

7. Activate the stream​

pnpm run activate:streams

Open http://localhost:3000, add trader addresses, and you should see live order events as streams deliver webhooks.

Database​

SQLite is used by default. Prisma schema is in prisma/schema.prisma.

Common commands:

pnpm prisma migrate dev --name <name>
pnpm db:seed
pnpm prisma studio

Webhook Security and Payload​


  • Endpoint: POST /api/webhook/streams
  • Headers required: x-qn-nonce, x-qn-timestamp, x-qn-signature
  • Payload can be gzip compressed; the handler auto-detects content-encoding: gzip
  • Signature verification uses QN_STREAM_SECURITY_TOKEN

API Endpoints​


Public endpoints:

  • GET /api/health - health check
  • GET /api/users - list monitored traders
  • GET /api/statuses - list status filters
  • POST /api/webhook/streams - Quicknode Streams webhook
  • GET /api/sse - SSE stream of order events

Protected endpoints (require Authorization: Bearer <ADMIN_API_KEY>):

  • POST /api/users - add a trader
  • POST /api/users/bulk - bulk add traders (50 address limit)
  • PATCH /api/users?id=... - update trader
  • DELETE /api/users?id=... - remove trader
  • GET /api/orders - list orders with filters
  • PATCH /api/statuses - update enabled statuses
  • POST /api/statuses/reset - reset to defaults

Synchronization Scripts​


  • pnpm run sync:statuses - Reconciles KV status list with database
  • pnpm run sync:users - Reconciles KV user list with database
  • pnpm run reset:kv - Deletes HyperCore KV lists

Preview

Preview

Contributions & Feedback
We'd love to hear your feedback and welcome any contributions to this sample app!
To report issues or share feedback, open a GitHub issue in the qn-guide-examples repository.
To contribute, follow these steps:
  1. Fork the repository
  2. Create a feature branch:
    git checkout -b feature/amazing-feature
  3. Commit your changes:
    git commit -m "Add amazing feature"
  4. Push your branch:
    git push origin feature/amazing-feature
  5. Open a Pull Request.
Explore More Sample Apps
Hyperliquid Portfolio Tracker
Build a real-time portfolio tracker that monitors Hyperliquid perpetual positions, PnL, margin utilization, and vault holdings using Quicknode's Hyperliquid info endpoint.
Hyperliquid Portfolio Tracker
Bitcoin Transaction Report Application
This application fetches and analyzes Bitcoin transactions associated with a specific address, leveraging the capabilities of Quicknode's Blockbook add-on. It provides users with detailed reports within a specified date range, offering insights into transaction history, balances after each transaction, and the USD value of Bitcoin movements.
Bitcoin Transaction Report Application
Crypto Portfolio Tracker
This web application allows users to input their cryptocurrency holdings and track their portfolio value over time. The app fetches current and historical exchange rates to display the total portfolio value and a chart of historical portfolio values in various currencies.
Crypto Portfolio Tracker