Skip to content

internet-court/internet-court-skill / vendored/quicknode/quicknode-skill

quicknode-skill

Verified

Quicknode blockchain infrastructure for 80+ chains: Core RPC API, Streams, Webhooks, Blazar WSS, Solana gRPC, HyperCore gRPC, SQL Explorer, Metaplex DAS API, Blockbook, Ordinals & Runes API, Swap API, x402, MPP, Agent Subscriptions, CLI, and MCP. Use for any Quicknode product, blockchain data access, or wallet-paid agent access.

references/hypercore-hyperliquid-reference.md

View on GitHub
# HyperCore & Hyperliquid Reference

Quicknode provides infrastructure for the Hyperliquid L1 chain through HyperCore, delivering gRPC, JSON-RPC, WebSocket, and Info API access to exchange and trading data, plus HyperEVM RPC for smart contract execution.

## Overview

| Property | Value |
|----------|-------|
| **Chain** | Hyperliquid L1 |
| **Consensus** | HyperBFT (based on HotStuff) |
| **Native Token** | HYPE |
| **Mainnet Chain ID** | 999 |
| **Testnet Chain ID** | 998 |
| **Block Rate** | ~12 blocks/sec |
| **Status** | Public Beta |
| **gRPC Compression** | zstd (~70% bandwidth reduction) |
| **Architecture** | HyperCore (exchange/trading) + HyperEVM (smart contracts) |

## Network Configuration

| Network | Endpoint Pattern | Chain ID |
|---------|-----------------|----------|
| **Mainnet** | `https://[name].hype-mainnet.quiknode.pro/[token]/` | 999 (0x3E7) |
| **Testnet** | `https://[name].hype-testnet.quiknode.pro/[token]/` | 998 |

Testnet is pruned to the last 250 blocks.

## HyperCore Access Methods

| Method | Path / Port | Protocol | Description |
|--------|-------------|----------|-------------|
| **Info** | `/info` | HTTP POST | 50+ specialized methods for market data, positions, orders |
| **JSON-RPC** | `/hypercore` | HTTP POST | Block queries: `hl_getLatestBlocks`, `hl_getBlock`, `hl_getBatchBlocks` |
| **WebSocket** | `/hypercore/ws` | WebSocket | Real-time subscriptions: `hl_subscribe`, `hl_unsubscribe` |
| **gRPC** | Port 10000 | gRPC (HTTP/2) | Lowest latency streaming: `Ping`, `StreamBlocks`, `StreamData` |

## Authentication

### URL Token (default)

```
https://your-endpoint.hype-mainnet.quiknode.pro/your-auth-token/
```

### Header-Based

```bash
curl -H "x-token: your-auth-token" \
  https://your-endpoint.hype-mainnet.quiknode.pro/evm
```

### gRPC Authentication

```javascript
const grpc = require("@grpc/grpc-js");

const metadata = new grpc.Metadata();
metadata.add("x-token", "your-auth-token");
// Pass metadata to all gRPC calls
```

Endpoint for gRPC: `your-endpoint.hype-mainnet.quiknode.pro:10000` (TLS required).

## Info Endpoint

The Info API provides 50+ methods for querying Hyperliquid exchange data. All requests are `POST` to `/info` with a `type` field.

> **Note:** Some Info methods (e.g., `allMids`, `l2Book`, `meta`) are also available via Hyperliquid's public endpoints without a Quicknode subscription. Check https://www.quicknode.com/docs/hyperliquid/llms.txt for details on which methods require a Quicknode endpoint vs. public access.

### Base URL

```
https://[endpoint].hype-mainnet.quiknode.pro/[token]/info
```

### Quick Example

```typescript
const response = await fetch(
  `${process.env.QUICKNODE_RPC_URL}info`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ type: "allMids" }),
  }
);
const midPrices = await response.json();
// { "BTC": "92385.0", "ETH": "3167.4", ... }
```

### Key Methods

