Deep Blue Alpha API
Pull DBA's whale intelligence as JSON — into your spreadsheets, bots, dashboards, and models. Read-only, key-authenticated, available on the Whale tier.
What you get
Six read-only JSON endpoints over the same tracked-whale data the website runs on:
/whale-indexToday's 0–100 Whale Sentiment Index, its context components and 30-day history./top-tokensTokens ranked by tracked whale volume over 1H, 24H or 7D, with net flow per token./top-walletsThe whale wallet leaderboard: address, label, rank and tracked volume./transactionsThe latest whale moves, newest first, with cursor pagination./token/{symbol}/flowOne token's whale flow over 24h, 7d and 30d, split into DEX swaps and exchange transfers./watchlistYour own saved wallets and tokens with 7-day net flow for each.
429 until the reset.Your first request
Copy, paste, swap in your key:
curl -s -H "X-API-Key: dba_your_key_here" \ https://deepbluealpha.io/api/v1/token/LINK/flow
Response shape EXAMPLE VALUES
{
"data": {
"symbol": "LINK",
"windows": {
"24h": {
"net_flow_usd": 250000.00,
"buy_volume_usd": 1000000.00,
"sell_volume_usd": 750000.00,
"trades": 40,
"wallets": 12,
"dex_buy_usd": 50000.00,
"dex_sell_usd": 25000.00,
"exchange_withdraw_usd": 950000.00,
"exchange_deposit_usd": 725000.00
},
"7d": { ...same fields... },
"30d": { ...same fields... }
}
},
"meta": {
"tier": "whale",
"endpoint": "/api/v1/token-flow",
"generated_at": "2026-01-01T00:00:00+00:00"
}
}
The numbers above are placeholders to show the shape, not live data. buy_volume_usd is the accumulation side (DEX buys plus coins pulled off exchanges) and sell_volume_usd the distribution side (DEX sells plus coins sent to exchanges); the four split fields show how much of each was a real swap versus an exchange transfer.
Using Claude, ChatGPT or Cursor? Connect them to our free MCP server at deepbluealpha.io/mcp — no key needed.
Try every endpoint in Postman: open the Deep Blue Alpha collection → · Machine-readable spec: OpenAPI 3.0 (JSON)
Authentication
Every request needs your API key in the X-API-Key header. (The older ?api_key= query parameter still works but is deprecated: keys in URLs end up in browser history and proxy logs, so please switch to the header.) Generate a key from your account page (Whale tier). Keys are shown once at creation — store them securely.
curl -H "X-API-Key: dba_your_key_here" \ https://deepbluealpha.io/api/v1/whale-index
Base URL: https://deepbluealpha.io/api/v1 · Rate limit: 25,000 requests/day per API key (Whale) · All responses are JSON in the shape { "data": …, "meta": { "tier", "endpoint", "generated_at" } }.
Endpoints
tf = 1H | 24H | 7D. Stablecoins excluded.before_id (use next_before_id from the response). Each row has an exchange field naming the exchange on exchange moves (empty on DEX swaps).dex_buy_usd, dex_sell_usd, exchange_withdraw_usd, exchange_deposit_usd. ETH includes native ETH, recorded as WETH.Endpoint reference pages
One page per endpoint group, each with parameters, auth, limits, curl and Python examples and a sample response:
- Recent whale movesAPI to track large Ethereum wallet transfers: GET /api/v1/transactions returns the latest moves by 20,000+ tracked whale wallets, labeled exchange deposit, exchange withdrawal or DEX swap.
- Token whale flowPer-token Ethereum whale flow over 24h, 7d and 30d: net flow, exchange withdrawals and deposits, DEX swaps, moves and distinct whale wallets. Fields, curl and Python example.
- Top whale tokensTokens ranked by tracked Ethereum whale volume with net flow per token. Free no-key endpoint (top 10, 24h) and authenticated endpoint (1H, 24H or 7D, up to 100).
- Whale Sentiment IndexDaily 0–100 Whale Sentiment Index for Ethereum whale flow as JSON: score, label, components, and 30-day history. Free no-key endpoint plus an authenticated one.
- Whale wallets & watchlistGET /api/v1/top-wallets returns tracked Ethereum whale wallets (address, label, rank, tracked volume); GET /api/v1/watchlist returns your saved wallets and tokens with 7-day net flow.
- Free stats endpointFree Ethereum whale data with no API key: /api/v1/public/stats, /top-tokens and /whale-index. JSON, CORS enabled, cached 60s, CC BY 4.0. Fields and examples.
- Graded whale signalsEvery Deep Blue Alpha whale signal since April 2026 with 1/7/30-day % change and ETH over the same window, graded on closing prices. /api/v1/signals, /signals/summary, backtests by key.
- Real-time webhooksReal-time whale transaction webhook API: one signed JSON POST for every move by 20,000+ tracked Ethereum whale wallets, filterable by coin, move type and USD size. Payload, signature, retries.
- Daily data filesDaily files of every move by tracked Ethereum whale wallets (CSV + JSONL), per-coin totals, manifest with SHA-256, graded signals. History from Jul 1, 2026 (DEX) and Sep 6, 2026 (exchange).
- MCP server (AI agents)Free Model Context Protocol server for Ethereum whale data at deepbluealpha.io/mcp: 7 read-only tools for AI agents. Streamable HTTP, no auth, 120 calls per 10 minutes. Setup and tools.
Example response: /top-tokens EXAMPLE VALUES
{
"data": {
"timeframe": "24H",
"tokens": [
{ "symbol": "LINK", "net_flow_usd": 1174687.65,
"buy_volume_usd": 4820102.1, "sell_volume_usd": 3645414.45, "trades": 128 }
]
},
"meta": { "tier": "whale", "endpoint": "/api/v1/top-tokens",
"generated_at": "2026-08-18T20:00:00+00:00" }
}
Business plan: higher limits, webhooks and daily files
How every field is built (exchange vs DEX labels, whale scope, pricing, history): see the data methodology.
Business: $299/month or $2,990/year (subscribe). This section documents what a Business plan includes, so you can plan an integration now. Business is for commercial use inside your organization (see the Business & API Terms); the Whale plan’s API is for personal use. Questions: team@deepbluealpha.io.
- API: 250,000 requests/day per account (all keys counted together), up to 5 keys. Same endpoints and responses;
meta.planis"business". - Webhooks: up to 3 HTTPS endpoints. One signed JSON POST for each new move by a tracked whale wallet, filtered by coin, move type and minimum USD size.
- Daily files: one set of files per UTC day. History: exchange moves from 2026-09-06, DEX swaps from 2026-07-01.
- Graded whale signals: every whale signal Deep Blue Alpha has fired since April 2026, with the coin’s % change 1, 7 and 30 days later and ETH’s change over the same window, graded on closing prices. As a daily-refreshed file and through
/api/v1/signalsand/api/v1/signals/summary. - Backtests by API:
POST /api/backtest/runaccepts a Business API key. - Exchange names: every exchange move in the files,
/api/v1/transactionsand webhooks carries anexchangefield (Binance, Coinbase, OKX, Kraken, …).
Webhook events
Add endpoints in your account. Each event is a POST with Content-Type: application/json, sent within seconds of the move being recorded:
{
"type": "whale_move",
"event_id": "mv_8812345",
"api_version": "2026-10-16",
"time_utc": "2026-10-16T10:41:23Z",
"tx_hash": "0x8b85…2b93",
"wallet": "0x83d8…e09e",
"token": "LINK",
"action": "CEX_WITHDRAW",
"usd_value": 412500.00,
"venue_type": "exchange",
"exchange": "Binance",
"flow": "withdrawn_from_exchange"
}
action:CEX_WITHDRAW/CEX_DEPOSIT(venue_type: "exchange") are transfers to or from an exchange, not purchases or sales.SWAP_BUY/SWAP_SELL(venue_type: "dex") are DEX swaps. These four are all you get on files and webhooks./api/v1/transactionscan also returnBOT_SWAP_BUY/BOT_SWAP_SELL(swaps by high-frequency bot wallets) andNONCOIN_SWAP(stablecoin, yield-token or re-wrap swaps, not a coin trade).flow:withdrawn_from_exchange,deposited_to_exchange,dex_swap_buyordex_swap_sell.exchange: the exchange on the other side of an exchange move (for exampleBinance,Coinbase,OKX,Kraken); empty on DEX swaps. Names come from our exchange address list (hand-checked plus public labels) and are heuristic.- Same fields as the free sample file;
event_idmatches theevent_idcolumn in the daily files. - The “Send test” button posts
{"type": "test", …}.
Verify the signature
Every request carries X-DBA-Signature: t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 of "<t>." + raw request body keyed with your webhook’s signing secret (whsec_…, shown once when you create the webhook or rotate the secret). Also sent: X-DBA-Event-Id, X-DBA-Timestamp. Check the signature on the raw bytes, before parsing, and reject timestamps older than 5 minutes.
import hmac, hashlib, time
def verify(secret: str, body: bytes, header: str, tolerance: int = 300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
ts, sig = int(parts["t"]), parts["v1"]
if abs(time.time() - ts) > tolerance:
return False
want = hmac.new(secret.encode(), f"{ts}.".encode() + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(want, sig)
Delivery, retries and pausing
- Reply with any
2xxwithin 10 seconds. Redirects are not followed. - Failed deliveries are retried after about 5 seconds, 30 seconds, 2 minutes and 10 minutes (5 tries).
- Events can arrive out of order and, rarely, more than once: de-duplicate on
event_idand order ontime_utc. - If your endpoint fails 20 events in a row over more than an hour, the webhook is paused, and we email you unless you’ve unsubscribed; the notice always shows in your account. Turn it back on there; moves you missed are in the daily files.
- Moves from DEX history that we fill in after the fact can arrive minutes or hours after their
time_utc. - Each webhook has a 7-day delivery log in your account.
- Endpoints must be public HTTPS addresses; private, loopback and internal addresses are refused.
Daily data files
Moves by tracked whale wallets, one set per UTC day, ready shortly after 00:40 UTC. The two most recent days are rebuilt once more so late-arriving moves land in their day. Download from your account, or with your API key (each call counts toward your daily limit):
curl -H "X-API-Key: dba_YOUR_KEY" https://deepbluealpha.io/data/files curl -H "X-API-Key: dba_YOUR_KEY" -O https://deepbluealpha.io/data/files/dba_whale_moves_2026-10-15.csv.gz
dba_whale_moves_YYYY-MM-DD.csv.gz— every move:time_utc, tx_hash, wallet, token, action, usd_value, venue_type, event_id, exchange(exchangenames the exchange on exchange moves, empty on DEX swaps)dba_whale_moves_YYYY-MM-DD.jsonl.gz— the same rows as JSON Linesdba_token_totals_YYYY-MM-DD.csv.gz— per coin: moves, wallets, exchange withdrawn / deposited / net, DEX swap buy / sell / netdba_manifest_YYYY-MM-DD.json— row counts, a SHA-256 for each file and the day’scoveragedba_graded_signals.csv.gz— every graded whale signal (rewritten daily; see below)- History: DEX swaps from 2026-07-01, exchange moves from 2026-09-06 (full coverage from that day). DEX coverage was thinner in July and August; days before 2026-09-06 are marked
coverage: dex_onlyin their manifest. Scope: tracked whale wallets as of the day the file was built. Labels are heuristic — see the methodology.
Graded whale signals
Every whale signal Deep Blue Alpha has fired since April 2026, each with the coin’s % price change 1, 7 and 30 days after the signal and ETH’s change over the same window. Graded on closing prices, never peaks: entry = median price within 2 hours of the signal; outcome = median price around +1d / +7d / +30d. Blank = not matured yet or no price data. Business plan only. Past results do not predict future results. Not investment advice.
start, end (YYYY-MM-DD; default the last 30 days; max 400-day window), signal_type (comma-separated), token, graded_only (only rows with a 7-day result). limit up to 1,000 per page; page with after_id = next_after_id from the response (null on the last page). Fields: signal_id, fired_at_utc, signal_type, token, token_address, entry_price_usd, ret_1d_pct, ret_7d_pct, ret_30d_pct, eth_1d_pct, eth_7d_pct, eth_30d_pct, vs_eth_7d_pct, verdict_7d, complete.n, hit rate (share with a 7-day result above +1%), verdict counts, average and median 7-day result, and the share that beat ETH over the same 7 days. Same start / end / signal_type / token filters.verdict_7d: BIG_WIN above +10%, WIN above +1%, FLAT above −1%, else LOSS. The same rows ship as dba_graded_signals.csv.gz in /data/files, refreshed daily.
Backtests by API
POST /api/backtest/run accepts a Business API key in the X-API-Key header (each run counts toward your daily limit). In the browser, the backtest page still needs Alpha or higher. Body:
curl -X POST -H "X-API-Key: dba_YOUR_KEY" -H "Content-Type: application/json" \
-d '{"start":"2026-08-01","end":"2026-09-30","signal_types":[]}' \
https://deepbluealpha.io/api/backtest/run
start,end(required):YYYY-MM-DDor an ISO datetime.endmust be afterstart, not in the future, and at most 365 days later.signal_types(optional): a list of signal type names; empty or missing runs every type. Unknown names return400.- Results are graded on the 7-day close (same rule as above). Past results do not predict future results. Not investment advice.
Errors
401— missing / invalid / revoked key403— key belongs to a tier below Whale (and has no Business plan)429— daily rate limit reached (resets at UTC midnight); body:{"error": "Daily rate limit reached (…requests/day). Resets at UTC midnight."}503— whale index temporarily unavailable
Changelog
- 2026-10-17 — Business: graded whale signals (
/api/v1/signals,/api/v1/signals/summaryand the dailydba_graded_signals.csv.gzfile);POST /api/backtest/runaccepts a Business API key; a newexchangefield names the exchange on every exchange move in/api/v1/transactions, the daily files and webhooks (empty on DEX swaps); daily files now go back to 2026-07-01 for DEX swaps and 2026-09-06 for exchange moves, and are no longer limited to the last 90 days. Existing fields are unchanged. - 2026-10-16 — Business plan live (card or crypto): 250,000 requests/day per account across up to 5 keys, signed webhooks for each tracked whale move, and daily data files (
/data/files). The OpenAPI spec now includes the Business endpoints. Responses to Whale keys are unchanged; Business keys addmeta.plan. - 2026-10-07 —
/top-tokens,/transactions,/token/{symbol}/flowand watchlist token metrics now count only tracked whale wallets (an exchange transfer counts when the wallet on our side is a tracked whale) and drop rows priced above $1B. Before this, those endpoints also included exchanges' own internal transfers, which inflated volumes and could flip a token's net-flow direction. Figures now match the website, daily reports and Whale Sentiment Index. Response fields are unchanged. The same applies to the free/api/v1/public/top-tokensand the 24h volume figures in/api/v1/public/stats.
Not financial advice
API data is on-chain analytics for informational purposes only — not financial advice. Past whale activity is not predictive of future results.