Getting Started

High-Quality Signal Data for Manual, Agentic, and Algorithmic Trading

Unlock the potential of real-time blockchain analytics to drive your trading strategies and financial applications. Our APIs deliver comprehensive data on both small and large-scale transactions, providing the transparency needed to train AI models, develop custom alert systems, or track institutional movements.

• Integrate alerts into existing trade flows
• Power AI trading agents with real-time data
• Create entity specific alerts
• Monitor market liquidity changes
• Monitor token transaction frequency
• Track exchange in- and outflows

Our high-quality transaction data is leveraged by numerous top trading firms, including market leaders such as Jump Trading and Tower Research.

Custom Alert Guides

• How to Create Customizable Alerts with the WebSocket API & IFTTT
• On-Chain Analysis Using the Whale Tracker API Framework in Python
• Setting Up Alerts for Large On-Chain Transactions Using API-Based Monitoring

API Access

The Whale Tracker REST and WebSocket APIs require an API key which needs to be included in most requests. API keys are available to users with an active developer subscription. Enterprise trial keys can be requested via email.

Real-time Whale Alerts

Whale Tracker is best known for the alerts posted on various social media. Our WebSocket service offers similar functionality, providing real-time, customized whale alerts directly to your application. Users can filter notifications based on transaction value, cryptocurrency symbol, transaction type, and blockchain.

Real-time Transaction Data

Our Enterprise API is designed for users who want to consume a lot of transaction data. It provides a constant stream of millions of standardized and enriched transactions which can be used to map address in- and outflows, measure cross-network stablecoin flows, network usage, custom alerts and more. The API comes with a high rate limit and a 30-day transaction history.

Historical Alert Archive

We have created a free downloadable archive containing historical alerts posted on our social media channels such as X and Telegram. This dataset is an ideal resource for back-testing trading models, feeding AI models, conducting academic research, or analyzing the historical impact of major whale movements on market volatility.

Enterprise Sample Data

Enterprise sample data is available for download. The data, stored in separate JSON files, represents a day's worth of transactions for each blockchain. In addition, alert data is provided that includes a day's worth of alert data for transactions exceeding a minimum value of 10M USD.

By accessing this data, you can familiarize yourself with the API's output structure and format, aiding in your application development and testing process.

Terms and Conditions

Our Terms and Conditions apply to the usage of all APIs described in these docs.

Custom Alerts API

About

The Custom Alerts API delivers customizable transaction alerts across multiple blockchains and cryptocurrencies. This API enables users to track, analyze, and immediately respond to substantial transaction events customized to their individual needs and preferences.

The most significant feature of the API is its customizability. Users can define specific criteria for alerts, ensuring the receipt of only the most relevant transaction notifications. Alerts follow a generalized format regardless of the blockchain involved, so users can seamlessly compare and analyze transactions across multiple blockchains.

The alerts also include the from and to owners of transactions, giving more insight into each transfer. This mapping of addresses to owners enables us to exclude self-changes or internal transfers, enhancing alert relevance and accuracy.

Connecting

The API uses the base URL below and requires an API key for authentication:

wss://leviathan.whale-alert.io/ws?api_key=YOUR_API_KEY

Reconnecting

If the WebSocket connection drops, it's important to reconnect to prevent missing alerts. After reconnecting, resubscribe to any alerts you were previously subscribed to. If you resubscribe within 5 minutes using the same id in the subscription message, any missed alerts will be sent again, preventing loss of data.

Subscribing to Alerts

To subscribe to events, send a JSON object with the following fields:

Example subscription request:

{
  "type": "subscribe_alerts",
  "blockchains": ["ethereum"],
  "symbols": ["eth", "weth"],
  "tx_types": ["transfer"],
  "min_value_usd": 1000000
}

The WebSocket responds with a confirmation message:

{
  "id": "8QFdN74g",
  "type": "subscribed_alerts",
  "blockchains": ["ethereum"],
  "symbols": ["eth", "weth"],
  "tx_types": ["transfer"],
  "min_value_usd": 1000000
}

Alert Schema

Alerts are returned in a standardized format for all blockchains. This format includes all relevant transaction data and an easy-to-read summary.

An example Whale Alert returned by the WebSocket API:

{
  "channel_id": "xlLZ7tJq",
  "timestamp": 1687389431,
  "blockchain": "ethereum",
  "transaction_type": "transfer",
  "from": "unknown wallet",
  "to": "unknown wallet",
  "amounts": [
    { "symbol": "USDC", "amount": 20006425.31, "value_usd": 20008425.95 },
    { "symbol": "WETH", "amount": 5122.12,    "value_usd": 9702266.33  }
  ],
  "text": "20,006,425 USDC and 5,122 WETH transferred between unknown wallets…",
  "transaction": { "height": 17531252, "hash": "0x60b2…", "sub_transactions": [ … ] }
}

Code Examples

const ws = new WebSocket(
  "wss:
);
ws.onopen = () => ws.send(JSON.stringify({
  type: "subscribe_alerts",
  blockchains: ["ethereum"],
  symbols: ["eth"],
  min_value_usd: 10000
}));
ws.onmessage = (msg) => {
  const data = JSON.parse(msg.data);
  console.log(data.text || msg.data);
};

