@gloom-sh/terminal 0.18.5 → 0.19.1

package/src/plugins/builtin/perps/cascade-tabs.tsx

@@ -0,0 +1,161 @@
+import { useCallback, useMemo, type ReactNode } from "react";
+import { isAccessDenied } from "../../../api-client/errors";
+import type { PerpDepthRow, PerpLiquidationMarket, PerpLiquidationPrint } from "../../../api-client/perps";
+import { ChartTableHeader, DataTableView, PaneStatusBody, QueryBar, useChartTableSelection, usePaneNoticeFooter, usePaneStatusFooter, useQueryBarSearch } from "../../../components";
+import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
+import { useAsyncResource, useAutoRefresh, usePluginPaneState } from "../../../public/react";
+import { useThemeColors } from "../../../theme/theme-context";
+import { Box } from "../../../ui";
+import { SignInWall } from "../cloud/auth-actions";
+import { useCloudUpgradeAction } from "../shared/cloud-upgrade";
+import { UpgradeLabel } from "../shared/locked-rows";
+import { isCloudSessionRequired, useResearchCloudSession } from "../shared/research-cloud-session";
+import { depthCell, depthColumns, depthFigures, depthFreshness, depthHistoryCount, depthSeries, depthStaleNote, LIQUIDATION_VIEWS, liquidationCell, liquidationColumns, liquidationFigures,
+  liquidationFreshness, liquidationSeries, printCell, printColumns, printHour, printKey, type DepthColumnId, type LiquidationColumnId, type LiquidationView, type PrintColumnId } from "./cascade";
+import { cachedPerpsDepth, cachedPerpsLiquidations, loadPerpsDepth, loadPerpsLiquidations } from "./client";
+import { compact } from "./model";
+import { useFreshnessStatusLine } from "./status-line";
+
+export interface CascadeTabProps {
+  /** The base asset the tab shows, shared with Compare. */
+  asset: string;
+  onAssetChange: (asset: string) => void;
+  accessKey: string;
+  width: number;
+  height: number;
+  focused: boolean;
+  /** Enter on a contract: its history. */
+  onOpenMarket: (marketId: string) => void;
+}
+
+const stamp = (s: string | null | undefined) => s ? `${s.slice(5, 10)} ${s.slice(11, 16)} UTC` : "";
+const magnitude = (n: number) => compact(Math.abs(n));
+const HOUR = 3_600_000;
+
+/** The preview's lock under the rows: what Pro adds to the tab. */
+function Lock({ text, role, onPress }: { text: string; role: string; onPress: () => void }) {
+  return <Box paddingX={1}><UpgradeLabel text={text} onPress={onPress} role={role} /></Box>;
+}
+
+/**
+ * One base asset's liquidations across the venues' public streams: the 24-hour and 7-day totals, the hourly columns
+ * (Pro), and the contracts or the largest prints below them. What each stream leaves out is in the data warnings.
+ */
+export function Liquidations({ asset, onAssetChange, accessKey, width, height, focused, onOpenMarket }: CascadeTabProps) {
+  const colors = useThemeColors();
+  const upgrade = useCloudUpgradeAction("perp");
+  const session = useResearchCloudSession();
+  const querySearch = useQueryBarSearch();
+  const [viewValue, setView] = usePluginPaneState<string>("perps:liquidation-view", "contracts");
+  const view: LiquidationView = viewValue === "prints" ? "prints" : "contracts";
+  const [selectedMarket, setSelectedMarket] = usePluginPaneState<string | null>("perps:liquidation-market", null);
+  const [selectedPrint, setSelectedPrint] = usePluginPaneState<string | null>("perps:liquidation-print", null);
+  const base = asset.trim().toUpperCase() || "BTC";
+  const loader = useCallback((force: boolean) => loadPerpsLiquidations(base, accessKey, force), [base, accessKey]);
+  const resource = useAsyncResource(loader, { initialData: () => cachedPerpsLiquidations(base, accessKey), clearOnError: isAccessDenied, keepPreviousData: true });
+  const data = resource.data?.payload;
+  useAutoRefresh(resource.updatedAt, resource.load, { intervalMs: 60_000 });
+  usePaneRefreshKey(() => { void resource.reload(); }, { focused: focused && !querySearch.active });
+  const declare = useCallback(() => data ? liquidationFreshness(data) : null, [data]);
+  const line = useFreshnessStatusLine(declare, resource.updatedAt);
+  usePaneStatusFooter({ registrationId: "perps:liquidations", loading: resource.loading, error: data ? resource.error : null, stale: resource.data?.stale, info: line });
+  usePaneNoticeFooter({ registrationId: "perps:liquidations-notice", focused, title: "Liquidation streams",
+    notices: [...resource.data?.refreshError ? [resource.data.refreshError] : [], ...data?.notes ?? []] });
+  const markets = data?.markets ?? [];
+  const prints = data?.largest ?? [];
+  const market = markets.find((row) => row.marketId === selectedMarket) ?? markets[0] ?? null;
+  const print = prints.find((row) => printKey(row) === selectedPrint) ?? prints[0] ?? null;
+  // A print stands in its hour's column, so the chart's cursor follows the selected print.
+  const link = useChartTableSelection({ rows: prints, getId: printKey, getDate: printHour, selectedId: print ? printKey(print) : null, onSelect: setSelectedPrint,
+    focused: focused && !querySearch.active, enabled: view === "prints" });
+  const series = useMemo(() => liquidationSeries(data, colors), [data, colors]);
+  if (!data && isCloudSessionRequired(resource.error)) return <SignInWall placement="perps-signin" action="view perpetual liquidations" needsVerification={session.needsVerification} />;
+  const pro = data?.access === "pro";
+  const since = data?.collectingSince ? Date.parse(data.collectingSince) : null;
+  const asOf = data ? Date.parse(data.asOf) : Date.now();
+  // The chart starts where collection did, when that is inside the week: earlier hours are missing, not quiet. A venue
+  // that sends its recent liquidations on connecting (OKX) can add earlier hours, which the chart then reaches back to.
+  const firstHour = data?.hourly[0] ? Date.parse(data.hourly[0].time) : Infinity;
+  const start = data ? Math.max(Date.parse(data.from), Math.min(firstHour, since === null ? -Infinity : Math.floor(since / HOUR) * HOUR - HOUR)) : 0;
+  const quiet = data?.collectingSince && since! > Date.parse(data.from) ? `No liquidations since collection started ${stamp(data.collectingSince)}` : "No liquidations in the last 7 days";
+  const chart = data && pro ? { series: data.hourly.length ? series : [], formatValue: magnitude, formatAxisValue: magnitude, remoteKind: "perpetual-liquidations",
+    ...(view === "prints" ? link : {}), viewport: { start: new Date(start), end: new Date(Math.ceil(asOf / HOUR) * HOUR) },
+    loading: !data && resource.loading, empty: data.hourly.length ? undefined : data.status === "unavailable" ? "Liquidations are not collected yet" : quiet } : null;
+  const figures = data ? liquidationFigures(data, colors) : [];
+  const contractColumns = liquidationColumns(width);
+  const shownPrintColumns = printColumns(width, data?.baseAsset ?? base);
+  const columns = view === "prints" ? shownPrintColumns : contractColumns;
+  const rows = view === "prints" ? prints.length : markets.length;
+  const before: ReactNode = <>
+    <QueryBar width={width} search={{ focused, value: asset, onChange: (value) => { onAssetChange(value); setSelectedMarket(null); setSelectedPrint(null); }, placeholder: "Base asset", debounceMs: 300, ...querySearch.searchProps }}
+      view={{ value: view, options: LIQUIDATION_VIEWS, onChange: setView }} />
+    <ChartTableHeader width={width} height={height - 1} tableRows={rows} tableColumns={columns} figures={figures} chart={chart} />
+  </>;
+  const lock = data && !pro ? <Lock text="Upgrade for hourly liquidations and the 20 largest prints" onPress={upgrade} role="perps-liquidations-upgrade" /> : null;
+  const metadata = () => [["As of", data?.asOf ?? ""], ["Base asset", data?.baseAsset ?? base], ["Collecting since", data?.collectingSince ?? ""],
+    ["Units", "notional in USD, stablecoins counted as USD; longs are long positions liquidated (forced sells), shorts short positions (forced buys)"],
+    ...(data?.notes ?? []).map((note) => ["Note", note])];
+  const empty = data?.status === "unavailable" ? "Liquidations are not collected yet." : `No perpetual contracts for ${base} on a liquidation stream.`;
+  return <PaneStatusBody loading={!data && resource.loading} error={!data ? resource.error : null} subject="perpetual liquidations">
+    {view === "prints"
+      ? <DataTableView<PerpLiquidationPrint> columns={shownPrintColumns} items={prints} focused={focused && !querySearch.active} rootWidth={width} rootHeight={height} rootBefore={before}
+        getItemKey={printKey} sortColumnId={null} sortDirection="desc" resetScrollKey={`${base}:prints`}
+        selection={{ kind: "id", selectedId: print ? printKey(print) : null, getId: printKey, onChange: setSelectedPrint }} onActivate={(row) => onOpenMarket(row.marketId)}
+        renderCell={(row, column) => printCell(row, column.id as PrintColumnId, colors)} selectedTextOverridesCellColor
+        emptyStateTitle={data?.status === "unavailable" ? empty : "No liquidations in the last 7 days."} bodyAfter={lock} getExportMetadata={metadata} />
+      : <DataTableView<PerpLiquidationMarket> columns={contractColumns} items={markets} focused={focused && !querySearch.active} rootWidth={width} rootHeight={height} rootBefore={before}
+        getItemKey={(row) => row.marketId} sortColumnId={null} sortDirection="desc" resetScrollKey={`${base}:contracts`}
+        selection={{ kind: "id", selectedId: market?.marketId ?? null, getId: (row) => row.marketId, onChange: setSelectedMarket }} onActivate={(row) => onOpenMarket(row.marketId)}
+        renderCell={(row, column) => liquidationCell(row, column.id as LiquidationColumnId, colors)} selectedTextOverridesCellColor
+        emptyStateTitle={empty} bodyAfter={lock} getExportMetadata={metadata} />}
+  </PaneStatusBody>;
+}
+
+/**
+ * One base asset's order books: the bids and asks resting within 0.5%, 1% and 2% of mid on each venue, read hourly.
+ * Pro charts the selected book's 1% depth over the week. A band wider than the book a venue returns reads `≥`.
+ */
+export function Depth({ asset, onAssetChange, accessKey, width, height, focused, onOpenMarket }: CascadeTabProps) {
+  const colors = useThemeColors();
+  const upgrade = useCloudUpgradeAction("perp");
+  const session = useResearchCloudSession();
+  const querySearch = useQueryBarSearch();
+  const [selectedId, setSelected] = usePluginPaneState<string | null>("perps:depth-selected", null);
+  const base = asset.trim().toUpperCase() || "BTC";
+  const loader = useCallback((force: boolean) => loadPerpsDepth(base, accessKey, force), [base, accessKey]);
+  const resource = useAsyncResource(loader, { initialData: () => cachedPerpsDepth(base, accessKey), clearOnError: isAccessDenied, keepPreviousData: true });
+  const data = resource.data?.payload;
+  useAutoRefresh(resource.updatedAt, resource.load, { intervalMs: 300_000 });
+  usePaneRefreshKey(() => { void resource.reload(); }, { focused: focused && !querySearch.active });
+  const declare = useCallback(() => data?.rows.length ? depthFreshness(data) : null, [data]);
+  const line = useFreshnessStatusLine(declare, resource.updatedAt);
+  usePaneStatusFooter({ registrationId: "perps:depth", loading: resource.loading, error: data ? resource.error : null, stale: resource.data?.stale, info: line });
+  const rows = data?.rows ?? [];
+  const staleNote = depthStaleNote(rows);
+  usePaneNoticeFooter({ registrationId: "perps:depth-notice", focused, title: "Order book depth",
+    notices: [...resource.data?.refreshError ? [resource.data.refreshError] : [], ...staleNote ? [staleNote] : [], ...data?.notes ?? []] });
+  const selected = rows.find((row) => row.marketId === selectedId) ?? rows[0] ?? null;
+  const series = useMemo(() => depthSeries(data?.history ?? [], selected, colors), [data?.history, selected, colors]);
+  if (!data && isCloudSessionRequired(resource.error)) return <SignInWall placement="perps-signin" action="view perpetual order book depth" needsVerification={session.needsVerification} />;
+  const pro = data?.access === "pro";
+  const columns = depthColumns(width);
+  const points = depthHistoryCount(data?.history ?? [], selected?.marketId);
+  // A chart that follows the selected book keeps its band on a book without history, and says so.
+  const chart = data && pro && rows.length ? { series: points >= 3 ? series : [], formatValue: compact, formatAxisValue: compact, remoteKind: "perpetual-depth",
+    empty: points >= 3 ? undefined : "Collecting hourly depth for this book" } : null;
+  const before: ReactNode = <>
+    <QueryBar width={width} search={{ focused, value: asset, onChange: (value) => { onAssetChange(value); setSelected(null); }, placeholder: "Base asset", debounceMs: 300, ...querySearch.searchProps }} />
+    <ChartTableHeader width={width} height={height - 1} tableRows={rows.length} tableColumns={columns} figures={depthFigures(rows)} chart={chart} />
+  </>;
+  const lock = data && !pro ? <Lock text="Upgrade for hourly depth history" onPress={upgrade} role="perps-depth-upgrade" /> : null;
+  return <PaneStatusBody loading={!data && resource.loading} error={!data ? resource.error : null} subject="order book depth">
+    <DataTableView<PerpDepthRow> columns={columns} items={rows} focused={focused && !querySearch.active} rootWidth={width} rootHeight={height} rootBefore={before}
+      getItemKey={(row) => row.marketId} sortColumnId={null} sortDirection="desc" resetScrollKey={base}
+      selection={{ kind: "id", selectedId: selected?.marketId ?? null, getId: (row) => row.marketId, onChange: setSelected }} onActivate={(row) => onOpenMarket(row.marketId)}
+      renderCell={(row, column) => depthCell(row, column.id as DepthColumnId, colors)} selectedTextOverridesCellColor
+      emptyStateTitle={data?.status === "unavailable" ? "Order book depth is not collected yet." : `No order book depth for ${base} yet.`} bodyAfter={lock}
+      getExportMetadata={() => [["As of", data?.asOf ?? ""], ["Base asset", data?.baseAsset ?? base],
+        ["Units", "quote notional in USD resting within the band of mid on each side; a value marked ≥ is a floor, the book returned ended inside the band; book reach in percent of mid"],
+        ...[...staleNote ? [staleNote] : [], ...data?.notes ?? []].map((note) => ["Note", note])]} />
+  </PaneStatusBody>;
+}

