Hyperliquid Portfolio Tracker

Build a real-time portfolio tracker that monitors Hyperliquid perpetual positions, PnL, margin utilization, and vault holdings using Quicknode's Hyperliquid info endpoint.

Deploy App

View Repo

Frontend Framework/Library:

React

Language:

TypeScript

Build Tool/Development Server:

Vite

Introduction

As a perpetual trader on Hyperliquid, having a comprehensive portfolio tracker is essential for monitoring your positions, PnL, and margin utilization in real-time. This guide shows you how to build a powerful portfolio tracker that monitors any Hyperliquid wallet using Quicknode's Hyperliquid info endpoint.

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

Additional Resources

For an in-depth guide on implementing this portfolio tracker from scratch, check out our comprehensive guide on Quicknode

Features

Live Position Tracking: Real-time updates on perpetual positions with PnL
Portfolio Analytics: Account value, margin usage, and risk metrics
Vault Management: Track vault value and lock-up schedules
Spot Holdings: Monitor token balances and USD values
Search For Any Wallet: Switch between different trading accounts

Tech Stack

Frontend

React + TypeScript + Tailwind CSS + shadcn/ui & Radix UI
Displays trading data in a responsive interface
Polls database every 1000ms for updates
Handles wallet switching through database requests

Backend

Node.js indexer with 500ms polling interval
Fetches data from 5 different Hyperliquid endpoints
Stores data in PostgreSQL with proper precision handling
Manages wallet switching requests from the frontend

Polling Considerations

This guide uses aggressive polling intervals (500ms for indexer, 1000ms for frontend) to demonstrate real-time updates. You can adjust these intervals if needed:

Frontend: src/Dashboard.tsx lines 260-264 - Change the 1000 value in:

const interval = setInterval(async () => {
  await fetchData(currentWallet);
}, 1000);

Indexer: src/indexer/indexer.ts lines 623-630 - Change the 500 value in:

setInterval(async () => {
  await indexer.checkForWalletSwitch();
  await indexer.indexData();
}, 500);

Monitor your Quicknode and Supabase usage to optimize costs.

Database

Supabase PostgreSQL
Stores trading data in 6 tables with financial precision (DECIMAL types)
Handles communication between frontend and indexer via wallet_switch_requests table
Uses unique constraints to prevent duplicate entries

Data Source

Hyperliquid info endpoint via Quicknode
Provides account data, positions, vault holdings, spot balances, and delegations
Returns data in JSON format with string numbers for precision
Accessed via HTTP POST requests with wallet address parameter

Architecture

                    ┌─────────────────┐
                    │   Perp Trader   │
                    └─────────┬───────┘
                              │ 1. Enter wallet address
                              ▼
                    ┌─────────────────┐
                    │ React Dashboard │◄─────────────────┐
                    └─────────┬───────┘                  │
                              │ 2. Store request         │ 6. Read & display data
                              ▼                          │
                    ┌─────────────────┐                  │
                    │    Supabase     │◄─────────────────┤
                    │   PostgreSQL    │                  │
                    └─────────┬───────┘                  │
                              │ 3. Detect request        │ 5. Store data
                              ▼                          │
                    ┌─────────────────┐                  │
                    │     Indexer     │──────────────────┘
                    │   (500ms poll)  │
                    └─────────┬───────┘
                              │ 4. Fetch HyperCore data
                              ▼
                    ┌─────────────────┐
                    │   Quicknode     │
                    │  Hyperliquid    │
                    │   Endpoint      │
                    └─────────────────┘

The portfolio tracker consists of three components that communicate through a PostgreSQL database. The indexer fetches data from Hyperliquid, stores it in the database, and the frontend queries the database for display.

Prerequisites

Quicknode account with Hyperliquid endpoint
Supabase account
Node.js v20+, npm, and a code editor
Basic React/TypeScript and REST API concepts
Basic SQL concepts
Optional: Hyperliquid perpetual trading experience

Why Quicknode Endpoint?

Quicknode provides dedicated Hyperliquid API endpoints that eliminate the need to run your own node:

Pre-configured endpoints with no setup required
Handles connection management and failover
Direct access to HyperCore data without additional infrastructure

Quick Start

1. Clone the Repository

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

2. Setup Environment File

cp .env.example .env

3. Supabase Database Setup

Create a new Supabase account or login at supabase.com
Create a new project, then click the Connect button

Connect Button

In the App Frameworks section, select React and change using to Vite

Select React

Copy the VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY values to your .env file 1
Navigate to the SQL Editor, paste the content of supabase/schema.sql, then click Run

SQL Editor

This creates all necessary tables and functions for storing and fetching trading data.

4. Quicknode Setup

Create a free trial Quicknode account
Create a Hyperliquid RPC endpoint
Copy the endpoint URL and paste it to your .env file

Important

Make sure you remove the existing /evm and add /info at the end of your Quicknode endpoint URL to gain access to the Hyperliquid info endpoints.

5. Start the Application

npm install && npm run dev:both

This runs both the frontend application and the indexer. Open your browser at http://localhost:5173 and use the demo wallet button to see the tracker in action.

Troubleshooting

If the indexer stops responding or no data appears after wallet search, simply re-run the indexer:

npm run dev:indexer

Then search again by inputting a valid wallet address.

Preview

Main Page

Dashboard View

Learn More

Future Improvements

Liquidation Warnings: Alert users when positions approach dangerous margin levels
Performance Charts: Track portfolio performance over time with Recharts
Price Alerts: Send notifications using your favorite notification service
Multi-Wallet Dashboard: Compare multiple trading accounts side-by-side

Contributions & Feedback

We'd love to hear your feedback and welcome any contributions to this sample app!

To report issues or share feedback, open a GitHub issue in the qn-guide-examples repository.

To contribute, follow these steps:

Fork the repository
Create a feature branch:
git checkout -b feature/amazing-feature
Commit your changes:
git commit -m "Add amazing feature"
Push your branch:
git push origin feature/amazing-feature
Open a Pull Request.

Explore More Sample Apps

HyperCore Order Monitor

Track trading orders on Hyperliquid Core (L1) in real-time with Quicknode Streams and KV Store for dynamic filtering.

Hyperliquid Trading Dashboard

A dashboard for real-time whale trades, liquidations, and trending tokens from Hyperliquid using Quicknode Hypercore gRPC.

SQL Explorer Cookbook

Query Hyperliquid on-chain data with standard SQL using Quicknode SQL Explorer.

Hyperliquid Portfolio Tracker

Introduction

Features

Tech Stack

Frontend​

Backend​

Database​

Data Source​

Architecture

Prerequisites

Quick Start

1. Clone the Repository​

2. Setup Environment File​

3. Supabase Database Setup​

4. Quicknode Setup​

5. Start the Application​