返回範例應用程式

錢包追蹤

Monitor a list of wallet addresses on Solana and Ethereum easily with Quicknode Streams. Update the wallet list through a simple UI.

作者

塞爾根·烏伊薩爾

部署應用程式

檢視儲存庫

前端框架／函式庫：

React

語言：

TypeScript

建置工具／開發伺服器：

Next.js

---

概覽

This sample app ships a live user activity feed that wires Quicknode Streams + Key-Value Store (KV Store) to monitor addresses, verify webhooks, store events in SQLite via Prisma, and push updates over SSE in real time (EVM + Solana).

建築

Blockchain (EVM + Solana)
  -> Quicknode Streams + KV
    -> POST /api/webhook/streams (signature verified)
      -> DB insert + SSE emit
        -> UI live feed

特色

• Quicknode Streams 腳本（建立 + 啟用）
• EVM filter for native transfers and ERC-20 Transfer logs
• Solana filter for native transfers and SPL token transfers
• Quicknode KV list backed user monitoring, enabling dynamic user monitoring without redeploying the stream
• Labeling monitored addresses
• Bulk add monitored addresses
• Webhook 簽名驗證與時間戳記檢查
• SSE live updates
• ENS resolution for EVM addresses
• Prisma + SQLite 本地儲存

先決條件

• Node.js 20 以上版本，以及一個套件管理工具（pnpm、yarn、npm）。
• Quicknode and API key: Create an account, and get your Admin API 因為 QN_API_KEY.
• EVM endpoint for ENS/ERC-20 metadata: Create an Ethereum endpoint and copy the HTTPS URL for QN_EVM_ENDPOINT.
• Solana RPC endpoint for SPL token metadata: Create a Solana endpoint and copy the HTTPS URL for QN_SOLANA_ENDPOINT.
• 公開 Webhook URL：請使用類似以下的隧道： ngrok 或將應用程式部署至 APP_URL Quicknode 可以連接到該位址。

專案架構

filters/
  evm-filter.js           # Quicknode Streams filter (EVM)
  solana-filter.js        # Quicknode Streams filter (Solana)
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/                  # Stream payload types
prisma/
  schema.prisma           # SQLite schema

環境變數

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

QN_API_KEY=""                  # Quicknode API key
QN_STREAM_SECURITY_TOKEN_EVM="" # EVM stream security token (from setup)
QN_STREAM_SECURITY_TOKEN_SOL="" # Solana stream security token (from setup)
QN_EVM_ENDPOINT=""             # Quicknode EVM endpoint URL
QN_SOLANA_ENDPOINT=""          # Solana RPC endpoint URL
DATABASE_URL="file:./dev.db"   # SQLite DB
APP_URL="http://localhost:3000" # Public app URL (ngrok for local webhooks)

註：

• QN_STREAM_SECURITY_TOKEN_EVM 以及 QN_STREAM_SECURITY_TOKEN_SOL are returned by 設定：streams per chain.
• APP_URL 必須能透過Quicknode 存取Quicknode 請使用 ngrok 或已部署的 URL）。

開始使用

1. 安裝依賴項

npm install
# pnpm install
# yarn install

2. 建立您的 env 檔案

cp .env.example .env

3. 加入必要的變數

請填寫 .env （參見 先決條件). 若要使用本機webhooks，請透過 ngrok 公開您的應用程式，並將 HTTPS URL 複製到 APP_URL:

ngrok http 3000

4. Create Quicknode Streams + KV lists

npm run setup:streams
# pnpm run setup:streams
# yarn setup:streams

請將列印出的安全代碼複製到 .env (QN_STREAM_SECURITY_TOKEN_EVM 或 QN_STREAM_SECURITY_TOKEN_SOL). If you want Solana, run the command again with chain=solana-mainnet （參見 Quicknode Streams Setup for options).

5. Set up the database and start the app

npx prisma migrate dev --name init
# pnpm prisma migrate dev --name init
# yarn prisma migrate dev --name init

npm run dev
# pnpm dev
# yarn dev

6. Activate the stream

npm run activate:streams
# pnpm run activate:streams
# yarn activate:streams

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

資料庫

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

常用指令：

pnpm prisma migrate dev --name init
pnpm prisma studio

Quicknode Streams Setup

Following the Getting Started section is enough. However, if you want to manage Streams settings or KV lists manually, follow these steps.