package/src/plugins/builtin/perps/cascade.ts

@@ -0,0 +1,236 @@
+import type { PerpDepthPayload, PerpDepthRow, PerpDepthSnapshot, PerpLiquidationMarket, PerpLiquidationPrint, PerpLiquidationsPayload } from "../../../api-client/perps";
+import type { DataTableCell, DataTableColumn, StatItem } from "../../../components";
+import { scalarPoint, staticSeries } from "../../../components/chart/static/series";
+import { getTableWidth } from "../../../components/ui/table-layout";
+import type { HeadlessPaneFreshness } from "../../../types/headless";
+import type { ThemeColors } from "../../../theme/colors";
+import { compact, price, venueName } from "./model";
+
+// Liquidations and order book depth of one base asset across the venues: the Liquidations and Depth tabs, their
+// text report and their charts read these, so the pane and `fn PERP` always agree.
+
+type Colors = Pick<ThemeColors, "positive" | "negative" | "text" | "textBright" | "textMuted" | "textDim">;
+/** Month to second, or to minute: the header names UTC. */
+const stamp = (s: string | null | undefined, seconds = false) => s ? `${s.slice(5, 10)} ${s.slice(11, seconds ? 19 : 16)}` : "--";
+const venueOrder = (venue: string) => { const at = ["binance", "bybit", "okx", "hyperliquid"].indexOf(venue); return at < 0 ? 9 : at; };
+/** The venues behind some rows, in the order the tabs list them. */
+const venuesIn = (rows: readonly { venue: string }[]) => [...new Set(rows.map((row) => row.venue))].sort((a, b) => venueOrder(a) - venueOrder(b));
+const usd = (n: number | null | undefined) => n == null ? "--" : compact(n);
+
+/**
+ * The columns that fit the pane, the least read going first. A pair (a band's bid and ask, a window's longs and
+ * shorts) goes together; the venue and the contract stay, since only both tell one venue's contracts apart.
+ */
+function fit<Id extends string>(columns: Record<Id, DataTableColumn>, ids: readonly Id[], drops: readonly (readonly Id[])[], width: number): DataTableColumn[] {
+  let kept = ids.map((id) => columns[id]);
+  for (const drop of drops) {
+    if (getTableWidth(kept) <= width) break;
+    kept = kept.filter((column) => !(drop as readonly string[]).includes(column.id));
+  }
+  return kept;
+}
+
+// ---- Liquidations ----
+
+export type LiquidationView = "contracts" | "prints";
+export const LIQUIDATION_VIEWS: Array<{ value: LiquidationView; label: string }> = [{ value: "contracts", label: "By contract" }, { value: "prints", label: "Largest" }];
+
+export type LiquidationColumnId = "venue" | "symbol" | "long24h" | "short24h" | "long7d" | "short7d" | "count24h" | "lastEventAt";
+const LIQUIDATION_COLUMNS: Record<LiquidationColumnId, DataTableColumn> = {
+  venue: { id: "venue", label: "Venue", width: 11, align: "left" },
+  symbol: { id: "symbol", label: "Contract", width: 14, align: "left" },
+  long24h: { id: "long24h", label: "Longs 24h USD", width: 13, align: "right" },
+  short24h: { id: "short24h", label: "Shorts 24h USD", width: 14, align: "right" },
+  long7d: { id: "long7d", label: "Longs 7d USD", width: 12, align: "right" },
+  short7d: { id: "short7d", label: "Shorts 7d USD", width: 13, align: "right" },
+  count24h: { id: "count24h", label: "Events 24h", width: 10, align: "right" },
+  lastEventAt: { id: "lastEventAt", label: "Last UTC", width: 11, align: "left" },
+};
+export const LIQUIDATION_COLUMN_IDS: LiquidationColumnId[] = ["venue", "symbol", "long24h", "short24h", "long7d", "short7d", "count24h", "lastEventAt"];
+export const liquidationColumns = (width: number) => fit(LIQUIDATION_COLUMNS, LIQUIDATION_COLUMN_IDS, [["lastEventAt"], ["count24h"], ["long7d", "short7d"]], width);
+export const liquidationColumnLabel = (id: LiquidationColumnId) => LIQUIDATION_COLUMNS[id].label;
+
+/** A contract's liquidations: longs liquidated are forced sells (negative), shorts forced buys (positive). */
+export function liquidationCellText(row: PerpLiquidationMarket, id: LiquidationColumnId): string {
+  if (id === "venue") return venueName(row.venue);
+  if (id === "symbol") return row.symbol;
+  if (id === "count24h") return row.count24h.toLocaleString("en-US");
+  if (id === "lastEventAt") return stamp(row.lastEventAt);
+  return usd(row[id]);
+}
+export function liquidationCell(row: PerpLiquidationMarket, id: LiquidationColumnId, colors: Colors): DataTableCell {
+  const text = liquidationCellText(row, id);
+  if (id === "venue") return { text, color: colors.textBright };
+  if (id === "symbol") return { text, color: colors.textMuted };
+  if (id === "lastEventAt") return { text, value: row.lastEventAt, color: colors.textDim };
+  if (id === "count24h") return { text, value: row.count24h, color: row.count24h ? colors.text : colors.textMuted };
+  const value = row[id];
+  return { text, value, color: !value ? colors.textMuted : id.startsWith("long") ? colors.negative : colors.positive };
+}
+
+export type PrintColumnId = "eventAt" | "venue" | "symbol" | "side" | "price" | "priceKind" | "quantity" | "notionalUsd" | "receivedAt";
+const printColumnsFor = (base: string): Record<PrintColumnId, DataTableColumn> => ({
+  eventAt: { id: "eventAt", label: "Time UTC", width: 14, align: "left" },
+  venue: { id: "venue", label: "Venue", width: 11, align: "left" },
+  symbol: { id: "symbol", label: "Contract", width: 14, align: "left" },
+  side: { id: "side", label: "Side", width: 5, align: "left" },
+  price: { id: "price", label: "Price", width: 12, align: "right" },
+  priceKind: { id: "priceKind", label: "Price basis", width: 11, align: "left" },
+  quantity: { id: "quantity", label: `Size ${base}`.slice(0, 14), width: Math.max(8, Math.min(14, base.length + 5)), align: "right" },
+  notionalUsd: { id: "notionalUsd", label: "Notional USD", width: 12, align: "right" },
+  receivedAt: { id: "receivedAt", label: "Received UTC", width: 12, align: "left" },
+});
+export const PRINT_COLUMN_IDS: PrintColumnId[] = ["eventAt", "venue", "symbol", "side", "notionalUsd", "price", "priceKind", "quantity", "receivedAt"];
+export const printColumns = (width: number, base: string) => fit(printColumnsFor(base), PRINT_COLUMN_IDS, [["receivedAt"], ["quantity"], ["priceKind"], ["price"]], width);
+export const printColumnLabel = (id: PrintColumnId, base: string) => printColumnsFor(base)[id].label;
+export const printKey = (row: PerpLiquidationPrint) => `${row.marketId}:${row.eventAt}:${row.side}:${row.price}:${row.quantity}`;
+
+export function printCellText(row: PerpLiquidationPrint, id: PrintColumnId): string {
+  if (id === "eventAt") return stamp(row.eventAt, true);
+  if (id === "receivedAt") return row.receivedAt.slice(11, 19);
+  if (id === "venue") return venueName(row.venue);
+  if (id === "symbol") return row.symbol;
+  if (id === "side") return row.side === "long" ? "Long" : "Short";
+  if (id === "price") return price(row.price);
+  if (id === "priceKind") return row.priceKind === "fill" ? "Fill" : "Bankruptcy";
+  if (id === "quantity") return compact(row.quantity);
+  return usd(row.notionalUsd);
+}
+export function printCell(row: PerpLiquidationPrint, id: PrintColumnId, colors: Colors): DataTableCell {
+  const text = printCellText(row, id);
+  const tone = row.side === "long" ? colors.negative : colors.positive;
+  if (id === "eventAt") return { text, value: row.eventAt };
+  if (id === "receivedAt") return { text, value: row.receivedAt, color: colors.textDim };
+  if (id === "venue") return { text, color: colors.textBright };
+  if (id === "symbol" || id === "priceKind") return { text, color: colors.textMuted };
+  if (id === "side") return { text, color: tone };
+  if (id === "price") return { text, value: row.price };
+  if (id === "quantity") return { text, value: row.quantity };
+  return { text, value: row.notionalUsd, color: tone };
+}
+
+const isRecent = (since: string | null, from: string) => !!since && Date.parse(since) > Date.parse(from);
+/** The four totals; a window that reaches back before collection started says when it starts. */
+export function liquidationFigures(data: PerpLiquidationsPayload, colors: Colors): StatItem[] {
+  // The date only when collection started on another UTC day, so the detail fits beside every figure.
+  const started = data.collectingSince?.slice(0, 10) === data.asOf.slice(0, 10) ? data.collectingSince.slice(11, 16) : stamp(data.collectingSince);
+  const since = isRecent(data.collectingSince, data.from) ? `since ${started} UTC` : undefined;
+  const day = isRecent(data.collectingSince, new Date(Date.parse(data.asOf) - 86_400_000).toISOString()) ? since : undefined;
+  // The tab and the chart's legend say these are liquidated positions; the label names the side and the window.
+  const figure = (id: "long24h" | "short24h" | "long7d" | "short7d", label: string, detail?: string): StatItem =>
+    ({ id, label, value: usd(data.totals[id]), color: id.startsWith("long") ? colors.negative : colors.positive, ...(detail ? { detail, detailVariants: [""] } : {}) });
+  return [figure("long24h", "Longs 24h", day), figure("short24h", "Shorts 24h", day), figure("long7d", "Longs 7d", since), figure("short7d", "Shorts 7d", since)];
+}
+
+/** Hourly liquidations as columns: shorts above zero, longs hanging below it, so the two sides of an hour never cover each other. */
+export function liquidationSeries(data: PerpLiquidationsPayload | null | undefined, colors: Pick<ThemeColors, "positive" | "negative">) {
+  const hours = data?.hourly ?? [];
+  return [
+    staticSeries(hours.map((hour) => scalarPoint(new Date(hour.time), hour.short)), { id: "liquidated-shorts", label: "Shorts liquidated", color: colors.positive, style: "columns", calendarSpaced: true }),
+    staticSeries(hours.map((hour) => scalarPoint(new Date(hour.time), -hour.long)), { id: "liquidated-longs", label: "Longs liquidated", color: colors.negative, style: "columns", calendarSpaced: true }),
+  ];
+}
+/** The hour a print falls in, where the chart's column for it stands. */
+export const printHour = (row: PerpLiquidationPrint) => new Date(Math.floor(Date.parse(row.eventAt) / 3_600_000) * 3_600_000);
+
+/** The streams that are down, with when each last reported: `Bybit stream down since 10-26 06:52 UTC`. Empty while every one is live. */
+export function downStreams(data: Pick<PerpLiquidationsPayload, "streams">): string[] {
+  return [...data.streams].sort((a, b) => venueOrder(a.venue) - venueOrder(b.venue)).filter((stream) => stream.state !== "live")
+    .map((stream) => `${venueName(stream.venue)} stream down${stream.lastOkAt ? ` since ${stamp(stream.lastOkAt)} UTC` : ""}`);
+}
+/**
+ * Who the figures come from and when they were counted: the venues' streams, tallied up to the server's time. Not a
+ * feed: the tab counts again each minute. A stream that is down is said, since its venue's figures stop growing.
+ */
+export function liquidationFreshness(data: PerpLiquidationsPayload): HeadlessPaneFreshness {
+  const venues = venuesIn(data.markets).map(venueName);
+  const down = downStreams(data);
+  return { ...(venues.length ? { source: venues.join(", ") } : {}), asOf: data.asOf, maxAgeMinutes: 10, ...(down.length ? { note: down.join("; ") } : {}) };
+}
+
+// ---- Depth ----
+
+const DEPTH_BANDS = [{ key: "05", label: "0.5%", fraction: 0.005 }, { key: "1", label: "1%", fraction: 0.01 }, { key: "2", label: "2%", fraction: 0.02 }] as const;
+type BandKey = typeof DEPTH_BANDS[number]["key"];
+export type DepthColumnId = "venue" | "symbol" | "mid" | `bid${BandKey}` | `ask${BandKey}` | "reach" | "observedAt";
+const DEPTH_COLUMNS: Record<DepthColumnId, DataTableColumn> = {
+  venue: { id: "venue", label: "Venue", width: 11, align: "left" },
+  symbol: { id: "symbol", label: "Contract", width: 14, align: "left" },
+  mid: { id: "mid", label: "Mid", width: 12, align: "right" },
+  bid05: { id: "bid05", label: "Bid 0.5% USD", width: 12, align: "right" },
+  ask05: { id: "ask05", label: "Ask 0.5% USD", width: 12, align: "right" },
+  bid1: { id: "bid1", label: "Bid 1% USD", width: 10, align: "right" },
+  ask1: { id: "ask1", label: "Ask 1% USD", width: 10, align: "right" },
+  bid2: { id: "bid2", label: "Bid 2% USD", width: 10, align: "right" },
+  ask2: { id: "ask2", label: "Ask 2% USD", width: 10, align: "right" },
+  reach: { id: "reach", label: "Book reach %", width: 12, align: "right" },
+  observedAt: { id: "observedAt", label: "Observed UTC", width: 17, align: "left" },
+};
+export const DEPTH_COLUMN_IDS: DepthColumnId[] = ["venue", "symbol", "mid", "bid05", "ask05", "bid1", "ask1", "bid2", "ask2", "reach", "observedAt"];
+export const depthColumns = (width: number) => fit(DEPTH_COLUMNS, DEPTH_COLUMN_IDS, [["reach"], ["mid"], ["observedAt"], ["bid2", "ask2"], ["bid05", "ask05"]], width);
+export const depthColumnLabel = (id: DepthColumnId) => DEPTH_COLUMNS[id].label;
+
+/** A band wider than the book the venue returned holds at least what the book shows: `≥57.58M`. */
+const bandFraction = (id: string) => DEPTH_BANDS.find((band) => id.endsWith(band.key))!.fraction;
+const isFloor = (row: Pick<PerpDepthSnapshot, "bidReach" | "askReach">, id: `${"bid" | "ask"}${BandKey}`) =>
+  bandFraction(id) > (id.startsWith("bid") ? row.bidReach : row.askReach) + 1e-9;
+/** How far the shorter side of the returned book reaches from mid. */
+const bookReach = (row: Pick<PerpDepthSnapshot, "bidReach" | "askReach">) => Math.min(row.bidReach, row.askReach);
+export function depthCellText(row: PerpDepthRow, id: DepthColumnId): string {
+  if (id === "venue") return venueName(row.venue);
+  if (id === "symbol") return row.symbol;
+  if (id === "mid") return price(row.mid);
+  if (id === "reach") return `${(bookReach(row) * 100).toFixed(2)}%`;
+  // A book not read for 2.5 hours says so, since the band totals leave it out.
+  if (id === "observedAt") return `${stamp(row.observedAt)}${row.stale ? " stale" : ""}`;
+  return `${isFloor(row, id) ? "≥" : ""}${usd(row[id])}`;
+}
+export function depthCell(row: PerpDepthRow, id: DepthColumnId, colors: Colors): DataTableCell {
+  const text = depthCellText(row, id);
+  if (id === "venue") return { text, color: row.stale ? colors.textDim : colors.textBright };
+  if (id === "symbol") return { text, color: colors.textMuted };
+  if (id === "mid") return { text, value: row.mid };
+  if (id === "reach") return { text, value: bookReach(row) * 100, color: colors.textMuted };
+  if (id === "observedAt") return { text, value: row.observedAt, color: row.stale ? colors.textMuted : colors.textDim };
+  return { text, value: row[id], color: row.stale ? colors.textMuted : id.startsWith("bid") ? colors.positive : colors.negative };
+}
+
+/**
+ * Each band's resting bids and asks summed over the current books; `floor` when any of them ends inside the band. A stale
+ * book (it left its venue's 50 largest, or the venue has been failing) is listed, marked, and not added to books read now.
+ */
+export function depthBandTotals(all: readonly PerpDepthRow[]) {
+  const rows = all.filter((row) => !row.stale);
+  if (!rows.length) return [];
+  return DEPTH_BANDS.map((band) => ({ key: band.key, label: `±${band.label} of mid`, books: rows.length,
+    bids: rows.reduce((sum, row) => sum + row[`bid${band.key}`], 0), asks: rows.reduce((sum, row) => sum + row[`ask${band.key}`], 0),
+    floor: rows.some((row) => isFloor(row, `bid${band.key}`) || isFloor(row, `ask${band.key}`)) }));
+}
+export const depthFigures = (rows: readonly PerpDepthRow[]): StatItem[] => depthBandTotals(rows).map(({ key, label, bids, asks, floor }) => ({
+  id: `band-${key}`, label, value: `${floor ? "≥" : ""}${usd(bids + asks)}`, detail: `bids ${usd(bids)} · asks ${usd(asks)}`, detailVariants: [`${usd(bids)} / ${usd(asks)}`, ""] }));
+
+/** Said under the depth figures when a stale book is left out of them. */
+export const depthStaleNote = (rows: readonly PerpDepthRow[]) => {
+  const stale = rows.filter((row) => row.stale).length;
+  return stale ? `${stale === 1 ? "One book" : `${stale} books`} not read for 2.5 hours ${stale === 1 ? "is" : "are"} marked stale and left out of the band totals.` : null;
+};
+
+/** One book's hourly bids and asks within 1% of mid, for the chart over the table. */
+export function depthSeries(history: readonly PerpDepthSnapshot[], row: PerpDepthRow | null, colors: Pick<ThemeColors, "positive" | "negative">) {
+  if (!row) return [];
+  const points = history.filter((point) => point.marketId === row.marketId).sort((a, b) => a.bucket.localeCompare(b.bucket));
+  const name = `${venueName(row.venue)} ${row.symbol}`;
+  return [
+    staticSeries(points.map((point) => scalarPoint(new Date(point.bucket), point.bid1)), { id: "depth-bids", label: `${name} bids 1%`, color: colors.positive, calendarSpaced: true }),
+    staticSeries(points.map((point) => scalarPoint(new Date(point.bucket), point.ask1)), { id: "depth-asks", label: "asks 1%", color: colors.negative, calendarSpaced: true }),
+  ];
+}
+export const depthHistoryCount = (history: readonly PerpDepthSnapshot[], marketId: string | undefined) => history.filter((point) => point.marketId === marketId).length;
+
+/** Each venue's newest book: what the footer, the report and a capture are dated by. Stale after 2.5 hours, as the server marks a row. */
+export function depthFreshness(data: Pick<PerpDepthPayload, "rows">): HeadlessPaneFreshness {
+  const venues = venuesIn(data.rows);
+  const sources = venues.map((venue) => ({ source: venueName(venue), asOf: data.rows.filter((row) => row.venue === venue).map((row) => row.observedAt).sort().at(-1)! }));
+  return { ...(sources.length ? { source: sources.map((entry) => entry.source).join(", ") } : {}), sources, ageOnly: true, maxAgeMinutes: 150,
+    observations: data.rows.map((row) => ({ observedAt: row.observedAt, stale: row.stale })), note: "order books read hourly" };
+}

