Getting Started

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

Last Updated 4th Jul 2023
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.

?api_key=YOUR_API_KEY   or   &api_key=YOUR_API_KEY
Base URL

All endpoints can be accessed through the base URL below.

https://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).

Transaction Type Description JSON key
Height int The block height at which the transaction was included. 'height'
Index int The index at which the transaction can be found in the block. The transaction index may not correspond to the index in the raw block data for certain blockchains. 'index_in_block'
Timestamp int The UNIX timestamp of the block containing the transaction. 'timestamp'
Hash string The hash of the transaction. 'hash'
Fee string The amount paid by the initiator of the transaction. The fee is included in the sub-transactions and added as an extra sub-transaction if there are no sub-transactions in the same currency as the fee. 'fee'
Fee Symbol string The currency in which the fee was paid. 'fee_symbol'
Fee Price string The price in USD per single unit of the currency at the block time. Based on the weighted average of exchange prices. 'fee_symbol_price'
Sub Transactions [ ]SubTransaction Every transaction can have any number of sub-transactions that change the balance of address(es) for a certain symbol. 'sub_transactions'

Transactions can include multiple sub-transactions. This accommodates multi-token swaps and necessary transaction fees, as seen in Ethereum or Bitcoin where fees are paid in native tokens during a token transfer.

Each individual sub-transaction within a transaction deals with a single token and transaction type.

SubTransaction Type Description JSON key
Symbol string The symbol of the currency. A sub-transaction can only have one single symbol. 'symbol'
Price string The price in USD per single unit of the currency at the block time. Based on the weighted average of exchange prices. 'unit_price_usd'
Transaction Type string Possible values: "transfer", "mint", "burn", "freeze", "unfreeze", "lock", "unlock".
Freezes affect the entire balance of the address for a specific symbol (for instance a Tether blacklist due to which a user can no longer move USDT from or to their address), while locks affect part of the balance (staking for instance in which a specific amount of currency is locked up).
'transaction_type'
Inputs [ ]Address The inputs of a transaction or the FROM. 'inputs'
Outputs [ ]Address The outputs of a transaction or the TO. 'outputs'

NOTE: the JSON for an address may, in some rare cases, deviate from the usual structure, containing multiple addresses instead of one, each featuring unique balances, owners, and other details. For most use cases you can safely ignore this edge case.

