# Hyperliquid Top Traders Leaderboard (`gochujang/hyperliquid-leaderboard`) Actor

Fetch the Hyperliquid on-chain perps leaderboard: top traders by PnL, ROI, or volume across day/week/month windows. Returns address, account size, P\&L, ROI, and trading volume. All data is fully on-chain and free. No API key required.

- **URL**: https://apify.com/gochujang/hyperliquid-leaderboard.md
- **Developed by:** [Hojun Lee](https://apify.com/gochujang) (community)
- **Categories:** Business
- **Stats:** 3 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

### What does Hyperliquid Leaderboard do?

**Hyperliquid Leaderboard** tracks the **top traders on Hyperliquid** — the fully on-chain perpetuals DEX — and returns structured data on their PnL, ROI, trading volume, and account size across 24h, 7d, 30d, and all-time windows. Every row includes the trader's Hyperliquid explorer URL for direct verification. No API key, no wallet, no setup.

Hyperliquid publishes all **perpetual trading rankings** on-chain, making every leaderboard position publicly verifiable. This actor fetches the official stats API and returns clean, filterable JSON — ideal for copy-trade research, market sentiment signals, and automated whale monitoring.

***

### Why use Hyperliquid Leaderboard?

1. **Copy-trade target discovery** — Rank traders by 30d ROI to find consistently skilled performers (not just well-capitalized ones) and analyze their patterns.
2. **Market sentiment signals** — Aggregate the directional bias of the top 50 traders to gauge whether smart perp money is net long or short at a given moment.
3. **Whale account monitoring** — Track how specific high-performing addresses rank week-over-week and correlate rank shifts with price action.
4. **Automated leaderboard archiving** — Schedule daily runs to build a historical record of **top traders Hyperliquid** rankings for backtesting or strategy research.
5. **Competitive intelligence** — Identify which traders are dominating by volume vs. by ROI, revealing different strategic styles (high-frequency vs. position trading).

***

### How to use Hyperliquid Leaderboard

1. Open the actor on Apify Store and click **Try for free**.
2. Set `timeWindow` (`day`, `week`, `month`, or `allTime`) and `sortBy` (`pnl`, `roi`, or `volume`).
3. Optionally set `minAccountValue` to filter out small accounts and focus on whales.
4. Set `limit` (default 50, max 200) to control how many traders to return.
5. Enable `includePositionState` to enrich each row with live open position count and unrealized PnL.
6. Click **Start** — results are ready in seconds.

***

### Input

| Parameter | Type | Default | Description |
|---|---|---|---|
| `timeWindow` | string | `"day"` | Ranking period: `day`, `week`, `month`, `allTime` |
| `sortBy` | string | `"pnl"` | Sort by: `pnl` (absolute USD), `roi` (percentage), `volume` |
| `limit` | integer | `50` | Max traders to return (5–200) |
| `minAccountValue` | number | `0` | Filter: only return traders with account value >= this USD amount |
| `includePositionState` | boolean | `false` | Enrich each trader with live open position count and unrealized PnL |

***

### Output

```json
{
  "rank": 1,
  "address": "0x85ecf584f25db6f146718b86d493e33c5af72052",
  "account_value_usd": 62529963.78,
  "pnl_usd": 95023.81,
  "roi_pct": 0.1761,
  "volume_usd": 1554167493.28,
  "time_window": "day",
  "day":   { "pnl_usd": 95023.81, "roi_pct": 0.1761, "volume_usd": 1554167493.28 },
  "week":  { "pnl_usd": -813721.88, "roi_pct": -0.9074, "volume_usd": 8929123456.0 },
  "month": { "pnl_usd": 4219041.53, "roi_pct": 4.8123, "volume_usd": 39812345678.0 },
  "hl_url": "https://app.hyperliquid.xyz/explorer/address/0x85ecf..."
}
```

***

### Data fields

| Field | Type | Description |
|---|---|---|
| `rank` | integer | Leaderboard position for the selected window and sort |
| `address` | string | Trader's on-chain wallet address |
| `account_value_usd` | float | Total account value in USD |
| `pnl_usd` | float | Realized PnL for the selected time window |
| `roi_pct` | float | Return on investment as a decimal (0.1761 = 17.61%) |
| `volume_usd` | float | Total trading volume for the selected time window |
| `time_window` | string | Window used for primary sort (`day`, `week`, `month`, `allTime`) |
| `day` / `week` / `month` | object | Stats for each window regardless of primary sort |
| `hl_url` | string | Direct Hyperliquid explorer link for this address |

***

### Cost estimation

**Pay-Per-Event: $0.002 per trader returned.**

| Use case | Traders | Estimated cost |
|---|---|---|
| Daily top-50 snapshot | 50 | $0.10 |
| Top 100 weekly leaderboard | 100 | $0.20 |
| Top 20 with position state | 20 | $0.04 |
| Daily archiving (top 200) | 200 | $0.40 |

***

### FAQ

**Where does the data come from?**
All data is fetched directly from the official Hyperliquid stats API — the same data shown on [Hyperliquid's public leaderboard](https://app.hyperliquid.xyz/leaderboard). This is not scraped; it is a fully on-chain, free public endpoint.

**What is the difference between PnL and ROI rankings on Hyperliquid?**
PnL (absolute USD) favors large accounts — a whale who made $1M is ranked above a smaller trader who made $100K even if the smaller trader had a higher percentage return. ROI ranking rewards capital efficiency and is better for identifying skilled traders rather than well-capitalized ones.

**Can I use this for automated copy-trading?**
This actor provides the data layer — leaderboard rankings with addresses and explorer links. Execution (opening positions) requires connecting to Hyperliquid's trading API separately. This actor is for research and data collection only.

> **Disclaimer**: Leaderboard rankings reflect historical performance and do not guarantee future results. **Perpetual trading rankings** on Hyperliquid change daily. Past top-trader performance is not indicative of future profitability. This actor is for informational and research purposes only — not financial advice.

***

### Related actors

- [Hyperliquid Whale Tracker](https://apify.com/gochujang/hyperliquid-whale-tracker) — Large position opens and closes on Hyperliquid perps
- [Hyperliquid Funding Tracker](https://apify.com/gochujang/hyperliquid-funding-tracker) — Funding rate history across all Hyperliquid markets
- [Smart Money Wallet Tracker](https://apify.com/gochujang/smart-money-tracker) — On-chain spot wallet activity for Hyperliquid traders

### Feedback

[Leave a review on Apify Store](https://apify.com/gochujang/hyperliquid-leaderboard#reviews)

# Actor input Schema

## `timeWindow` (type: `string`):

Leaderboard time period to rank traders over.

## `sortBy` (type: `string`):

Ranking criterion.

## `limit` (type: `integer`):

Maximum number of traders to return (5-200).

## `minAccountValue` (type: `number`):

Only return traders with account value above this threshold. Set 0 for no filter.

## `includePositionState` (type: `boolean`):

Enrich each trader with their current open position count and unrealized PnL. Adds API calls per trader, slower for large limits.

## Actor input object example

```json
{
  "timeWindow": "day",
  "sortBy": "pnl",
  "limit": 50,
  "minAccountValue": 0,
  "includePositionState": false
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("gochujang/hyperliquid-leaderboard").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("gochujang/hyperliquid-leaderboard").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 '{}' |
apify call gochujang/hyperliquid-leaderboard --silent --output-dataset

```

## MCP server setup

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

```

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/79Jru4KUnfzjLm21p/builds/ez36oAz4EeSqQvw4L/openapi.json