package/src/plugins/builtin/perps/client.ts

@@ -1,6 +1,6 @@
 import { apiClient } from "../../../api-client";
-import type { PerpBoardPayload, PerpBoardQuery, PerpBoardRow, PerpEquitiesPayload, PerpEquityListing, PerpHistoryPayload, PerpHistoryQuery, PerpLongShortPoint,
-  PerpLongShortRatio, PerpMarketPayload, PerpRankingsPayload } from "../../../api-client/perps";
+import type { PerpBoardPayload, PerpBoardQuery, PerpBoardRow, PerpDepthPayload, PerpDepthSnapshot, PerpEquitiesPayload, PerpEquityListing, PerpHistoryPayload, PerpHistoryQuery,
+  PerpLiquidationsPayload, PerpLongShortPoint, PerpLongShortRatio, PerpMarketPayload, PerpRankingsPayload } from "../../../api-client/perps";
 import { createPluginCache } from "../../../data/plugin-cache";
 import { cachedCloudResource, loadCloudResource } from "../shared/cloud-resource";
 import { baseOfLabel, marketLabel, perpBaseCandidates, separatedPairBase } from "./model";
@@ -97,6 +97,60 @@ export const loadPerpsRankings = (access: string, force = false) => loadCloudRes
 const compareKey = (baseAsset: string, access: string) => `compare:v1:${baseAsset.toUpperCase()}:${access}`;
 export const cachedPerpsCompare = (baseAsset: string, access: string) => cachedCloudResource(perpsCache, compareKey(baseAsset, access), (data) => validatePerpsCompare(data, baseAsset));
 export const loadPerpsCompare = (baseAsset: string, access: string, force = false) => loadCloudResource(perpsCache, compareKey(baseAsset, access), () => fetchPerpsCompare(baseAsset), { force, validate: (data) => validatePerpsCompare(data, baseAsset) });
