# Hyperliquid Whale Wallet Copier (`xtracto/hyperliquid-whales`) Actor Track top Hyperliquid perp-DEX whale traders and their live positions/fills via the fully-open no-auth JSON API. Rank the leaderboard by PnL/ROI/account value, or pull positions + recent trades for specific 0x wallets. - **URL**: https://apify.com/xtracto/hyperliquid-whales.md - **Developed by:** [Farhan Febrian Nauval](https://apify.com/xtracto) (community) - **Categories:** Integrations, Lead generation, Agents - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $2.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 Wallet Tracker Find the most profitable traders on the **Hyperliquid** perpetuals exchange — the "whales" — and follow their live positions and recent trades. This actor ranks every trader on the platform by profit and account size, then (optionally) pulls each wallet's open positions and trade history. A ready-made smart-money / copy-trading signal. ### Why use this actor - **No account, no API key, no login** — just press Run. - **Find the biggest winners** — rank every trader by profit (PnL), return (ROI), or account value, over a day, week, month, or all time. - **See what whales are holding right now** — open positions with size, entry price, leverage, and live unrealized profit for any wallet. - **Recent trade history** — the latest fills for a wallet (what they bought/sold, price, size, and realized profit). - **Smart-money signals** — spot which wallets are winning and mirror their moves. - **Clean, stable JSON** ready for spreadsheets, dashboards, databases, or alerting. Export to JSON, CSV, or Excel, and run it on a schedule. ### How it works 1. Pick a **mode**: `leaderboard` (rank the top traders) or `address` (look up specific wallets). 2. For the leaderboard, choose the time window (day / week / month / all time), what to rank by (profit / return / account value), a minimum account size, and how many to return. 3. For specific wallets, paste their addresses. 4. Press **Run**. Results stream into the dataset and can be exported to JSON, CSV, or Excel. No scrapers, servers, or blocks to manage — the actor handles retries for you. ### Modes | Mode | What it returns | Key input | | --- | --- | --- | | `leaderboard` *(default)* | The top-ranked traders for a chosen window and metric. | `window`, `sortBy`, `minAccountValue`, `maxItems` | | `address` | Live positions + recent trades for specific wallet addresses. | `addresses` | Turn on **Enrich with live positions** in leaderboard mode to attach each ranked whale's current open positions. ### Input **Leaderboard mode (default):** ```json { "mode": "leaderboard", "window": "allTime", "sortBy": "pnl", "minAccountValue": 1000000, "maxItems": 100, "enrichPositions": false } ```` **Address mode:** ```json { "mode": "address", "addresses": ["0x8def9f50456c6c4e37fa5d3d57f108ed23992dae"] } ``` | Field | Type | Description | | --- | --- | --- | | `mode` | string | `leaderboard` or `address`. | | `window` | string | Leaderboard: time window to rank on — `day`, `week`, `month`, or `allTime`. | | `sortBy` | string | Leaderboard: rank by `pnl` (profit), `roi` (return %), or `accountValue`. | | `minAccountValue` | integer | Leaderboard: drop wallets below this account size in USD (default keeps real whales). | | `maxItems` | integer | Leaderboard: how many top traders to return (`0` = all that pass the filter). | | `enrichPositions` | boolean | Leaderboard: attach each whale's live open positions (slower). | | `addresses` | array of strings | Address mode: wallet addresses to look up. | | `proxyConfiguration` | object | Optional. Not required — the data is public. | ### Output Every record carries a small header (`_input`, `_scrapedAt`, `_source`, `recordType`) plus the wallet data with the platform's original field names preserved. Convenience numeric fields (e.g. `accountValueNum`, `windowPnl`) are added for easy sorting. #### `WHALE_LEADERBOARD` — mode `leaderboard`, all-time profit ```json { "_input": "leaderboard window=allTime sortBy=pnl minAV=1e+07 top=3", "_source": "S1-leaderboard", "_scrapedAt": "2026-07-09T11:07:07Z", "recordType": "WHALE_LEADERBOARD", "rank": 1, "window": "allTime", "accountValueNum": 225006134.760987, "windowPnl": 445047889.570987, "windowRoi": 26412.572786162, "windowVlm": 15999.34, "ethAddress": "0x4ec8fe22a531a96c8a846aaf5cbef73202649a80", "accountValue": "225006134.7609870136", "windowPerformances": [ ["day", { "pnl": "0.0", "roi": "0.0", "vlm": "0.0" }], ["week", { "pnl": "0.0", "roi": "0.0", "vlm": "0.0" }], ["month", { "pnl": "0.0", "roi": "0.0", "vlm": "0.0" }], ["allTime", { "pnl": "445047889.5709869862", "roi": "26412.572786162", "vlm": "15999.34" }] ], "prize": 0, "displayName": null } ``` #### `WHALE_ADDRESS` — mode `address` (a wallet with $11.3M and 9 open positions) ```json { "_input": "0x8def9f50456c6c4e37fa5d3d57f108ed23992dae", "_source": "S1-address", "_scrapedAt": "2026-07-09T15:57:00Z", "recordType": "WHALE_ADDRESS", "address": "0x8def9f50456c6c4e37fa5d3d57f108ed23992dae", "accountValueNum": 11343690.714951, "numPositions": 9, "numFills": 2000, "clearinghouseState": { "marginSummary": { "accountValue": "11343690.7149509992", "totalNtlPos": "72748391.6416019946", "totalRawUsd": "-61404700.926651001", "totalMarginUsed": "11383784.3314909991" }, "withdrawable": "0.0", "assetPositions": [ { "type": "oneWay", "position": { "coin": "SOL", "szi": "169806.92", "leverage": { "type": "cross", "value": 17 }, "entryPx": "74.6913", "positionValue": "13177356.6058399994", "unrealizedPnl": "494245.12716", "returnOnEquity": "0.6624689199", "marginUsed": "775138.623872", "maxLeverage": 20 } } // ... 8 more positions (AAVE, WLD, NEAR, HYPE, XPL, ASTER, ZEC, XMR) ], "time": 1783612389491 }, "userFills": [ { "coin": "ZEC", "px": "446.5", "sz": "0.06", "side": "A", "time": 1782995681964, "startPosition": "49563.81", "dir": "Close Long", "closedPnl": "5.053344", "hash": "0x596d27cbbe3b301c5ae6043f0bba8d020d3200b1593e4eeefd35d31e7d3f0a06", "oid": 485730606780, "crossed": false, "fee": "0.003214", "feeToken": "USDC" } // ... up to ~2000 recent fills ] } ``` #### Key output fields | Field | Type | Description | | --- | --- | --- | | `recordType` | string | `WHALE_LEADERBOARD` or `WHALE_ADDRESS`. | | `rank` | integer | Leaderboard position (1 = best) for the chosen window and metric. | | `window` | string | The time window this ranking is for. | | `ethAddress` / `address` | string | The wallet address. | | `accountValueNum` / `accountValue` | number / string | Current account value in USD. | | `windowPnl` | number | Profit over the chosen window (USD). | | `windowRoi` | number | Return over the chosen window. | | `windowVlm` | number | Trading volume over the chosen window. | | `windowPerformances` | array | Profit / return / volume for every window (day, week, month, all time). | | `clearinghouseState.marginSummary` | object | Account value, total position value, and margin used. | | `clearinghouseState.assetPositions` | array | Open positions: `coin`, size (`szi`), `entryPx`, `leverage`, `unrealizedPnl`, `returnOnEquity`. | | `userFills` | array | Recent trades: `coin`, price (`px`), size (`sz`), direction (`dir`), realized profit (`closedPnl`), time. | | `numPositions` / `numFills` | integer | Count of open positions and returned trades. | On any failure the actor emits a `{_input, _source, _scrapedAt, _error, _errorDetail}` record instead of silently skipping. ### Notes & limits - A trader's leaderboard account value is a snapshot and may differ from the live figure — top-ranked wallets often hold staked or spot balances rather than open positions, so an enriched or address-mode lookup can show few or no open perpetual positions. Use `address` mode for the current live state. - `userFills` returns the most recent trades only (up to ~2000), not full lifetime history. - All data is public — no account or key needed. A proxy is optional. - Run on a daily schedule to track how the whale rankings change over time. # Actor input Schema ## `mode` (type: `string`): Which data to pull. 'leaderboard' streams the global whale leaderboard, filters and ranks it. 'address' fetches live positions + recent fills for specific wallet addresses. ## `window` (type: `string`): Leaderboard mode only. Which PnL/ROI/volume window to rank and report on: day, week, month, or all time. ## `sortBy` (type: `string`): Leaderboard mode only. Metric used to rank whales (descending) within the selected window: realized+unrealized PnL, ROI, or current account value. ## `minAccountValue` (type: `integer`): Leaderboard mode only. Drop wallets whose current account value (USD) is below this threshold before ranking. Default 1,000,000 keeps only real whales. ## `maxItems` (type: `integer`): Leaderboard mode only. Number of top-ranked whales to output (0 = all that pass the account-value filter). ## `enrichPositions` (type: `boolean`): Leaderboard mode only. If enabled, make one extra clearinghouseState call per whale to attach their current open positions and margin. Slower (one request per whale). ## `addresses` (type: `array`): Address mode only. List of 0x wallet addresses. For each, the actor emits one record with live clearinghouseState (positions/margin) and recent userFills (trades). ## `proxyConfiguration` (type: `object`): Optional. Hyperliquid's API is a public no-auth JSON API, so a proxy is not required; datacenter is fine. Residential is offered as a default for consistency / heavy runs. ## Actor input object example ```json { "mode": "leaderboard", "window": "allTime", "sortBy": "pnl", "minAccountValue": 1000000, "maxItems": 100, "enrichPositions": false, "addresses": [ "0x85ecf584f25db6f146718b86d493e33c5af72052" ], "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } ``` # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "mode": "leaderboard", "window": "allTime", "sortBy": "pnl", "addresses": [ "0x85ecf584f25db6f146718b86d493e33c5af72052" ] }; // Run the Actor and wait for it to finish const run = await client.actor("xtracto/hyperliquid-whales").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "mode": "leaderboard", "window": "allTime", "sortBy": "pnl", "addresses": ["0x85ecf584f25db6f146718b86d493e33c5af72052"], } # Run the Actor and wait for it to finish run = client.actor("xtracto/hyperliquid-whales").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).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", "window": "allTime", "sortBy": "pnl", "addresses": [ "0x85ecf584f25db6f146718b86d493e33c5af72052" ] }' | apify call xtracto/hyperliquid-whales --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=xtracto/hyperliquid-whales", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Hyperliquid Whale Wallet Copier", "description": "Track top Hyperliquid perp-DEX whale traders and their live positions/fills via the fully-open no-auth JSON API. Rank the leaderboard by PnL/ROI/account value, or pull positions + recent trades for specific 0x wallets.", "version": "0.1", "x-build-id": "oCaUaf2SChRMZMOCs" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/xtracto~hyperliquid-whales/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-xtracto-hyperliquid-whales", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/xtracto~hyperliquid-whales/runs": { "post": { "operationId": "runs-sync-xtracto-hyperliquid-whales", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/xtracto~hyperliquid-whales/run-sync": { "post": { "operationId": "run-sync-xtracto-hyperliquid-whales", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "mode": { "title": "Mode", "enum": [ "leaderboard", "address" ], "type": "string", "description": "Which data to pull. 'leaderboard' streams the global whale leaderboard, filters and ranks it. 'address' fetches live positions + recent fills for specific wallet addresses.", "default": "leaderboard" }, "window": { "title": "Performance window", "enum": [ "day", "week", "month", "allTime" ], "type": "string", "description": "Leaderboard mode only. Which PnL/ROI/volume window to rank and report on: day, week, month, or all time.", "default": "allTime" }, "sortBy": { "title": "Sort by", "enum": [ "pnl", "roi", "accountValue" ], "type": "string", "description": "Leaderboard mode only. Metric used to rank whales (descending) within the selected window: realized+unrealized PnL, ROI, or current account value.", "default": "pnl" }, "minAccountValue": { "title": "Minimum account value (USD)", "minimum": 0, "type": "integer", "description": "Leaderboard mode only. Drop wallets whose current account value (USD) is below this threshold before ranking. Default 1,000,000 keeps only real whales.", "default": 1000000 }, "maxItems": { "title": "Max whales to return", "minimum": 0, "type": "integer", "description": "Leaderboard mode only. Number of top-ranked whales to output (0 = all that pass the account-value filter).", "default": 100 }, "enrichPositions": { "title": "Enrich with live positions", "type": "boolean", "description": "Leaderboard mode only. If enabled, make one extra clearinghouseState call per whale to attach their current open positions and margin. Slower (one request per whale).", "default": false }, "addresses": { "title": "Wallet addresses", "type": "array", "description": "Address mode only. List of 0x wallet addresses. For each, the actor emits one record with live clearinghouseState (positions/margin) and recent userFills (trades).", "items": { "type": "string" } }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Optional. Hyperliquid's API is a public no-auth JSON API, so a proxy is not required; datacenter is fine. Residential is offered as a default for consistency / heavy runs.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```