whale-data

Hyperliquid named whale fills

hl_whales

Read-onlyIdempotent

Recent whale-sized Hyperliquid fills WITH THE WALLET ADDRESS attached. Hyperliquid is the one venue whose public feed names the account on both sides of a fill, so every row here is followable to a live book. Use this to see which named accounts just traded a coin ("which HL whales just bought BTC"). For one wallet's full book and leverage use hl_wallet; for the ranked tracked-account board and net bias use hl_board; for the proven-profitable cohort use smart_money. Keyless. Descriptive market data only.

Input Schema

TableJSON Schema

Name	Required	Description
`coin`	No	Filter to one coin, for example PEPE. Matched against the parsed symbol as well as the raw market name, so the 1000-unit markets (kPEPE, kSHIB, kBONK) are found under PEPE, SHIB and BONK. One symbol, not a list. Omit for every coin.
`pair`	No	Alias for coin.
`limit`	No	Max fills returned. Defaults to 50, hard ceiling 200 for everyone and no plan raises it.
`since_ms`	No	Polling cursor: only rows newer than this Unix-ms timestamp, applied before the row cap. Pass back the next_since_ms from the previous answer so a timer never re-reads the same rows.

Output Schema

TableJSON Schema

Name	Required	Description
`coin`	No	The coin filter applied, or null for every coin.
`note`	No	One line saying what the numbers cover, or why there are none. Read it before reporting any zero as a market reading.
`count`	No	How many rows this reply carries.
`venue`	No	Always Hyperliquid.
`capped`	No	Present only when an argument was cut down to a ceiling. Absent means nothing was clamped, so a smaller number than you asked for is the data and not a limit.
`trades`	No	The fills, each carrying the wallet on both sides, the coin, the direction, the size and the time. Pass a wallet to hl_wallet for that account live positions.
`available`	No	False when this lane could not answer: a producer is dark, the pair sits outside this plan, or the argument named something we do not carry. Absent or true means the numbers are a real reading, not a guess.
`access_note`	No	What this connection could not return and what lifts it. Always pass this on to the user: it is the only place that information appears.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 5, 2026

addedInput schema / properties / since_ms

Added value: +{
+  "description": "Polling cursor: only rows newer than this Unix-ms timestamp, applied before the row cap. Pass back the next_since_ms from the previous answer so a timer never re-reads the same rows.",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}

Changed3 schema fields changedAug 13, 2026

addedInput schema / properties / coin / description

Added value: +"Filter to one coin, for example PEPE. Matched against the parsed symbol as well as the raw market name, so the 1000-unit markets (kPEPE, kSHIB, kBONK) are found under PEPE, SHIB and BONK. One symbol, not a list. Omit for every coin."

addedInput schema / properties / limit / description

Added value: +"Max fills returned. Defaults to 50, hard ceiling 200 for everyone and no plan raises it."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "properties": {
+    "access_note": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "What this connection could not return and what lifts it. Always pass this on to the user: it is the only place that information appears."
+    },
+    "available": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "False when this lane could not answer: a producer is dark, the pair sits outside this plan, or the argument named something we do not carry. Absent or true means the numbers are a real reading, not a guess."
+    },
+    "capped": {
+      "anyOf": [
+        {
+          "additionalProperties": false,
+          "properties": {
+            "applied": {
+              "description": "The value actually used.",
+              "type": "number"
+            },
+            "argument": {
+              "description": "Which argument was cut down, for example limit or hours.",
+              "type": "string"
+            },
+            "by": {
+              "description": "Why it was cut: keyless for the free ceiling, plan_max for a paid ceiling, tool_max for a ceiling no plan raises.",
+              "type": "string"
+            },
+            "max": {
+              "description": "The ceiling that applied.",
+              "type": "number"
+            },
+            "requested": {
+              "description": "The value the caller asked for.",
+              "type": "number"
+            }
+          },
+          "required": [
+            "argument",
+            "requested",
+            "applied",
+            "max",
+            "by"
+          ],
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Present only when an argument was cut down to a ceiling. Absent means nothing was clamped, so a smaller number than you asked for is the data and not a limit."
+    },
+    "coin": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The coin filter applied, or null for every coin."
+    },
+    "count": {
+      "anyOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "How many rows this reply carries."
+    },
+    "note": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "One line saying what the numbers cover, or why there are none. Read it before reporting any zero as a market reading."
+    },
+    "trades": {
+      "anyOf": [
+        {
+          "items": {},
+          "type": "array"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The fills, each carrying the wallet on both sides, the coin, the direction, the size and the time. Pass a wallet to hl_wallet for that account live positions."
+    },
+    "venue": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Always Hyperliquid."
+    }
+  },
+  "type": "object"
+}

First observedAug 13, 2026

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, and non-destructive, so the description doesn't need to restate safety. It adds behavior beyond annotations: every fill row is 'followable to a live book', the data is 'descriptive market data only', and the venue uniquely names both sides of fills. It could add more about time window or rate limits, but the schema and output schema cover much of that.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core capability, then gives a use example, sibling routing, and access note in compact sentences. No filler or tautology; each sentence adds decision-relevant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-required-parameter read query with fully covered schema and an output schema present, the description covers the tool's purpose, differentiation, use cases, and access posture. Nothing necessary for an agent to select and invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the input schema already documents coin, pair, limit, and since_ms with domain-specific detail (e.g., kPEPE matching, polling cursor semantics). The description itself adds no parameter-level meaning beyond the general use case, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise verb+resource statement: 'Recent whale-sized Hyperliquid fills WITH THE WALLET ADDRESS attached.' It gives an explicit query example ('which HL whales just bought BTC') and differentiates itself from sibling tools by naming the venue's unique named-feed property.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It tells the agent exactly when to use this tool ('Use this to see which named accounts just traded a coin') and routes to specific alternatives: hl_wallet for per-wallet book/leverage, hl_board for ranked board/net bias, and smart_money for the profitable cohort. 'Keyless' also clarifies access expectations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All whale-data tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?