Introduction

The Whale Alert REST APIs provide blockchain transaction data without the user needing to have extensive technical blockchain knowledge. The blockchain data offered through the API includes value, currency mints and burns and other value relevant types. The transaction data includes the currency unit price at the time of the transaction and, where available, the attribution of an address to a known entity. All transactions are delivered in the same standardized format, regardless of blockchain protocol making tracking multiple blockchains and currencies cross chain 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 will be available through the API's.

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.

API Access

The Whale Alert REST APIs require an API key which need to be included in every request. API keys are available to users with an active subscription and are API version dependent and cannot be shared with other users. 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.

Use Cases

Whale Alert API data can be used for example to detect large transactions, power trading algorithms, track stable coin mints and burns, uncover and monitor blockchain trends, calculate exchange in- and outflows, monitor addresses and assets and much more. Whale Alert itself uses the API data to power its social media accounts with interesting transactions and to analyze and monitor suspected and confirmed scam payment addresses for Scam Alert. Various universities also use the API data for a wide variety of research topics.

Terms and Conditions

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

Leviathan API

About

The Leviathan API is a complete redesign of the original Whale Alert API and provides a full overview of blockchain transactions without value limitations, meaning that every value transaction on-chain is stored and analyzed and available through the various endpoints (depending on subscription). The API provides analyzed 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 as correct and complete as possible. Additional tokens or blockchains can be requested by contacting us.

Note: access to the Leviathan API is limited to Enterprise and Institutional subscriptions.

Rate Limiting

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

API Key

The Leviathan 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

Depending on the type of your subscription, address attribution can be accessed by adding the parameter &attributes to the call. Including attributes might increase API response time.

 Copyhttps://leviathan.whale-alert.io/bitcoin/block/771103?api_key=API_KEY&attributes

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. Sub-transactions can have different addresses, owners amounts and symbols compared to other sub-transactions. 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": 771437,
  "index_in_block": 2000,
  "timestamp": 1673438516,
  "hash": "59130ae427b838486adc09b413299af6f7e83ad817497ccfe87a5b59e5175b6e",
  "fee": "0.00003398",
  "fee_symbol": "BTC",
  "fee_symbol_price": 17437.418500000407,
  "state_changes": [
    {
      "symbol": "BTC",
      "unit_price_usd": 17437.418500000407,
      "transaction_type": "transfer",
      "inputs": [
        {
          "amount": "0.00105893",
          "addresses": [
            {
              "address": "115E3baxJZsJHeTay1jvUh3nSTHBJhkskc",
              "balance": "0.20697731",
              "owner": "binance",
              "owner_type": "exchange"
            }
          ]
        }
      ],
      "outputs": [
        {
          "amount": "0.00101949",
          "addresses": [
            {
              "address": "115E3baxJZsJHeTay1jvUh3nSTHBJhkskc",
              "balance": "0.20697731"
            }
          ]
        },
        {
          "amount": "0.00000546",
          "addresses": [
            {
              "address": "1Ch8EWwGndfW1gSxGExrBNcvCQ3tV2GW81",
              "balance": "0.00001092"
            }
          ]
        }
      ]
    },
    {
      "symbol": "USDT",
      "unit_price_usd": 1.0003,
      "transaction_type": "transfer",
      "inputs": [
        {
          "amount": "252.92",
          "addresses": [
            {
              "address": "115E3baxJZsJHeTay1jvUh3nSTHBJhkskc",
              "balance": "22328.73622607",
              "owner": "binance",
              "owner_type": "exchange"
            }
          ]
        }
      ],
      "outputs": [
        {
          "amount": "252.92",
          "addresses": [
            {
              "address": "1Ch8EWwGndfW1gSxGExrBNcvCQ3tV2GW81",
              "balance": "549.01"
            }
          ]
        }
      ]
    }
  ]
}
 

Endpoints

The Whale Alert 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 15 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,
  "state_changes": [
    {
      "symbol": "BTC",
      "unit_price_usd": 16789.04681818237,
      "transaction_type": "transfer",
      "inputs": [
        {
          "amount": "833.50911112",
          "addresses": [
            {
              "address": "1Kr6QSydW9bFQG1mXiPNNu6WpJGmUa9i1g",
              "balance": "2647.68435103"
            }
          ]
        },
        {
          "amount": "9.10317788",
          "addresses": [
            {
              "address": "1Kr6QSydW9bFQG1mXiPNNu6WpJGmUa9i1g",
              "balance": "2647.68435103"
            }
          ]
        }
      ],
      "outputs": [
        {
          "amount": "0.064",
          "addresses": [
            {
              "address": "34y5EHsyvMKS8yANvbTzHw4tw65FxnAVaS",
              "balance": "0.064"
            }
          ]
        },
        {
          "amount": "842.54772484",
          "addresses": [
            {
              "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 15 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",
      "state_changes": [
        {
          "symbol": "BTC",
          "unit_price_usd": 17244.9556666662,
          "transaction_type": "mint",
          "inputs": null,
          "outputs": [
            {
              "amount": "6.29047284",
              "addresses": [
                {
                  "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,
      "state_changes": [
        {
          "symbol": "BTC",
          "unit_price_usd": 17244.9556666662,
          "transaction_type": "transfer",
          "inputs": [
            {
              "amount": "0.00231716",
              "addresses": [
                {
                  "address": "1KSfWveXdLxudkZTCMTbXbNPJy5o2Rwxxi",
                  "balance": "0.00477555"
                }
              ]
            },
            {
              "amount": "0.00231716",
              "addresses": [
                {
                  "address": "1KSfWveXdLxudkZTCMTbXbNPJy5o2Rwxxi",
                  "balance": "0.00477555"
                }
              ]
            }
          ],
          "outputs": [
            {
              "amount": "0.00293262",
              "addresses": [
              {
                  "address": "1KSfWveXdLxudkZTCMTbXbNPJy5o2Rwxxi",
                  "balance": "0.00477555"
              }
            ]
          }
        ]
      },
      ...
    ]
  }