Address Type Description JSON key
Amount string The amount of currency by which the address balance is altered. 'amount'
Address string The hash of the address. 'address'
Balance string The balance of the address after the transaction was concluded. Note this is a string type instead of a float to prevent issues related to precision. 'balance'
Locked string The amount locked at the address. This amount cannot be transferred by the owner of the address. 'locked'
Is Frozen bool True if the address has been frozen. A frozen address cannot transfer any current or future balance of this address. 'is_frozen'
Owner string The entity to which the address has been attributed. Empty when no owner data is available.
NOTE: Only exchanges are attributed by default for the Quantitative plan.
'owner'
Owner Type string The type of the entity to which the address has been attributed. 'owner_type'
Address Type string The type of the address. Possible values: deposit_wallet, hot_wallet, cold_wallet, exchange_wallet, fraud_deposit_address, hack_deposit_address, blackmail_deposit_address, theft_deposit_address, burn_address, coinbase_address, coinjoin_address, change_address, premine_address, donation_address, treasury_address, mixer_wallet, merchant_wallet. 'address_type'
Transaction Example
{
	"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
GET https://leviathan.whale-alert.io/status?api_key=API_KEY
Response Example

[
  {
    "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
GET https://leviathan.whale-alert.io/bitcoin/status?api_key=API_KEY
Response Example


  {"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
GET https://leviathan.whale-alert.io/bitcoin/transaction/d090f501a9aad3c47da972f029ac76ab30d204c41520dcfd23fb4a68273dfa84?api_key=API_KEY
Response Example

[
 {
  "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"
        }
      ]
    }
  ]
}
 


{"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
GET https://leviathan.whale-alert.io/bitcoin/transactions?format&limit=1000&start_height=768801&api_key=YOUR_API_KEY
Parameters
Name Type Description
start_height int The height of the block at which to start retrieving transactions from.
symbol (Optional) string Only retrieve those txs that have at least one sub-transaction for a specific symbol (BTC, ETH, TRX etc.). Note that a transaction can still contain multiple symbols so make sure to check for the correct symbol when using the data. Full list of available symbols can be retrieved using the /status endpoint.
transaction_type (Optional) string Retrieve sub-transactions for a specific type only. Available types are: transfer, mint, burn, freeze, unfreeze, lock, unlock.
limit (Optional) int The maximum number of transactions to be retrieved in the request. Default 256, maximum dependent on subscription type.
start_index (Optional) int Automatically included in the "next" field of the response.
order (Optional) string List transactions in ascending (&order=asc) or descending (&order=desc) order. Default asc.
format (Optional) none Transforms the response JSON to a more readable format. May increase the size of the response.
Response Example

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

 
GET {blockchain}/block/{height}

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

Note: the number of transactions and transaction indexes may not directly correspond to the raw blockchain data. For example, Ethereum has an additional transaction added per block at index 0 representing the mining reward for the block. Block requests are not paginated so responses might be slow for large blocks. To retrieve the most recent transactions use of the /transactions endpoint is strongly recommended.

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

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

 
GET {blockchain}/address/{hash}/transactions

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

Parameters
Name Type Description
start_height int The height of the block at which to start retrieving transactions from.
symbol (Optional) string Only retrieve those txs that have at least one sub-transaction for a specific symbol (BTC, ETH, TRX etc.). Note that a transaction can still contain multiple symbols so make sure to check for the correct symbol when using the data. Full list of available symbols can be retrieved using the /status endpoint.
limit (Optional) int The maximum number of transactions to be retrieved in the request. Default 256, maximum dependent on subscription type.
start_index (Optional) int Automatically included in the "next" field of the response.
order (Optional) string List transactions in ascending (&order=asc) or descending (&order=desc) order. Default desc.
format (Optional) none Transforms the response JSON to a more readable format. May increase the size of the response.
HTTP Request Example
GET https://leviathan.whale-alert.io/bitcoin/address/198aMn6ZYAczwrE5NvNTUMyJ5qkfy4g3Hi/transactions?api_key=API_KEY
Response Example

{
  "next": "",
  "address": "198aMn6ZYAczwrE5NvNTUMyJ5qkfy4g3Hi",
  "transactions": [
    {
      "height": 844345,
      "index_in_block": 1912,
      "timestamp": 1716236919,
      "hash": "c0b65a37948886f6081d0ef34c7a0e88772116370630d04a63d91b2d02618195",
      "fee": "0.00001232",
      "fee_symbol": "BTC",
      "fee_symbol_price": 69548.9659687315,
      "sub_transactions": [
        {
          "symbol": "BTC",
          "unit_price_usd": 69548.9659687315,
          "transaction_type": "transfer",
          "inputs": [
            {
              "amount": "0.00018905",
              "address": "bc1pyhyywjkns5m62na7j00kjcdr84nzph2h4f96nxka4ptfdcul2fmsg8ula3",
              "balance": "0.0005633",
              "address_type": "coinjoin"
            }
          ],
          "outputs": [
            {
              "amount": "0.00000546",
              "address": "198aMn6ZYAczwrE5NvNTUMyJ5qkfy4g3Hi",
              "balance": "8000.00649391",
              "address_type": "cold_wallet"
            },
            {
              "amount": "0.00017127",
              "address": "bc1pyhyywjkns5m62na7j00kjcdr84nzph2h4f96nxka4ptfdcul2fmsg8ula3",
              "balance": "0.0005633",
              "address_type": "coinjoin"
            }
          ]
        }
      ]
    }
  ]
}

 
GET {blockchain}/address/{hash}/owner_attributions

Returns the owners of the specified address. A single address might have multiple owners, especially in cases where it's linked to a white label exchange or when the ownership becomes ambiguous due to obfuscation techniques.

Each owner is paired with a confidence score ranging from 0 to 1:

  • 0 to 0.1: Indicators suggest potential association with the owner.
  • 0.1 to 0.3: Some evidence suggests ownership.
  • 0.3 to 0.6: Evidence of ownership.
  • 0.6 to 0.9: Highly probable ownership.
  • 0.9 to 1.0: Near certainty of ownership.
  • 1.0: Certainty of ownership.

Note: This confidence score is not equivalent to a probability measurement.

HTTP Request Example
GET https://leviathan.whale-alert.io/address/121zDkvXABFnFXQ8KY1dFzTvnm2k4Sased/owner_attributions?api_key=API_KEY
Response Example

[
   {
      "name":"Binance",
      "confidence":1
   },
   {
      "name":"Nexo",
      "confidence":0.49
   },
   {
      "name":"Godex",
      "confidence":0.59
   }
]
 

Websocket API

Last Updated 4th Jul 2023
About

The Whale Alert WebSocket API delivers customizable transaction alerts across multiple blockchains and cryptocurrencies, similar to the alerts on our Twitter account. 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 Whale Alert WebSocket API is its customizability. Users can define specific criteria for alerts, ensuring the receipt of only the most relevant transaction notifications.

Furthermore, as with our REST API, alerts generated by the Whale Alert WebSocket API follow a generalized format, regardless of the blockchain involved. This means users can seamlessly compare and analyze transactions across multiple blockchains, enhancing their understanding and decision-making capabilities within the blockchain landscape.

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

This API is ideally suited for sectors including financial institutions, security monitoring, research & analytics, regulatory compliance, and blockchain development. With its real-time alerts and exceptional customization capabilities, the Whale Alert WebSocket API allows users to make informed decisions based on the ever-changing landscape of blockchain transactions.

For users interested in monitoring the alerts shared on our social media platforms, we provide events that display the complete text of each post, along with direct URLs to each specific posts.

Connecting

The WebSocket API shares the same base URL and requires the same API key for authentication as the REST API described previously:

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, you will need to resubscribe to any alerts to which you were previously subscribed if you wish to continue receiving them. Be aware that alerts may be missed while disconnected. However, 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 events

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

Subscribing to Alerts
Address Type Description
type string The type of events to subscribe to. Only alerts are available for now: "subscribe_alerts".
id (Optional) string Can be any arbitrary string. When set to the same id as before, any missed alerts while disconnected (up to 5 minutes) will be resent. Sending a subscription request with the same id will overwrite the existing one.
blockchains (Optional) []string A list of blockchains to subscribe to. Available blockchains can be retrieved using the /status API endpoint described earlier. If omitted, the subscription will automatically include all available blockchains.
symbols (Optional) []string A list of symbols to subscribe to. Available symbols can be retrieved using the /status API endpoint described earlier. If omitted, the subscription will automatically include all available symbols.
tx_types (Optional) []string A list of transaction types to subscribe to. The complete list of transaction types is: transfer, mint, burn, freeze, unfreeze, lock, unlock. If omitted, the subscription will automatically include all available transaction types.
min_value_usd float The minimum transaction value in USD to trigger an alert.

Example of a subscription request that subscribes to all alerts for transactions that transfer Ethereum or Wrapped Ethereum on the Ethereum blockchain with a value equal to or greater than 1,000,000 USD:

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

The WebSocket responds with a message of type 'subscribed_alerts'. Example response for the above subscription request:

{
    "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 as described in the Transaction Schema above, but also an easy-to-read summary of the alert similar to the alerts posted in our Twitter channel.

Alert Type Description JSON key
Type string Type that indicates this is an alert. Value is set to "alert". 'type'
Channel ID string The id of the alert channel. If this was not set in the subscription request, a random id is assigned. Use this id when re-subscribing to a alerts after a disconnect in order to receive any missed alerts. 'channel_id'
Timestamp int The timestamp of the transaction. 'timestamp'
Blockchain string The blockchain this transaction was created on 'blockchain'
Transaction Type string Possible values: "transfer", "mint", "burn", "freeze", "unfreeze", "lock", "unlock". 'transaction_type'
From string The owner of the from-address(es) that initiated the transaction. 'from'
To string The owner of the to-address(es) that are the receiver(s). Note that the there can be multiple receivers in a transaction. Only the receiver associated with the highest value is shown here. Refer to the transaction data field for complete information. 'to'
Amounts []Amount The amounts transferred by the initiator of the transaction. A single transaction can have multiple symbols and amounts. 'amounts'
Text string A human-readable representation of the transaction, similar to the Whale Alerts posted on our Twitter channel. 'text'
Transaction Transaction Complete transaction data. This has the same format as the data returned from the REST API endpoints described previously. 'transaction'
Amount Type Description JSON key
Symbol string The symbol of the currency. 'symbol'
Amount float The amount of tokens. Note that this field is of the float type. If your use case requires exact amounts down to the Satoshi or Wei use the amounts from the full transaction data in the 'transaction' field. 'amount'
Value USD float The USD value of the amount. 'value_usd'

An example of a 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.310176,
         "value_usd":20008425.95270702
      },
      {
         "symbol":"WETH",
         "amount":5122.118861012107,
         "value_usd":9702266.325340524
      }
   ],
   "text":"20,006,425 USDC (20,008,425 USD) and 5,122 WETH (9,702,266 USD) transferred from unknown wallet to unknown wallet. Blockchain: ethereum. Transaction hash: 0x60b2f4ac1d2a1308aa04c82d70c388404c92c1d3474c13ca29188ada1edad9dc",
   "transaction":{
      "height":17531252,
      "index_in_block":8,
      "timestamp":1687389431,
      "hash":"0x60b2f4ac1d2a1308aa04c82d70c388404c92c1d3474c13ca29188ada1edad9dc",
      "fee":"0.004094476112033575",
      "fee_symbol":"ETH",
      "fee_symbol_price":1896.3385891487344,
      "sub_transactions":[
         {
            "symbol":"ETH",
            "unit_price_usd":1896.3385891487344,
            "transaction_type":"transfer",
            "inputs":[
               {
                    "amount":"0.004094476112078375",
                    "address":"0x0cac3d1a887206e0f6169222c4504301a8b4b993",
                    "balance":"50.076697315223177111"
               }
            ],
            "outputs":[
               {
                    "amount":"0.0000000000000448",
                    "address":"0xa69babef1ca67a37ffaf7a485dfff3382056e78c",
                    "balance":"98.022538180146464781"
               }
            ]
         },
         {
            "symbol":"USDC",
            "unit_price_usd":1.0001,
            "transaction_type":"transfer",
            "inputs":[
               {
                    "amount":"20006425.310176",
                    "address":"0xa69babef1ca67a37ffaf7a485dfff3382056e78c",
                    "balance":"0.000001"
               }
            ],
            "outputs":[
               {
                    "amount":"20006425.310176",
                    "address":"0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
                    "balance":"137582557.825184"
               }
            ]
         },
         {
            "symbol":"WETH",
            "unit_price_usd":1894.19,
            "transaction_type":"transfer",
            "inputs":[
               {
                    "amount":"5122.118861012106882592",
                    "address":"0xa69babef1ca67a37ffaf7a485dfff3382056e78c",
                    "balance":"8183.586571433944346458"
               }
            ],
            "outputs":[
               {
                    "amount":"5122.118861012106882592",
                    "address":"0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
                    "balance":"60731.388902993727955153"
               }
            ]
         }
      ]
   }
}
 
Code Examples

Below you can find code examples for the WebSocket API in JavaScript, Go and Python.

<html>
<head>
    <title>Live Alerts</title>
    <style>
        body {
            background: #FAFAFA;
            font-family: Arial, sans-serif;
            color: #333;
            display: flex;
            align-items: center;
            justify-content: center;
            flex-direction: column; /* set flex direction to column */
            height: 100vh;
            margin: 0;
            padding: 20px; /* added padding */
        }
        #alerts {
            text-align: left;
            background: #FFF;
            width: 90%;
            height: 600px;
            padding: 20px;
            overflow-y: auto;
            border: 1px solid #DDD;
            margin-bottom: 20px;
            box-shadow: 0 0 10px rgba(0,0,0,0.1);
        }
        #myForm {
            background: #FFF;
            width: 90%;
            padding: 20px;
            box-shadow: 0 0 10px rgba(0,0,0,0.1);
        }
        button {
            background-color: #4CAF50;
            border: none;
            color: white;
            padding: 10px 20px;
            text-align: center;
            text-decoration: none;
            display: inline-block;
            font-size: 16px;
            margin: 10px 2px;
            cursor: pointer;
            border-radius: 4px;
            transition: background-color 0.3s;
        }
        button:hover {
            background-color: #45a049;
        }
        input, textarea {
            width: 100%;
            padding: 12px 20px;
            margin: 8px 0;
            display: inline-block;
            border: 1px solid #ccc;
            border-radius: 4px;
            box-sizing: border-box;
        }
        h3 {
            margin-bottom: 20px;
        }
    </style>
