Skip to content

quiknode-labs/hyperliquid-workaround-methods

BranchesTags

Repository files navigation

Hyperliquid API Workarounds via Quicknode

TypeScript library for accessing Hyperliquid data through Quicknode's HyperCore data streams.

Overview

This library provides higher-throughput alternatives to some of Hyperliquid's public info endpoints. If you're hitting rate limits on Hyperliquid's native API, these workarounds let you access the same data through Quicknode's HyperCore infrastructure.

Looking for the original Hyperliquid methods? See the Quicknode Hyperliquid Info Endpoints documentation for the native API reference. This library provides drop-in TypeScript implementations for Hyperliquid's most commonly used API methods, with two approaches per method:

  • HTTP JSON-RPC: For point-in-time queries and historical data backfilling.

  • gRPC Streaming: For real-time, low-latency data subscriptions.

Note: These methods bypass Hyperliquid’s public API limits, but standard Quicknode endpoint limits and API credits usage still apply.

Supported Data Access Methods

Approach Best For Coverage Latency
HTTP JSON-RPC Quick queries, point-in-time or historical data Recent blocks or specific block ranges Sub-second
gRPC Streaming Real-time monitoring New events after subscribing (no backfill) Real-time

Important:

  • Historical data coverage: Some datasets have retention starting around 1 October 2025. You can query the latest ~200 blocks, or specify a fromBlock/toBlock range to access older historical data (auto-paginated in chunks of 200).
  • gRPC is real-time only: Streaming does not backfill historical blocks, it captures events from the moment you subscribe.
  • Filtering: Both approaches support server-side filtering by user, coin, and order ID to reduce bandwidth. See the Stream Filtering Documentation for details.

Example: Need user fills?

  • HTTP: getUserFills(address) → Get recent fills instantly
  • HTTP: getUserFills(address, { fromBlock: 1000, toBlock: 1500 }) → Get fills from a specific block range
  • gRPC: streamUserFills(...) → Subscribe and receive new fills as they happen

Methods Reference

The table below maps each workaround method to its corresponding Hyperliquid API method. Use this library when you need a workaround path for methods affected by Hyperliquid native API rate limits.

Hyperliquid Method HTTP Workaround gRPC Workaround Description
userFills getUserFills() streamUserFills() User's executed trades
userFillsByTime getUserFillsByTime() streamUserFillsByTime() Fills within a time range
recentTrades getRecentTrades() streamRecentTrades() Recent market trades (all users)
orderStatus getOrderStatus() streamOrders() Status of a specific order
historicalOrders getHistoricalOrders() collectHistoricalOrders() User's past orders
userTwapSliceFills getUserTwapSliceFills() streamUserTwapSliceFills() TWAP order execution details
userNonFundingLedgerUpdates getUserNonFundingLedgerUpdates() streamUserNonFundingLedgerUpdates() Transfers, deposits, withdrawals
userFunding getUserFunding() streamUserFunding() Funding payments
delegatorHistory getDelegatorHistory() streamDelegatorHistory() Delegation events

Features

Implemented Methods

All methods return data in a format compatible with Hyperliquid's public API responses.

Trading & Orders

  • getUserFills - Get user's executed trades
  • getUserFillsByTime - Get fills within a time range
  • getRecentTrades - Get recent market trades (all users)
  • getOrderStatus - Check status of a specific order
  • getHistoricalOrders - Get user's past orders

Advanced Order Types

  • getUserTwapSliceFills - Get TWAP order execution details
  • getUserNonFundingLedgerUpdates - Get transfers, deposits, withdrawals
  • getUserFunding - Get funding payments
  • getDelegatorHistory - Get delegation events

Streaming Versions (gRPC)

Streaming equivalents for the HTTP methods:

  • streamUserFills
  • streamUserFillsByTime
  • streamRecentTrades
  • streamOrders (covers orderStatus + historicalOrders)
  • streamUserTwapSliceFills
  • streamUserNonFundingLedgerUpdates
  • streamUserFunding
  • streamDelegatorHistory

Additional gRPC helpers:

  • collectHistoricalOrders, findOrderByOid
  • streamUserTwap (TWAP order-state stream, not a public API method)

Quick Start

Installation

# Clone the repository
git clone https://github.com/quiknode-labs/hyperliquid-workaround-methods.git
cd hyperliquid-workaround-methods

# Install dependencies
npm install

# or yarn install
# or pnpm install

# Build the Project
npm run build
# or yarn build
# or pnpm build

Configuration

Create a .env file with your Quicknode endpoint:

cp .env.example .env

Edit .env:

# Quicknode HyperCore Endpoint Configuration
#
# HTTP Endpoint (required)
# Format: https://{endpoint-name}.hype-mainnet.quiknode.pro/{token}/hypercore
QUICKNODE_ENDPOINT=https://your-endpoint.hype-mainnet.quiknode.pro/your-token/hypercore

# gRPC Endpoint (required for streaming)
# Format: {endpoint-name}.hype-mainnet.quiknode.pro:10000
# Note: gRPC uses port 10000, NOT the standard HTTP port
# Example: example-guide-demo.hype-mainnet.quiknode.pro:10000
QUICKNODE_GRPC_ENDPOINT=your-endpoint.hype-mainnet.quiknode.pro:10000

# gRPC Token (required for streaming)
# The token from your HTTP endpoint URL
# Example: abc123def456
QUICKNODE_GRPC_TOKEN=your-token

Get your endpoint at Quicknode.com - HyperCore data streams are included with Hyperliquid nodes.

