# Hyperliquid Whale Tracker — Top Perp Traders Live Positions (`gochujang/hyperliquid-whale-tracker`) Actor

Live positions and PnL for the top traders on Hyperliquid perp DEX. Filter by min position USD, fills lookback, PnL alert. Catch whale entries before the crowd. No API key. PPE $0.003/trader scanned.

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

## Pricing

$3.00 / 1,000 trader scanneds

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?

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

### Hyperliquid Whale Tracker — Live Perp Positions, PnL & Liquidation Monitor

> The leading **Hyperliquid whale tracker** for monitoring top **perpetual trading whales** — live open positions, unrealized PnL, leverage, and distance-to-liquidation across every tracked wallet. Build **large position monitors**, find copy-trade targets, and receive liquidation cascade warnings via Telegram. No API key required.

***

### What does Hyperliquid Whale Tracker do?

**Hyperliquid Whale Tracker** monitors any set of Hyperliquid wallet addresses and returns their complete perpetual trading positions in real time. For each tracked trader it delivers **open positions per coin** (direction, size, leverage, entry price, mark price), **unrealized PnL and return-on-equity**, **liquidation price and distance-to-liquidation percentage**, and a trader-level summary covering account value, total notional exposure, and recent fill history. The Actor ships with a curated seed list of publicly-known whale wallets, so you get actionable data in 30 seconds with no configuration. Because Hyperliquid publishes all position data on-chain, every field in this dataset is verifiably accurate — no opaque CEX APIs, no estimated figures.

***

### Why use Hyperliquid Whale Tracker?

**Crypto traders, algo funds, and risk desks** use on-chain perp data to front-run narrative shifts and avoid getting caught in cascades. Here is what this **large position monitor** unlocks:

- **Copy-trade signal generation** — See exactly what the top-performing wallets are long or short before they post on Twitter. Query every 5 minutes and feed the output into your execution layer.
- **Liquidation cascade early warning** — When whales are 1–3% from their liquidation price, forced unwinds are imminent. Pipe `distance_to_liq_pct < 3` rows into a Telegram alert to get notified before the market moves.
- **Crowded trade detection** — If 8 out of 10 tracked **perpetual trading whales** are net short BTC, that is a contrarian signal worth acting on. The trader summary makes this count trivial to compute.
- **Portfolio risk monitoring** — Risk teams use this Actor to track whether known whale wallets are building dangerous concentrations in any single asset.
- **Narrative tracking** — Which coins are whales rotating into this week? `recent_traded_coins` in the summary answers that automatically.

***

### How to use Hyperliquid Whale Tracker

1. Click **Try for free** on the Apify Store listing.
2. Optionally add wallet addresses to the `traders` array. Leave it empty to use the built-in seed list of known **Hyperliquid whale** wallets.
3. Set `minPositionUsd` to filter out small positions (default: $10,000).
4. Enable Telegram alerts by adding `telegramBotToken` and `telegramChatId`.
5. Click **Start** — results arrive in under 60 seconds.
6. For continuous monitoring, click **Schedule** and set the cadence (every 5–15 minutes recommended).

***

### Input

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `traders` | string\[] | seed list | Wallet addresses to monitor. Empty = bundled seed list of public whales |
| `minPositionUsd` | integer | `10000` | Skip positions below this notional value |
| `includeRecentFills` | boolean | `true` | Also fetch each trader's recent fill history |
| `fillsLookbackHours` | integer | `24` | How many hours back to pull fills |
| `sortBy` | string | `size_desc` | `size_desc`, `pnl_desc`, `pnl_asc`, `leverage_desc`, `distance_to_liq_asc` |
| `alertPnlUsd` | integer | `0` | Telegram alert when any position's absolute PnL exceeds this USD amount. `0` = disabled |
| `telegramBotToken` | string (secret) | — | Telegram bot token for alerts |
| `telegramChatId` | string | — | Chat ID to receive alerts |

**Example — Track specific whales, alert on large PnL:**

```json
{
  "traders": ["0xabc...", "0xdef..."],
  "minPositionUsd": 500000,
  "sortBy": "size_desc",
  "alertPnlUsd": 1000000,
  "telegramBotToken": "<token>",
  "telegramChatId": "<chat>"
}
```

**Example — Liquidation early-warning scan:**

```json
{"minPositionUsd": 100000, "sortBy": "distance_to_liq_asc"}
```