</head>
<body>
<h3>Live Alerts</h3>
<pre id="alerts"></pre>
<form id="myForm">
    <input placeholder="API Key" id="api_key" name="api_key" type="text">
    <button type="button" id="connectButton" onclick="connect();">Connect</button>
    <br><br>
    <textarea placeholder="Request" id="text" name="text" rows="15"></textarea><br><br>
    <button type="button" onclick="send();">Send</button>
</form>

<script>
    let ws;

    // Define the delay before attempting to reconnect
    const RECONNECT_DELAY = 10000;

    // Get the alert, api key input, connect button, and text area elements
    const alerts = document.getElementById("alerts");
    const apiKeyInput = document.getElementById("api_key");
    const connectButton = document.getElementById("connectButton");
    const text = document.getElementById("text");

    // Function to establish WebSocket connection
    function connect() {
        if(ws) {
            ws.close(); // Close any existing connections.
        }

        // Check if API key is set
        if (document.getElementById("api_key").value === "") {
            alerts.innerText = now() + " " + "API key not set.\n" + alerts.innerText;
            return;
        }

        // Display connection status in alerts
        alerts.innerText = now() + " " + "Connecting to WebSocket.\n" + alerts.innerText;

        // Get URL with the input API key
        let url = "wss://leviathan.whale-alert.io/ws?api_key=" + document.getElementById("api_key").value;

        // Create new WebSocket connection
        ws = new WebSocket(url);

        // When the WebSocket connection is opened
        ws.onopen = function(e) {
            // Display connection status in alerts and update the UI
            alerts.innerText = now() + " " + "Connected to WebSocket.\n" + alerts.innerText;
            apiKeyInput.style.borderColor = "green";
            connectButton.disabled = true;
        }

        // When a message is received through the WebSocket
        ws.onmessage = function (msg) {
            // Parse the message data and display it in alerts
            let msgData = JSON.parse(msg.data);
            if (msgData.text) {
                alerts.innerText = now() + " " + msgData.text + "\n" + alerts.innerText;
            } else {
                alerts.innerText = now() + " " + msg.data + "\n" + alerts.innerText;
            }
        }

        // When the WebSocket connection is closed
        ws.onclose = function(e) {
            // Display disconnection status in alerts and update the UI, then try to reconnect
            alerts.innerText = now() + " " + "Disconnected from WebSocket.\n" + alerts.innerText;
            apiKeyInput.style.borderColor = "";
            connectButton.disabled = false;

            setTimeout(connect, RECONNECT_DELAY); // try reconnecting after the defined delay
        }

        // When there's an error in the WebSocket connection
        ws.onerror = function(e) {
            // Display error status in alerts and update the UI
            alerts.innerText = now() + " " + "Failed to connect to WebSocket.\n" + alerts.innerText;
            apiKeyInput.style.borderColor = "";
            connectButton.disabled = false;
        }
    }

    // Function to get current time
    function now() {
        let iso = new Date().toISOString();
        return iso.split("T")[1].split(".")[0]; // return only the time part
    }

    // Function to send data through WebSocket
    function send() {
        if (ws && ws.readyState === WebSocket.OPEN) {
            // Send the text value if the WebSocket is open, and then clear the input
            ws.send(text.value);
            text.value = "";
        } else {
            // If the WebSocket is not open, display an error message
            alerts.innerText = now() + " " + "Error: Connection not established.\n" + alerts.innerText;
        }
    }

