跳至主要內容
返回範例應用程式

HyperCore Order Monitor

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

部署圖示
部署應用程式
GitHub 圖示
檢視儲存庫
前端框架／函式庫：
React
語言：
TypeScript
建置工具／開發伺服器：
Next.js
範例應用程式預覽

概覽

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.

建築​

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

特色​


  • 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 設定腳本（建立 + 啟用）
  • Bulk add trader addresses
  • Webhook 簽名驗證與時間戳記檢查
  • ENS resolution for Ethereum addresses (optional)
  • Prisma + SQLite 本地儲存

先決條件​


  • Node.js 20 以上版本，以及一個套件管理工具（pnpm、yarn、npm）。
  • Quicknode 帳戶 with Streams and KV Store access: Create an account, and get your 管理員 API 金鑰 因為 QN_API_KEY.
  • 公開 webhook URL：請使用類似以下的隧道： ngrok 或將應用程式部署至 APP_URL Quicknode 可以連接到該位址。
  • Optional: Ethereum mainnet RPC endpoint for ENS name resolution (QN_EVM_ENDPOINT).

專案架構​

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

環境變數​

複製 .env.example 至 .env 並填寫：

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

註：

  • QN_STREAM_SECURITY_TOKEN is returned by 設定：串流.
  • APP_URL 必須能透過 Quicknode 存取（請使用 ngrok 或已部署的 URL）。
  • Ensure your API key has both Streams and KV Store permissions enabled.

開始使用​

1. 安裝依賴項​

pnpm install
# npm install
# yarn install

2. 建立您的 env 檔案​

cp .env.example .env

3. 加入必要的變數​

填寫 .env （參見 先決條件). 對於本地 Webhook，請使用 ngrok 公開您的應用程式，並將 HTTPS URL 複製到 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

請將列印出的安全代碼複製到 .env (QN_STREAM_SECURITY_TOKEN).

6. Start the app​

pnpm dev

7. Activate the stream​

pnpm run activate:streams

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

資料庫​

預設使用 SQLite。Prisma 資料結構位於 prisma/schema.prisma.

常用指令：

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

Webhook 的安全性與有效載荷​


  • 終點： POST /api/webhook/streams
  • 必填標題： x-qn-nonce, x-qn-timestamp, x-qn-signature
  • 有效載荷可進行 gzip 壓縮；處理程式會自動偵測 content-encoding: gzip
  • 簽名驗證的用途 QN_STREAM_SECURITY_TOKEN

API 端點​


Public endpoints:

  • GET /api/health - 健康檢查
  • GET /api/users - list monitored traders
  • GET /api/statuses - list status filters
  • POST /api/webhook/streams - Quicknode Streams 網路掛鉤
  • 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

預覽

預覽

貢獻與回饋
我們非常樂意聽取您的意見，並歡迎您為這個範例應用程式提供任何貢獻！
若要回報問題或提供意見回饋，請在 qn-guide-examples 儲存庫。
若要貢獻，請依照以下步驟操作：
  1. 分叉此儲存庫
  2. 建立功能分支：
    git checkout -b feature/amazing-feature
  3. 將您的變更提交：
    git commit -m "新增超棒的功能"
  4. 推送您的分支：
    git push origin feature/amazing-feature
  5. 開啟一個 Pull Request。
探索更多範例應用程式
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
Hyperliquid Trading Dashboard
A dashboard for real-time whale trades, liquidations, and trending tokens from Hyperliquid using Quicknode Hypercore gRPC.
Hyperliquid TP/SL 熱力圖
A real-time browser dashboard that visualizes resting Hyperliquid TP/SL trigger orders as price-level clusters, anchored against live bid/ask prices from Quicknode Hypercore gRPC streams.