+// Liquidations and order book depth of one base asset. Older servers answer 404, which the tab shows as its error.
+const finite = (n: unknown) => typeof n === "number" && Number.isFinite(n);
+const nonNegative = (n: unknown) => finite(n) && (n as number) >= 0;
+const strings = (value: unknown) => Array.isArray(value) && value.every((entry) => typeof entry === "string");
+const cascadeEnvelope = (data: { access: string; locked: boolean; asOf: string; baseAsset: string; notes: unknown }) =>
+  !!data && ["pro", "preview"].includes(data.access) && typeof data.locked === "boolean" && date(data.asOf) && typeof data.baseAsset === "string" && strings(data.notes);
+const named = (row: { marketId: string; venue: string; symbol: string }) => !!row && typeof row.marketId === "string" && typeof row.venue === "string" && typeof row.symbol === "string";
+const TOTALS = ["long24h", "short24h", "long7d", "short7d", "count24h", "count7d"] as const;
+export function validatePerpsLiquidations(data: PerpLiquidationsPayload): PerpLiquidationsPayload {
+  if (!cascadeEnvelope(data) || !date(data.from) || !(data.collectingSince === null || date(data.collectingSince)) || !data.totals || !TOTALS.every((key) => nonNegative(data.totals[key]))
+    || !Array.isArray(data.markets) || !data.markets.every((row) => named(row) && TOTALS.every((key) => nonNegative(row[key])) && (row.lastEventAt === null || date(row.lastEventAt)))
+    || new Set(data.markets.map((row) => row.marketId)).size !== data.markets.length
+    || !Array.isArray(data.hourly) || !data.hourly.every((hour) => !!hour && date(hour.time) && nonNegative(hour.long) && nonNegative(hour.short) && nonNegative(hour.count))
+    || !Array.isArray(data.largest) || !data.largest.every((print) => named(print) && (print.side === "long" || print.side === "short") && (print.priceKind === "fill" || print.priceKind === "bankruptcy")
+      && [print.price, print.quantity, print.notionalUsd].every(nonNegative) && date(print.eventAt) && date(print.receivedAt))
+    || !Array.isArray(data.streams) || !data.streams.every((stream) => !!stream && typeof stream.venue === "string" && (stream.state === "live" || stream.state === "down")))
+    throw new Error("The server returned unreadable perpetual liquidations");
+  return data;
+}
+const BANDS = ["bid05", "ask05", "bid1", "ask1", "bid2", "ask2"] as const;
+const validSnapshot = (row: PerpDepthSnapshot) => !!row && typeof row.marketId === "string" && date(row.bucket) && date(row.observedAt) && (row.sourceAsOf === null || date(row.sourceAsOf))
+  && finite(row.mid) && row.mid > 0 && BANDS.every((band) => nonNegative(row[band])) && nonNegative(row.bidReach) && nonNegative(row.askReach) && finite(row.levels) && (row.grouping === null || finite(row.grouping));
+export function validatePerpsDepth(data: PerpDepthPayload): PerpDepthPayload {
+  if (!cascadeEnvelope(data) || !Array.isArray(data.rows) || !data.rows.every((row) => validSnapshot(row) && named(row) && typeof row.stale === "boolean")
+    || new Set(data.rows.map((row) => row.marketId)).size !== data.rows.length
+    || !Array.isArray(data.history) || !data.history.every(validSnapshot) || !Array.isArray(data.sources)) throw new Error("The server returned unreadable order book depth");
+  return data;
+}
+/** A name the venues do not list as typed (ETH-USD, bitcoin) is read as the base asset it stands for, as Compare reads it. */
+async function byBaseAsset<T extends { markets?: unknown[]; rows?: unknown[] }>(baseAsset: string, fetch: (base: string) => Promise<T>): Promise<T> {
+  const listed = (data: T) => (data.markets ?? data.rows ?? []).length > 0;
+  const direct = await fetch(baseAsset);
+  if (listed(direct)) return direct;
+  for (const base of perpBaseCandidates(baseAsset).map(baseOfLabel)) {
+    const found = await fetch(base);
+    if (listed(found)) return found;
+  }
+  return direct;
+}
+export const fetchPerpsLiquidations = (baseAsset: string, client: Pick<typeof apiClient, "getCloudPerpsLiquidations"> = apiClient) =>
+  byBaseAsset(baseAsset, async (base) => validatePerpsLiquidations(await client.getCloudPerpsLiquidations(base)));
+export const fetchPerpsDepth = (baseAsset: string, client: Pick<typeof apiClient, "getCloudPerpsDepth"> = apiClient) =>
+  byBaseAsset(baseAsset, async (base) => validatePerpsDepth(await client.getCloudPerpsDepth(base)));
+export const perpsLiquidationsCache = createPluginCache<PerpLiquidationsPayload>({ kind: "perps-liquidations", source: "gloom-cloud", schemaVersion: 1,
+  policy: { staleMs: 60_000, expireMs: 86_400_000 } });
+export const perpsDepthCache = createPluginCache<PerpDepthPayload>({ kind: "perps-depth", source: "gloom-cloud", schemaVersion: 1,
+  policy: { staleMs: 300_000, expireMs: 86_400_000 } });
+const cascadeKey = (kind: string, baseAsset: string, access: string) => `${kind}:v1:${baseAsset.toUpperCase()}:${access}`;
+export const cachedPerpsLiquidations = (baseAsset: string, access: string) => cachedCloudResource(perpsLiquidationsCache, cascadeKey("liquidations", baseAsset, access), validatePerpsLiquidations);
+export const loadPerpsLiquidations = (baseAsset: string, access: string, force = false) => loadCloudResource(perpsLiquidationsCache, cascadeKey("liquidations", baseAsset, access),
+  () => fetchPerpsLiquidations(baseAsset), { force, validate: validatePerpsLiquidations });
+export const cachedPerpsDepth = (baseAsset: string, access: string) => cachedCloudResource(perpsDepthCache, cascadeKey("depth", baseAsset, access), validatePerpsDepth);
+export const loadPerpsDepth = (baseAsset: string, access: string, force = false) => loadCloudResource(perpsDepthCache, cascadeKey("depth", baseAsset, access),
+  () => fetchPerpsDepth(baseAsset), { force, validate: validatePerpsDepth });
 const sameListing = (value: PerpEquityListing | null | undefined, listing: PerpEquityListing) =>
   value?.symbol === listing.symbol && value.exchange === listing.exchange;
 /** The server's proof that a stock contract belongs to the listing asked about. */