1. Check the filter

The EVM filter lives in filters/evm-filter.js. It emits:

• nativeTransfer events (ETH transfers with non-zero value)
• erc20Transfer events (ERC-20 Transfer logs)

The filter checks addresses against the userstream_monitored_users_evm KV list.

The Solana filter lives in filters/solana-filter.js. It emits:

• solTransfer events (native SOL transfers)
• splTransfer events (SPL token transfers)

The filter checks addresses against the userstream_monitored_users_sol KV list.

Adding addresses through UI will update the KV list automatically. However, if you need to manage KV lists manually, you can do so through the Quicknode REST API. Check the Key-Value Store documentation page to learn more.

2. Create stream + KV lists

pnpm run setup:streams

This will:

• Create the KV list for the selected chain (userstream_monitored_users_evm 或 userstream_monitored_users_sol)
• Base64 encode the filter for the chosen chain
• Test the filter with a test block number (as KV list will be empty at first, no events will be emitted.)
• Create a stream with:
  • status=paused
  • dataset=block_with_receipts (EVM) or dataset=block (Solana)
  • required webhook attributes (compression, retries, timeouts)
• Save the stream id to .quicknode/streams.json
• Print the security_token 因為 .env (QN_STREAM_SECURITY_TOKEN_EVM 或 QN_STREAM_SECURITY_TOKEN_SOL)
• Creates a single stream per run (run again with chain=solana-mainnet 或 chain=ethereum-mainnet to create both).

You can override options using key=value args, for example:

pnpm run setup:streams chain=ethereum-mainnet name="UserStream EVM Monitor" test_block_number=24223192
pnpm run setup:streams chain=solana-mainnet name="UserStream Solana Monitor" test_block_number=393612994

Common options:

• chain=ethereum-mainnet (alias: network=ethereum-mainnet)
• dataset=block_with_receipts
• dataset_batch_size=1
• status=paused
• elastic_batch_enabled=true
• filter_path=filters/evm-filter.js
• test_block_number=24223192
• destination_compression=none
• destination_headers='{"Content-Type":"application/json"}'
• destination_max_retry=3
• destination_retry_interval_sec=1
• destination_post_timeout_sec=10

Webhook 安全性與有效載荷

• Endpoint： POSTstreams
• 必填標題： x-qn-nonce, x-qn-timestamp, x-qn-signature
• 有效載荷可進行 gzip 壓縮；處理程式會自動偵測 content-encoding: gzip
• 簽名驗證的用途 QN_STREAM_SECURITY_TOKEN_EVM 或 QN_STREAM_SECURITY_TOKEN_SOL

API 端點

• GET /api/health - 健康檢查
• GET /api/users - list monitored users
• POST /api/users - add a single user (錢包地址, optional 名稱)
• PATCH /api/users?id=... - update user name/displayName
• DELETE /api/users?id=... - delete a user
• POST /api/users/bulk - bulk add users (newline separated)
• POSTstreams -Quicknode Streams
• POST /api/webhook/test - local-only webhook test
• GET /api/sse - SSE stream of activity events

---

預覽

貢獻與回饋

我們非常樂意聽取您的意見，並歡迎您為這個範例應用程式提供任何貢獻！

若要回報問題或提供意見回饋，請在 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。

探索更多範例應用程式

Aave V3 清算追蹤器

此應用程式提供對 Aave V3 協議上清算事件的即時監控與深入分析。該應用程式基於無伺服器架構建置，充分展現了Quicknode Streams 無縫區塊鏈資料串流Streams 強大功能。

Ethereum 報告應用程式

此應用程式透過Quicknode 的 Blockbook API，針對指定地址擷取並分析Ethereum 上的交易紀錄，並提供指定日期範圍內的詳細報告。

Ethereum 瀏覽器

此應用程式使用Quicknode Ethereum endpoint API，向區塊鏈查詢與特定錢包相關的代幣、交易及 NFT。

這頁對您有幫助嗎？

• 與我們的社群聊天
• 請查看我們的產品變更紀錄
• 查詢我們的服務狀態
• 請閱讀我們的部落格，了解最新公告

想了解 Web3 的最新消息嗎？

我們每月都會發送 #Web3Vibes 電子報，內容涵蓋區塊鏈領域中最酷的資訊。請在下方訂閱！

電子郵件地址