| Method (`type`) | Parameters | Description |
|-----------------|------------|-------------|
| `allMids` | — | Real-time mid-market prices for all pairs |
| `l2Book` | `coin` | Level 2 order book (up to 20 levels per side) |
| `recentTrades` | `coin` | Recent executed trades |
| `candleSnapshot` | `coin`, `interval`, `startTime`, `endTime` | OHLCV candlestick data |
| `meta` | — | Exchange metadata: trading pairs, leverage limits |
| `metaAndAssetCtxs` | — | Market data with funding, OI, oracle prices |
| `spotMeta` | — | Spot market metadata |
| `spotMetaAndAssetCtxs` | — | Spot metadata with prices |
| `clearinghouseState` | `user` | Account positions, margin, P&L |
| `spotClearinghouseState` | `user` | Spot token balances |
| `openOrders` | `user` | All open orders for a user |
| `frontendOpenOrders` | `user` | Open orders (frontend format) |
| `historicalOrders` | `user` | Up to 2,000 recent historical orders |
| `orderStatus` | `user`, `oid` | Status of a specific order |
| `userFills` | `user` | Up to 2,000 recent trade executions |
| `userFillsByTime` | `user`, `startTime` | Fills within a time range |
| `fundingHistory` | `coin`, `startTime` | Historical funding rates |
| `predictedFundings` | — | Forecasted funding rates |
| `activeAssetData` | `user`, `coin` | Active trading data for user/asset |
| `portfolio` | `user` | Account value and P&L history |
| `vaultDetails` | `vaultAddress` | Vault analytics |
| `exchangeStatus` | — | Exchange status and maintenance info |

## JSON-RPC Methods

POST requests to `/hypercore`.

### hl_getLatestBlocks

```typescript
const response = await fetch(
  `${process.env.QUICKNODE_RPC_URL}hypercore`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      method: "hl_getLatestBlocks",
      params: { stream: "trades", count: 10 },
      id: 1,
    }),
  }
);
const { result } = await response.json();
// result.blocks: [{ local_time, block_time, block_number, events }]
```

### hl_getBlock

```typescript
const response = await fetch(
  `${process.env.QUICKNODE_RPC_URL}hypercore`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      method: "hl_getBlock",
      params: ["trades", 817824084],
      id: 1,
    }),
  }
);
```

### hl_getBatchBlocks

```typescript
const response = await fetch(
  `${process.env.QUICKNODE_RPC_URL}hypercore`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      method: "hl_getBatchBlocks",
      params: { stream: "trades", from: 817824078, to: 817824090 },
      id: 1,
    }),
  }
);
```

### hl_getLatestBlockNumber

```typescript
const response = await fetch(
  `${process.env.QUICKNODE_RPC_URL}hypercore`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      method: "hl_getLatestBlockNumber",
      params: ["events"],
      id: 1,
    }),
  }
);
```

## WebSocket

Connect to `/hypercore/ws` for real-time subscriptions.

### Subscribe

```typescript
import WebSocket from "ws";

const ws = new WebSocket(
  `${process.env.QUICKNODE_WSS_URL}hypercore/ws`
);

ws.on("open", () => {
  // Subscribe to trades
  ws.send(
    JSON.stringify({
      jsonrpc: "2.0",
      method: "hl_subscribe",
      params: { streamType: "trades" },
      id: 1,
    })
  );
});

ws.on("message", (data) => {
  const message = JSON.parse(data.toString());
  if (message.params) {
    console.log("Trade event:", message.params);
  }
});

// Unsubscribe
ws.send(
  JSON.stringify({
    jsonrpc: "2.0",
    method: "hl_unsubscribe",
    params: { streamType: "trades" },
    id: 2,
  })
);
```

## gRPC Streaming

Port 10000 provides the lowest-latency access to HyperCore data via three RPC methods.

### Connection Setup

