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.
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.
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.
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.
Our Terms and Conditions apply to the usage of the Whale Alert APIs described in these docs.
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.
Requests are limited to a maximum of 1000 calls per minute.
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.
?api_key=YOUR_API_KEY or &api_key=YOUR_API_KEY
All endpoints can be accessed through the base URL below.
https://leviathan.whale-alert.io
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.
https://leviathan.whale-alert.io/bitcoin/block/771103?api_key=API_KEY&attributes
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).
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 state changes and added as an extra InOut if the remaining state changes are not in the same currency as the fee. | 'fee' |
Fee Symbol | string | The currency in which the fee was paid. | 'fee_symbol' |
[ ]StageChange | Every transaction is made up out of zero, one or multiple state changes or sub-transactions that influence the balance of an address for a certain symbol. | 'state_changes' |
StateChange | Type | Description | JSON key |
---|---|---|---|
Symbol | string | The symbol of the currency. A state change can only have one single symbol. | 'symbol' |
Price | string | The price in USD per single unit of the currency at the block time (e.g. 1 BTC). 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 | [ ]InOut | The inputs of a transaction or the FROM. A sub-transaction can contain zero, one or multiple inputs. | 'inputs' |
Outputs | [ ]InOut | The outputs of a transaction or the TO. A sub-transaction can contain zero, one or multiple outputs. | 'outputs' |
InOut | Type | Description | JSON key |
---|---|---|---|
Amount | string | The amount of currency by which the address balance is altered in the state change. | 'amount' |
Address | string | The hash of the address. | 'address' |
Balance | string | The balance of the address after the transaction was concluded. | 'balance' |
Owner | string | The entity to which the address has been attributed. If no owner data is available or if the selected subscription does not support attribution the field is omitted. |
'owner' |
Owner Type | string | The type of the entity to which the address has been attributed. | 'owner_type' |
{
"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"
}
]
}
]
}
]
}
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.
Returns a full overview of the supported blockchains and currencies available per blockchain.
GET https://leviathan.whale-alert.io/status?api_key=API_KEY
[
{
"name": "bitcoin",
"symbols": [
"BTC",
"USDT",
"EURT"
]
},
{
"name": "dogecoin",
"symbols": [
"DOGE"
]
},
{
"name": "tron",
"symbols": [
"USDD",
"TRX",
"BTT",
"USDT",
"USDC",
"TUSD",
"USDJ",
"WBTC"
]
}
]
Returns the heights of the newest and oldest available blocks of a specific blockchain. Older blocks are available at request.
GET https://leviathan.whale-alert.io/bitcoin/status?api_key=API_KEY
{"start_height":770789,"end_height":776799,"block_count":6011}
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).
GET https://leviathan.whale-alert.io/bitcoin/transaction/d090f501a9aad3c47da972f029ac76ab30d204c41520dcfd23fb4a68273dfa84?api_key=API_KEY
[
{
"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"
}
]
}
]
}
]
}
{"error": "not found"}
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).
GET https://leviathan.whale-alert.io/bitcoin/transactions?format&limit=1000&start_height=768801&api_key=YOUR_API_KEY
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. |
{
"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"
}
]
}
]
},
...
]
}
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.
GET https://leviathan.whale-alert.io/bitcoin/block/771103?api_key=API_KEY
{
"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"
}
]
}
]
},
...
]
}
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.
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.
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
All endpoints can be accessed through the base URL below.
https://api.whale-alert.io/v1
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' |
{
"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
}
The API is accessible through various endpoints. Responses are in JSON format. All endpoints share the same rate limits.
Returns a full overview of the supported blockchains and currencies available per blockchain.
GET https://api.whale-alert.io/v1/status?api_key=API_KEY
{
"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"
},
...
]
}
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.
GET https://api.whale-alert.io/bitcoin/transaction/d090f501a9aad3c47da972f029ac76ab30d204c41520dcfd23fb4a68273dfa84?api_key=API_KEY
{
"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}
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.
GET https://api.whale-alert.io/v1/transactions?start=1641997800&min_value=100000&currency=btc&cursor=6a202650-6a1fffc5-61dee5fe&api_key=YOUR_API_KEY
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. |
{
"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"
},
...
]
}