メインコンテンツへスキップ
サンプルアプリに戻る

Wallet Tracking

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

アイコンの展開
アプリをデプロイする
GitHubのアイコン
リポジトリを表示
フロントエンドフレームワーク／ライブラリ：
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 setup scripts (create + activate)
  • 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 signature verification and timestamp checks
  • SSE live updates
  • ENS resolution for EVM addresses
  • Prisma + SQLite local storage

前提条件​


  • Node.js 20+ and a package manager (pnpm, yarn, npm).
  • Quicknodeアカウント and API key: Create an account, and get your Admin API key ～のために 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.
  • Public webhook URL: Use a tunnel like ngrok or deploy the app so APP_URL is reachable by 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 and fill in:

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 setup:streams per chain.
  • APP_URL must be reachable by Quicknode (use ngrok or a deployed URL).

はじめに​

1. Install dependencies​

npm install
# pnpm install
# yarn install

2. Create your env file​

cp .env.example .env

3. Add required variables​

記入してください .env (see 前提条件). For local webhooks, expose your app with ngrok and copy the HTTPS URL into APP_URL:

ngrok http 3000

4. Create Quicknode Streams + KV lists​

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

Copy the printed security token into .env (QN_STREAM_SECURITY_TOKEN_EVM または QN_STREAM_SECURITY_TOKEN_SOL). If you want Solana, run the command again with chain=solana-mainnet (see 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.

Database​

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

Common commands:

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 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_EVM または QN_STREAM_SECURITY_TOKEN_SOL

APIエンドポイント​


  • GET /api/health - health check
  • GET /api/users - list monitored users
  • POST /api/users - add a single user (walletAddress, 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)
  • POST /api/webhook/streams - Quicknode Streams webhook
  • POST /api/webhook/test - local-only webhook test
  • GET /api/sse - SSE stream of activity events

プレビュー

プレビュー

投稿とフィードバック
皆様からのご意見をお待ちしております。また、このサンプルアプリへのご協力も大歓迎です！
問題の報告やフィードバックをお寄せいただくには、GitHubのイシューを qn-ガイド-例 リポジトリ。
投稿するには、以下の手順に従ってください：
  1. リポジトリをフォークする
  2. フィーチャーブランチを作成する：
    git checkout -b feature/amazing-feature
  3. 変更内容をコミットします：
    git commit -m "素晴らしい機能を追加"
  4. ブランチをプッシュしてください：
    git push origin feature/amazing-feature
  5. プルリクエストを作成してください。
その他のサンプルアプリを見る
Aave V3 Liquidation Tracker
This application provides real-time monitoring and in-depth analysis of liquidation events on the Aave V3 protocol. Built on a serverless architecture, this app showcases the power of Quicknode Streams for seamless blockchain data streaming.
Aave V3 Liquidation Tracker
Ethereum Transaction Report Application
This application fetches and analyzes Ethereum transactions for a given address using Quicknode's EVM Blockbook add-on, providing detailed reports within a specified date range.
Ethereum Transaction Report Application
Ethereum Wallet Explorer
This application uses Quicknode's Ethereum endpoint and APIs to query the blockchain for tokens, transactions, and NFTs associated with a given wallet.
Ethereum Wallet Explorer