```typescript
const grpc = require("@grpc/grpc-js");
const protoLoader = require("@grpc/proto-loader");

const ENDPOINT = "your-endpoint.hype-mainnet.quiknode.pro:10000";
const TOKEN = "your-auth-token";

const packageDefinition = protoLoader.loadSync("streaming.proto", {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
});

const proto = grpc.loadPackageDefinition(packageDefinition);
const channelCredentials = grpc.credentials.createSsl();
const client = new proto.streaming.Streaming(ENDPOINT, channelCredentials, {
  "grpc.max_receive_message_length": 100 * 1024 * 1024, // 100MB
});

const metadata = new grpc.Metadata();
metadata.add("x-token", TOKEN);
```

### gRPC Methods

| Method | Type | Description |
|--------|------|-------------|
| `Ping` | Unary | Connection health check |
| `StreamBlocks` | Server streaming | Stream blocks from a timestamp |
| `StreamData` | Bidirectional streaming | Subscribe to filtered data streams |

### Ping

```typescript
client.Ping({ count: 1 }, metadata, (error, response) => {
  if (error) console.error("Ping failed:", error);
  else console.log("Ping response:", response);
});
```

### StreamData (Bidirectional)

```typescript
const stream = client.StreamData(metadata);

// Subscribe to trades for specific coins
stream.write({
  subscribe: {
    stream_type: "TRADES",
    coins: ["BTC", "ETH"],
  },
});

// Send keepalive pings every 30 seconds
const pingInterval = setInterval(() => {
  stream.write({ ping: { timestamp: Date.now() } });
}, 30000);

stream.on("data", (response) => {
  if (response.data) {
    const block = JSON.parse(response.data.data);
    console.log("Block:", response.data.block_number, block);
  }
  if (response.pong) {
    console.log("Pong:", response.pong.timestamp);
  }
});

stream.on("error", (error) => {
  console.error("Stream error:", error);
  clearInterval(pingInterval);
});

stream.on("end", () => {
  clearInterval(pingInterval);
});
```

## gRPC Stream Types

| Stream Type | Volume | Available Via |
|-------------|--------|---------------|
| **TRADES** | High | gRPC, JSON-RPC, WebSocket |
| **ORDERS** | Very High | gRPC, JSON-RPC, WebSocket |
| **BOOK_UPDATES** | Very High | gRPC, JSON-RPC, WebSocket |
| **TWAP** | Low | gRPC, JSON-RPC, WebSocket |
| **EVENTS** | High | gRPC, JSON-RPC, WebSocket |
| **BLOCKS** | Extreme | gRPC only |
| **WRITER_ACTIONS** | Low | gRPC, JSON-RPC, WebSocket |

### Stream Data Details

- **TRADES**: Execution data — coin, price, size, side, fees, liquidation info
- **ORDERS**: Order lifecycle — 18+ status types (open, filled, canceled, rejected variants)
- **BOOK_UPDATES**: Level-2 order book diffs — individual order adds/removes
- **TWAP**: Time-weighted average price order updates — activated, finished, terminated
- **EVENTS**: Ledger updates, funding payments, deposits, withdrawals, delegations
- **BLOCKS**: Raw HyperCore blocks with all 34 action types (gRPC only)
- **WRITER_ACTIONS**: System-level spot token transfers (HyperCore to HyperEVM)

## gRPC Filtering

Filter streams by coin, user, side, and other fields depending on stream type.

### Filter Fields by Stream

| Stream | Available Filters |
|--------|-------------------|
| **TRADES** | `coin`, `user`, `side`, `liquidation`, `builder` |
| **ORDERS** | `coin`, `user`, `status`, `builder` |
| **BOOK_UPDATES** | `coin`, `side` |
| **TWAP** | `coin`, `user`, `status` |
| **EVENTS** | `user`, `type` |
| **WRITER_ACTIONS** | `user`, `action.type`, `action.token` |

### Filter Logic

- **AND across fields** — When multiple filter fields are specified (e.g., `coin` and `side`), all conditions must match (AND logic).
- **OR within values** — When a field has multiple values (e.g., `coin: { values: ["BTC", "ETH"] }`), any value can match (OR logic).
- **Special value `"*"`** — Matches any event where the field exists (non-null).
- **Special value `"null"`** — Matches events where the field is explicitly null.
- **Recursive matching** — Filters match recursively into nested JSON structures, so top-level field filters also apply to nested objects.

