Backtest liquidation clusters with heatmap history

// Backtest liquidation clusters: how often did the price reach the largest liquidation cluster near it within the next
// hours? Node 18+, no dependencies. Reads the heatmap history (GET /heatmap/{coin}) and the candles (GET /candles/{coin})
// of the same window and checks every hourly column.
//
//   export BLOCKMETRIC_API_KEY=bm_live_...            # free key: every coin, the last 24 hours (DAYS=1); Pro: every coin, 1 year
//   export BLOCKMETRIC_BASE_URL=https://<domain>/api/v1
//   node backtest.mjs
//
// Options: COIN (BTC), DAYS (14, at most 30 with tf=1h), MIN_USD (5000000: clusters of at least $5M),
// MAX_DISTANCE (0.03: clusters within 3 % of the mark), HORIZON_HOURS (24), CSV (file name for every test, optional).
// Descriptive statistics over a short window, not a trading signal.
import fs from 'node:fs'

const BASE = (process.env.BLOCKMETRIC_BASE_URL ?? '').replace(/\/+$/, '')
const KEY = process.env.BLOCKMETRIC_API_KEY
if (!BASE) throw new Error('Set BLOCKMETRIC_BASE_URL, e.g. https://<domain>/api/v1')
const COIN = process.env.COIN ?? 'BTC'
const DAYS = Math.min(30, Number(process.env.DAYS ?? 14))
const MIN_USD = Number(process.env.MIN_USD ?? 5_000_000)
const MAX_DISTANCE = Number(process.env.MAX_DISTANCE ?? 0.03)
const HORIZON = Number(process.env.HORIZON_HOURS ?? 24)

async function api(path, params = {}) {
  const url = new URL(BASE + path)
  for (const [k, v] of Object.entries(params)) if (v !== undefined && v !== null && v !== '') url.searchParams.set(k, String(v))
  const res = await fetch(url, { headers: KEY ? { Authorization: `Bearer ${KEY}` } : { 'X-Blockmetric-Access': 'public' }, signal: AbortSignal.timeout(60_000) })
  const body = await res.json()
  if (!res.ok) throw new Error(`${res.status} ${body.error?.code}: ${body.error?.message}`)
  return body
}

/** The largest cluster per side of one column within maxDistance of the mark (null when none is big enough). */
export function nearestBig(h, col) {
  const mark = h.mark[col]
  const best = { long: null, short: null }
  h.prices.forEach((price, row) => {
    const dist = (price - mark) / mark
    if (Math.abs(dist) > MAX_DISTANCE) return
    // Longs liquidate below the mark, shorts above it.
    const side = price < mark ? 'long' : 'short'
    const usd = side === 'long' ? h.longCells[col][row] : h.shortCells[col][row]
    if (usd >= MIN_USD && (!best[side] || usd > best[side].usd)) best[side] = { side, price, usd, dist }
  })
  return [best.long, best.short].filter(Boolean)
}

async function main() {
  const { data: h } = await api(`/heatmap/${encodeURIComponent(COIN)}`, { tf: '1h', hours: DAYS * 24 })
  const { data: c } = await api(`/candles/${encodeURIComponent(COIN)}`, { tf: '1h', from: h.times[0], limit: 5000 })
  const byHour = new Map(c.candles.map((k) => [k.t, k]))
  const tests = []
  h.times.forEach((t, col) => {
    if (h.hasSnapshot?.[col] === false || !h.mark[col]) return
    const start = Date.parse(t)
    if (start + (HORIZON + 1) * 3_600_000 > Date.now()) return // the horizon has not passed yet
    for (const cl of nearestBig(h, col)) {
      let hitAfter = null
      for (let i = 1; i <= HORIZON && hitAfter === null; i++) {
        const k = byHour.get(new Date(start + i * 3_600_000).toISOString())
        if (k && (cl.side === 'long' ? k.low <= cl.price : k.high >= cl.price)) hitAfter = i
      }
      tests.push({ time: t, side: cl.side, price: cl.price, usd: cl.usd, distance: cl.dist, hitAfter })
    }
  })

  console.log(`${COIN}: clusters of at least $${MIN_USD / 1e6}M within ${MAX_DISTANCE * 100} % of the mark, ${h.times.length} hourly columns since ${h.times[0].slice(0, 10)}`)
  console.log('side    tested   reached   hit rate   median hours to reach')
  for (const side of ['long', 'short']) {
    const s = tests.filter((x) => x.side === side)
    const hits = s.filter((x) => x.hitAfter !== null).map((x) => x.hitAfter).sort((a, b) => a - b)
    const rate = s.length ? `${((hits.length / s.length) * 100).toFixed(0)} %` : '-'
    const median = hits.length ? String(hits[Math.floor(hits.length / 2)]) : '-'
    console.log(`${(side + 's').padEnd(7)} ${String(s.length).padStart(6)} ${String(hits.length).padStart(9)} ${rate.padStart(10)}   ${median.padStart(6)}`)
  }
  console.log(`Horizon ${HORIZON} h. Longs = clusters of long liquidations below the mark, shorts = above it.`)
  if (process.env.CSV) {
    fs.writeFileSync(process.env.CSV, ['time,side,price,usd,distance,hit_after_hours', ...tests.map((x) => `${x.time},${x.side},${x.price},${x.usd},${x.distance.toFixed(5)},${x.hitAfter ?? ''}`)].join('\n') + '\n')
    console.log(`Wrote ${tests.length} tests to ${process.env.CSV}`)
  }
}

main().catch((e) => {
  console.error(e.message)
  process.exit(1)
})