package/src/plugins/builtin/perps/headless.ts

@@ -1,10 +1,12 @@
-import type { PerpBoardPayload, PerpBoardRow } from "../../../api-client/perps";
+import type { PerpBoardPayload, PerpBoardRow, PerpDepthRow, PerpLiquidationMarket, PerpLiquidationPrint } from "../../../api-client/perps";
 import type { HeadlessBundleSection, HeadlessPaneColumn, HeadlessPaneLoadArgs, HeadlessPaneRow } from "../../../types/headless";
 import type { HeadlessPaneDefinition } from "../../../types/plugin";
-import { boardSearchText, fetchPerpSelection, fetchPerpsBoard, fetchPerpsCompare, fetchPerpsHistory, fetchPerpsRankings, marketQuery, nearestPerpMarkets } from "./client";
+import { DEPTH_COLUMN_IDS, depthBandTotals, depthCellText, depthColumnLabel, depthFreshness, depthStaleNote, downStreams, LIQUIDATION_COLUMN_IDS, liquidationCellText, liquidationColumnLabel, liquidationFreshness,
+  PRINT_COLUMN_IDS, printCellText, printColumnLabel, type DepthColumnId, type LiquidationColumnId, type PrintColumnId } from "./cascade";
+import { boardSearchText, fetchPerpSelection, fetchPerpsBoard, fetchPerpsCompare, fetchPerpsDepth, fetchPerpsHistory, fetchPerpsLiquidations, fetchPerpsRankings, marketQuery, nearestPerpMarkets } from "./client";
 import { perpFreshness } from "./freshness";
 import { aprFootnote, ASSET_FILTERS, BOARD_COLUMNS, BOARD_SORTS, collectedVenueCount, COMPARE_COLUMNS, compact, fundingSpread, HISTORY_METRICS, label, marketLabel, openingTab, PERP_TABS, perpCellText,
-  perpColumnLabel, percent, perpHistoryProText, positioningFields, price, RANKING_COLUMNS, rankingRows, RANKINGS, ratioText, share, time, VENUES, venueName, type PerpColumnId } from "./model";
+  perpColumnLabel, percent, perpHistoryProText, positioningFields, price, RANKING_COLUMNS, rankingRows, RANKINGS, ratioText, share, time, uncoveredVenueNote, VENUES, venueName, IDENTITY_VENUES, type PerpColumnId } from "./model";
 import { freePreviewNote } from "../shared/free-preview";
 import { basisSpotSymbol } from "../futures-curve/model";
 