### Filter Limits

| Limit | Maximum |
|-------|---------|
| Values per `user` / `address` filter | 100 |
| Values per `coin` filter | 50 |
| Values per `type` / `status` filter | 20 |
| Total filter values across all fields | 500 |
| Named filters per stream | 10 |

### Filtering Examples

```typescript
const stream = client.StreamData(metadata);

// Subscribe to BTC and ETH buy trades only
stream.write({
  subscribe: {
    stream_type: "TRADES",
    filters: {
      coin: { values: ["BTC", "ETH"] },
      side: { values: ["B"] },
    },
  },
});

// Subscribe to order status changes for a specific user
stream.write({
  subscribe: {
    stream_type: "ORDERS",
    filters: {
      user: { values: ["0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036"] },
      status: { values: ["filled", "canceled"] },
    },
  },
});

// Subscribe to all events where the user field exists
stream.write({
  subscribe: {
    stream_type: "EVENTS",
    filters: {
      user: { values: ["*"] },
    },
  },
});

// Subscribe to liquidation trades only
stream.write({
  subscribe: {
    stream_type: "TRADES",
    filters: {
      liquidation: { values: ["*"] },
    },
  },
});
```

## HIP-4 Prediction Markets

HIP-4 is the Hyperliquid standard for on-chain prediction markets. Key implementation notes as of mid-2026:

- **Collateral currency**: USDC (not USDH — prior guides using USDH are outdated)
- **Read API**: Prediction market metadata is exposed by Hyperliquid's Info API via `type: "outcomeMeta"`. On Quicknode, use your Hyperliquid endpoint Info path (`/info`) to query outcome market metadata.
- **Exchange API**: Quicknode's Hyperliquid Exchange API builder endpoints use `api.hyperliquidapi.com` for zero-custody action construction and submission workflows.

```typescript
// HIP-4 outcome market metadata via Hyperliquid Info API
const response = await fetch("https://[endpoint].hype-mainnet.quiknode.pro/[token]/info", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ type: "outcomeMeta" }),
});
```

For trading data related to prediction markets (fills, orders, funding), use SQL Explorer or the HyperCore gRPC streams.

## Orderbook Dataset & StreamData Filtering

Hyperliquid orderbook data is available in SQL Explorer as a dedicated dataset alongside trades, orders, and fills. For real-time orderbook updates, use the `BOOK_UPDATES` stream via gRPC.

The `StreamData` gRPC method supports filtering on `BOOK_UPDATES` by `coin` and `side`:

```typescript
// Filter book updates to BTC asks only
stream.write({
  subscribe: {
    stream_type: "BOOK_UPDATES",
    filters: {
      coin: { values: ["BTC"] },
      side: { values: ["A"] }, // "A" = asks, "B" = bids
    },
  },
});
```

