Recent large on-chain transfers plus an hourly volume histogram.

Populates the /on-chain/whales dashboard. Returns the newest `limit` transfers at or above `min_usd` plus an hourly rollup of USD volume for the trailing window. Rows include `fromLabel` / `toLabel` when the sender or recipient is a known exchange wallet. Empty feed returns `meta.unavailable = "no-data"` — not a 500.

Query parameters

All query parameters are optional unless marked required.

Response shape

Always wrapped in the standard envelope. Nullable fields are explicitly marked — treat missing numeric data as a real data-source gap, not as an error.

// Wrapped in the standard envelope:
// {
//   data: /* shape below */,
//   meta?: { total?: number; limit?: number; offset?: number; ... }
// }

{
  transfers: Array<{
    ts: number;
    chain: string;
    symbol: string;
    txHash: string;
    fromAddr: string;
    toAddr: string;
    fromLabel: string | null;
    toLabel: string | null;
    amountBase: number | null;
    amountUsd: number | null;
    source: string;
  }>;
  volume: Array<{ ts: number; volumeUsd: number }>;
}

Example

Copy the curl, replace YOUR_KEY with a real key from your dashboard, and run.

curl -sS "http://localhost:3000/api/v1/on-chain/whale-transfers?min_usd=10000000&limit=5" \
  -H "Authorization: Bearer cg_live_YOUR_KEY"

{
  "data": {
    "transfers": [
      {
        "ts": 1744835000000,
        "chain": "ETH",
        "symbol": "USDT",
        "txHash": "0xabc...",
        "fromAddr": "0x28c6...d60",
        "toAddr": "0x71660...d3",
        "fromLabel": "Binance 14 (hot)",
        "toLabel": "Coinbase 1",
        "amountBase": 25000000,
        "amountUsd": 25000000,
        "source": "whale_alert"
      }
    ],
    "volume": [
      { "ts": 1744833600000, "volumeUsd": 42000000 },
      { "ts": 1744837200000, "volumeUsd": 18500000 }
    ]
  },
  "meta": { "total": 1, "limit": 5, "minUsd": 10000000, "hours": 48 }
}

Notes

• Feed depends on an optional whale-alert ingestion worker.
• Gaps in `volume` are genuine — we don't zero-fill empty hours.