API Documentation

WhaleVault REST API — track whale movements, alerts, and market sentiment.

Authentication

Authenticate by including your API key in the X-API-Key header, or use a Bearer token from a session cookie.

curl https://whalevault.io/api/v1/transactions \ -H "X-API-Key: YOUR_API_KEY"

Retrieve your API key from Dashboard → API Keys. Keep it secret — it grants access to your account.

Rate Limits

Plan	Requests / Day	Requests / Minute
Free	100	10
Pro	5,000	100
Enterprise	100,000	Unlimited

Endpoints

GET/api/v1/transactions

Auth required

Fetch recent whale transactions with pagination and filtering.

Parameters

pagenumberoptionalPage number (default: 1)

limitnumberoptionalItems per page, max 100 (default: 20)

min_amountnumberoptionalMinimum USD value (default: 100000)

Example Response

{
  "transactions": [
    {
      "id": "clx1...",
      "hash": "0xabc...",
      "chain": "ethereum",
      "fromAddress": "0xd8dA...",
      "toAddress": "0x28C6...",
      "token": "USDC",
      "amount": 2400000,
      "usdValue": 2400000,
      "timestamp": "2024-06-01T12:00:00Z",
      "type": "transfer"
    }
  ],
  "total": 150,
  "page": 1,
  "limit": 20
}

GET/api/v1/transactions/:chain

Fetch transactions filtered to a specific chain.

Parameters

chainstringrequiredChain name (path param)

pagenumberoptionalPage number

limitnumberoptionalResults per page

Example Response

{ "transactions": [...], "total": 42, "page": 1, "limit": 20, "chain": "solana" }

GET/api/v1/wallets/:address/activity

Get full activity history for a whale wallet address.

Parameters

addressstringrequiredWallet address (path param)

chainstringoptionalChain context (default: ethereum)

limitnumberoptionalMax transactions to return

Example Response

{
  "wallet": {
    "address": "0xd8dA...",
    "chain": "ethereum",
    "totalVolumeUsd": 14200000,
    "transactionCount": 48,
    "lastActive": "2024-06-01T10:30:00Z",
    "topTokens": [...],
    "recentTransactions": [...]
  }
}

GET/api/v1/analytics/top-tokens

Get top tokens by whale trading volume.

Parameters

periodstringoptionalTime window: 24h | 7d | 30d (default: 24h)

Example Response

{
  "tokens": [
    { "token": "ETH", "chain": "ethereum", "usdVolume": 820000000, "change24h": 4.2, "sentiment": "bullish" }
  ],
  "period": "24h"
}

GET/api/v1/analytics/sentiment

Get current market sentiment score driven by whale activity.

GET/api/v1/alerts

Auth required

List all alerts for the authenticated user.

POST/api/v1/alerts

Auth required

Create a new alert.

Parameters

typestringrequiredAlert type: large_transaction | wallet_activity | token_accumulation | price_impact | new_whale_wallet

configobjectrequiredAlert configuration (thresholdUsd, walletAddress, chain, token, etc.)

deliveryMethodstring[]optionalDelivery channels: email | telegram | webhook | in_app

Example Response

{ "alert": { "id": "clx2...", "type": "large_transaction", "active": true, "createdAt": "..." } }

DELETE/api/v1/alerts/:id

Auth required

Delete a specific alert by ID.

Parameters

idstringrequiredAlert ID (path param)

Example Response

{ "message": "Alert deleted." }

Try It

Test any GET endpoint directly from your browser (no auth required for public endpoints).