See the [gRPC Filtering](#grpc-filtering) section for the full filter field reference per stream type.

## HyperEVM

HyperEVM provides EVM-compatible smart contract execution on Hyperliquid. Two RPC paths are available:

| Path | Protocol | Archive | Debug/Trace | Use Case |
|------|----------|---------|-------------|----------|
| `/evm` | HTTP | Partial | No | Standard blockchain operations |
| `/nanoreth` | HTTP + WebSocket | Extended | Yes (`debug_*`, `trace_*`) | Advanced debugging, tracing, subscriptions |

### Standard EVM Example (`/evm`)

```typescript
import { JsonRpcProvider } from "ethers";

const provider = new JsonRpcProvider(
  `${process.env.QUICKNODE_RPC_URL}evm`
);

const blockNumber = await provider.getBlockNumber();
const balance = await provider.getBalance("0x...");
```

### Debug/Trace Example (`/nanoreth`)

```typescript
import { JsonRpcProvider } from "ethers";

const provider = new JsonRpcProvider(
  `${process.env.QUICKNODE_RPC_URL}nanoreth`
);

// Standard methods work on nanoreth too
const blockNumber = await provider.getBlockNumber();

// Debug and trace methods only available on /nanoreth
const trace = await provider.send("debug_traceTransaction", [
  "0xTransactionHash...",
  { tracer: "callTracer" },
]);
```

### WebSocket Subscriptions (`/nanoreth`)

```typescript
import { WebSocketProvider } from "ethers";

const wsProvider = new WebSocketProvider(
  `${process.env.QUICKNODE_WSS_URL}nanoreth`
);

wsProvider.on("block", (blockNumber) => {
  console.log("New block:", blockNumber);
});
```

### Hyperliquid-Specific EVM Methods

| Method | Description |
|--------|-------------|
| `eth_getSystemTxsByBlockNumber` | Internal system transactions (HyperCore-to-HyperEVM) |
| `eth_getSystemTxsByBlockHash` | System transactions by block hash |
| `eth_usingBigBlocks` | Check if address uses big blocks |
| `eth_bigBlockGasPrice` | Gas price for big blocks |

## Best Practices

1. **Use gRPC for lowest latency** — Port 10000 gRPC streaming provides sub-millisecond data delivery, ideal for trading applications.
2. **Enable zstd compression** — Reduces bandwidth by ~70%, critical for high-volume streams like ORDERS and BOOK_UPDATES.
3. **Use `/nanoreth` for debugging** — Extended archive and trace/debug methods are only available on `/nanoreth`, not `/evm`.
4. **Handle ~12 blocks/sec throughput** — Hyperliquid produces blocks rapidly. Ensure your consumer can process events at this rate.
5. **Send gRPC keepalive pings** — Send pings every 30 seconds to maintain the connection.
6. **Note public beta status** — HyperCore on Quicknode is in public beta. APIs and behavior may change.

## Troubleshooting

| Issue | Cause | Solution |
|-------|-------|----------|
| gRPC connection refused on port 10000 | Wrong endpoint or port | Use `endpoint.hype-mainnet.quiknode.pro:10000` with TLS |
| Auth failed on gRPC | Missing or wrong `x-token` metadata | Add `metadata.add('x-token', TOKEN)` to all gRPC calls |
| No data from `/info` | Wrong path or missing `type` field | POST to `/info` with `{"type": "methodName"}` |
| WebSocket disconnects | No ping/pong or server maintenance | Implement reconnection logic with backoff |
| `/evm` missing debug methods | Debug methods not available on `/evm` | Switch to `/nanoreth` for `debug_*` and `trace_*` methods |
| Testnet data missing | Testnet pruned to last 250 blocks | Use mainnet for historical data; testnet is for testing only |
| High bandwidth usage | Unfiltered high-volume streams | Apply coin/user/side filters and enable zstd compression |

## Documentation

- **Hyperliquid Overview**: https://www.quicknode.com/docs/hyperliquid
- **Hyperliquid Overview (llms.txt)**: : https://www.quicknode.com/docs/hyperliquid/llms.txt
- **Hyperliquid gRPC API**: https://www.quicknode.com/docs/hyperliquid/grpc-api
- **HyperCore Filtering**: https://www.quicknode.com/docs/hyperliquid/filtering
- **Hyperliquid llms.txt**: https://www.quicknode.com/docs/hyperliquid/llms.txt
- **HyperCore Info Methods**: https://www.quicknode.com/docs/hyperliquid (Info endpoint section)
- **HyperEVM**: https://www.quicknode.com/docs/hyperliquid (HyperEVM section)
- **Guides**: https://www.quicknode.com/guides/tags/hyperliquid
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 195kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
paperclip-pagepaperclipai/paperclipPublish static HTML pages and asset folders to the Paperclip S3/CloudFront page host. Use when asked to deploy, host, or share a persistent page, viewer, prototype, report, or static site without here.now.Stars: 114kUpdated Claude CodeCodexVerifiedInstall
verify-paperclippaperclipai/paperclipVerify Paperclip from a source checkout, published npm install, or existing staging or production stack. Select the environment, data state, version, and platform; drive real UI or CLI journeys and capture evidence. Route deployment to the private Cloud skills.Stars: 114kUpdated Claude CodeCodexVerifiedInstall