Usage Examples

HTTP Approach (Recent or Historical Queries)

import "dotenv/config";
import { getUserFills, getOrderStatus } from 'hyperliquid-workaround-methods/http';

// Get recent fills for a user (latest blocks)
const fills = await getUserFills('0x1234...', {
  aggregateByTime: false
});

console.log(`Found ${fills.length} fills`);

// Get fills from a specific block range (historical)
const historicalFills = await getUserFills('0x1234...', {
  fromBlock: 50000,
  toBlock: 50500  // ranges > 200 blocks are auto-paginated
});

// Get order status
const order = await getOrderStatus('0x1234...', 305023273119);
console.log(`Order status: ${order.status}`);

gRPC Approach (Real-time Streaming)

import "dotenv/config";
import { streamUserFills, streamOrders } from 'hyperliquid-workaround-methods/grpc';

// Stream new fills as they occur (real-time only)
const fillsStream = streamUserFills({
  userAddress: '0x1234...',
  onFill: (fill, user, blockNumber) => {
    console.log(`Block ${blockNumber}: ${user} ${fill.coin} ${fill.dir} ${fill.sz}`);
  },
  onError: (error) => console.error('Stream error:', error),
});

// Stop after 10 seconds
setTimeout(() => fillsStream.stop(), 10000);

// Stream order updates in real-time
const ordersStream = streamOrders({
  userAddress: '0x1234...',
  onOrder: (event, blockNumber) => {
    console.log(`Block ${blockNumber}: ${event.order.coin} ${event.status}`);
  },
});

setTimeout(() => ordersStream.stop(), 10000);

Run Examples

# HTTP approach
npm run example:http

# gRPC streaming approach
npm run example:grpc

Project Structure

hyperliquid-workaround-methods/
├── src/
│   ├── http/           # HTTP JSON-RPC implementations
│   ├── grpc/           # gRPC streaming implementations
│   └── shared/         # Shared utilities and types
├── examples/           # Usage examples

How It Works

Why Use This Library?

Hyperliquid's public info endpoints have rate limits that can block high-frequency queries. This library provides an alternative path to the same data through Quicknode's HyperCore infrastructure.

For the original Hyperliquid API methods, see Quicknode's Hyperliquid Info Endpoints.

The Solution

Quicknode's HyperCore API provides access to the underlying data through L1 data streams:

  1. Data Streams: Quicknode ingests Hyperliquid's L1 data and exposes it through specialized streams:

    • trades - Executed fills
    • orders - Order lifecycle events
    • book_updates - Order book changes
    • events - Transfers, deposits, withdrawals
    • twap - TWAP execution data

  2. Response Format Compatibility: The data from these streams matches Hyperliquid's public API format exactly - no transformation needed.

  3. Two Access Methods:

    • HTTP JSON-RPC: Query recent blocks (default) or specific historical block ranges via fromBlock/toBlock
    • gRPC Streaming: Subscribe for real-time updates only (no historical backfill)

Key Technical Details

  • Endpoint: https://{endpoint}.hype-mainnet.quiknode.pro/{token}/hypercore
  • gRPC compression: Uses zstd compression for efficient streaming
  • Event formats: Vary by stream type (trades use tuples, orders/events use objects)
  • Filtering: Server-side filtering by user, coin, order ID reduces bandwidth and improves performance. See filtering documentation for all available filter options.

Testing & Validation

# Compare HTTP methods with Hyperliquid's public API (auto-discovers active users)
npm run test:compare -- --auto

# Compare gRPC methods with Hyperliquid's public API (real-time only)
npm run test:grpc-compare

# Test with specific user address and timeout
npm run test:grpc-compare -- 0xYourAddress 30000 ETH

# Run usage examples
npm run example:http
npm run example:grpc

gRPC Test Configuration

The gRPC comparison test accepts command-line arguments:

npm run test:grpc-compare -- [userAddress] [timeoutMs] [coin]
Argument Default Description
userAddress 0xdc66f4759f... Wallet address to test user-specific methods
timeoutMs 10000 How long to wait for real-time events (ms)
coin ETH Coin for recentTrades test

You can also use environment variables:

export TEST_USER_ADDRESS=0xYourAddress
export TEST_TIMEOUT_MS=30000
npm run test:grpc-compare

Note: gRPC comparisons only capture events during the timeout window. Empty results are expected if no matching events occur. Use higher timeouts (30000-60000ms) and active addresses for better results.

See TESTING.md for comprehensive testing instructions.

Method Coverage

Methods aim to return data in a format compatible with Hyperliquid's public API.

Trading & Orders:

  • getUserFills / streamUserFills
  • getUserFillsByTime / streamUserFillsByTime
  • getRecentTrades / streamRecentTrades
  • getOrderStatus / streamOrders
  • getHistoricalOrders / collectHistoricalOrders

Advanced:

  • getUserTwapSliceFills / streamUserTwapSliceFills
  • getUserNonFundingLedgerUpdates / streamUserNonFundingLedgerUpdates
  • getUserFunding / streamUserFunding
  • getDelegatorHistory / streamDelegatorHistory

Development Setup

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode for development
npm run dev

Requirements

  • Node.js: 18.0.0 or higher
  • Package Manager: npm, yarn, or pnpm
  • Quicknode Account: With Hyperliquid endpoint (HyperCore enabled)

Links

Support

For issues and questions:

Built with ❤️ for the Hyperliquid community

About

Hyperliquid Workaround Methods

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages