Introduction

The Whale Alert REST and WebSocket APIs provides blockchain transaction data without the need for blockchain specific client software or knowledge about the workings of each. Currently supported are Bitcoin, Ethereum, Algorand, Bitcoin Cash, Dogecoin, Litecoin, Polygon, Solana and Tron. More blockchains are added regularly. The blockchain data offered through the API includes transfers, mints and burns and other value relevant types. All transactions are delivered in the a standardized format, regardless of the blockchain protocol. This makes tracking multiple blockchains and currencies across chains a simple task. The API transaction data is updated live, meaning that almost as soon as a block is finalized on a blockchain, the analyzed transaction data with updated attribution data will be available through the API's.

Enriched Data

The transaction data that is returned is enriched with additional information like currency unit price at the time of the transaction, attribution of addresses to known entities and address attributes like deposit or hot wallets types.

Disclaimer: transaction analysis is a continuous process and newly available data may affect the attribution of existing addresses, meaning that address attribution may change over time as more information comes available.

API Access

The Whale Alert REST and WebSocket APIs require an API key which needs to be included in every request. API keys are available to users with an active subscription. Please visit our PRICING page for more information on the available subscriptions and obtaining an API key. Trial keys can be requested via our contact page.

Real-time Whale Alerts

Whale Alert 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. It's a powerful tool for tracking essential transactions and asset movements in the dynamic world of cryptocurrencies, much like staying up-to-date with our Twitter feed.

Use Cases

The transaction data provided by the Whale Alert APIs is used to analyze both historical and real-time data in order to predict price changes, uncover market trends and manage asset risk by tracking addresses containing large asset quantities and asset transaction volume. The data provided is especially powerful if combined with historical analytics to help uncover patterns in blockchain usage and its correlation to price changes, but can also be used to track large transactions and mints and burns which have a proven impact on price volatility. If you would like to discuss how our data can be used to solve your specific blockchain related problem, feel free to contact us.

Completeness

Built with a dedication to accuracy and completeness, our API delivers comprehensive data down to the Satoshi and Wei or equivalent smallest unit, without rounding errors. It's an often overlooked fact that on some blockchains certain value transfers are completely invisible. Typically, these are staking or mining rewards that are silently added to the balances of the involved addresses. To ensure that our API includes all data that have an effect on balances, we add extra transactions or sub-transactions where needed.

Moreover, some cryptocurrency transfers, obscured by intricate smart contracts, are not visible via official clients or third-party explorers or require significant effort to decode. This might occur with complex swap transactions or transactions involving decentralized exchanges (DEXs). To address this, we also include these as sub-transactions that are easy to read.

In essence, our API is designed to offer a complete picture of the blockchain landscape, maximizing transparency for all users. Through this approach, we aim to equip our users with the most accurate and comprehensive data, thereby enabling them to gain detailed insights into the blockchain activity.

Tutorial with IFTTT

For users interested in building custom alerts, we have prepared a tutorial that demonstrates how to integrate our WebSocket API with IFTTT (If This, Then That). This guide walks you through the process of setting up real-time whale alerts directly to your device or application, allowing you even more control and customization over the transaction data you receive. You can find the tutorial here.

Historical Data

The Whale Alert APIs provide limited historical data due to the size of the data sets. Complete historical data including attribution and price data can be purchased separately and is delivered in csv or json format. For more information on historical data pricing, please visit our Pricing page.

Sample Data

Sample data is available for download at whale-alert.io/sample-data/. This 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 our API's output structure and format, aiding in your application development and testing process. For any queries, feel free to contact our support team.

Terms and Conditions

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

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 and easy to process data on millions of transactions per day including price data and attribution. Whale Alert has developed a number of advanced checks to ensure the provided data is correct and complete. Additional tokens or blockchains can be requested by contacting us.

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 which needs be provided by Whale Alert. The API key needs to be added as a parameter to every request as shown below. See Getting Started on how to obtain a key.

 Copy?api_key=YOUR_API_KEY   or   &api_key=YOUR_API_KEY

Base URL

All endpoints can be accessed through the base URL below.

 Copyhttps://leviathan.whale-alert.io

Attribution

Address attribution refers to our process of associating specific owners with their corresponding addresses. The depth of this attribution and the number of entities returned are dependent on the selected subscription plan. For instance, if you opt for our Enterprise plan, the top 25 identified entities are provided. See our plans page for more details.

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. Each sub-transactions can have its own addresses, owners amounts and symbol. For instance, a Bitcoin Tether transaction includes both a #BTC and #USDT transfer (OMNI layer), which are both added as sub-transactions in the API (example below).

 Copy{
	"height": 17616182,
	"index_in_block": 6,
	"timestamp": 1688420591,
	"hash": "0xa3cf00e868300cbc846390bc5c5e69875abd895f747ad42876d4f4fb4ebbb0bc",
	"fee": "0.00238487557",
	"fee_symbol": "ETH",
	"fee_symbol_price": 1957.0039893171593,
	"sub_transactions": [
		{
			"symbol": "ETH",
			"unit_price_usd": 1957.0039893171593,
			"transaction_type": "transfer",
			"inputs": [
				{
					"amount": "0.00238487557",
					"address": "0xffec0067f5a79cff07527f63d83dd5462ccf8ba4",
					"balance": "225.162872285186500265",
					"owner": "nexo",
					"owner_type": "bank"
				}
			],
			"outputs": [
				{
					"amount": "0",
					"address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
					"balance": "0.000000000000000001"
				}
			]
		},
		{
			"symbol": "USDT",
			"unit_price_usd": 1.000015,
			"transaction_type": "transfer",
			"inputs": [
				{
					"amount": "20000",
					"address": "0xffec0067f5a79cff07527f63d83dd5462ccf8ba4",
					"balance": "3385212.42783",
					"owner": "nexo",
					"owner_type": "bank"
				}
			],
			"outputs": [
				{
					"amount": "20000",
					"address": "0xf8e0a4a00a4c5a3d486eab23ed26ccdbfdfc9430",
					"balance": "20000"
				}
			]
		}
	]
}
 

