---
title: "Public whale movements archive — paginated 1-year history (no auth, MCP-compatible)"
method: GET
path: "/api/public/whale-movements"
---

# Public whale movements archive — paginated 1-year history (no auth, MCP-compatible)

`GET /api/public/whale-movements`

## Request

- Base URL: `https://cryptowhaleinsights.com`
- URL: `https://cryptowhaleinsights.com/api/public/whale-movements`
- Auth: none declared

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. ?minUsd=1000000 for $1M+ moves. Movements with no resolvable USD value (usdValue: null) are excluded when minUsd is set. Pagination: page (1-indexed, default 1), pageSize fixed at 20. period filter: 7d | 30d | 90d | 365d (default 90d). Use 365d to retrieve up to 1 year of history. Response: { items[], total, page, pageSize, hasMore, sinceDays, dataSource, updatedAt }. Each item: id, tokens (chain in [0]), typeLabel, outcome, returnPct, direction ('inflow'|'outflow'|'transfer'|null), walletLabel, createdAt. No authentication required. 60 requests/min rate limit.

## Query parameters

- `page` integer
- `chain` 'BTC' | 'ETH' | 'SOL' | 'BSC' | 'BASE' | 'ARB' | 'POLYGON' | 'TON' | 'SUI' | 'HYPE' | 'TRX' | 'SEI' | 'INJ' | 'APT'
- `direction` 'inflow' | 'outflow' | 'transfer'
- `period` '7d' | '30d' | '90d' | '365d'
- `q` string

## Response `200`

Paginated public whale movements (up to 1 year / 365-day window, no auth).

- object
  - `items` object[]: Whale movement records in reverse-chronological order.
    - `id` number: Unique signal row ID
    - `chain` string, nullable: Chain identifier, e.g. 'ETH', 'BTC', 'SOL'. Convenience alias for tokens[0].
    - `tokens` string[]: Chain identifier in tokens[0], e.g. ['ETH']
    - `typeLabel` string: Always 'Whale Move' for this endpoint
    - `outcome` string, nullable: 'win' | 'loss' | 'neutral' | null
    - `returnPct` number, nullable: Return in pct-points if resolved; null otherwise.
    - `direction` string, nullable: 'inflow' | 'outflow' | 'transfer' | null (unknown)
    - `amount` string, nullable: Transfer amount in native token units, e.g. '1200 ETH'. Parsed from signal summary; null if not available.
    - `usdValue` string, nullable: 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.
    - `walletLabel` string, nullable: Human-readable wallet label, e.g. 'ETH Whale #3'
    - `timestamp` string, date-time: ISO-8601 timestamp when the movement was recorded. Alias for createdAt.
    - `createdAt` string, date-time
  - `total` number: Total matching records in the window
  - `page` number: Current page (1-indexed)
  - `pageSize` number: Fixed at 20 records per page
  - `hasMore` boolean: Whether more pages are available
  - `sinceDays` number: Number of days of history returned
  - `dataSource` string
  - `updatedAt` string, date-time
  - `attribution` Attribution: Source attribution returned on every response. Cite CryptoWhaleInsights when using this data.
    - `source` string
    - `url` string, uri
    - `poweredBy` string
    - `usagePolicy` string, uri

## Other responses

- `429`: Rate limit exceeded (120 req/min per endpoint per IP). Includes a Retry-After header. See https://cryptowhaleinsights.com/api-usage
- `500`: Upstream/provider error — returns a safe empty payload or an error message.

---

[API](https://skmtc.dev/cryptowhaleinsights/apis/cryptowhaleinsights-public-api.md) · [All operations](https://skmtc.dev/cryptowhaleinsights/apis/cryptowhaleinsights-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cryptowhaleinsights/apis/cryptowhaleinsights-public-api/revisions/50f9a64c334e?raw)