# BTC Liquidation Cluster Heatmap API

> BTC Liquidation Cluster Heatmap API is a paid API for AI agents from nonvisceral-eloisa-mousily.ngrok-free.dev, paid per call via x402, $0.02/call, status unknown (last checked 2026-09-14).

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.

## Facts

- Endpoint: GET https://nonvisceral-eloisa-mousily.ngrok-free.dev/api/liq-cluster
- Price: $0.02/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/btc-liquidation-cluster-heatmap-api-b54c0a70
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_xM9FbZjx14iaRgyc-Ah9k

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability btc-liquidation-cluster-heatmap-api-b54c0a70
```

Example prompt: 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.

## When to prefer this

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.

## Known failure modes

- 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

## How this service works

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.

## Output

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.

## Request schema (JSON Schema)

```json
{
 "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"
      }
     }
    }
   }
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/btc-liquidation-cluster-heatmap-api-b54c0a70/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from nonvisceral-eloisa-mousily.ngrok-free.dev](https://www.zero.xyz/host/nonvisceral-eloisa-mousily.ngrok-free.dev/llms.txt)