# Hyperliquid Pro Scraper — Traders, Vaults & Markets (`zhorex/hyperliquid-scraper`) Actor

Real-time Hyperliquid DEX data — perpetual markets, leaderboard, wallet positions, trade history, and vault performance. Built for DeFi quants, copy-trading research, and on-chain analytics. Pure HTTP, no auth needed.

- **URL**: https://apify.com/zhorex/hyperliquid-scraper.md
- **Developed by:** [Sami](https://apify.com/zhorex) (community)
- **Categories:** Developer tools, Automation, Integrations
- **Features:** Limited permissions
- **Stats:** 9 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $50.00 / 1,000 wallet positions snapshots

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Hyperliquid Pro Scraper — Traders, Vaults & Markets

Real-time data from **Hyperliquid**, the leading on-chain perpetual DEX with **$1B+ daily volume**. Extract the **leaderboard of top traders**, wallet positions and trade history, vault performance, and a full perpetual markets snapshot — all from Hyperliquid's public API. **No login, no proxy, no API key required.**

### How to scrape Hyperliquid in 3 easy steps

1. **Go to [Hyperliquid Pro Scraper](https://apify.com/zhorex/hyperliquid-scraper)** on Apify Store and click **"Try for free"**
2. **Choose your mode** — leaderboard, wallet positions, trade history, vault details, or market overview
3. **Click Run** and download your data in JSON, CSV, Excel, or XML

No coding required. Works with Apify's free plan.

### Why this scraper?

- **Pure HTTP, no browser**: runs in 256 MB RAM, fast and cheap
- **5 modes in one Actor**: leaderboard, wallet state, trade history, vaults, markets
- **Filterable leaderboard**: rank by day / week / month / all-time PnL, filter by minimum account value
- **Full position breakdown**: per-asset positions with leverage, entry price, unrealized PnL, liquidation price
- **Cross-margin & isolated detail**: distinguishes cross-margin equity from isolated positions
- **Vault analytics**: APR, TVL, top depositors, follower-count metrics
- **Real-time market state**: mid, mark, oracle prices, funding rates, open interest, 24h volume per perp

### Modes

| Mode | What you get | Best for |
|------|--------------|----------|
| **Leaderboard** | Top traders ranked by PnL, with day/week/month/all-time metrics | Copy-trading research, trader-of-the-week studies |
| **User State** | Account equity + per-asset positions for wallet addresses | Wallet tracking, whale watching, alpha leaks |
| **User Fills** | Trade execution history for wallet addresses | Strategy reverse-engineering, backtesting datasets |
| **Vault Details** | Vault metadata, APR, TVL, top depositors | Vault discovery, performance comparison |
| **Market Overview** | Snapshot of every perp market: prices, funding, OI, volume | Market scanners, arbitrage signals, dashboards |

### Data fields

#### Leaderboard entry

- **address**, **displayName**, **accountValue** (USD)
- **performance**: day / week / month / allTime → `{pnl, roi, vlm}`
- **primaryWindow** (the window you sorted by)
- **profileUrl**, **scrapedAt**

#### User state (per wallet)

- **address**, **accountValue**, **totalNotionalPosition**, **totalMarginUsed**, **withdrawable**
- **crossMarginAccountValue**, **crossMaintenanceMarginUsed**
- **openPositionsCount**, **positions\[]** (coin, size, entryPx, positionValue, unrealizedPnl, marginUsed, liquidationPx, leverage, type)
- **profileUrl**, **scrapedAt**

#### User fill (trade execution)

- **coin**, **side** (B/A), **size**, **price**, **value**, **fee**, **closedPnl**
- **direction** (open / close), **orderId**, **timestamp**, **hash**, **tid**
- **scrapedAt**

#### Vault details

- **vaultAddress**, **name**, **description**, **leader**, **apr**, **tvl**, **followerCount**
- **followers\[]** (user, vaultEquity, pnl, daysFollowing)
- **vaultUrl**, **scrapedAt**

#### Market (per perp)

- **coin**, **maxLeverage**, **szDecimals**
- **midPrice**, **markPrice**, **oraclePrice**, **openInterest**, **fundingRate**, **premium**
- **dayVolume** (notional USD), **dayBaseVolume** (base asset units)
- **scrapedAt**

### Input examples

#### Top 50 traders by all-time PnL, accounts > $50K

```json
{
    "mode": "leaderboard",
    "leaderboardWindow": "allTime",
    "minAccountValue": 50000,
    "maxResults": 50
}
```

#### Whale-watch: track positions of specific wallets

```json
{
    "mode": "user_state",
    "wallets": [
        "0x1234567890abcdef1234567890abcdef12345678",
        "0xabcdef1234567890abcdef1234567890abcdef12"
    ],
    "includeFills": true,
    "maxFillsPerWallet": 200
}
```

#### Pull every fill from a single wallet

```json
{
    "mode": "user_fills",
    "wallets": ["0x1234567890abcdef1234567890abcdef12345678"],
    "maxFillsPerWallet": 2000
}
```

#### Vault performance comparison

```json
{
    "mode": "vault_details",
    "vaultAddresses": [
        "0x0000000000000000000000000000000000000001",
        "0x0000000000000000000000000000000000000002"
    ]
}
```

#### Real-time market snapshot (all perps)

```json
{
    "mode": "market_overview"
}
```

### Output sample — leaderboard entry

```json
{
    "mode": "leaderboard_entry",
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "displayName": "PerpKing",
    "accountValue": 824150.42,
    "primaryWindow": "month",
    "performance": {
        "day": {"pnl": 18420.1, "roi": 0.022, "vlm": 5840000},
        "week": {"pnl": 142800.5, "roi": 0.18, "vlm": 38400000},
        "month": {"pnl": 612300.0, "roi": 1.84, "vlm": 152000000},
        "allTime": {"pnl": 4820000.0, "roi": 9.45, "vlm": 1840000000}
    },
    "profileUrl": "https://app.hyperliquid.xyz/explorer/address/0x...",
    "scrapedAt": "2026-05-06T03:00:00Z"
}
```

### Pricing

Pay-per-event:

| Event | Price |
|-------|-------|
| Per leaderboard entry | **$0.02** |
| Per wallet state snapshot | **$0.05** |
| Per individual trade fill | **$0.005** |
| Per vault detail record | **$0.10** |
| Per market snapshot (one row per perp) | **$0.005** |

**Typical costs:**

- Top 50 traders snapshot: ~$1.00
- Track 10 whale wallets daily: ~$0.50/run
- Full trade history of 1 trader (up to 2,000 fills): ~$10
- All Hyperliquid perp markets snapshot (~150 markets): ~$0.75
- 5 vault performance comparison: ~$0.50

**Apify platform compute is included** — you only pay for the scraped items above, never for run duration.

Apify's free plan includes $5 of monthly credit — enough for about 100 wallet snapshots, 250 leaderboard entries or 50 vaults.

### Use cases

- **Copy-trading research**: identify consistently profitable traders, analyze their strategy via fill history
- **Whale watching / alpha leaks**: track known smart-money wallets, detect entries before the crowd
- **Quant signal generation**: cross-reference funding rates, open interest, leaderboard PnL momentum
- **Vault performance dashboards**: rank vaults by APR + TVL + drawdown for selection
- **Market scanners**: real-time snapshot of every perp's funding, OI, volume — feed into your own strategy
- **Backtesting datasets**: pull months of fills from top performers as training data

### Scrape Hyperliquid with Python, JavaScript, or no code

**Python**

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")

run = client.actor("zhorex/hyperliquid-scraper").call(run_input={
    "mode": "leaderboard",
    "leaderboardWindow": "month",
    "minAccountValue": 100000,
    "maxResults": 100,
})

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(f"{item['displayName']:20s}  PnL(month)={item['performance']['month']['pnl']:>12,.0f}")
```

**JavaScript**

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' });

const run = await client.actor('zhorex/hyperliquid-scraper').call({
    mode: 'market_overview'
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### FAQ

**Does it require a Hyperliquid account or API key?** No. The Actor uses Hyperliquid's public read-only API (no auth, no signing, no key).

**Can I track wallets in real time?** Schedule the Actor to run every N minutes via Apify Schedules. Each run is a fresh snapshot — store dataset versions for time-series analysis.

**What's the leaderboard time-window granularity?** Hyperliquid exposes 4 windows: 24h (`day`), 7d (`week`), 30d (`month`), and `allTime`. The Actor returns metrics for ALL four windows on every entry; pick which one drives the sort with `leaderboardWindow`.

**Can I get historical OHLCV / candles?** Not in this Actor — it focuses on trader and market state. Hyperliquid's `candleSnapshot` endpoint can be added on request; open an issue if you need it.

**What about spot markets?** This v1 covers perpetuals (the bulk of Hyperliquid volume). Spot data can be added — open an issue if you need spot tickers.

**Are the wallet addresses I provide stored anywhere?** No. The Actor only forwards them to Hyperliquid's public API. Apify retains the input on the run record (you control retention via Apify Console).

**Is scraping Hyperliquid legal?** The Actor reads Hyperliquid's public, read-only market and account data, the same data its website and explorer show. It sends no credentials and signs nothing. Whether your use is allowed depends on your jurisdiction and Hyperliquid's terms — review them for your use case.

### Integrations & data export

Export results in JSON, CSV, Excel, or XML. Integrate with:

- **Google Sheets** — automatic dashboards
- **Zapier / Make / n8n** — alert flows when a wallet opens a position
- **REST API** — programmatic access from any language
- **Webhooks** — real-time triggers on run completion

### Other scrapers by Zhorex

**DeFi & Markets:**

- [Hyperliquid Pro Scraper](https://apify.com/zhorex/hyperliquid-scraper) — *(this Actor)*
- [Solana DEX Scraper](https://apify.com/zhorex/solana-dex-scraper) — Raydium + Orca normalized swap stream (dev-grade schema)
- [TradingView Multi-Market Scraper](https://apify.com/zhorex/tradingview-scraper) — Stocks, crypto, forex, indices

**AI & Search:**

- [Perplexity AI Search Scraper](https://apify.com/zhorex/perplexity-ai-scraper) — AI-powered search results

**Chinese Digital Intelligence Suite:**

- [Weibo Scraper](https://apify.com/zhorex/weibo-scraper) — China's Twitter (580M+ users)
- [Bilibili Scraper](https://apify.com/zhorex/bilibili-scraper) — China's YouTube (300M+ users)
- [RedNote (Xiaohongshu) Scraper](https://apify.com/zhorex/rednote-xiaohongshu-scraper) — Posts, profiles, comments, videos
- [RedNote Shop Scraper](https://apify.com/zhorex/rednote-shop-scraper) — Xiaohongshu e-commerce
- [Douban Scraper](https://apify.com/zhorex/douban-scraper) — Long-form reviews (movies, books, music)

**B2B Review Intelligence:**

- [G2 Reviews Scraper](https://apify.com/zhorex/g2-reviews-scraper)
- [Capterra Reviews Scraper](https://apify.com/zhorex/capterra-reviews-scraper)
- [Booking.com Reviews Scraper](https://apify.com/zhorex/booking-reviews-scraper)

Not affiliated with, endorsed by or sponsored by Hyperliquid. Names are used only to describe the data source.

***

### Your Review Matters ⭐

If you have used this Actor, **a 30-second rating helps, good or bad**:

1. Go to the [Hyperliquid Pro Scraper page](https://apify.com/zhorex/hyperliquid-scraper)
2. Click the star rating
3. Optionally leave a short note

**Why it matters**: ratings help other users judge whether this Actor fits their use case.

**Found a bug or want a new metric?** [Open an issue](https://apify.com/zhorex/hyperliquid-scraper/issues).

***

**Feature requests or bugs?** Open an Issue on this Actor's page.

# Actor input Schema

## `mode` (type: `string`):

Choose what to extract from Hyperliquid.

## `maxResults` (type: `integer`):

Maximum results to return (per mode).

## `leaderboardWindow` (type: `string`):

Time window to rank traders by (used in 'leaderboard' mode).

## `minAccountValue` (type: `integer`):

Filter out leaderboard entries below this threshold (e.g. 50000 to skip small accounts).

## `wallets` (type: `array`):

List of 0x EVM addresses (used in 'user_state' and 'user_fills' modes).

## `vaultAddresses` (type: `array`):

List of vault contract addresses (used in 'vault_details' mode).

## `includeFills` (type: `boolean`):

When in 'user_state' mode, also fetch each wallet's recent trade history.

## `maxFillsPerWallet` (type: `integer`):

Cap on how many trade fills to return per wallet.

## `proxyConfiguration` (type: `object`):

Optional. Hyperliquid's API doesn't require proxies for normal use, but rotating proxies help avoid rate limits on large batches.

## Actor input object example

```json
{
  "mode": "leaderboard",
  "maxResults": 100,
  "leaderboardWindow": "allTime",
  "wallets": [
    "0x1234567890abcdef1234567890abcdef12345678"
  ],
  "includeFills": false,
  "maxFillsPerWallet": 100,
  "proxyConfiguration": {}
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "leaderboard",
    "maxResults": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("zhorex/hyperliquid-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "leaderboard",
    "maxResults": 100,
}

# Run the Actor and wait for it to finish
run = client.actor("zhorex/hyperliquid-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "leaderboard",
  "maxResults": 100
}' |
apify call zhorex/hyperliquid-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,zhorex/hyperliquid-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/gdmH3I28JnV1zy8MV/builds/WeJjT2paCgkGZwyfz/openapi.json