c, _, err := websocket.Dial(ctx,
  "wss:
if err != nil { log.Fatal(err) }
defer c.Close(websocket.StatusNormalClosure, "")

sub := AlertSubscriptionJSON{
  Type:        "subscribe_alerts",
  Blockchains: []string{"ethereum"},
  Symbols:     []string{"eth"},
  MinValueUSD: 10000,
}
wsjson.Write(ctx, c, &sub)

for {
  var msg AlertJSON
  wsjson.Read(ctx, c, &msg)
  fmt.Println(msg.Text)
}

import asyncio, json, websockets

async def connect():
    url = f"wss:
    sub = {
        "type": "subscribe_alerts",
        "blockchains": ["ethereum"],
        "symbols": ["eth"],
        "min_value_usd": 10000,
    }
    async with websockets.connect(url) as ws:
        await ws.send(json.dumps(sub))
        async for msg in ws:
            print(msg)

asyncio.run(connect())

Subscribing to Social Media Posts

To track our social media posts you can subscribe to the socials events. Once an alert is posted, the WebSocket will respond with the post's text and direct links.

{ "type": "subscribe_socials" }

Confirmation:

{ "id": "8QFdN74g", "type": "subscribed_socials" }

Socials Schema

{
  "channel_id": "xlLZ7tJq",
  "timestamp": 1692724660,
  "blockchain": "tron",
  "text": "1,200,000,000 USDT (1,200,398,999 USD) burned at Tether Treasury",
  "urls": [
    "https://twitter.com/whale_alert/status/1694036126422450598",
    "https://t.me/whale_alert_io/72364"
  ]
}

Rate Limits

The WebSocket API allows a maximum of 2 concurrent connections per API key. There is also a cap of 100 alerts received per hour.

Tutorial

A tutorial that demonstrates how to integrate the WebSocket API with IFTTT is available, along with example code on GitHub.

Errors

Errors are returned in the form of:

{ "error": "ERROR_MESSAGE" }

Enterprise REST API

About

Our REST API provides a full overview of blockchain transactions without limitations, meaning that all analyzed value transactions are available through the various endpoints (max history depending on subscription). The API provides enriched, easy-to-process data on millions of transactions per day including price data and attribution.

Rate Limiting

Requests are limited to a maximum of 1000 calls per minute.

API Key

The REST API is only accessible with an API key, added as a parameter to every request:

?api_key=YOUR_API_KEY   or   &api_key=YOUR_API_KEY

Base URL

https://leviathan.whale-alert.io

Attribution

Address attribution refers to the process of associating specific owners with their corresponding addresses. The depth of attribution and the number of entities returned are dependent on the selected subscription plan.

Transaction Schema

All transactions returned by the API use the same JSON schema regardless of blockchain protocol. Transactions can contain multiple currencies and/or transaction types, which are split by the API into sub-transactions.

Transaction Example

{
  "height": 17616182,
  "index_in_block": 6,
  "timestamp": 1688420591,
  "hash": "0xa3cf00e868300cbc846390bc5c5e69875abd895f747ad42876d4f4fb4ebbb0bc",
  "fee": "0.00238487557",
  "fee_symbol": "ETH",
  "fee_symbol_price": 1957.0,
  "sub_transactions": [
    {
      "symbol": "ETH",
      "transaction_type": "transfer",
      "inputs":  [ { "amount": "0.00238", "address": "0xffec…", "owner": "nexo" } ],
      "outputs": [ { "amount": "0",       "address": "0xdac1…" } ]
    },
    {
      "symbol": "USDT",
      "transaction_type": "transfer",
      "inputs":  [ { "amount": "20000", "address": "0xffec…", "owner": "nexo" } ],
      "outputs": [ { "amount": "20000", "address": "0xf8e0…" } ]
    }
  ]
}

Endpoints

The API is accessible through various endpoints. Responses are in JSON format. All endpoints share the same rate limits.

Status

Returns a full overview of the supported blockchains and currencies available per blockchain.

GET https://leviathan.whale-alert.io/status

[
  { "name": "bitcoin",  "symbols": ["BTC", "USDT", "EURT"] },
  { "name": "dogecoin", "symbols": ["DOGE"] },
  { "name": "tron",     "symbols": ["USDD","TRX","BTT","USDT","USDC","TUSD","USDJ","WBTC"] }
]

Transaction

Returns a specific transaction for a blockchain.

GET https://leviathan.whale-alert.io/bitcoin/transaction/d090f5…?api_key=API_KEY

Transactions

Returns all transactions for a blockchain since the specified start height. The response includes a next URL for the next call; use it to ensure all transactions are retrieved without duplicates.

GET https://leviathan.whale-alert.io/bitcoin/transactions?limit=100&start_height=768801&api_key=YOUR_API_KEY

Block

Returns timestamp, hash and transactions for a block at a specific height.

GET https://leviathan.whale-alert.io/bitcoin/block/771103?api_key=API_KEY

Address Transactions

Returns the transactions for an address for the last 30 days.