# Hyperliquid Whale Tracker: Scored Perp Trades, Wallet PnL (`mrlarryjohnson/hyperliquid-whale-tracker`) Actor

Track Hyperliquid whales: large perp trades scored 0-100 with both counterparty addresses + tx hash, funding/OI market snapshots, and full wallet position/PnL reports. Dedup billing — the same trade is never charged twice.

- **URL**: https://apify.com/mrlarryjohnson/hyperliquid-whale-tracker.md
- **Developed by:** [Larry Johnson](https://apify.com/mrlarryjohnson) (community)
- **Categories:** AI, Developer tools, Automation
- **Stats:** 3 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 whale trades

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 — scored trades, funding extremes, wallet PnL

Most "whale alert" feeds tell you a big trade happened. This one tells you **how much
attention it deserves** — every large Hyperliquid perp trade is scored 0–100 on the
patterns that correlate with informed flow, and every record carries **both
counterparty addresses** plus the tx hash (when Hyperliquid provides one — see FAQ),
so you can verify records on-chain yourself. No API keys, no wallet connection,
pay per result.

### What it does

#### 🐋 Whale feed (`whale-feed`)

Each run grabs the most recent trades per coin (instant bootstrap), then **live-streams
the actual trade tape over websocket for your `listenSeconds` window** (default 90s,
max 300s). Honest coverage model: you see everything that prints during your listen
window — schedule runs back-to-back for near-continuous coverage. Every qualifying
trade is scored:

| Signal | Why it matters |
|---|---|
| Notional size ($10k → $1M+) | Base attention weight |
| **Single print ≥1% of the coin's open interest** | One trade moving a whole market |
| **Contrarian vs crowded funding** | Buying when shorts pay / selling when longs pay — fading the herd |
| Thin market (<$5M daily volume) | Big fish in a small pond |

Every row: coin, side, price, size, USD, score, **buyer address, seller address,
tx hash**, trade id, plus the coin's funding rate, open interest, and 24h volume
for context. Cross-run dedup means a scheduled run never returns (or bills) the
same trade twice.

#### 📊 Market snapshot (`market-snapshot`)

Per-coin table: mark price, 24h change, 24h volume, open interest, hourly funding,
**annualized funding APR**, and a `crowdedFunding` flag (≥25% APR — somebody's
paying dearly to hold that side). The fastest way to find squeeze candidates and
funding-farm setups.

#### 👛 Wallet tracker (`wallet-tracker`)

For any address: account value, every open position (side, size, notional, entry,
**liquidation price**, leverage, unrealized PnL) and recent fills with closed PnL.
Vet a "top trader" before copying them, or watch a known whale's book in one call.

### Quick start

```json
{ "mode": "whale-feed", "minTradeUsd": 50000, "topCoins": 25 }
```

Schedule it back-to-back (e.g. every 5 min with `listenSeconds: 290`) + a webhook to
Slack/Discord/Telegram for a near-continuous whale-alert service. Cross-run dedup
(insertion-ordered, oldest-evicted) means overlapping windows never bill the same
trade twice.

```json
{ "mode": "wallet-tracker", "wallets": ["0x..."] }
```

### Honest data, honestly billed

Built by the maker of [Polymarket Whale Tracker Pro](https://apify.com/mrlarryjohnson/polymarket-whale-tracker-pro),
[Polymarket Top Traders](https://apify.com/mrlarryjohnson/polymarket-top-traders) and the
[Polymarket MCP Server](https://apify.com/mrlarryjohnson/polymarket-mcp-server), with the same rules:

- A rate-limited upstream call **raises** — it is never passed off as "no data"
- Error records are pushed for transparency but **never billed**
- Cross-run dedup happens **before** billing — the same trade id is never charged twice
- Data comes from Hyperliquid's public info API in real time; nothing is cached or stale

### FAQ

**Which trades appear in the feed?** Everything at or above your `minTradeUsd`
that prints during the run: an instant bootstrap of each coin's most recent trades,
plus the full live tape for your `listenSeconds` window. Coverage equals your listen
window — back-to-back scheduled runs approximate a continuous feed, and dedup
guarantees overlapping runs only ever bill a trade once.

**Are the addresses real?** Yes — Hyperliquid's API returns both sides of every
fill. Note: Hyperliquid reports some internalized fills with a zero hash; we report
those as `hash: null` rather than pretending — the trade id, timestamp and both
addresses remain the verification keys.

**Does it work for spot?** v0.2 covers perps (where the whales are). Spot support
is on the roadmap — open an issue if you need it.

### More tools by this maker

| Tool | What it does |
|---|---|
| [Polymarket Whale Tracker Pro](https://apify.com/mrlarryjohnson/polymarket-whale-tracker-pro) | Insider-scored large trades, top holders, wallet P\&L |
| [Polymarket Top Traders](https://apify.com/mrlarryjohnson/polymarket-top-traders) | Leaderboards with cross-window consistency + verified P\&L |
| [Polymarket MCP Server](https://apify.com/mrlarryjohnson/polymarket-mcp-server) | The same live data as native AI-agent tools (MCP) |
| [Hyperliquid Whale Tracker](https://apify.com/mrlarryjohnson/hyperliquid-whale-tracker) | Scored perp trades w/ counterparty addresses, funding/OI, wallet PnL |
| [Web Search MCP Server](https://apify.com/mrlarryjohnson/web-search-mcp-server) | Multi-engine web/news search + instant answers for AI agents |

Same engineering rules everywhere: fail-loud data integrity, dedup-before-billing, errors never billed.

# Actor input Schema

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

whale-feed = large perp trades across the most active coins, scored 0-100, with both counterparty addresses + tx hash. market-snapshot = per-coin funding/open-interest/volume table with crowded-funding flags. wallet-tracker = open positions, leverage, liquidation prices, PnL and recent fills for given addresses.

## `minTradeUsd` (type: `integer`):

whale-feed: only surface trades at or above this notional dollar size. Default 10000 keeps the default run reliably non-empty; raise it for true whale-only feeds.

## `topCoins` (type: `integer`):

whale-feed / market-snapshot: how many of the highest-volume coins to include (whale-feed max 60, snapshot max 230).

## `coins` (type: `array`):

Optional list of coin symbols (e.g. BTC, ETH, SOL) to always include regardless of volume rank. In market-snapshot mode, providing this scans ONLY these coins.

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

whale-feed: cap on returned trades, largest first (max 1000).

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

wallet-tracker: Hyperliquid addresses to profile (max 50 per run).

## `fillsLimit` (type: `integer`):

wallet-tracker: how many recent fills to include per wallet.

## `dedupAcrossRuns` (type: `boolean`):

whale-feed: remember seen trade ids in a named store so the same trade is never returned (or billed) twice across scheduled runs.

## `listenSeconds` (type: `integer`):

whale-feed: after the instant REST bootstrap, live-stream the trade tape over websocket for this many seconds (0 = bootstrap only, max 300). Your coverage equals this window — schedule runs back-to-back for near-continuous coverage.

## `stateKey` (type: `string`):

whale-feed: name of the named key-value store holding seen trade ids. Give each parallel schedule its own name so they don't suppress each other's records.

## Actor input object example

```json
{
  "mode": "whale-feed",
  "minTradeUsd": 10000,
  "topCoins": 25,
  "coins": [],
  "maxResults": 200,
  "wallets": [],
  "fillsLimit": 20,
  "dedupAcrossRuns": true,
  "listenSeconds": 90,
  "stateKey": "hl-whale-tracker-state"
}
```

# Actor output Schema

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

All records produced by this run as JSON items.

# 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("mrlarryjohnson/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 = {}

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

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,mrlarryjohnson/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/TrlgS0BMkhXLxcNSd/builds/q6lfICor5VJfDrDNE/openapi.json