@@ -71,6 +73,18 @@ const REVISION_COLUMNS: HeadlessPaneColumn[] = [
   { key: "fingerprint", header: "Fingerprint", format: (value) => text(value)?.slice(0, 8) || "--" },
 ];
 
+// Liquidations and depth print what their tabs' cells show, through the same formatters.
+const LIQUIDATION_RIGHT = new Set<string>(["long24h", "short24h", "long7d", "short7d", "count24h", "notionalUsd", "price", "quantity", "mid", "bid05", "ask05", "bid1", "ask1", "bid2", "ask2", "reach"]);
+const cascadeColumn = <Id extends string>(id: Id, header: string, format: (row: HeadlessPaneRow) => string): HeadlessPaneColumn =>
+  ({ key: id === "reach" ? "bidReach" : id, header, ...(LIQUIDATION_RIGHT.has(id) ? { align: "right" as const } : {}), format: (_, row) => format(row) });
+const LIQUIDATION_TEXT_COLUMNS = LIQUIDATION_COLUMN_IDS.map((id: LiquidationColumnId) => cascadeColumn(id, liquidationColumnLabel(id), (row) => liquidationCellText(row as unknown as PerpLiquidationMarket, id)));
+const printTextColumns = (base: string) => PRINT_COLUMN_IDS.map((id: PrintColumnId) => cascadeColumn(id, printColumnLabel(id, base), (row) => printCellText(row as unknown as PerpLiquidationPrint, id)));
+const DEPTH_TEXT_COLUMNS = DEPTH_COLUMN_IDS.map((id: DepthColumnId) => cascadeColumn(id, depthColumnLabel(id), (row) => depthCellText(row as unknown as PerpDepthRow, id)));
+const HOURLY_COLUMNS: HeadlessPaneColumn[] = [timeColumn("time", "Hour"), right("long", "Longs USD", (value) => compact(num(value))), right("short", "Shorts USD", (value) => compact(num(value))),
+  right("count", "Events", (value) => num(value)?.toLocaleString("en-US") ?? "--")];
+const DEPTH_HISTORY_COLUMNS: HeadlessPaneColumn[] = [{ key: "marketId", header: "Market", format: (value) => text(value) ?? "--" }, timeColumn("bucket", "Hour"),
+  ...(["bid05", "ask05", "bid1", "ask1", "bid2", "ask2"] as const).map((id) => right(id, depthColumnLabel(id), (value) => compact(num(value))))];
+
 // With no market the report shows the first; a market nothing matches names ones that work, a builder dex's among them.
 const EXAMPLE_MARKETS = ["BTC", "ETH", "SOL"] as const;
 const DEFAULT_MARKET = EXAMPLE_MARKETS[0];
