{"uid":"cap_xM9FbZjx14iaRgyc-Ah9k","slug":"btc-liquidation-cluster-heatmap-api-b54c0a70","name":"BTC Liquidation Cluster Heatmap API","description":"BTC liquidation cluster heatmap API: estimated aggregate notional trapped in long-liquidation pockets below current BTC price and short-liquidation pockets above it. Returns the heaviest cluster on each side, tier tags (HEAVY/MEDIUM/LIGHT), total notional per side, source venues, and an explicit DIY-model accuracy disclaimer. Complements /api/liq-aggregate (actual liquidation tape) with forward-looking cluster geometry.","url":"https://nonvisceral-eloisa-mousily.ngrok-free.dev/api/liq-cluster","method":"GET","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["input"],"properties":{"input":{"type":"object","required":["type","method"],"properties":{"type":{"type":"string","const":"http"},"method":{"enum":["GET"],"type":"string"},"queryParams":{"type":"object","properties":{}}},"additionalProperties":false},"output":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"example":{"type":"object","properties":{"clusters":{"type":"object"},"btc_price":{"type":"number"},"updated_at":{"type":"string"},"state_fresh":{"type":"boolean"},"accuracy_note":{"type":"string"},"source_venues":{"type":"array"},"history_snapshots":{"type":"number"},"top_cluster_above":{"type":"object"},"top_cluster_below":{"type":"object"},"history_days_covered":{"type":"number"},"bot_state_age_seconds":{"type":"number"},"price_bucket_size_pct":{"type":"number"},"total_notional_long_below_usd":{"type":"number"},"total_notional_short_above_usd":{"type":"number"}}}}}}},"responseSchema":null,"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.02","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.02/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.02","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.02","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_G_IQuDhgH1eiUnKW7i-0R","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.02","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Returns estimated aggregate notional value trapped in BTC long-liquidation pockets below and short-liquidation pockets above the current price, with tier tags and cluster geometry.","exampleAgentPrompt":"Show me the current BTC liquidation cluster heatmap — I want to know the heaviest long-liquidation pocket below price and short-liquidation pocket above price, with tier tags and total notional on each side.","exampleUseCases":[{"title":"Pre-trade liquidation risk check","prompt":"Before I open a large BTC long position, can you pull the liquidation cluster data and tell me where the biggest short-squeeze clusters are above current price and how heavy the long-liquidation pockets below are?"},{"title":"Market regime analysis for algo strategy","prompt":"I'm building a BTC trading algo — pull the liquidation cluster heatmap so I can see the total notional trapped on each side and the tier tags for the top clusters above and below current price."},{"title":"Real-time volatility watch for risk desk","prompt":"Can you check the BTC liquidation cluster geometry right now and flag if any cluster on either side is tagged HEAVY, and tell me the total notional at risk above and below current price?"}],"resultDescription":"Returns a JSON object with: current BTC price, top liquidation cluster above price (with notional and tier tag), top liquidation cluster below price (with notional and tier tag), full clusters map, total notional for long-liquidation pockets below (USD), total notional for short-liquidation pockets above (USD), source venues list, state freshness flag, bot state age in seconds, price bucket size percentage, history snapshot count, days covered, and an explicit accuracy disclaimer noting this is a DIY model estimate.","failureModes":["Stale data if upstream venue feeds are delayed (state_fresh: false)","Partial venue coverage if Binance/Bybit liquidation feeds are unavailable (only OKX + Hyperliquid)","Model inaccuracy due to estimated cluster geometry rather than actual order book data","Service unavailability if ngrok tunnel is down","Empty or null cluster objects if insufficient history snapshots exist"],"whenToPreferThis":"Choose this endpoint when you need forward-looking BTC liquidation cluster geometry — i.e., where trapped notional is likely to trigger cascading liquidations — rather than the actual historical liquidation tape (use /api/liq-aggregate for that). Best for pre-trade risk assessment, volatility regime analysis, or identifying key price levels where liquidation cascades could accelerate moves. Note the built-in accuracy disclaimer: this is a model estimate, not exchange-reported data.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T00:41:48.310Z","isFirstParty":false}