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

錢包追蹤

透過 Quicknode Streams，輕鬆監控 Solana 和 Ethereum 上的錢包地址清單。透過簡易的使用者介面更新錢包清單。

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

概覽

此範例應用程式提供一個即時使用者活動動態串流，該串流整合了 QuicknodeStreams 與鍵值儲存庫（KV Store），用於監控地址、驗證 Webhook、透過 Prisma 將事件儲存至 SQLite，並透過 SSE 即時推送更新（EVM + Solana）。

建築​

區塊鏈（EVM + Solana）
  -> Quicknode Streams + KV
    -> 向 /api/webhook/streams 發送 POST 請求（簽名已驗證）
      -> 資料庫插入 + SSE 發送
        -> UI 即時動態

特色​


  • Quicknode Streams 設定腳本（建立 + 啟用）
  • 用於原生轉帳及 ERC-20 轉帳日誌的 EVM 過濾器
  • Solana 針對原生轉帳與 SPL 代幣轉帳的過濾器
  • Quicknode 支援基於 KV 清單的用戶監控，無需重新部署資料流即可實現動態用戶監控
  • 為受監控的地址標記
  • 批量新增受監控地址
  • Webhook 簽名驗證與時間戳記檢查
  • 上海證券交易所即時動態
  • EVM 位址的 ENS 解析
  • Prisma + SQLite 本地儲存

先決條件​


  • Node.js 20 以上版本，以及一個套件管理工具（pnpm、yarn、npm）。
  • Quicknode 帳戶 以及 API 金鑰：建立一個帳戶，並取得您的 管理員 API 金鑰 因為 QN_API_KEY.
  • ENS/ERC-20 元資料的 EVM 端點：建立一個以太坊端點，並複製其 HTTPS 網址： QN_EVM_ENDPOINT.
  • SPL 代幣元資料的 Solana RPC 端點：建立一個 Solana 端點，並複製其 HTTPS URL： QN_SOLANA_ENDPOINT.
  • 公開 webhook URL：請使用類似以下的隧道： ngrok 或將應用程式部署至 APP_URL Quicknode 可以連接到該位址。

專案架構​

filters/
  evm-filter.js           # Quicknode Streams 過濾器 (EVM)
  solana-filter.js        # Quicknode Streams 篩選器 (Solana)
scripts/
  setup-streams.ts        # 建立 KV 清單 + 串流（暫停中）
  activate-streams.ts     # 根據 ID 啟用串流
src/
  app/api/                # API 路由（Webhook、使用者、SSE）
  lib/                    # Quicknode、Webhook、SSE 輔助函式
  types/                  # 串流載荷類型
prisma/
  schema.prisma           # SQLite 資料結構

環境變數​

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

QN_API_KEY=""                  # Quicknode API 金鑰
QN_STREAM_SECURITY_TOKEN_EVM="" # EVM 串流安全憑證（來自設定）
QN_STREAM_SECURITY_TOKEN_SOL="" # Solana 串流安全憑證（來自設定）
QN_EVM_ENDPOINT=""             # Quicknode EVM 端點網址
QN_SOLANA_ENDPOINT=""          # Solana RPC 端點網址
DATABASE_URL="file:./dev.db"   # SQLite 資料庫
APP_URL="http://localhost:3000" # 公開應用程式網址（ngrok 用於本地 Webhook）

註：

  • QN_STREAM_SECURITY_TOKEN_EVM 以及 QN_STREAM_SECURITY_TOKEN_SOL 由 設定：串流 每條鏈。
  • APP_URL 必須能透過 Quicknode 存取（請使用 ngrok 或已部署的 URL）。

開始使用​

1. 安裝依賴項​

npm 安裝
# pnpm install
# yarn install

2. 建立您的 env 檔案​

cp .env.example .env

3. 加入必要的變數​

填寫 .env （參見 先決條件). 對於本地 Webhook，請使用 ngrok 公開您的應用程式，並將 HTTPS URL 複製到 APP_URL:

ngrok http 3000

4. 建立 Quicknode 串流 + KV 清單​

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

請將列印出的安全代碼複製到 .env (QN_STREAM_SECURITY_TOKEN_EVM 或 QN_STREAM_SECURITY_TOKEN_SOL). 若您想要 Solana，請使用以下指令再次執行： chain=solana-mainnet （參見 Quicknode 串流設定 （有關選項）。