Endpoints

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

Note: due to technical issues with the Solana blockchain, Solana historical data may not be complete and address balances may fluctuate. The Solana team has indicated the issues with archival data will be resolved in the future.

GET /status

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

HTTP Request Example

 CopyGET https://leviathan.whale-alert.io/status?api_key=API_KEY

Response Example

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

GET {blockchain}/status

Returns the heights of the newest and oldest available blocks of a specific blockchain. Older blocks are available at request.

HTTP Request Example

 CopyGET https://leviathan.whale-alert.io/bitcoin/status?api_key=API_KEY

Response Example

 Copy
  {"start_height":770789,"end_height":776799,"block_count":6011}

 

GET {blockchain}/transaction/{hash}

Returns a specific transaction for a blockchain.

Note: standard API access does not return transactions older than 60 days. Certain blockchains have an unusual amount of spam or non-value transactions (such as votes) and these may not be available through this endpoint (this is particularly the case with Solana).

HTTP Request Example

 CopyGET https://leviathan.whale-alert.io/bitcoin/transaction/d090f501a9aad3c47da972f029ac76ab30d204c41520dcfd23fb4a68273dfa84?api_key=API_KEY

Response Example

 Copy[
 {
  "height": 770614,
  "index_in_block": 18,
  "timestamp": 1673000439,
  "hash": "d090f501a9aad3c47da972f029ac76ab30d204c41520dcfd23fb4a68273dfa84",
  "fee": "0.00056416",
  "fee_symbol": "BTC",
  "fee_symbol_price": 16789.04681818237,
  "sub_transaction": [
    {
      "symbol": "BTC",
      "unit_price_usd": 16789.04681818237,
      "transaction_type": "transfer",
      "inputs": [
        {
          "amount": "833.50911112",
          "address": "1Kr6QSydW9bFQG1mXiPNNu6WpJGmUa9i1g",
          "balance": "2647.68435103"
        },
        {
          "amount": "9.10317788",
          "address": "1Kr6QSydW9bFQG1mXiPNNu6WpJGmUa9i1g",
          "balance": "2647.68435103"
        }
      ],
      "outputs": [
        {
          "amount": "0.064",
          "address": "34y5EHsyvMKS8yANvbTzHw4tw65FxnAVaS",
          "balance": "0.064"
        },
        {
          "amount": "842.54772484",
          "address": "1Kr6QSydW9bFQG1mXiPNNu6WpJGmUa9i1g",
          "balance": "2647.68435103"
        }
      ]
    }
  ]
}
 

 Copy
{"error": "not found"}
 

GET {blockchain}/transactions

Returns all transactions for a blockchain since the specified start height. If the start height is not available due to age (transactions older than 60 days are currently not available through the API, contact us for more historical data) the first available height is retrieved. It is recommended to use this endpoint if you want a constant stream of transactions.

Note: the response includes the URL for the next request (your API key will be omitted from the "next" field for security reasons). Use the "next" URL included in the response for the next call to ensure all transactions are retrieved without duplicates. If no new block is available, the response will be empty except for the "next" field (keep making the same request until a new block is available). Note that block times can vary greatly between blockchains (from less than a second up to multiple hours per block).

HTTP Request Example

 CopyGET https://leviathan.whale-alert.io/bitcoin/transactions?format&limit=1000&start_height=768801&api_key=YOUR_API_KEY

Parameters

Response Example

 Copy{
  "height": 771103,
  "hash": "0000000000000000000710a85f27193f2131ffcfe3f04cf822bd53825c6bb787",
  "timestamp": 1673258657,
  "transactions": [
  {
      "height": 771103,
      "index_in_block": 0,
      "timestamp": 1673258657,
      "hash": "c51c0f3c215e94e865be40b15ea719ebaa2cb2ad981e26ac976b87efa0dcebde",
      "sub_transactions": [
        {
          "symbol": "BTC",
          "unit_price_usd": 17244.9556666662,
          "transaction_type": "mint",
          "inputs": null,
          "outputs": [
            {
              "amount": "6.29047284",
              "address": "38XnPvu9PmonFU9WouPXUjYbW91wa5MerL",
              "balance": "201.36838525"
            }
          ]
        }
      ]
  },
  {
      "height": 771103,
      "index_in_block": 1,
      "timestamp": 1673258657,
      "hash": "7b1842d6b915152c8f477ce4a9450858831061d8e2996673d005b8bfd0ebbe7a",
      "fee": "0.0017017",
      "fee_symbol": "BTC",
      "fee_symbol_price": 17244.9556666662,
      "sub_transactions": [
        {
          "symbol": "BTC",
          "unit_price_usd": 17244.9556666662,
          "transaction_type": "transfer",
          "inputs": [
            {
              "amount": "0.00231716",
              "address": "1KSfWveXdLxudkZTCMTbXbNPJy5o2Rwxxi",
              "balance": "0.00477555"
            },
            {
              "amount": "0.00231716",
              "address": "1KSfWveXdLxudkZTCMTbXbNPJy5o2Rwxxi",
              "balance": "0.00477555"
            }
          ],
          "outputs": [
            {
              "amount": "0.00293262",
              "address": "1KSfWveXdLxudkZTCMTbXbNPJy5o2Rwxxi",
              "balance": "0.00477555"
          }
        ]
      },
      ...
    ]
  }