@@ -92,7 +106,7 @@ const tabOf = (args: HeadlessPaneLoadArgs) => PERP_TABS.find((tab) => tab === ar
 // A free account's market opens its latest values under the title, so the title names the function, not the Pro history: a table the free view
 // locks is left out and named on the report's one Pro line (`lockedTable`), never marked on the title over the free ones.
 const TITLES: Record<typeof PERP_TABS[number], string> = { board: "Perpetual markets", rankings: "Perpetual rankings", compare: "Perpetual contracts across venues",
-  history: "Perpetuals", evidence: "Perpetual evidence" };
+  liquidations: "Perpetual liquidations across venues", depth: "Perpetual order book depth across venues", history: "Perpetuals", evidence: "Perpetual evidence" };
 const copy = (rows: readonly PerpBoardRow[]) => rows.map((row) => ({ ...row }));
 const more = (count: number, noun: string) => `${count.toLocaleString("en-US")} more ${noun} need Gloom Pro`;
 // A table the free view leaves empty is locked: the report leaves it out and its one Pro line says what Pro adds.
@@ -108,7 +122,7 @@ const historyLock = (selected: PerpBoardRow, venues: number | null) => {
 const venueNotice = (venue: string, selected: PerpBoardRow, requested: string, access: string) => {
   if (venue === "all" || selected.venue === venue) return [];
   const [wanted, shown] = [venueName(venue), venueName(selected.venue)];
-  return [VENUES.some((id) => requested.startsWith(`${id}:`)) ? `${requested} is a ${shown} market, so the ${wanted} filter does not apply.`
+  return [IDENTITY_VENUES.some((id) => requested.startsWith(`${id}:`)) ? `${requested} is a ${shown} market, so the ${wanted} filter does not apply.`
     : `${wanted} has no ${selected.baseAsset} contract${access === "pro" ? "" : " in the free preview"}; showing ${shown}.`];
 };
 const venueUnused = (venue: string, tab: string) => venue === "all" ? [] : [`The ${venueName(venue)} filter applies to the board, not ${tab}; showing every venue.`];
@@ -116,17 +130,20 @@ const listMetadata = (data: Pick<PerpBoardPayload, "asOf" | "access" | "status">
 
 export const perpsHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle", argument: { kind: "free-text", optional: true, placeholder: "market",
-    description: "A base asset, underlying, canonical market identity or Market column label, such as BTC, hyperliquid:xyz:TSLA or SP500 · XYZ. Opens its history; with --tab board it searches the board, with --tab compare it is the base asset. Without one, the board." },
+    description: "A base asset, underlying, canonical market identity or Market column label, such as BTC, hyperliquid:xyz:TSLA or SP500 · XYZ. Opens its history; with --tab board it searches the board, with --tab compare, liquidations or depth it is the base asset. Without one, the board." },
   options: [
-    { key: "tab", type: "enum", settingKey: "tab", values: PERP_TABS.map((value) => ({ value })), description: "Board, rankings, compare, history or evidence. Board without a market, history with one." },
+    { key: "tab", type: "enum", settingKey: "tab", values: PERP_TABS.map((value) => ({ value })), description: "Board, rankings, compare, liquidations, depth, history or evidence. Board without a market, history with one." },
     { key: "asset-class", type: "enum", settingKey: "assetClass", values: ASSET_FILTERS.map((value) => ({ value })), defaultValue: "all", description: "Board asset class." },
-    { key: "venue", type: "enum", settingKey: "venue", values: ["all", ...VENUES].map((value) => ({ value })), defaultValue: "all", description: "Board venue; with a market, opens that venue's contract when the board lists it." },
+    { key: "venue", type: "enum", settingKey: "venue", values: ["all", ...VENUES].map((value) => ({ value })), defaultValue: "all", invalidValueHint: uncoveredVenueNote,
+      description: "Board venue; with a market, opens that venue's contract when the board lists it." },
     { key: "sort", type: "enum", settingKey: "sort", values: BOARD_SORTS.map((value) => ({ value })), defaultValue: "oi", description: "Board order: open interest, funding, open-interest change, premium or long share of accounts." },
     { key: "days", type: "enum", settingKey: "days", values: ["1", "7", "30", "90", "365"].map((value) => ({ value })), defaultValue: "7", description: "History lookback in days." },
     { key: "metric", type: "enum", settingKey: "metric", values: HISTORY_METRICS.map((value) => ({ value })), defaultValue: "funding", description: "Displayed history chart; JSON retains every series." },
   ],
   discovery: { aliases: ["PERP"], dataRequirements: ["Perpetual market observations"], limitations: ["Free accounts see a fixed preview of the board, rankings and comparisons, and latest values for one market.", "Pro unlocks every market, full rankings and history.", "Rankings list up to ten markets each.", "Rates, premiums and changes are fractions in JSON.", "Open-interest history begins at first collection.", "Funding APR is a simple annualization, not a forecast.",
-    "Long/short account shares: venue definitions differ; history begins at first collection."] },
+    "Long/short account shares: venue definitions differ; history begins at first collection.",
+    "Liquidations come from each venue's public stream and begin at first collection: Binance and OKX send at most one a second per contract, Hyperliquid only its vault's backstop liquidations. Free shows totals and the three largest; Pro the hourly series and twenty.",
+    "Order book depth is read hourly for each venue's 50 largest markets; a band wider than the book a venue returns is a floor (≥). Free shows the latest; Pro the week's history."] },
   describe: (args) => TITLES[tabOf(args)],
   async load(args, ctx) {
     const requested = requestedOf(args);
@@ -173,6 +190,45 @@ export const perpsHeadless: HeadlessPaneDefinition<"bundle"> = {
           ...listMetadata(compare), total: compare.total, baseAsset: base,
           ...(spread ? { fundingSpread8h: spread.value, fundingSpreadHigh: spread.high.marketId, fundingSpreadLow: spread.low.marketId } : {}) } };
     }