</script>
</body>
</html>
               
package main

import (
	"context"
	"fmt"
	"log"
	"nhooyr.io/websocket"
	"nhooyr.io/websocket/wsjson"
	"time"
)

const apiKey = "API_KEY" // Replace with your API key

type AlertSubscriptionJSON struct {
	Type        string   `json:"type"`
	ID          string   `json:"id"`
	Blockchains []string `json:"blockchains"`
	Symbols     []string `json:"symbols"`
	Types       []string `json:"tx_types"`
	MinValueUSD float64  `json:"min_value_usd"`
}

type TransactionJSON struct {
	BlockHeight           uint64           `json:"height"`
	IndexInBlock          int              `json:"index_in_block"`
	Timestamp             int64            `json:"timestamp"`
	CustomTransactionData string           `json:"custom_transaction_data,omitempty"`
	Hash                  string           `json:"hash"`
	Fee                   string           `json:"fee,omitempty"`
	FeeSymbol             string           `json:"fee_symbol,omitempty"`
	FeeSymbolPrice        float64          `json:"fee_symbol_price,omitempty"`
	SubTransactions       []SubTransaction `json:"sub_transactions"`
}

type SubTransaction struct {
	Symbol          string   `json:"symbol"`
	Price           float64  `json:"unit_price_usd,omitempty"`
	TransactionType string   `json:"transaction_type"`
	Inputs          []Amount `json:"inputs"`
	Outputs         []Amount `json:"outputs"`
}

type Amount struct {
	Amount      string `json:"amount"`
	Address     string `json:"address,omitempty"`
	Balance     string `json:"balance,omitempty"`
	Locked      string `json:"locked,omitempty"`
	IsFrozen    bool   `json:"is_frozen,omitempty"`
	Owner       string `json:"owner,omitempty"`
	OwnerType   string `json:"owner_type,omitempty"`
	AddressType string `json:"address_type,omitempty"`
}

type AlertJSON struct {
	ChannelId       string `json:"channel_id"`
	Timestamp       int    `json:"timestamp"`
	Blockchain      string `json:"blockchain"`
	TransactionType string `json:"transaction_type"`
	From            string `json:"from"`
	To              string `json:"to"`
	Amounts         []struct {
		Symbol   string  `json:"symbol"`
		Amount   float64 `json:"amount"`
		ValueUsd float64 `json:"value_usd"`
	} `json:"amounts"`
	Text        string           `json:"text"`
	Transaction TransactionJSON `json:"transaction"`
}

func main() {
	// Set a timeout context
	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
	defer cancel()

	// Connect to the WebSocket server
	c, _, err := websocket.Dial(ctx, fmt.Sprintf("wss://leviathan.whale-alert.io/ws?api_key=%s", apiKey), nil)
	if err != nil {
		log.Fatal("Failed to connect: ", err)
	}
	defer c.Close(websocket.StatusNormalClosure, "") // Close the connection on exit

	// Create the subscription message
	// Subscribe to alerts for the Eth symbol on the Ethereum chain with a value of at least 10,000 USD
	sub := AlertSubscriptionJSON{
		Type: "subscribe_alerts",
		Blockchains: []string{
			"ethereum",
		},
		Symbols: []string{
			"eth",
		},
		MinValueUSD: 10_000,
	}

	// Set a timeout context for the subscription
	subCtx, cancel := context.WithTimeout(ctx, time.Second)
	defer cancel()

	// Send the subscription message
	if err := wsjson.Write(subCtx, c, &sub); err != nil {
		log.Fatal(err)
	}

	// Read the confirmation message for the subscription
	var subConfirm AlertSubscriptionJSON
	err = wsjson.Read(ctx, c, &subConfirm)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Received subscription confirmation: %+v\n", subConfirm)

	// Keep reading alerts from the WebSocket
	for {
		var msg AlertJSON
		err := wsjson.Read(context.Background(), c, &msg)
		if err != nil {
			log.Fatal(err)
		}

		fmt.Printf("%s\n", msg.Text)
	}
}

                    
                
