Whale Data API for Trading Bots & Desks: Limits, Fields and Setup

A trading bot or desk dashboard asks an API the same few questions over and over: what moved since my last call, how big was it, which wallet, and was it a trade or a transfer? The API that serves it well has stable fields, a cursor to page through new moves without gaps, clear error codes, a call budget that fits the polling rate, and a license that covers the way the bot is run. This page lays out those points for Deep Blue Alpha and the main alternatives.

The endpoints a bot actually uses

A minimal polling loop (Python)

import time, requests
BASE = "https://deepbluealpha.io/api/v1"
H = {"X-API-Key": "dba_your_key_here"}
seen = set()

while True:
    r = requests.get(f"{BASE}/transactions", headers=H, params={"limit": 50}, timeout=10)
    if r.status_code == 429:          # daily limit: wait for 00:00 UTC
        time.sleep(600); continue
    r.raise_for_status()
    for tx in r.json()["data"]["transactions"]:
        key = (tx.get("tx_hash"), tx.get("wallet_address"), tx.get("direction"))
        if key in seen:
            continue
        seen.add(key)
        handle(tx)                    # your logic; check the label before calling it a trade
    time.sleep(6)                     # ~14,400 calls/day

A 6-second loop uses about 14,400 calls/day, inside the Whale plan’s 25,000. Several bots on one account, or faster loops, are what the Business plan’s 250,000 calls/day and 5 keys are for.

Bot-facing limits compared

Turning rows into bot features

Each move row carries seven fields: time_utc, tx_hash, wallet, token, action, usd_value and venue_type. Bots commonly derive a handful of features from them, and each one should stay split by venue:

• Net exchange flow per token over a rolling window: exchange_withdraw_usd − exchange_deposit_usd from /token/{symbol}/flow, or summed from rows.
• Net DEX flow per token: dex_buy_usd − dex_sell_usd. This is the only part that reflects trades.
• Distinct wallets moving a token in a window (the wallets field), which separates one large wallet from a broad move.
• Size filters: ignore rows under your own USD floor so small moves do not trigger logic.
• Wallet-level history: keep your own record per wallet from the rows you collect, since the tracked set changes over time.

Two caveats bots should handle explicitly. First, Ethereum moves can be revised by chain reorganizations or arrive late during provider outages, so a bot should tolerate a late row rather than assume the stream is complete. Second, USD values are approximations at the time of the move and can be off for thinly traded tokens; rows priced implausibly are rejected before they are stored.

Polling now, push later

Today a bot polls /transactions. When the Business plan opens, its firehose webhook (launching soon) is planned to push one signed POST per tracked whale move with filters by coin, move type and USD size, which removes most polling. Keeping the polling loop as a backstop is still good practice. See crypto whale webhook APIs for the push options that exist today.

Five rules for a bot that reads whale flow

1. Budget your calls. Count polls per minute per bot. A bot polling /transactions every 5 seconds uses 17,280 calls/day; the Whale plan allows 25,000/day per account and Business 250,000/day across up to 5 keys.
2. Paginate with a cursor, not offsets. Store next_before_id from each /api/v1/transactions response and request older pages with before_id so you never skip or repeat a move.
3. Deduplicate on tx hash, wallet and direction. One transaction can produce more than one row (for example a swap touching two tracked wallets). Use the three together as your key.
4. Treat exchange transfers and swaps differently. Only SWAP_BUY and SWAP_SELL are trades. CEX_WITHDRAW and CEX_DEPOSIT are transfers; model them as separate features.
5. Handle 401, 403 and 429. 401 = bad key, 403 = plan below Whale, 429 = daily limit reached until 00:00 UTC. Back off on 429 instead of retrying in a loop.

Plans