+    if (tab === "liquidations" || tab === "depth") {
+      // A canonical identity names one contract; its base asset is what the venues share. A pair or plain name reads as its base asset.
+      const identity = marketQuery(requested);
+      const asked = identity.includes(":") ? (await fetchPerpSelection(identity, ctx.apiClient)).rows[0]?.baseAsset ?? identity : (requested || DEFAULT_MARKET).toUpperCase();
+      const notices = (base: string) => [...(requested ? [] : [`Showing ${DEFAULT_MARKET}. Try fn PERP ${EXAMPLE_MARKETS[1]} --tab ${tab}.`]),
+        ...requested && !identity.includes(":") && base.toUpperCase() !== asked ? readAs(base, requested) : [], ...venueUnused(String(args.options.venue ?? "all"), tab)];
+      if (tab === "liquidations") {
+        const data = await fetchPerpsLiquidations(asked, ctx.apiClient);
+        if (!data.markets.length && data.status !== "unavailable") throw noMarket(requested || asked, await nearestPerpMarkets(requested || asked, ctx.apiClient));
+        const told = notices(data.baseAsset);
+        const locked = lockedTable(data.locked);
+        const entries = (["long24h", "short24h", "long7d", "short7d"] as const).map((key) => ({ key, label: `${key.startsWith("long") ? "Longs" : "Shorts"} liquidated ${key.endsWith("24h") ? "24h" : "7d"}`,
+          value: data.totals[key], formatted: `${compact(data.totals[key])} USD` }));
+        return { sections: [{ title: "Totals", entries: [...entries, { key: "collectingSince", label: "Collecting since", value: data.collectingSince, formatted: time(data.collectingSince) }] },
+          { title: "By contract", columns: LIQUIDATION_TEXT_COLUMNS, rows: data.markets.map((row) => ({ ...row })) },
+          { title: "Hourly", columns: HOURLY_COLUMNS, rows: data.hourly.map((row) => ({ ...row })), ...locked },
+          { title: "Largest prints", columns: printTextColumns(data.baseAsset), rows: data.largest.map((row) => ({ ...row })) }],
+          complete: !data.locked && data.status === "ok" && !downStreams(data).length, notes: data.notes,
+          errors: data.locked ? [freePreviewNote({ shows: "liquidation totals and the three largest prints", adds: "the hourly series and the twenty largest prints" })] : [],
+          freshness: liquidationFreshness(data),
+          metadata: { ...(requested ? {} : { defaultArgument: DEFAULT_MARKET }), ...(told.length ? { notices: told } : {}), baseAsset: data.baseAsset, asOf: data.asOf, from: data.from,
+            access: data.access, locked: data.locked, status: data.status, collectingSince: data.collectingSince, streams: data.streams, notionalCurrency: "USD" } };
+      }
+      const data = await fetchPerpsDepth(asked, ctx.apiClient);
+      if (!data.rows.length && data.status !== "unavailable") throw noMarket(requested || asked, await nearestPerpMarkets(requested || asked, ctx.apiClient));
+      const told = notices(data.baseAsset);
+      const staleNote = depthStaleNote(data.rows);
+      // The band totals over the current books, as the tab's figures show them; a floor (≥) when a book ends inside the band.
+      const bands = depthBandTotals(data.rows).map((band) => ({ key: `band${band.key}`, label: band.label, value: band.bids + band.asks,
+        formatted: `${band.floor ? "≥" : ""}${compact(band.bids + band.asks)} USD (bids ${compact(band.bids)} · asks ${compact(band.asks)}, ${band.books} ${band.books === 1 ? "book" : "books"})` }));
+      return { sections: [...bands.length ? [{ title: "Band totals", entries: bands }] : [],
+        { title: "Order books", columns: DEPTH_TEXT_COLUMNS, rows: data.rows.map((row) => ({ ...row })) },
+        { title: "Hourly depth", columns: DEPTH_HISTORY_COLUMNS, rows: data.history.map((row) => ({ ...row })), ...lockedTable(data.locked) }],
+        complete: !data.locked && data.status === "ok" && !staleNote, notes: [...staleNote ? [staleNote] : [], ...data.notes],
+        errors: data.locked ? [freePreviewNote({ shows: "each book's latest depth", adds: "the week's hourly depth" })] : [],
+        freshness: depthFreshness(data),
+        metadata: { ...(requested ? {} : { defaultArgument: DEFAULT_MARKET }), ...(told.length ? { notices: told } : {}), baseAsset: data.baseAsset, asOf: data.asOf,
+          access: data.access, locked: data.locked, status: data.status, sources: data.sources, notionalCurrency: "USD", reach: "fraction of mid" } };
+    }
     const search = requested || DEFAULT_MARKET, venue = String(args.options.venue ?? "all");
     const market = await fetchPerpSelection(search, ctx.apiClient, venue !== "all" ? venue : undefined);
     const selected = market.rows[0];