Suivi des commandes HyperCore
Suivez en temps réel les ordres de négociation sur Hyperliquid Core (L1) grâce à Quicknode Streams et KV Store, qui permettent un filtrage dynamique.
Aperçu
Cette application d'exemple permet le suivi en temps réel des ordres de trading sur Hyperliquid Core (L1). Elle exploite Quicknode Streams et Key-Value Store (KV Store) pour un filtrage intelligent et dynamique, sans nécessiter de redémarrage des flux. Surveillez les grands traders, suivez l'état des ordres et recevez des mises à jour en direct grâce à une interface utilisateur moderne.
Architecture
Noyau hyperliquide (L1)
-> Quicknode Streams + KV
-> POST /api/webhook/streams (signature vérifiée)
-> Mise à jour ou insertion dans OrderLog + émission SSE
-> Flux de commandes en temps réel dans l'interface utilisateur
Fonctionnalités
- Filtrage d'adresses en temps réel via des listes de KV Store
- Filtrage dynamique des statuts (ouvert, traité, annulé, rejeté, déclenché)
- Filtrage natif de la blockchain au niveau du flux
- Événements envoyés par le serveur (SSE) pour la mise à jour en temps réel de l'interface utilisateur
- Scripts de configuration de Quicknode Streams (création + activation)
- Ajouter en masse les adresses des traders
- Vérification de la signature des webhooks et contrôle de l'horodatage
- Résolution ENS pour les adresses Ethereum (facultatif)
- Prisma + stockage local SQLite
Prérequis
- Node.js 20+ et un gestionnaire de paquets (pnpm, yarn, npm).
- Compte Quicknode avec accès à Streams et au KV Store : Créez un compte et obtenez votre Clé API d'administration pour
QN_API_KEY. - URL publique du webhook : utilisez un tunnel tel que
ngrokou déployez l'application de manière à ce queAPP_URLest accessible via Quicknode. - Facultatif : point de terminaison RPC du réseau principal Ethereum pour la résolution des noms ENS (
QN_EVM_ENDPOINT).
Structure du projet
filtres/
hl-orders-filter.js # Filtre Quicknode Streams (HyperCore)
scripts/
setup-streams.ts # Crée des listes KV + un flux (en pause)
activate-streams.ts # Active un flux par ID
src/
app/api/ # Routes API (webhooks, utilisateurs, SSE)
lib/ # Aides pour Quicknode, les webhooks et SSE
types/ # Définitions TypeScript
prisma/
schema.prisma # Schéma SQLite
Variables d'environnement
Copier .env.example to .env et complétez :
QN_API_KEY="" # Clé API Quicknode avec autorisations Streams + KV
QN_STREAM_SECURITY_TOKEN="" # Jeton de sécurité Stream (provenant du script d'installation)
APP_URL="http://localhost:3000" # URL publique de l'application (ngrok pour les webhooks locaux)
DATABASE_URL="file:./dev.db" # Base de données SQLite
QN_EVM_ENDPOINT="" # Facultatif : RPC Ethereum pour la résolution ENS
ADMIN_API_KEY="" # Facultatif pour le développement local, obligatoire pour la production
Remarques :
QN_STREAM_SECURITY_TOKENest renvoyée parconfiguration : flux.APP_URLdoit être accessible via Quicknode (utilisez ngrok ou une URL déployée).- Assurez-vous que les autorisations « Streams » et « KV Store » sont activées pour votre clé API.
Démarrer
1. Installer les dépendances
pnpm installer
# npm install
# yarn install
2. Créez votre fichier d'environnement
cp .env.example .env
3. Ajouter les variables requises
Remplissez .env (voir Prérequis).
Pour les webhooks locaux, exposez votre application avec ngrok et copiez l'URL HTTPS dans APP_URL:
ngrok http 3000
4. Initialiser la base de données
pnpm prisma migrate dev --name hypercore-order-monitor
pnpm db:seed
Le script d'initialisation crée des filtres d'état (permettant ouvrir, rempli, déclenché (par défaut) et ajoute une adresse de trader à titre d'exemple.
5. Créer des flux Quicknode et des listes KV
pnpm exécuter setup:streams
Copiez le jeton de sécurité imprimé dans .env (QN_STREAM_SECURITY_TOKEN).
6. Lancez l'application
pnpm dev
7. Activer le flux
pnpm exécuter activate:streams
Ouvrir http://localhost:3000, ajoutez les adresses des traders, et vous devriez voir s'afficher en temps réel les événements liés aux ordres à mesure que les flux transmettent des webhooks.
Base de données
SQLite est utilisé par défaut. Le schéma Prisma se trouve dans prisma/schema.prisma.
Commandes courantes :
pnpm prisma migrate dev --name <name>
pnpm db:seed
pnpm prisma studio
Sécurité et charge utile des webhooks
- Point final :
POST /api/webhook/streams - En-têtes obligatoires :
x-qn-nonce,x-qn-timestamp,x-qn-signature - La charge utile peut être compressée au format gzip ; le gestionnaire la détecte automatiquement
content-encoding : gzip - Utilisations de la vérification des signatures
QN_STREAM_SECURITY_TOKEN
Points de terminaison de l'API
Points de terminaison publics :
GET /api/health- bilan de santéGET /api/users- liste des opérateurs faisant l'objet d'une surveillanceGET /api/statuses- filtres de statut de la listePOST /api/webhook/streams- Webhook Quicknode StreamsGET /api/sse- Flux d'événements liés aux ordres de la SSE
Terminaux protégés (nécessitent Authorization: Bearer <ADMIN_API_KEY>):
POST /api/users- ajouter un traderPOST /api/users/bulk- Ajouter des traders en masse (limite de 50 adresses)PATCH /api/users?id=...- mettre à jour le traderDELETE /api/users?id=...- supprimer un traderGET /api/commandes- afficher les commandes à l'aide de filtresPATCH /api/statuses- mettre à jour les statuts « activé »POST /api/statuses/reset- rétablir les paramètres par défaut
Scripts de synchronisation
pnpm run sync:statuses- Rapproche la liste des statuts KV avec la base de donnéespnpm run sync:users- Synchronise la liste des utilisateurs KV avec la base de donnéespnpm run reset:kv- Supprime les listes KV HyperCore
Aperçu
- Créer une branche du dépôt
- Créer une branche de fonctionnalité :git checkout -b feature/amazing-feature
- Validez vos modifications :git commit -m "Ajout d'une fonctionnalité géniale"
- Publiez votre branche :git push origin feature/amazing-feature
- Créez une Pull Request.