import asyncio
import websockets
import json

async def connect():
    api_key = "your_api_key_here"  # Please replace with your API key

    # The WebSocket API URL with the API key included
    url = f"wss://leviathan.whale-alert.io/ws?api_key={api_key}"

    # The subscription message
    subscription_msg = {
        "type": "subscribe_alerts",
        "blockchains": ["ethereum"],
        "symbols": ["eth"],
        "min_value_usd": 10_000,
    }

    # Connect to the WebSocket server
    async with websockets.connect(url) as ws:
        # Send the subscription message
        await ws.send(json.dumps(subscription_msg))

        # Wait for a response
        response = await ws.recv()

        # Print the response
        print(f"Received: {response}")

        # Continue to handle incoming messages
        while True:
            try:
                # Wait for a new message
                message = await asyncio.wait_for(ws.recv(), timeout=20)  # 20 seconds timeout
                print(f"Received: {message}")
            except asyncio.TimeoutError:
                print('Timeout error, closing connection')
                break
            except websockets.ConnectionClosed:
                print('Connection closed')
                break

# Run the connect function until it completes
asyncio.run(connect())

                
Subscribing to Social Media Posts

In order to track our social media posts you can subscribe to the socials events. Once a Whale Alert is posted on social media the WebSocket will respond with the posts' text and direct links to the post.

Address Type Description
type string The type of events to subscribe to. To subscribe to social media posts, set this field to "subscribe_socials".
id (Optional) string Can be any arbitrary string. When set to the same id as before, any missed alerts while disconnected (up to 5 minutes) will be resent. Sending a subscription request with the same id will overwrite the existing one.

Example of a subscription request that subscribes to Whale Alerts social media posts:

{
    "type": "subscribe_socials"
}

The WebSocket responds with a message of type 'subscribed_socials'. Example response for the above subscription request:

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

Alerts are returned in a standardized format for all blockchains and social media.

Socials Type Description JSON key
Type string Type that indicates this is an alert. Value is set to "socials". 'type'
Channel ID string The id of the alert channel. If this was not set in the subscription request, a random id is assigned. Use this id when re-subscribing to a alerts after a disconnect in order to receive any missed alerts. 'channel_id'
Timestamp int The timestamp of the transaction. 'timestamp'
Blockchain string The blockchain this transaction was created on 'blockchain'
Text string A human-readable representation of the transaction, similar to the Whale Alerts posted on our Twitter channel. 'text'
Urls []string Array of direct links to the social media posts that were made. 'urls'

An example of a Whale Alert social media post returned by the WebSocket API:

 {
   "channel_id":"xlLZ7tJq",
   "timestamp":1692724660,
   "blockchain":"tron",
   "text":"🔥 🔥 🔥 🔥 🔥 🔥 🔥 🔥 🔥 🔥  1,200,000,000 #USDT (1,200,398,999 USD) burned at Tether Treasury\n\nhttps://whale-alert.io/transaction/tron/cf5b1ae18be3d3596a9920c0dffce82c5247e9672b4ff7b1194d0355e5bec470",
   "urls":["https://twitter.com/whale_alert/status/1694036126422450598","https://t.me/whale_alert_io/72364"]

}
 
API Limits

The WebSocket API allows a maximum of 2 concurrent connections per API key. There is also a cap to the number of alerts per hour. For more details, visit our plans page for more info.

Tutorial

A tutorial that demonstrates how to integrate the WebSocket API with IFTTT is available here. You can find the code used in this tutorial on our github page.

Errors

Errors are returned in the form of:

 {
        "error": "ERROR_MESSAGE"
}
 
Error Description
invalid request The request is formatted incorrectly or is missing required field(s). Check for missing fields and parentheses and invalid data types.
not authenticated Request is missing authentication or the client is not authorized to use of this endpoint.
not allowed The client is not allowed to subscribe to this event.
invalid message type The 'type' field must be set to "subscribe_alerts".
min usd value too low The 'min_value_usd' field is set to a too low value.
id too long The 'id' field value must have a length less than 32 chars.
invalid message type The 'tx_types' field must be empty or one or more of: "transfer", "mint", "burn", "freeze", "unfreeze", "lock", "unlock".
invalid blockchain The 'blockchains' field must be empty or one or more of the blockchains returned by the /status endpoint.
invalid symbol The 'symbols' field must be empty or one or more of the symbols returned by the /status endpoint.
alert rate limit exceeded The number of alerts per hour has been exceeded for your account. This error is only shown once per minute. Note that alerts are silently dropped once the rate limit is reached.

