Live · 7 endpoints · OpenAPI 3.0 · Trial available

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.

9.6M+whale transactions 1.24M+scored addresses 712entity labels 3.85MMeiklejohn clusters OpenAPI 3.0spec at /v1/openapi.json

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.

MethodPathWhat 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.

🔍 Open in Swagger Editor 📖 Browse via SwaggerHub 📮 Import to Postman 📄 Raw JSON
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)
Monthly request budget 10,000
Per-minute rate limit 60
All 7 endpoints
CSV bulk export
HMAC signed requests (optional)
OpenAPI 3.0 spec
Academic / institutional discount
Auto-activated Telegram / Google / email login

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.

401 missing_auth
Authorization header missing or malformed
Add Authorization: Bearer swi_live_.... Header must be present even on browser-CORS preflight.
401 invalid_key
API key not found or revoked
Token doesn't match any active key. Check for typos, or generate a new one at /api-access.
403 tier_blocked
Endpoint not in your tier
Trial keys cannot access certain endpoints during evaluation. Upgrade to Research or contact support for academic access.
404 not_found
Resource doesn't exist
For /whale/{txid} and /address/{addr}: not in our whale-tracking cache. Try /address/{addr}/lookup for any-address resolution.
429 rate_limited
Hit per-minute or monthly ceiling
Honour Retry-After header. Check X-RateLimit-Remaining on every successful response to throttle proactively.
502 upstream_error
mempool.space upstream failed
Only on /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?
Log in to dashboard.btcwhalealerts.com via Telegram, Google or email. Every login activates a 90-day Trial (10k requests/month) automatically. Visit /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?
Same data, different transport. REST is for traditional applications (Python, Node.js, Go) that pull data on a schedule or in response to user actions. MCP is for AI assistants (Claude, Cursor, ChatGPT) that call tools conversationally. Both authenticate to the same backend; choose based on your client. See /mcp/ for the MCP server.
Is HMAC required?
No. Bearer token alone is sufficient. HMAC signing is an optional defence-in-depth layer for environments where Bearer tokens might leak (logs, proxies, mobile apps). It signs 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?
Two ceilings: monthly (10k Trial / 100k Research) and per-minute (60). When you hit either, the response is HTTP 429 with a 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?
The 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?
Yes. The spec at /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?
Your account stays active and your dashboard access is unaffected — only the API key stops accepting calls (returns 401 invalid_key with a hint). Re-Trial is not available (one Trial per stable identifier: Telegram ID, Google sub, or verified email). Upgrade to Research at any time on /api-access; your existing key keeps working with the new ceiling.
What's your uptime / SLA?
No formal SLA on Trial. Research tier has a 99.5% monthly uptime target measured by external uptime checks. Outages are reported on our Bluesky feed (@btcwhalealerts.com) and via email if you've registered. Planned maintenance windows are announced at least 48h in advance.
Where do I report bugs or request endpoints?
Email [email protected] with the request URL, expected vs actual response, and your 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.