# Hyperliquid Liquidation Radar: Scored Liquidation Feed (`mrlarryjohnson/hyperliquid-liquidation-radar`) Actor A scored, deduplicated feed of forced-liquidation events on Hyperliquid perps: coin, side liquidated, total notional, mark price, liquidated wallet, and a cascade flag, with open-interest and funding context. Aggregated per liquidation (not per fill) and billed only for new events. No API key. - **URL**: https://apify.com/mrlarryjohnson/hyperliquid-liquidation-radar.md - **Developed by:** [Larry Johnson](https://apify.com/mrlarryjohnson) (community) - **Categories:** AI, Agents, Automation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $10.00 / 1,000 liquidation events 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/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 Liquidation Radar A scored, deduplicated feed of forced liquidations on Hyperliquid perps. For each liquidation you get the coin, which side blew up (long or short), the total notional, the average fill price, the exchange mark price, the liquidated wallet, a cascade flag, and the coin's open interest and funding context. This is the data perp traders look at right after price itself, because a wave of liquidations is where the violent moves come from. ### What makes this one honest Two things most liquidation tools get wrong: 1. **One liquidation is not one fill.** When a position is force closed it usually executes as many separate fills against many maker orders. A single liquidated BTC short can be a dozen fills sharing the same instant. This actor aggregates every fill of one liquidation into a single event with the true total notional, so you are not looking at a single blowup shattered into twelve confusing rows, and you are not billed twelve times for it. 2. **Coverage is stated plainly.** Hyperliquid does not publish a global liquidation endpoint. The only place a liquidation appears is as a field on a per wallet fill. So this actor seeds a wallet set from recent trades and the live trade tape, finds who got liquidated, then reads each liquidated wallet's own fills to reconstruct the full event. Coverage equals the wallets seen in the window, and it compounds because the actor remembers the liquidator wallets it finds and polls them first next run. This is a near real time enriched feed, not a guaranteed capture of every single liquidation on the venue. We would rather tell you that than pretend. ### Input ```json { "topCoins": 30, "listenSeconds": 60, "minNotionalUsd": 1000, "lookbackMinutes": 60 } ```` - `topCoins`: how many of the highest volume perps to seed from. Default 30. - `listenSeconds`: seconds to live stream the trade tape to widen the active wallet set (0 = REST only). Default 60. - `minNotionalUsd`: only return liquidations at or above this total size. Default 1000. - `lookbackMinutes`: only return liquidations from the last N minutes. Default 60. This is what keeps the feed recent instead of dumping old history. For continuous coverage, schedule the run every few minutes with a window slightly larger than the gap between runs. - `maxSeedWallets`, `maxEnrich`, `maxResults`: caps that trade coverage for run time. Defaults are sensible. - `dedupAcrossRuns`: remember events (and liquidator wallets) so the same liquidation is never returned or billed twice and coverage compounds. Default true. ### Output One record per liquidation event: ```json { "coin": "BTC", "liquidatedSide": "SHORT", "notionalUsd": 184320.5, "totalSize": 1.62, "avgPx": 113778.1, "markPx": 113800.0, "fillCount": 12, "method": "market", "score": 80, "cascade": true, "cascadeCount": 4, "pctOfOpenInterest": 0.41, "coinOpenInterestUsd": 44900000, "coinFundingAprPct": 11.2, "liquidatedUser": "0x66815db1...", "eventTimeMs": 1781473250300 } ``` - `liquidatedSide` is the side that was force closed (a long liquidation is a forced sell, a short liquidation is a forced buy). - `score` (0 to 100) weights notional size, share of the coin's open interest, whether it is part of a cascade, and whether the coin is thinly traded. - `cascade` is true when several liquidations of the same coin and side land inside a short window, which is the signature of a chain reaction. - `liquidatedUser` is the actual on chain wallet, so you can verify any event yourself. ### Billing You pay per new liquidation event. The dedup key is the atomic `(coin, liquidatedUser, time)`, so the same liquidation is never billed twice across scheduled runs, even though it is discovered from several wallets at once. Error rows are always delivered and never billed. If our data sources are unreachable the run fails loudly rather than returning an empty result that looks like "no liquidations." ### Use it from an AI agent The same feed runs as a tool an AI agent can call to watch for liquidation pressure on a coin before it acts. Pair it with the Hyperliquid Whale Tracker for the full picture of large flow plus forced flow. # Actor input Schema ## `topCoins` (type: `integer`): How many of the highest-volume Hyperliquid perps to seed the scan from (recent trades + live tape). More coins = wider coverage, slower run. ## `coins` (type: `array`): Optional coin symbols (e.g. BTC, ETH, SOL) to always watch regardless of volume rank. ## `listenSeconds` (type: `integer`): After the instant REST seed, live-stream the trade tape over websocket for this many seconds to widen the active-wallet set (0 = REST seed only, max 300). Schedule runs back-to-back for near-continuous coverage. ## `minNotionalUsd` (type: `integer`): Only surface liquidation events at or above this total notional. Default 1000. ## `lookbackMinutes` (type: `integer`): Only surface liquidations from the last N minutes. Keeps this a near-real-time feed (not a backfill of old liquidations) and bounds the first run. Default 60. For continuous coverage, schedule the run every few minutes with a window a bit longer than the gap. ## `maxEnrich` (type: `integer`): Cap on how many discovered liquidations get a full authoritative size lookup (largest first). Bounds run time. Default 200. ## `maxSeedWallets` (type: `integer`): Cap on how many wallets get a userFills poll while discovering liquidations. Higher = better coverage, longer run. Persisted liquidator wallets are always polled first. ## `maxResults` (type: `integer`): Cap on returned events per run, largest notional first. ## `dedupAcrossRuns` (type: `boolean`): Remember liquidation events (and discovered liquidator wallets) in a named store so the same liquidation is never returned or billed twice across scheduled runs, and coverage compounds over time. Leave this ON. Turning it OFF means a liquidation still inside the recency window will be returned and billed again on every scheduled run. ## `stateKey` (type: `string`): Name of the named key-value store holding seen liquidation events + known liquidator wallets. Give each parallel schedule its own name so they don't suppress each other. ## Actor input object example ```json { "topCoins": 30, "coins": [], "listenSeconds": 60, "minNotionalUsd": 1000, "lookbackMinutes": 60, "maxEnrich": 200, "maxSeedWallets": 120, "maxResults": 500, "dedupAcrossRuns": true, "stateKey": "hl-liquidation-radar-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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("mrlarryjohnson/hyperliquid-liquidation-radar").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 = {} # Run the Actor and wait for it to finish run = client.actor("mrlarryjohnson/hyperliquid-liquidation-radar").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 '{}' | apify call mrlarryjohnson/hyperliquid-liquidation-radar --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=mrlarryjohnson/hyperliquid-liquidation-radar", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Hyperliquid Liquidation Radar: Scored Liquidation Feed", "description": "A scored, deduplicated feed of forced-liquidation events on Hyperliquid perps: coin, side liquidated, total notional, mark price, liquidated wallet, and a cascade flag, with open-interest and funding context. Aggregated per liquidation (not per fill) and billed only for new events. No API key.", "version": "0.1", "x-build-id": "1YwhhWPb0oq5ocikd" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/mrlarryjohnson~hyperliquid-liquidation-radar/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-mrlarryjohnson-hyperliquid-liquidation-radar", "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/mrlarryjohnson~hyperliquid-liquidation-radar/runs": { "post": { "operationId": "runs-sync-mrlarryjohnson-hyperliquid-liquidation-radar", "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/mrlarryjohnson~hyperliquid-liquidation-radar/run-sync": { "post": { "operationId": "run-sync-mrlarryjohnson-hyperliquid-liquidation-radar", "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": { "topCoins": { "title": "Top coins by volume to watch", "minimum": 1, "maximum": 100, "type": "integer", "description": "How many of the highest-volume Hyperliquid perps to seed the scan from (recent trades + live tape). More coins = wider coverage, slower run.", "default": 30 }, "coins": { "title": "Always-include coins", "type": "array", "description": "Optional coin symbols (e.g. BTC, ETH, SOL) to always watch regardless of volume rank.", "default": [], "items": { "type": "string" } }, "listenSeconds": { "title": "Live tape listen window (seconds)", "minimum": 0, "maximum": 300, "type": "integer", "description": "After the instant REST seed, live-stream the trade tape over websocket for this many seconds to widen the active-wallet set (0 = REST seed only, max 300). Schedule runs back-to-back for near-continuous coverage.", "default": 60 }, "minNotionalUsd": { "title": "Minimum liquidation size (USD)", "minimum": 0, "type": "integer", "description": "Only surface liquidation events at or above this total notional. Default 1000.", "default": 1000 }, "lookbackMinutes": { "title": "Recency window (minutes)", "minimum": 1, "maximum": 1440, "type": "integer", "description": "Only surface liquidations from the last N minutes. Keeps this a near-real-time feed (not a backfill of old liquidations) and bounds the first run. Default 60. For continuous coverage, schedule the run every few minutes with a window a bit longer than the gap.", "default": 60 }, "maxEnrich": { "title": "Max liquidations enriched per run", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Cap on how many discovered liquidations get a full authoritative size lookup (largest first). Bounds run time. Default 200.", "default": 200 }, "maxSeedWallets": { "title": "Max wallets polled per run", "minimum": 1, "maximum": 600, "type": "integer", "description": "Cap on how many wallets get a userFills poll while discovering liquidations. Higher = better coverage, longer run. Persisted liquidator wallets are always polled first.", "default": 120 }, "maxResults": { "title": "Max liquidation events returned", "minimum": 1, "maximum": 2000, "type": "integer", "description": "Cap on returned events per run, largest notional first.", "default": 500 }, "dedupAcrossRuns": { "title": "Dedup across runs", "type": "boolean", "description": "Remember liquidation events (and discovered liquidator wallets) in a named store so the same liquidation is never returned or billed twice across scheduled runs, and coverage compounds over time. Leave this ON. Turning it OFF means a liquidation still inside the recency window will be returned and billed again on every scheduled run.", "default": true }, "stateKey": { "title": "Dedup state name", "type": "string", "description": "Name of the named key-value store holding seen liquidation events + known liquidator wallets. Give each parallel schedule its own name so they don't suppress each other.", "default": "hl-liquidation-radar-state" } } }, "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 } } } } } } } } } } ```