Skip to main content
Glama

whale-insights

by com.cryptowhaleinsights
OverviewDiscussionsAdmin

whale_movements

Read-onlyIdempotent

Public whale movements archive — paginated 1-year history (no auth, MCP-compatible) — Returns a paginated archive of large whale on-chain movements recorded in the CryptoWhaleInsights signal-history database, covering up to 1 year (365 days). This is the public, unauthenticated counterpart to the authenticated /api/whale-history endpoint: it omits the explorerUrl field (Pro-only). AI agents can use this to analyse historical on-chain flow direction (inflow/outflow/transfer) across 14 chains without any credentials. Supported chains (chain filter values): BTC, ETH, SOL, BSC, BASE, ARB, POLYGON, TON, SUI, HYPE, TRX, SEI, INJ, APT. Supported directions (direction filter values): inflow, outflow, transfer. Keyword search: use ?q= to filter by token name, signal summary, or wallet label (case-insensitive, max 100 chars). Example: ?q=USDT returns only moves mentioning USDT; ?q=ETH+Whale+%237 returns moves by that wallet label. USD filter: use ?minUsd= to only return movements at or above that real USD value, e.g. ?

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
qNoKeyword search (case-insensitive, max 100 chars). Matches against token name, signal summary, or wallet label. Example: q=USDT returns moves mentioning USDT; q=ETH+Whale+%237 returns moves by that wallet label.
pageNoPage number (1-indexed, default 1).
chainNoFilter by chain. Valid values: BTC, ETH, SOL, BSC, BASE, ARB, POLYGON, TON, SUI, HYPE, TRX, SEI, INJ, APT. Default: all chains.
periodNoTime window: 7d | 30d | 90d | 365d (default 90d). Use 365d to retrieve up to 1 year of history.90d
directionNoFilter by flow direction: inflow | outflow | transfer. Default: all directions.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
pageNoCurrent page (1-indexed)
itemsNoWhale movement records in reverse-chronological order.
totalNoTotal matching records in the window
hasMoreNoWhether more pages are available
pageSizeNoFixed at 20 records per page
sinceDaysNoNumber of days of history returned
updatedAtNo
dataSourceNo
attributionNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "properties": {
+    "attribution": {
+      "$ref": "#/components/schemas/Attribution"
+    },
+    "dataSource": {
+      "type": "string"
+    },
+    "hasMore": {
+      "description": "Whether more pages are available",
+      "type": "boolean"
+    },
+    "items": {
+      "description": "Whale movement records in reverse-chronological order.",
+      "items": {
+        "properties": {
+          "amount": {
+            "description": "Transfer amount in native token units, e.g. '1200 ETH'. Parsed from signal summary; null if not available.",
+            "nullable": true,
+            "type": "string"
+          },
+          "chain": {
+            "description": "Chain identifier, e.g. 'ETH', 'BTC', 'SOL'. Convenience alias for tokens[0].",
+            "nullable": true,
+            "type": "string"
+          },
+          "createdAt": {
+            "format": "date-time",
+            "type": "string"
+          },
+          "direction": {
+            "description": "'inflow' | 'outflow' | 'transfer' | null (unknown)",
+            "nullable": true,
+            "type": "string"
+          },
+          "id": {
+            "description": "Unique signal row ID",
+            "type": "number"
+          },
+          "outcome": {
+            "description": "'win' | 'loss' | 'neutral' | null",
+            "nullable": true,
+            "type": "string"
+          },
+          "returnPct": {
+            "description": "Return in pct-points if resolved; null otherwise.",
+            "nullable": true,
+            "type": "number"
+          },
+          "timestamp": {
+            "description": "ISO-8601 timestamp when the movement was recorded. Alias for createdAt.",
+            "format": "date-time",
+            "type": "string"
+          },
+          "tokens": {
+            "description": "Chain identifier in tokens[0], e.g. ['ETH']",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "typeLabel": {
+            "description": "Always 'Whale Move' for this endpoint",
+            "type": "string"
+          },
+          "usdValue": {
+            "description": "Real USD value of the transfer, e.g. '$2.15M', computed from the resolved token price at signal time. Null if no price was resolvable.",
+            "nullable": true,
+            "type": "string"
+          },
+          "walletLabel": {
+            "description": "Human-readable wallet label, e.g. 'ETH Whale #3'",
+            "nullable": true,
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "page": {
+      "description": "Current page (1-indexed)",
+      "type": "number"
+    },
+    "pageSize": {
+      "description": "Fixed at 20 records per page",
+      "type": "number"
+    },
+    "sinceDays": {
+      "description": "Number of days of history returned",
+      "type": "number"
+    },
+    "total": {
+      "description": "Total matching records in the window",
+      "type": "number"
+    },
+    "updatedAt": {
+      "format": "date-time",
+      "type": "string"
+    }
+  },
+  "type": "object"
+}
  2. Added

TDQS

A4.1/5.0
Behavior5/5

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

Annotations already declare read-only, idempotent, and non-destructive behavior, and the description adds substantial context: no authentication, 1-year limit, pagination, omission of the Pro-only explorerUrl field, and filter semantics. This goes well beyond what the structured annotations already convey.

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

Conciseness3/5

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

The description is front-loaded with important qualifiers, but the first two sentences redundantly repeat 'public', 'paginated', and '1-year' territory. The final sentence cuts off mid-example ('e.g. ?'), making the end feel incomplete and less polished than the rest.

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

Completeness4/5

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

With rich annotations, a complete input schema, and an output schema, the description covers the essential operational context: authentication, time range, supported filters, and data omissions. The truncated USD-filter example and the undocumented minUsd parameter are minor gaps, but an agent can still invoke the tool reliably from the schema and supplied examples.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the description adds helpful examples for q, lists valid chain and direction values, and explains period choices. It also mentions a minUsd parameter that is not present in the input schema, which is a minor inconsistency but does not obscure the core parameter meanings.

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

Purpose4/5

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

The description clearly states the tool returns a paginated archive of large whale on-chain movements and identifies it as the public counterpart to an authenticated endpoint. It is specific about resource, scope, and capabilities, though it does not explicitly distinguish this from sibling tools like whale_movements_summary or recent_whales.

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

Usage Guidelines4/5

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

The description gives clear usage context: it is for historical on-chain flow analysis without credentials, supports 14 chains, and is MCP-compatible. It does not explicitly state when to choose this tool over a sibling or when not to use it, so it stops short of full guidance.

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

All whale-insights toolsInspect
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