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

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.

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 format. For more information of historical data pricing, please visit our Pricing page.

Terms and Conditions

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

Enterprise API

About

The Enterprise API provides a full overview of blockchain transactions without value limitations, meaning that all analyzed value transactions are available through the various endpoints (max history 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 Enterprise API is limited to Enterprise and Institutional subscriptions.

Rate Limiting

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

API Key

The Enterprise 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 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"
              }
            ]
          }
        ]
      },
      ...
    ]
  }