NAV Navbar

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:

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.