***

### Output

Two record types per trader are written to the dataset.

**Position rows** (`_type: "position"`) — one per open position:

```json
{
  "_type": "position",
  "trader": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
  "coin": "BTC",
  "direction": "long",
  "position_size": 12.5,
  "position_size_usd": 859500,
  "leverage": 20,
  "leverage_type": "cross",
  "entry_px": 67800,
  "mark_px": 68760,
  "unrealized_pnl_usd": 12000,
  "return_on_equity_pct": 27.94,
  "liquidation_px": 64850,
  "distance_to_liq_pct": 5.69,
  "margin_used_usd": 42975
}
```

**Trader summaries** (`_type: "trader_summary"`) — one per wallet:

```json
{
  "_type": "trader_summary",
  "trader": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
  "account_value_usd": 1245000,
  "total_position_notional": 6800000,
  "open_positions_count": 8,
  "long_count": 5,
  "short_count": 3,
  "total_unrealized_pnl_usd": 42500,
  "fills_count_recent": 23,
  "recent_realized_pnl_usd": 8400,
  "recent_volume_usd": 4200000,
  "recent_traded_coins": ["BTC", "ETH", "SOL", "HYPE"]
}
```

***

### Data fields

| Field | Description |
|-------|-------------|
| `_type` | Record type: `position` or `trader_summary` |
| `trader` | Wallet address of the **perpetual trading whale** |
| `coin` | Asset being traded (BTC, ETH, SOL, etc.) |
| `direction` | `long` or `short` |
| `position_size_usd` | Notional position value in USD |
| `leverage` | Leverage multiplier applied |
| `entry_px` | Average entry price |
| `mark_px` | Current mark price |
| `unrealized_pnl_usd` | Unrealized profit or loss in USD |
| `return_on_equity_pct` | PnL as percentage of margin used |
| `liquidation_px` | Price at which position is forcibly closed |
| `distance_to_liq_pct` | Distance from mark price to liquidation — **the primary cascade signal** |
| `account_value_usd` | Total account equity of the tracked trader |
| `total_position_notional` | Sum of all open position sizes |
| `recent_traded_coins` | Coins traded in the lookback window |

***

### Cost estimation

Pricing is **Pay-Per-Event at $0.003 per trader scanned**.

| Use case | Traders | Cost per run | Monthly cost (24 runs/day) |
|----------|---------|--------------|---------------------------|
| 10 whales (default seed) | 10 | **$0.03** | **$21.60** |
| 20 whales | 20 | **$0.06** | **$43.20** |
| 100 whales | 100 | **$0.30** | **$216** |

Tracking 10 **Hyperliquid whale** wallets every hour costs about $0.72/day.

***

### FAQ

**Does Hyperliquid require authentication to access position data?**
No. Hyperliquid's REST API at `api.hyperliquid.xyz/info` is fully public. All position, fill, and account data is on-chain and openly accessible — no API key, no wallet signature, no rate-limit configuration needed.

**Can I track wallets I found on Twitter?**
Yes — paste any Hyperliquid wallet address (0x...) into the `traders` array. The Actor fetches their positions directly from the public API.

**How do I use this for liquidation cascade alerts?**
Set `sortBy` to `distance_to_liq_asc` and add Telegram credentials. Then filter the results downstream for `distance_to_liq_pct < 3` — wallets within 3% of liquidation are the highest-risk cascade triggers.

> **Disclaimer:** This **Hyperliquid whale tracker** provides position data for informational and research purposes only. It does not constitute financial advice. Copy-trading carries significant risk; large position holders may reverse positions rapidly. Past PnL of tracked wallets does not predict future performance. Always manage your own risk independently.

***

### Live Sample Run

A real run executed on 2026-06-10:

| Field | Value |
|-------|-------|
| Items in dataset | 2004 |
| Dataset (JSON) | `https://api.apify.com/v2/datasets/b64yMifgEwo8Fq0Tr/items?clean=1&format=json` |
| Dataset (CSV) | `https://api.apify.com/v2/datasets/b64yMifgEwo8Fq0Tr/items?clean=1&format=csv` |
| Run summary (KVS) | `https://api.apify.com/v2/key-value-stores/Dmdz28nnGFaC9phCe/records/SUMMARY` |
| Run details | `https://api.apify.com/v2/actor-runs/KTgakr2IOwmvsjxcR` |

***

### Related Actors

