{"components":{"responses":{"BadGateway":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Upstream service error."},"NotFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Resource not found. Hint field may suggest corrective action."},"RateLimited":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded. Honour Retry-After header."},"Unauthorized":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Authentication required or failed. Includes X-RateLimit-* headers when key was identified."}},"schemas":{"AddressLookupResponse":{"properties":{"_source":{"enum":["electrs","mempool.space","cache"],"example":"mempool.space","type":"string"},"address":{"type":"string"},"balance_btc":{"example":0.0432,"type":"number"},"tx_count":{"example":17,"type":"integer"},"txs":{"items":{"type":"object"},"nullable":true,"type":"array"},"utxos":{"items":{"type":"object"},"nullable":true,"type":"array"}},"type":"object"},"AddressMetrics":{"properties":{"address":{"example":"bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh","type":"string"},"balance_btc":{"example":4128.5,"type":"number"},"cluster_id":{"example":184273,"nullable":true,"type":"integer"},"entity_label":{"example":"Binance Cold Storage","nullable":true,"type":"string"},"first_seen":{"example":"2018-03-12T14:22:00+00:00","format":"date-time","type":"string"},"last_seen":{"example":"2026-04-30T07:11:00+00:00","format":"date-time","type":"string"},"tx_count":{"example":1247,"type":"integer"},"volume_index_calibrated":{"example":0.84,"maximum":1,"minimum":0,"type":"number"}},"type":"object"},"ErrorResponse":{"properties":{"error":{"properties":{"code":{"example":"missing_auth","type":"string"},"message":{"example":"Authorization header missing or malformed","type":"string"}},"required":["code","message"],"type":"object"}},"required":["error"],"type":"object"},"PingResponse":{"properties":{"ok":{"example":true,"type":"boolean"},"time":{"example":"2026-04-30T11:23:45.123456+00:00","format":"date-time","type":"string"}},"type":"object"},"SentimentResponse":{"properties":{"label":{"example":"neutral-bullish","type":"string"},"platforms":{"additionalProperties":{"type":"number"},"example":{"bluesky":65.0,"reddit":58.2,"telegram":64.1},"type":"object"},"score":{"example":62.4,"maximum":100,"minimum":0,"type":"number"},"updated_at":{"format":"date-time","type":"string"}},"type":"object"},"StatsResponse":{"properties":{"address_cache":{"example":1241387,"type":"integer"},"last_block":{"example":947812,"type":"integer"},"last_block_ts":{"example":"2026-04-30T11:18:42+00:00","format":"date-time","type":"string"},"today_whale_tx":{"example":2543,"type":"integer"},"total_whale_tx":{"example":9647821,"type":"integer"}},"type":"object"},"WhaleListResponse":{"properties":{"count":{"example":50,"type":"integer"},"data":{"items":{"$ref":"#/components/schemas/WhaleTx"},"type":"array"},"next_cursor":{"example":"eyJ0cyI6IjIwMjYtMDQtMzBUMDg6MTQ6MjJaIn0=","nullable":true,"type":"string"}},"type":"object"},"WhaleTx":{"properties":{"block_height":{"example":902456,"type":"integer"},"btc_amount":{"example":1247.83,"type":"number"},"fee_sat_per_vb":{"example":12.4,"type":"number"},"flow_type":{"enum":["to_exchange","from_exchange","wallet_to_wallet","exchange_to_exchange","self_send"],"example":"to_exchange","type":"string"},"recipient_label":{"example":"Binance Hot Wallet","nullable":true,"type":"string"},"sender_label":{"example":"Coinbase Custody","nullable":true,"type":"string"},"ts":{"example":"2026-04-30T08:14:22+00:00","format":"date-time","type":"string"},"txid":{"example":"f4184fc596403b9d638783cf57adfe4c75c605f6356fbc91338530e9831e9e16","type":"string"},"usd_at_tx":{"example":87412345.5,"type":"number"},"volume_index_calibrated":{"example":0.78,"type":"number"}},"type":"object"}},"securitySchemes":{"BearerAuth":{"bearerFormat":"swi_live_<keyid>_<secret>","description":"Bearer token created on dashboard /api-access page. Optional HMAC signing via X-Signature + X-Timestamp headers (replay window 5 min).","scheme":"bearer","type":"http"}}},"info":{"contact":{"email":"hello@btcwhalealerts.com","url":"https://btcwhalealerts.com"},"description":"Real-time Bitcoin on-chain intelligence: whale transactions, address metrics, sentiment. All endpoints (except /ping) require Bearer token. Rate limits: Trial 10k req/month, Research 100k req/month + 60 req/min. Successful and 4xx-after-key-lookup responses include X-RateLimit-Limit-Monthly, X-RateLimit-Limit-Per-Min, X-API-Tier headers.","license":{"name":"Commercial","url":"https://btcwhalealerts.com/terms/"},"termsOfService":"https://btcwhalealerts.com/terms/","title":"Swiss Whale Intelligence API","version":"1.0.0"},"openapi":"3.0.3","paths":{"/address/{addr}":{"get":{"parameters":[{"example":"bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh","in":"path","name":"addr","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressMetrics"}}},"description":"Aggregated address metrics"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Address not in whale-metrics cache \u2014 try /address/{addr}/lookup for any-address resolution"}},"summary":"Address metrics (whale-tracked only)"}},"/address/{addr}/lookup":{"get":{"description":"Resolves ANY valid Bitcoin address by proxying mempool.space (cached 5 min, rate-limited 5 QPS globally). Differentiation vs /address/{addr}: this works for addresses NOT in the whale-tracked set \u2014 useful for ad-hoc forensics, academic research, journalist source-checks. Returns balance_btc, tx_count, mempool stats. Optionally include UTXOs + recent TXs.","parameters":[{"in":"path","name":"addr","required":true,"schema":{"type":"string"}},{"description":"Include up to 50 unspent UTXOs","in":"query","name":"utxos","schema":{"default":false,"type":"boolean"}},{"description":"Include recent confirmed/mempool TXs","in":"query","name":"txs","schema":{"default":false,"type":"boolean"}},{"description":"Max recent TXs when txs=1","in":"query","name":"tx_limit","schema":{"default":25,"maximum":50,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressLookupResponse"}}},"description":"Address summary + optional UTXOs/TXs"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Address has no on-chain history per mempool.space"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/BadGateway"}},"summary":"Public any-address lookup (Research-tier)"}},"/ping":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PingResponse"}}},"description":"Service is up"}},"security":[],"summary":"Health check (no auth)"}},"/sentiment":{"get":{"parameters":[{"in":"query","name":"hours","schema":{"default":24,"maximum":720,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SentimentResponse"}}},"description":"Overall + per-platform sentiment"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Confidence-weighted community sentiment"}},"/stats":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}},"description":"Whale-tx and address-cache totals"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Coverage + activity snapshot"}},"/whale/{txid}":{"get":{"parameters":[{"example":"f4184fc596403b9d638783cf57adfe4c75c605f6356fbc91338530e9831e9e16","in":"path","name":"txid","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhaleTx"}}},"description":"Transaction metadata"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Single transaction detail"}},"/whales/export.csv":{"get":{"description":"Analyst-grade bulk export. Max 100k rows/request. Counts as 1 API call.","parameters":[{"in":"query","name":"days","schema":{"default":30,"maximum":365,"type":"integer"}},{"in":"query","name":"min_btc","schema":{"default":100,"type":"number"}},{"description":"Filter by flow classification. self_send = internal change-output sweeps.","in":"query","name":"flow","schema":{"enum":["to_exchange","from_exchange","wallet_to_wallet","exchange_to_exchange","self_send"],"type":"string"}},{"in":"query","name":"limit","schema":{"default":100000,"maximum":100000,"type":"integer"}}],"responses":{"200":{"content":{"text/csv":{"example":"txid,btc_amount,usd_at_tx,block_height,ts,flow_type,...\\nf4184fc...,1247.83,87412345.50,902456,2026-04-30T08:14:22+00:00,to_exchange,...","schema":{"type":"string"}}},"description":"text/csv stream (16 columns, UTF-8)"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Streaming CSV export (bulk data)"}},"/whales/recent":{"get":{"parameters":[{"in":"query","name":"limit","schema":{"default":50,"maximum":500,"type":"integer"}},{"in":"query","name":"min_btc","schema":{"default":100,"type":"number"}},{"description":"Filter by flow classification. self_send = internal change-output sweeps (Hot-Cold consolidations, not real cross-address flows).","in":"query","name":"flow","schema":{"enum":["to_exchange","from_exchange","wallet_to_wallet","exchange_to_exchange","self_send"],"type":"string"}},{"description":"Opaque cursor from previous page's next_cursor field (historical pagination).","in":"query","name":"before","schema":{"type":"string"}},{"description":"Legacy frontier streaming cursor \u2014 only works for rows since 2026-04 with populated id column.","in":"query","name":"since_id","schema":{"type":"integer"}},{"in":"query","name":"lang","schema":{"default":"en","enum":["en","de","es"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhaleListResponse"}}},"description":"Array of whale objects with intent classification"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Recent whale transactions (paginated)"}}},"security":[{"BearerAuth":[]}],"servers":[{"description":"Production","url":"https://dashboard.btcwhalealerts.com/v1"}]}