# Hyperliquid Leaderboard Scraper (`parseforge/hyperliquid-leaderboard-scraper`) Actor Track the Hyperliquid trader leaderboard by time window. Each trader returns the address, account value, PnL, ROI, volume, position count, top position, win rate, days active, and rank. Useful for DeFi research, copy trading ideas, or monitoring perpetual futures performance. - **URL**: https://apify.com/parseforge/hyperliquid-leaderboard-scraper.md - **Developed by:** [ParseForge](https://apify.com/parseforge) (community) - **Categories:** Developer tools, Automation, Other - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $7.69 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. 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 ![ParseForge Banner](https://github.com/ParseForge/apify-assets/blob/ad35ccc13ddd068b9d6cba33f323962e39aed5b2/banner.jpg?raw=true) ## ๐Ÿ† Hyperliquid Leaderboard Scraper > ๐Ÿš€ **Export Hyperliquid perpetual trading records in seconds. Pull the full product or entity catalog into clean structured rows ready for analytics and downstream tooling.** > ๐Ÿ•’ **Last updated** 2026-06-05 ยท **๐Ÿ“Š 12 fields** per record ยท Hyperliquid coverage ยท Real-time The Hyperliquid Leaderboard Scraper turns the public [Hyperliquid](https://app.hyperliquid.xyz/leaderboard) catalog into a clean structured feed. It calls the public storefront or platform API, normalizes the response, and surfaces one record per item. Coverage spans the live perpetual trading surface of Hyperliquid. Every record carries the most important attributes upstream exposes, normalized into a flat row. | ๐ŸŽฏ Target Audience | ๐Ÿ’ก Primary Use Cases | |---|---| | ๐Ÿ“Š Data analysts | Mirror Hyperliquid data into structured rows | | ๐Ÿข Pricing teams | Track listings across runs | | ๐Ÿค– ML engineers | Build training sets from perpetual trading catalogs | | ๐Ÿ“ฐ Journalists | Verify perpetual trading facts in seconds | | ๐ŸŽ“ Researchers | Build longitudinal datasets of perpetual trading | | ๐Ÿ‘ฉโ€๐Ÿ’ป Developers | Pipe Hyperliquid listings into your own warehouse | ### ๐Ÿ“‹ What the Hyperliquid Leaderboard Scraper does - Calls the public Hyperliquid endpoint that powers the live page. - Normalizes the response into one flat row per entity with stable field names. - Applies optional client-side filters described in the input schema. - Surfaces upstream rate-limit or error notes as a clean `error` record. - Pushes structured rows into your dataset, ready for export in any of the supported download formats. > ๐Ÿ’ก **Why it matters** Direct access to the live Hyperliquid catalog without writing scraping code. ### ๐ŸŽฌ Full Demo _๐Ÿšง Coming soon._ ### โš™๏ธ Input
FieldTypeRequiredDescription
searchQuerystringNoOptional text filter applied to the wallet address. Leave empty for the full leaderboard.
windowenumNoLeaderboard time window.
maxItemsintegerNoFree plan caps at 10 items. Paid plans go up to 1,000,000. Prefill 10.
**Example 1** ```json { "searchQuery": "milk", "maxItems": 25 } ```` **Example 2** ```json { "maxItems": 50, "window": "day" } ``` > โš ๏ธ **Good to Know** The upstream endpoint may rate-limit aggressive use. Schedule recurring runs at a sane cadence and keep `maxItems` reasonable. ### ๐Ÿ“Š Output Each record is a flat object. The `error` field is always last. | Field | Type | Description | |---|---|---| | ๐Ÿ‘› Address `address` | string | address value from the upstream record. | | ๐Ÿ’ผ Account Value `account_value` | number | account\_value value from the upstream record. | | ๐Ÿ“ˆ PnL `pnl` | number | pnl value from the upstream record. | | ๐Ÿ“Š ROI `roi` | number | roi value from the upstream record. | | ๐Ÿ’ฑ Volume `volume` | number | volume value from the upstream record. | | ๐Ÿ”ข Positions `position_count` | number | position\_count value from the upstream record. | | ๐Ÿฅ‡ Top Position `top_position` | string | top\_position value from the upstream record. | | ๐ŸŽฏ Win Rate `win_rate` | number | win\_rate value from the upstream record. | | ๐Ÿ“… Days Active `days_active` | number | days\_active value from the upstream record. | | ๐Ÿ† Rank `rank` | number | rank value from the upstream record. | | ๐Ÿ•’ `scrapedAt` | string | When this row was collected. | | โŒ `error` | string | Populated only on upstream errors. | **Sample record** ```json { "address": "0xabc123...", "account_value": 2540000, "pnl": 180000, "roi": 7.5, "volume": 45000000, "position_count": 4, "top_position": "BTC", "win_rate": 0.62, "days_active": 184, "rank": 1, "scrapedAt": "2026-06-05T07:00:00.000Z", "error": null } ``` ### โœจ Why choose this Actor | ๐Ÿ†“ | Works without an API key for public endpoints. | | ๐Ÿงน | Flat schema with stable field names. | | ๐Ÿ”ข | Numeric fields cast to real numbers. | | ๐Ÿ›Ÿ | Upstream errors surface as a clean `error` record. | | ๐Ÿ”Œ | Plays well with Apify schedules and webhooks. | | ๐Ÿ’พ | One push to the dataset, multiple download formats. | ### ๐Ÿ“ˆ How it compares to alternatives | Approach | Setup time | Field normalization | Rate-limit handling | |---|---|---|---| | Roll your own fetch | 30 minutes plus | manual | manual | | Headless browser | hours | partial | partial | | **This Actor** | 5 seconds | full | yes | ### ๐Ÿš€ How to use 1. Click **Try for free**. 2. Configure the input fields described above. 3. Click **Start**. 4. Download your dataset in your preferred export format. ### ๐Ÿ’ผ Business use cases **๐Ÿ“Š Market intelligence.** Monitor Hyperliquid perpetual trading listings across time to spot trends. **๐Ÿ’ผ Operations.** Mirror upstream catalog into internal tooling for inventory or compliance. **๐Ÿ“ฐ Reporting.** Pull verifiable facts from the live Hyperliquid surface for stories and briefs. **๐Ÿค– Machine learning.** Build clean training sets from perpetual trading data without writing scrapers. ### ๐Ÿ”Œ Automating Hyperliquid Leaderboard Scraper - **Make and Zapier** trigger the actor and route results into Airtable, Google Sheets, or Slack. - **Cron** native Apify scheduler runs the actor on any cadence you want. - **Webhooks** POST run results straight to your warehouse loader. - **Slack and Discord** push a daily digest into your team channel. ### ๐ŸŒŸ Beyond business use cases **๐ŸŽ“ Education.** Teach data analysis with fresh perpetual trading datasets. **๐Ÿงช Personal research.** Track your own watchlist over time. **๐Ÿค Non-profit and open data.** Build public dashboards for civic interest projects. **๐Ÿงฐ Tinkering.** Pipe Hyperliquid data into a side project or bot. ### ๐Ÿค– Ask an AI assistant about this scraper Paste this README into ChatGPT, Claude, or any AI assistant. The schema, examples, and field list above contain everything an LLM needs to map your workflow to actor inputs. ### โ“ Frequently Asked Questions **โ“ Do I need an API key?** No. The endpoint used is public. **โ“ How fresh is the data?** Every run hits the live endpoint. **โ“ Can I filter results?** Yes via the input schema fields. **โ“ Can I limit the result count?** Yes via `maxItems`. Free plan caps at 10. **โ“ Will the schema change?** Stable core fields. Optional fields may be added if upstream exposes new metadata. **โ“ Is this scraping or API?** Public API normalization. **โ“ Does it handle rate limits?** Yes. Upstream rate-limit notes surface as an `error` record. **โ“ Does it follow pagination?** Yes when `maxItems` exceeds one page worth of results. **โ“ Can I schedule runs?** Yes via Apify scheduler, Make, Zapier, or cron. **โ“ Can I integrate with my warehouse?** Yes. Apify pipes datasets to BigQuery, Snowflake, Postgres, or any webhook target. ### ๐Ÿ”Œ Integrate with any app Apify ships native integrations with Make, Zapier, Slack, Discord, Google Drive, Google Sheets, Gmail, Airbyte, Keboola, Telegram, GitHub, and any REST or webhook endpoint. Trigger from a calendar event, a form submission, or a cron job. Pipe results into BigQuery, Snowflake, or Postgres. ### ๐Ÿ”— Recommended Actors | Actor | What it does | |---|---| | [ParseForge Alpha Vantage Scraper](https://apify.com/parseforge/alpha-vantage-public-scraper) | Stocks, FX, crypto, and indicators. | | [ParseForge OurAirports Scraper](https://apify.com/parseforge/ourairports-scraper) | Global airport database. | | [ParseForge Yahoo Finance Scraper](https://apify.com/parseforge) | Equities, funds, indices. | | [ParseForge NBA Stats Scraper](https://apify.com/parseforge/nba-stats-scraper) | Player and team stats. | > ๐Ÿ’ก **Pro Tip** browse the complete [ParseForge collection](https://apify.com/parseforge) for 900+ production-grade scrapers across business intelligence, real estate, e-commerce, sports, finance, and public records. *** **Disclaimer** This actor scrapes only publicly available data. ParseForge is not affiliated with, endorsed by, or sponsored by any of the third-party services referenced. Users are responsible for complying with the target site's terms of service and applicable law. [Create a free account w/ $5 credit](https://console.apify.com/sign-up?fpr=vmoqkp). # Actor input Schema ## `searchQuery` (type: `string`): Optional text filter applied to the wallet address. Leave empty for the full leaderboard. ## `maxItems` (type: `integer`): Free users are limited to 10 items (preview). Paid users can request up to 1,000,000. ## `window` (type: `string`): Leaderboard time window. ## Actor input object example ```json { "maxItems": 10 } ``` # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "maxItems": 10 }; // Run the Actor and wait for it to finish const run = await client.actor("parseforge/hyperliquid-leaderboard-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "maxItems": 10 } # Run the Actor and wait for it to finish run = client.actor("parseforge/hyperliquid-leaderboard-scraper").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 '{ "maxItems": 10 }' | apify call parseforge/hyperliquid-leaderboard-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=parseforge/hyperliquid-leaderboard-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Hyperliquid Leaderboard Scraper", "description": "Track the Hyperliquid trader leaderboard by time window. Each trader returns the address, account value, PnL, ROI, volume, position count, top position, win rate, days active, and rank. Useful for DeFi research, copy trading ideas, or monitoring perpetual futures performance.", "version": "0.1", "x-build-id": "YaAGmbrDdEMsMNKEv" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/parseforge~hyperliquid-leaderboard-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-parseforge-hyperliquid-leaderboard-scraper", "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/parseforge~hyperliquid-leaderboard-scraper/runs": { "post": { "operationId": "runs-sync-parseforge-hyperliquid-leaderboard-scraper", "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/parseforge~hyperliquid-leaderboard-scraper/run-sync": { "post": { "operationId": "run-sync-parseforge-hyperliquid-leaderboard-scraper", "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": { "searchQuery": { "title": "Address filter", "type": "string", "description": "Optional text filter applied to the wallet address. Leave empty for the full leaderboard." }, "maxItems": { "title": "Max Items", "minimum": 1, "maximum": 1000000, "type": "integer", "description": "Free users are limited to 10 items (preview). Paid users can request up to 1,000,000." }, "window": { "title": "Time window", "enum": [ "day", "week", "month", "allTime" ], "type": "string", "description": "Leaderboard time window." } } }, "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 } } } } } } } } } } ```