- **[Long/Short + OI Aggregator](https://apify.com/gochujang/long-short-oi-aggregator)** — Aggregate cross-exchange positioning context alongside whale trades.
- **[Smart Money Wallet Tracker](https://apify.com/gochujang/smart-money-tracker)** — Spot-market whale activity across EVM and Solana.
- **[CEX Funding Rate Aggregator](https://apify.com/gochujang/cex-funding-aggregator)** — Funding rates and open interest across CEX perps.

### Feedback

If this Actor saves you time, a quick review helps others find it: [Leave a review on Apify Store](https://apify.com/gochujang/hyperliquid-whale-tracker#reviews)

# Actor input Schema

## `traders` (type: `array`):

Hyperliquid trader wallet addresses to monitor (0x... format). Empty = use the bundled seed list of known public whales.

## `vaults` (type: `array`):

Hyperliquid public vault addresses to track. Each emits a vault\_summary row (name/leader/APR/followers/TVL) plus all its positions. Empty + includeSeedVaults=true uses bundled seed.

## `includeSeedVaults` (type: `boolean`):

When vaults list is empty, use bundled seed list of well-known public HL vaults (currently HLP).

## `minPositionUsd` (type: `integer`):

Only return positions whose notional value exceeds this. 0 = include all.

## `includeRecentFills` (type: `boolean`):

Also fetch and emit each trader's recent fills (last 100). Adds detail but doubles API calls per trader.

## `fillsLookbackHours` (type: `integer`):

When recent fills enabled, only return fills from the last N hours.

## `minTradeSize` (type: `number`):

Only include fills (recent trades) above this USD notional value. 0 = include all.

## `tradeDirection` (type: `string`):

Filter fills by direction. 'long' = buys only (side B), 'short' = sells only (side A), 'all' = no filter.

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

Sort order for position rows.

## `alertThresholdUsd` (type: `number`):

Only return fills (trades) at or above this USD notional. Also used as the minimum for trade\_cluster labeling. Default 500000 = half-million minimum.

## `alertPnlUsd` (type: `integer`):

Alert when any tracked trader has a position with |unrealized PnL| above this. 0 = disabled.

## `telegramBotToken` (type: `string`):

Telegram bot token for alerts. Leave empty to disable.

## `telegramChatId` (type: `string`):

Chat ID to receive alerts.

## Actor input object example

```json
{
  "traders": [
    "0x31ca8395cf837de08b24da3f660e77761dfb974b",
    "0x0f7f9e6d18b07cee5d22a23fcf0816f4ea9c44a2"
  ],
  "vaults": [
    "0xdfc24b077bc1425ad1dea75bcb6f8158e10df303"
  ],
  "includeSeedVaults": true,
  "minPositionUsd": 10000,
  "includeRecentFills": true,
  "fillsLookbackHours": 24,
  "minTradeSize": 10000,
  "tradeDirection": "all",
  "sortBy": "size_desc",
  "alertThresholdUsd": 500000,
  "alertPnlUsd": 0,
  "telegramChatId": ""
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

## `summary` (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 = {
    "traders": [
        "0x31ca8395cf837de08b24da3f660e77761dfb974b",
        "0x0f7f9e6d18b07cee5d22a23fcf0816f4ea9c44a2"
    ],
    "vaults": [
        "0xdfc24b077bc1425ad1dea75bcb6f8158e10df303"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("gochujang/hyperliquid-whale-tracker").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 = {
    "traders": [
        "0x31ca8395cf837de08b24da3f660e77761dfb974b",
        "0x0f7f9e6d18b07cee5d22a23fcf0816f4ea9c44a2",
    ],
    "vaults": ["0xdfc24b077bc1425ad1dea75bcb6f8158e10df303"],
}

# Run the Actor and wait for it to finish
run = client.actor("gochujang/hyperliquid-whale-tracker").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 '{
  "traders": [
    "0x31ca8395cf837de08b24da3f660e77761dfb974b",
    "0x0f7f9e6d18b07cee5d22a23fcf0816f4ea9c44a2"
  ],
  "vaults": [
    "0xdfc24b077bc1425ad1dea75bcb6f8158e10df303"
  ]
}' |
apify call gochujang/hyperliquid-whale-tracker --silent --output-dataset

```

## MCP server setup

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

```

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/pxAPkyW8bLq0wL6xA/builds/bCG003jD3cfl03gzD/openapi.json