Developer API (Deprecated)

Last Updated 20th Feb 2023
About

The Developer API provides transaction data for various blockchains including pricing and attribution (where available) data. The transactions are retrieved and analyzed live from their respective blockchains and are available through the API almost instantly. The Developer API provides a 1-month history.

Rate Limiting

API rate limiting is dependent on your plan. For the free plan the number of requests is limited to 10 per minute. The personal plan has a rate limit of 60 per minute. If you need a higher rate limit, please contact us for subscription options.

API Key

Requests require an API key, which can be obtained through a subscription. The API keys are intended for use with a specific API version and are not interchangeable between them.

?api_key=YOUR_API_KEY   or   &api_key=YOUR_API_KEY
Base URL

All endpoints can be accessed through the base URL below.

https://api.whale-alert.io/v1
Transaction Schema

All transactions returned by the API use the same JSON schema regardless of blockchain protocol. Transactions with values under 10 USD are grouped together in order to limit the amount of data. This is reflected in the values for hash, addresses and transaction count.

Transaction Type Description JSON key
Blockchain string The blockchain on which the transaction took place. 'blockchain'
Symbol string The symbol of the currency used in the transaction. 'symbol'
Id int The Whale Alert assigned id of the transaction. 'id'
Transaction Type string Transaction types available are: "transfer", "mint", "burn", "lock", "unlock". 'transaction_type'
Hash string The hash of the transaction. Value is "Multiple" in the case of grouped transactions. 'hash'
From Address The sender of the transaction. 'from'
To Address The receiver of the transaction. 'to'
Timestamp int The Unix timestamp of the transaction. 'timestamp'
Amount float The amount of the currency of the transaction. 'amount'
Amount USD float The USD value of the amount at the time of the transaction. 'amount_usd'
Transaction Count int The number of transactions included in this specific transaction. The API groups small transactions and transactions to and from the same addresses. 'transaction_count'
Address Type Description JSON key
Address string The hash of the address. Value is "Multiple Addresses" in case of grouped addresses 'address'
Owner string The entity the address has been attributed to for instance "binance, "huobi' etc. Value is "unknown" in case the owner has not been determined. 'owner'
Outputs string The type of the entity the address has been attributed to. Most common is the "exchange" type. Value is "unknown" in case the owner has not been determined. 'owner_type'
Transaction Example
 {
      "blockchain": "bitcoin",
      "symbol": "btc",
      "id": "1780328866",
      "transaction_type": "transfer",
      "hash": "Multiple Hashes",
      "from": {
        "address": "Multiple Addresses",
        "owner": "unknown",
        "owner_type": "unknown"
      },
      "to": {
        "address": "Multiple Addresses",
        "owner": "unknown",
        "owner_type": "unknown"
      },
      "timestamp": 1641978900,
      "amount": 0.07014008,
      "amount_usd": 2995.3953,
      "transaction_count": 9
 }
 
Endpoints

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

GET /status

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

HTTP Request Example
GET https://api.whale-alert.io/v1/status?api_key=API_KEY
Response Example

{
	"result": "success",
	"blockchain_count": 15,
	"blockchains": [
		{
			"name": "ethereum",
			"symbols": [
				"bnt",
				"eth",
				"qkc",
				"hpt",
				"iost",
				"qash",
				"rep",
				"sxp",
				"zil",
				"bzrx",
				...
			],
			"status": "connected"
		},
		{
			"name": "bitcoin",
			"symbols": [
				"btc",
                "usdt"
			],
			"status": "connected"
		},
		{
			"name": "icon",
			"symbols": [
				"icx"
			],
			"status": "connected"
		},
    ...
    ]
 }
 
GET /transaction/{blockchain}/{hash}

Returns a specific transaction for a blockchain.

Note: the API does not return transactions older than 30 days or transactions that are below the subscription value threshold. Depending on the blockchain, a hash can return multiple transactions. This is because complex transactions are divided into smaller parts.

HTTP Request Example
GET https://api.whale-alert.io/bitcoin/transaction/d090f501a9aad3c47da972f029ac76ab30d204c41520dcfd23fb4a68273dfa84?api_key=API_KEY
Response Example

