Introduction

Whale Alert's API allows you to retrieve live and historical transaction data from major blockchains. Currently supported are Bitcoin, Ethereum, Ripple, NEO, EOS, Stellar and Tron. More blockchains will be added in the future. Please read our terms and conditions before using the API.

Authentication

Whale Alert uses API keys for access to the API. To create an API key please sign up here.

Each API request should target REST URI: https://api.whale-alert.io/v1 and must include the API key using one of two ways:

Request header named X-WA-API-KEY Or
Query parameter named api_key

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 more requests, please contact us for an Enterprise account.

Endpoints

Status

HTTP request example

GET https://api.whale-alert.io/v1/status?api_key=your-api-key-here

HTTP response example (shortened)

{
    "result": "success",
    "blockchain_count": 5,
    "blockchains": [
        {
            "name": "ethereum",
            "symbols": [
                "ae",
                "agi",
                "aion",
                "aoa",
                "appc",
                "bat"
            ],
            "status": "connected"
        },
        {
            "name": "ripple",
            "symbols": [
                "xrp"
            ],
            "status": "connected"
        }
    ]
}

Shows the current status of Whale Alert. Response lists all currently tracked blockchains, currencies and the current status for each blockchain. If Whale Alert is currently receiving data from a blockchain the status will be listed as "connected".

HTTP Request

GET /v1/status

Transaction

HTTP request example

GET https://api.whale-alert.io/v1/transaction/ethereum/0x0015286d8642f0e0553b7fefa1c168787ae71173cbf82ec2f2a1b2e0ffee72b2?api_key=your-api-key-here

HTTP response example (shortened)

{
  "result": "success",
  "count": 1,
  "transactions": [
    {
      "blockchain": "ethereum",
      "symbol": "eth",
      "transaction_type": "transfer",
      "hash": "0015286d8642f0e0553b7fefa1c168787ae71173cbf82ec2f2a1b2e0ffee72b2",
      "from": {
        "address": "d24400ae8bfebb18ca49be86258a3c749cf46853",
        "owner": "gemini",
        "owner_type": "exchange"
      },
      "to": {
        "address": "07ee55aa48bb72dcc6e9d78256648910de513eca",
        "owner_type": "unknown"
      },
      "timestamp": 1549908368,
      "amount": 42000,
      "amount_usd": 5110718.5,
      "transaction_count": 1
    }
  ]
}

Returns the transaction from a specific blockchain by hash. Blockchain inputs are: bitcoin, ethereum, ripple, neo, eos, tron and stellar. If a transaction consists of multiple OUTs, it is split into multiple transactions, provided the corresponding OUT is of high enough value (>=$10 USD).

HTTP Request

GET /v1/transaction/{blockchain}/{hash}

URL Parameters

Parameter	Type	Description
blockchain	string	The blockchain to search for the specific hash (lowercase)
hash	string	The hash of the transaction to return

Transactions

Returns transactions with timestamp after a set start time (excluding) in order in which they were added to our database. This timestamp is the execution time of the transaction on its respective blockchain. Some transactions might be reported with a small delay.

Use the cursor with the same start time when retrieving transactions in multiple or continuous requests (when retrieving the newest transactions or when the number of retrieved transactions is higher than the limit per result set).

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?api_key=your-api-key-here&min_value=10000&start=1550237797&cursor=2bc7e46-2bc7e46-5c66c0a7

HTTP response example (shortened)

{
  "result": "success",
  "cursor": "2bc7efa-2bc7efa-5c66c095",
  "count": 4,
  "transactions": [
    {
      "blockchain": "ethereum",
      "symbol": "eth",
      "transaction_type": "transfer",
      "hash": "f11c10e44880f0b282fbc40390cd4f50a4d6e6662cc6a3847d57032c79c7e256",
      "from": {
        "address": "3bcf29647e479473dd18dff467a066fcb5a597a0",
        "owner_type": "Unknown"
      },
      "to": {
        "address": "5e032243d507c743b061ef021e2ec7fcc6d3ab89",
        "owner": "bittrex",
        "owner_type": "Exchange"
      },
      "timestamp": 1550237833,
      "amount": 144.24371,
      "amount_usd": 17721.047,
      "transaction_count": 1
    },
    {
      "blockchain": "ethereum",
      "symbol": "eth",
      "transaction_type": "transfer",
      "hash": "76210c5c2cda39b4b2f4685e5e57c342ad7e3b577ba71184792cf76706ec5345",
      "from": {
        "address": "a1ba7454a59ed71c39de58448ca8ff9048e2d0ef",
        "owner_type": "unknown"
      },
      "to": {
        "address": "1423e4e89f9d5913f2fa4f5ecf60a3e2775e4152",
        "owner": "bitfinex",
        "owner_type": "exchange"
      },
      "timestamp": 1550237833,
      "amount": 90.40528,
      "amount_usd": 11106.731,
      "transaction_count": 1
    }
  ]
}

HTTP Request

GET /v1/transactions

URL Parameters

Parameter	Type	Description
start	int	(Required) Unix timestamp for retrieving transactions from timestamp (exclusive). Retrieves transactions based on their execution time on the blockchain.
end	int	Unix timestamp for retrieving transactions until timestamp (inclusive).
cursor	string	Pagination key from the previous response. Recommended when retrieving transactions in intervals.
min_value	int	Minimum USD value of transactions returned (value at time of transaction). Allowed minimum value varies per plan ($500k for Free, $100k for Personal).
limit	int	Maximum number of results returned. Default 100, max 100.
currency	string	Returns transactions for a specific currency code. Returns all currencies by default.

Errors

When an error is encountered you will receive an HTTP status code along with a message and error code in the body of the response.

We use the following status codes for errors:

Error Code	Meaning
200	Ok -- The request was successful.
400	Bad Request -- Your request was not valid.
401	Unauthorized -- No valid API key was provided
403	Forbidden -- Access to this resource is restricted for the given caller.
404	Not Found -- The requested resource does not exist.
405	Method Not Allowed -- An invalid method was used to access a resource.
406	Not Acceptable -- An unsupported format was requested.
429	Too Many Requests -- You have exceeded the allowed number of calls per minute. Lower call frequency or upgrade your plan for a higher rate limit.
500	Internal Server Error -- There was a problem with the API host server. Try again later.
503	Service Unavailable -- API is temporarily offline for maintenance. Try again later.