Wallet Tracking

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

Implementar a aplicação

Ver repositório

Framework/Biblioteca de front-end:

Reagir

Idioma:

TypeScript

Ferramenta de compilação/Servidor de desenvolvimento:

Next.js

Pré-visualização da aplicação de exemplo

Visão geral

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).

Arquitetura

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

Características

Scripts de configuração do Quicknode Streams (criar + ativar)
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
Verificação da assinatura do webhook e verificações do carimbo temporal
SSE live updates
ENS resolution for EVM addresses
Prisma + armazenamento local SQLite

Pré-requisitos

Node.js 20+ e um gestor de pacotes (pnpm, yarn, npm).
Conta Quicknode and API key: Create an account, and get your Chave da API de administração para 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.
URL pública do webhook: Utilize um túnel como ngrok ou implementar a aplicação de forma a que APP_URL é acessível através do Quicknode.

Estrutura do projeto

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

Variáveis de ambiente

Copiar .env.example para .env e preencha:

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)

Notas:

QN_STREAM_SECURITY_TOKEN_EVM e QN_STREAM_SECURITY_TOKEN_SOL are returned by configuração:streams per chain.
APP_URL tem de estar acessível pelo Quicknode (utilize o ngrok ou um URL implementado).

Introdução

1. Instalar as dependências

npm install
# pnpm install
# yarn install

2. Crie o seu ficheiro de ambiente

cp .env.example .env

3. Adicionar as variáveis necessárias

Preencha .env (ver Pré-requisitos). Para webhooks locais, exponha a sua aplicação com o ngrok e copie o URL HTTPS para APP_URL:

ngrok http 3000

4. Create Quicknode Streams + KV lists

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

Copie o token de segurança impresso para .env (QN_STREAM_SECURITY_TOKEN_EVM ou QN_STREAM_SECURITY_TOKEN_SOL). If you want Solana, run the command again with chain=solana-mainnet (ver 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

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

Base de dados

O SQLite é utilizado por predefinição. O esquema do Prisma encontra-se em prisma/schema.prisma.

Comandos comuns:

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 ou 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 para .env (QN_STREAM_SECURITY_TOKEN_EVM ou QN_STREAM_SECURITY_TOKEN_SOL)
Creates a single stream per run (run again with chain=solana-mainnet ou 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

Segurança e carga útil do Webhook

Ponto final: POST /api/webhook/streams
Cabeçalhos obrigatórios: x-qn-nonce, x-qn-timestamp, x-qn-signature
A carga útil pode ser comprimida com gzip; o manipulador deteta automaticamente content-encoding: gzip
Utilizações da verificação de assinaturas QN_STREAM_SECURITY_TOKEN_EVM ou QN_STREAM_SECURITY_TOKEN_SOL

Pontos de acesso da API

GET /api/health - exame médico
GET /api/users - list monitored users
POST /api/users - add a single user (walletAddress, optional nome)
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 - Webhook do Quicknode Streams
POST /api/webhook/test - local-only webhook test
GET /api/sse - SSE stream of activity events

Pré-visualização

Contribuições e comentários

Adoraríamos receber os vossos comentários e agradecemos quaisquer contribuições para esta aplicação de exemplo!

Para comunicar problemas ou partilhar comentários, abra uma issue no GitHub na qn-guia-exemplos repositório.

Para contribuir, siga estes passos:

Fazer um fork do repositório
Criar um ramo de funcionalidades:
git checkout -b feature/amazing-feature
Envie as suas alterações:
git commit -m "Adicionar uma funcionalidade fantástica"
Envie o seu branch:
git push origin feature/amazing-feature
Abrir um Pull Request.

Explore mais aplicações de exemplo

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.

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.