5. 建立資料庫並啟動應用程式​

npx prisma migrate dev --name init
# pnpm prisma migrate dev --name init
# yarn prisma migrate dev --name init
npm 執行 dev
# pnpm dev
# yarn dev

6. 啟動串流​

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

開啟 http://localhost:3000, 新增錢包地址，當串流傳送 webhook 時，您應該就能看到即時事件。

資料庫​

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

常用指令：

pnpm prisma migrate dev --name init
pnpm prisma studio

Quicknode 串流設定​

只需按照「開始使用」章節的說明操作即可。不過，若您想手動管理 Streams 設定或 KV 清單，請依照以下步驟操作。

1. 檢查濾網​

EVM 濾波器位於 filters/evm-filter.js. 它會發出：

  • nativeTransfer 事件（金額不為零的 ETH 轉帳）
  • erc20Transfer 事件（ERC-20 轉帳記錄）

該篩選器會將地址與 userstream_monitored_users_evm KV 清單。

Solana 過濾器位於 filters/solana-filter.js. 它會發出：

  • solTransfer 事件（原生 SOL 轉帳）
  • splTransfer 事件（SPL 代幣轉帳）

該篩選器會將地址與 userstream_monitored_users_sol KV 清單。

透過使用者介面新增地址時，KV 清單會自動更新。不過，若您需要手動管理 KV 清單，可透過 Quicknode REST API 進行操作。 請參閱「鍵值儲存庫」文件頁面以了解更多資訊。

2. 建立串流 + 鍵值對清單​

pnpm run setup:streams

這將：

  • 為選定的區塊鏈建立 KV 清單（userstream_monitored_users_evm 或 userstream_monitored_users_sol)
  • 將所選鏈的篩選器進行 Base64 編碼
  • 請使用測試區塊編號來測試篩選器（由於 KV 清單起初為空，因此不會觸發任何事件。）
  • 請使用以下方式建立串流：
    • 狀態=暫停
    • 資料集=block_with_receipts (EVM) 或 資料集=block (Solana)
    • 必填的 Webhook 屬性（壓縮、重試、超時）
  • 將串流 ID 儲存至 .quicknode/streams.json
  • 列印 security_token 因為 .env (QN_STREAM_SECURITY_TOKEN_EVM 或 QN_STREAM_SECURITY_TOKEN_SOL)
  • 每次執行時建立一個串流（若要再次執行，請使用 chain=solana-mainnet 或 chain=ethereum-mainnet （以建立這兩者）。

您可以使用以下方式覆寫選項： key=value args，例如：

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

常見選項：

  • chain=ethereum-mainnet (別名： network=ethereum-mainnet)
  • 資料集=block_with_receipts
  • dataset_batch_size=1
  • 狀態=暫停
  • 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 的安全性與有效載荷​


  • 終點： POST /api/webhook/streams
  • 必填標題： 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 - 列出受監控的使用者
  • POST /api/users - 新增一位使用者 (錢包地址, 可選 名稱)
  • PATCH /api/users?id=... - 更新使用者名稱／顯示名稱
  • DELETE /api/users?id=... - 刪除使用者
  • POST /api/users/bulk - 批量新增使用者（以換行符分隔）
  • POST /api/webhook/streams - Quicknode Streams 網路掛鉤
  • POST /api/webhook/test - 僅限本機的 webhook 測試
  • GET /api/sse - SSE 活動事件流

預覽

預覽

貢獻與回饋
我們非常樂意聽取您的意見，並歡迎您為這個範例應用程式提供任何貢獻！
若要回報問題或提供意見回饋，請在 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 在實現無縫區塊鏈資料串流方面的強大功能。
Aave V3 清算追蹤器
以太坊交易報告應用程式
此應用程式利用 Quicknode 的 EVM Blockbook 擴充功能，針對指定地址擷取並分析以太坊交易，並提供指定日期範圍內的詳細報告。
以太坊交易報告應用程式
以太坊錢包瀏覽器
此應用程式使用 Quicknode 的以太坊端點和 API，向區塊鏈查詢與特定錢包相關的代幣、交易及 NFT。
以太坊錢包瀏覽器