Bitcoin whale data via REST
Hello world in 60 seconds. Sign up via Telegram, Google or email on the dashboard. Every login auto-activates a 90-day Trial. Generate a Bearer token. Curl. Done.
7 REST endpoints over the same data that powers the dashboard, MCP server, and Bluesky alerts. Bearer auth, optional HMAC signing, OpenAPI 3.0.3 machine-readable spec, structured JSON errors with hint fields, rate-limit headers on every response.
60-second quickstart
Three steps from zero to JSON in your terminal. No SDK install, no boilerplate, no signup wizard.
1 Get a key
Log in to dashboard.btcwhalealerts.com via Telegram, Google or email. Every login auto-activates a 90-day Trial (10k requests/month). Open /api-access, click Create Key, copy the token.
2 Test ping (no auth)
Verify connectivity before authenticating:
curl https://dashboard.btcwhalealerts.com/v1/ping
Returns {"ok":true,"time":"..."}
3 Authenticated call
Replace $SWI_KEY with your token:
export SWI_KEY="swi_live_abc_xyz..."
curl -H "Authorization: Bearer $SWI_KEY" \
https://dashboard.btcwhalealerts.com/v1/whales/recent?limit=5
Returns the 5 most recent whale transactions as JSON.
7 endpoints
All under https://dashboard.btcwhalealerts.com/v1/. Full OpenAPI 3.0.3 spec at /v1/openapi.json — paste into Swagger Editor or use openapi-generator for typed SDKs.
| Method | Path | What it returns |
|---|---|---|
| GET | /ping Public | Health-check, no auth. Returns {"ok":true,"time":"..."}. |
| GET | /stats Bearer | Coverage + activity snapshot: total whale-tx count, today's count, address-cache size, last-block timestamp. |
| GET | /whales/recent Bearer | Recent whale transactions. Query: limit, min_btc, flow_type (to_exchange, from_exchange, w2w, e2e), cursor for pagination. |
| GET | /whale/{txid} Bearer | Single transaction detail with sender/recipient cluster, flow type, USD-at-tx price, fee rate, entity labels. |
| GET | /address/{addr} Bearer | Address metrics from our whale-tracking cache: balance, tx count, cluster ID, entity label, volume index 0-1. |
| GET | /address/{addr}/lookup Bearer | Any-address lookup via mempool.space proxy (5-min cache, 5 QPS shared). Works for addresses NOT in whale cache. Optional utxos=1, txs=1, tx_limit=N. |
| GET | /sentiment Bearer | Confidence-weighted community sentiment from Reddit + Telegram + Bluesky. Updates every 30 min. |
| GET | /whales/export.csv Bearer | Streaming CSV bulk export. Max 100k rows. Same filters as /whales/recent. |
Open in your favourite tool
The OpenAPI 3.0.3 spec lives at /v1/openapi.json. It now includes components.schemas with examples for every response — typed SDK generators (openapi-generator, openapi-typescript) produce real DTOs, not empty stubs.
Generate a typed SDK
# Python
openapi-generator generate -i https://dashboard.btcwhalealerts.com/v1/openapi.json \
-g python -o swi-client-py
# TypeScript (fetch)
openapi-generator generate -i https://dashboard.btcwhalealerts.com/v1/openapi.json \
-g typescript-fetch -o swi-client-ts
# Or lighter via openapi-typescript:
npx openapi-typescript https://dashboard.btcwhalealerts.com/v1/openapi.json -o swi.d.ts
Authentication
Bearer token in the Authorization header. HMAC signing optional for hardened workflows.
Token format: swi_live_<keyid>_<secret>. Get yours on the dashboard /api-access page.
curl -H "Authorization: Bearer swi_live_abc_xyz" \
https://dashboard.btcwhalealerts.com/v1/whales/recent?limit=5
Every successful response includes X-RateLimit-Limit-Monthly, X-RateLimit-Remaining, and X-RateLimit-Reset. 429 responses include Retry-After.
Optional defence-in-depth. Sign timestamp.method.path.body with HMAC-SHA256 + your separate HMAC secret (created when you create the API key with HMAC enabled). Send token + signature + timestamp:
TS=$(date +%s)
SIG=$(echo -n "${TS}.GET./v1/whales/recent." | openssl dgst -sha256 -hmac "$HMAC_SECRET" | awk '{print $2}')
curl -H "Authorization: Bearer swi_live_abc" \
-H "X-Signature: sha256=$SIG" \
-H "X-Timestamp: $TS" \
https://dashboard.btcwhalealerts.com/v1/whales/recent
Replay window: 5 minutes. Use this only when Bearer leakage is a real threat (mobile clients, log aggregation, CI logs).
import os, requests
BASE = "https://dashboard.btcwhalealerts.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SWI_KEY']}"}
r = requests.get(f"{BASE}/whales/recent",
params={"limit": 10, "min_btc": 1000, "flow_type": "to_exchange"},
headers=HEADERS, timeout=10)
r.raise_for_status() # works correctly — 4xx/5xx have correct status codes
for tx in r.json()["data"]:
print(tx["txid"], tx["btc_amount"], tx["flow_type"])
const BASE = "https://dashboard.btcwhalealerts.com/v1";
const res = await fetch(`${BASE}/whales/recent?limit=10&min_btc=1000`, {
headers: { Authorization: `Bearer ${process.env.SWI_KEY}` },
});
if (!res.ok) throw new Error(`API ${res.status}: ${await res.text()}`);
const { data } = await res.json();
for (const tx of data) {
console.log(tx.txid, tx.btc_amount, tx.flow_type);
}
Tiers
Trial for evaluation, Research for production. Cancel anytime, no fees, Trial keeps working.
| Trial | Research | |
|---|---|---|
| Price | Free (90 days) | 149 CHF / month |
| Monthly request budget | 10,000 | 100,000 |
| Per-minute rate limit | 60 | 60 |
| All 7 endpoints | ✓ | ✓ |
| CSV bulk export | ✓ | ✓ |
| HMAC signed requests | ✓ (optional) | ✓ (optional) |
| OpenAPI 3.0 spec | ✓ | ✓ |
| Academic / institutional discount | — | On request |
| Auto-activated | Telegram / Google / email login | Stripe checkout from /api-access |
Trial expires after 90 days but you keep the account. Re-Trial is not available (one Trial per stable identifier — Telegram ID, Google sub, or verified email). Upgrade to Research at any time; your existing API key keeps working with the new ceiling.
Error reference
All errors return JSON with {"error":{"code":"...","message":"..."}} and the correct HTTP status code. Some include a hint field with corrective action.
Authorization: Bearer swi_live_.... Header must be present even on browser-CORS preflight./api-access./whale/{txid} and /address/{addr}: not in our whale-tracking cache. Try /address/{addr}/lookup for any-address resolution.Retry-After header. Check X-RateLimit-Remaining on every successful response to throttle proactively./address/{addr}/lookup. Retry after 30 seconds — our cache absorbs short blips.
Calls to https://api.btcwhalealerts.com with paths like /v1/whales/recent return a hint field pointing you to the correct host (dashboard.btcwhalealerts.com/v1/...). The api. subdomain hosts a separate HMAC-signed alert-detail surface; the public Dev-API lives on dashboard..
Ready to ship?
One Telegram, Google or email login on the dashboard activates a 90-day Trial automatically. No credit card. No demo call. No sales gate.
Get API key →FAQ
How do I get an API key?
/api-access on the dashboard to generate your Bearer token. The key is shown once at creation — copy it to a password manager immediately.
What's the difference between this REST API and your MCP server?
Is HMAC required?
timestamp.method.path.body with HMAC-SHA256 and a separate secret, so a leaked Bearer token alone can't be replayed.
How do rate limits work?
Retry-After header (in seconds). Successful responses include X-RateLimit-Limit-Monthly, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix timestamp). Throttle proactively when remaining drops below 5% of your budget.
Why does api.btcwhalealerts.com return 404 for the Dev-API paths?
api. subdomain hosts a separate HMAC-signed alert-detail API used by the public TX-detail pages. The public Dev-API lives at dashboard.btcwhalealerts.com/v1/ for historical reasons. As of 2026-04-30, calls to api.btcwhalealerts.com/v1/whales/recent (and similar Dev-API paths) return a 404 with a hint field pointing you to the correct host.
Can I generate an SDK from the OpenAPI spec?
/v1/openapi.json is OpenAPI 3.0.3, validates clean against Swagger Editor. For Python: openapi-generator generate -i .../v1/openapi.json -g python -o swi-client. For TypeScript: same command with -g typescript-fetch. We don't ship pre-built SDKs because the surface is small enough that hand-rolling a client is faster than maintaining auto-generated bindings across 5 languages.
What happens when my Trial expires?
/api-access; your existing key keeps working with the new ceiling.
What's your uptime / SLA?
Where do I report bugs or request endpoints?
cf-ray header value (visible in any error response) — that lets us pull the relevant logs. For new endpoint requests, describe the use case; we add what real workflows need, not speculative APIs.