{
  "result": "success",
  "count": 2,
  "transactions": [
    {
      "blockchain": "bitcoin",
      "symbol": "btc",
      "id": "1942315985",
      "transaction_type": "transfer",
      "hash": "c375c2e31c2f4bfd8789f0ac1f42aa902dd3bdcaf4889af796a6c8af26b5afd3",
      "from": {
        "address": "32UoZ5XnzmwYxpGqbzzr4859QwpttaMusB",
        "owner": "unknown",
        "owner_type": "unknown"
      },
      "to": {
        "address": "37biYvTEcBVMoR1NGkPTGvHUuLTrzcLpiv",
        "owner": "unknown",
        "owner_type": "unknown"
      },
      "timestamp": 1671629792,
      "amount": 300,
      "amount_usd": 5053319,
      "transaction_count": 1
    },
    {
      "blockchain": "bitcoin",
      "symbol": "btc",
      "id": "1942315986",
      "transaction_type": "transfer",
      "hash": "c375c2e31c2f4bfd8789f0ac1f42aa902dd3bdcaf4889af796a6c8af26b5afd3",
      "from": {
        "address": "32UoZ5XnzmwYxpGqbzzr4859QwpttaMusB",
        "owner": "unknown",
        "owner_type": "unknown"
      },
      "to": {
        "address": "3782yFb1C8nXWMTtiYwogdfQvAJQX3GptV",
        "owner": "unknown",
        "owner_type": "unknown"
      },
      "timestamp": 1671629792,
      "amount": 2700,
      "amount_usd": 45479870,
      "transaction_count": 1
    }
  ]
}
 


{"result":"success","count":0}
 
GET {blockchain}/transactions

Returns transactions with timestamp after a set start time in order in which they were added to the Whale Alert database. This timestamp is the execution time of the transaction on its respective blockchain. Some transactions might be reported with a small delay, which is why it is important to use the cursor to ensure all transactions are included in the response. Use of the cursor is strongly recommended for subsequent calls. When using the cursor the set start time remains the same for subsequent calls (e.g. if your first call was made without cursor and a star time of 1673611970, the next call with cursor included will use the same start time. Low value transactions (< 10 USD) are periodically grouped per blockchain and per FROM and TO address owner to reduce data size.

HTTP Request Example
GET https://api.whale-alert.io/v1/transactions?start=1641997800&min_value=100000&currency=btc&cursor=6a202650-6a1fffc5-61dee5fe&api_key=YOUR_API_KEY
Parameters
Name Type Description
start int The UNIX time from which transactions are to be retrieved. Start time is a constant when using the cursor to get a stream of transactions.
end (Optional) int The UNIX time until which transactions are to be retrieved. Do not use this parameter when getting a constant stream of transactions.
cursor (Optional) string Used to prevent duplicates or missing transaction in subsequent calls. Highly recommended.
limit (Optional) int The maximum number of transactions to be retrieved in the request. Default and max set at 100.
min_value (Optional) int Minimum USD value of transactions returned (value at time of transaction). Allowed minimum value varies per plan ($500k for Free, $100k for Personal).
currency (Optional) string Returns transactions for one single currency (for example: &currency=btc). Returns all currencies by default, multiple currency codes per request not supported.
Response Example

{
  "result": "success",
  "cursor": "6a20261e-6a200142-61dee5fe",
  "count": 100,
  "transactions": [
    {
      "blockchain": "bitcoin",
      "symbol": "btc",
      "id": "1780491806",
      "transaction_type": "transfer",
      "hash": "Multiple Hashes",
      "from": {
        "address": "Multiple Addresses",
        "owner": "unknown",
        "owner_type": "unknown"
      },
      "to": {
        "address": "Multiple Addresses",
        "owner": "unknown",
        "owner_type": "unknown"
      },
      "timestamp": 1641997800,
      "amount": 23.108807,
      "amount_usd": 1015909.44,
      "transaction_count": 3770
    },
    {
      "blockchain": "bitcoin",
      "symbol": "btc",
      "id": "1780481970",
      "transaction_type": "transfer",
      "hash": "208ac7dbb8e72d21a3cfe608cd80ee60bebf37ea17b7c2e50f119b1993ca9603",
      "from": {
        "address": "Multiple Addresses",
        "owner": "unknown",
        "owner_type": "unknown"
      },
      "to": {
        "address": "1Kr6QSydW9bFQG1mXiPNNu6WpJGmUa9i1g",
        "owner": "Bitfinex",
        "owner_type": "exchange"
      },
      "timestamp": 1641997822,
      "amount": 2.4107838,
      "amount_usd": 105982.89,
      "transaction_count": 1
    },
    {
      "blockchain": "bitcoin",
      "symbol": "btc",
      "id": "1780481974",
      "transaction_type": "transfer",
      "hash": "546bbc56e1faa5a415c65538cfe7e4da8d5be620cf39401c9849e70dd0a4fa52",
      "from": {
        "address": "bc1qwqdg6squsna38e46795at95yu9atm8azzmyvckulcc7kytlcckxswvvzej",
        "owner": "unknown",
        "owner_type": "unknown"
      },
      ...
    ]
  }