Hyperliquid TP/SL Heatmap

A real-time browser dashboard that visualizes resting Hyperliquid TP/SL trigger orders as price-level clusters, anchored against live bid/ask prices from Quicknode Hypercore gRPC streams.

Autor

Sergen Uysal

Repo anzeigen

Frontend-Framework/Bibliothek:

Reagieren

Sprache:

TypeScript

Build-Tool/Entwicklungsserver:

Vite

Übersicht

This app connects to Quicknode's Hyperliquid gRPC endpoint to stream live TP/SL trigger order events (StreamTpslUpdates) and best bid/offer prices (StreamBboBook). Open orders are clustered into configurable price buckets and pushed to the browser over WebSocket, where a canvas-based heatmap renders the aggregated trigger pressure at each price level in real time.

The app ships with a built-in demo mode that uses a synthetic feed, so you can explore the UI without any credentials.

This example app is provided for educational and demonstration purposes only.

Architektur

Browser (React + Canvas)
        ▲
        │  WebSocket
        │
Node.js HTTP + WebSocket Server
        │
        ├── gRPC: StreamTpslUpdates ──┐
        │                             ├── Quicknode Hyperliquid gRPC Endpoint
        └── gRPC: StreamBboBook ──────┘

Funktionen

Real-time TP/SL heatmap: price-bucket clusters updated live from Quicknode gRPC streams
BBO anchor: current bid and ask prices overlaid on the heatmap for market context
TP/SL mix indicator: each bucket shows a small green/red marker for take-profit vs. stop-loss share
Multi-asset support: monitor BTC, ETH, SOL, HYPE, and any other Hyperliquid perp symbol simultaneously
Configurable bucket width: BUCKET_SIZE_PCT scales bucket size relative to the current mid price
Demo mode: runs with a synthetic feed when credentials are missing or DEMO_MODE=true
Health endpoint: GET /health returns server status and current run mode as JSON

Voraussetzungen

Quicknode account with a Hyperliquid endpoint (gRPC access required)
Node.js v18+
pnpm

Projektstruktur

proto/
  orderbook.proto           # gRPC service definition
src/
  client/
    App.tsx                 # Coin selector and WebSocket client
    HeatmapCanvas.tsx       # Canvas-based heatmap renderer
    main.tsx                # React entry point
    styles.css              # App styles
  server/
    cluster-store.ts        # Order clustering and BBO state
    config.ts               # Env var loading
    demo.ts                 # Synthetic demo feed
    grpc.ts                 # gRPC client setup
    server.ts               # HTTP + WebSocket server
    streams.ts              # Live gRPC stream connections
  shared/
    types.ts                # Shared TypeScript types

Umgebungsvariablen

Kopieren .env.example zu .env and fill in your credentials:

# https://your-endpoint.hype-mainnet.quiknode.pro:10000
QUICKNODE_GRPC_ENDPOINT=your-endpoint.hype-mainnet.quiknode.pro:10000
QUICKNODE_GRPC_TOKEN=your-auth-token
TARGET_COINS=BTC,ETH,SOL
DEFAULT_COIN=BTC
BUCKET_SIZE_PCT=0.75
DEMO_MODE=false
PORT=8787

Variable	Beschreibung
`QUICKNODE_GRPC_ENDPOINT`	Your Quicknode Hyperliquid gRPC endpoint (host:port)
`QUICKNODE_GRPC_TOKEN`	Auth token for the gRPC endpoint
`TARGET_COINS`	Comma-separated list of Hyperliquid perp symbols to monitor
`DEFAULT_COIN`	Which coin to display on load (must be in `TARGET_COINS`)
`BUCKET_SIZE_PCT`	Bucket width as a percentage of mid price (e.g., `0.75` = ~$500 buckets on BTC near $64k)
`DEMO_MODE`	Set to `wahr` to force demo mode regardless of credentials
`PORT`	HTTP server port (default: `8787`)

Erste Schritte

1. Das Repo klonen

git clone https://github.com/quiknode-labs/qn-guide-examples.git
cd qn-guide-examples/sample-dapps/hyperliquid-tpsl-heatmap

2. Abhängigkeiten installieren

pnpm installieren

3. Configure environment

cp .env.example .env

Open .env and set QUICKNODE_GRPC_ENDPOINT und QUICKNODE_GRPC_TOKEN with your Quicknode Hyperliquid endpoint credentials. Omitting them will start the app in demo mode automatically.