gloomberb 0.18.4 → 0.19.0

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/freshness.ts

@@ -2,7 +2,7 @@ import type { PerpBoardRow } from "../../../api-client/perps";
 import type { HeadlessPaneFreshness } from "../../../types/headless";
 import { venueName, venuesOf } from "./model";
 
-type Dated = Pick<PerpBoardRow, "venue" | "observedAt">;
+type Dated = Pick<PerpBoardRow, "venue" | "observedAt" | "stale">;
 type Funded = Pick<PerpBoardRow, "venue" | "fundingRate" | "fundingRate8h" | "fundingKind" | "nextFundingAt">;
 
 const WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"] as const;
@@ -47,23 +47,25 @@ export function fundingNote(rows: readonly Funded[], now = Date.now()): string |
   }).join("; ")}`;
 }
 
+/** What a capture reads of a row: when it was observed and whether the venue has stopped answering for it. */
+const perpObservation = (row: Pick<PerpBoardRow, "observedAt" | "stale">) => ({ observedAt: row.observedAt, stale: row.stale });
+
 /**
- * How current a view of perpetual markets is: each venue's own newest observation, read once a minute (live while
- * every row followed has a price from its venue's socket within the minute) and stale after an hour without a read, and
- * what the funding figures it shows (`funding`) are. The report, the capture and the pane footer all read this, so they
- * end with the same line.
+ * How current a view of perpetual markets is: each venue's own newest observation, how old the oldest price shown is,
+ * and what the funding figures it shows (`funding`) are. `live` only while every row followed streams from its venue's
+ * socket; otherwise no feed word, since a row off the stream is the venue's own reading from the last pass (about once
+ * a minute), neither streamed nor held back. Stale after an hour without a read, or for a row whose venue stopped
+ * answering. The report, the capture and the pane footer all read this, rows and all, so they end with the same line.
  */
 export function perpFreshness(rows: readonly Dated[], { funding = [], venue = "all", now = Date.now(), live = false }: {
   funding?: readonly Funded[]; venue?: string; now?: number;
-  /** Every row followed moves with its venue's socket: the view is a live feed, not the minute's read. */
+  /** Every row followed moves with its venue's socket: the view is a live feed. */
   live?: boolean;
 } = {}): HeadlessPaneFreshness {
   const sources = venuesOf(rows).map((id) => ({ source: venueName(id), asOf: new Date(Math.max(...rows.filter((row) => row.venue === id)
     .map((row) => Date.parse(row.observedAt)))).toISOString() }));
   const source = sources.length ? sources.map((entry) => entry.source).join(", ") : venue !== "all" ? venueName(venue) : null;
   const note = fundingNote(funding, now);
-  return { ...(source ? { source } : {}), sources, status: live ? "live" : "delayed", maxAgeMinutes: 60, ...(note ? { note } : {}) };
+  return { ...(source ? { source } : {}), sources, ...(live ? { status: "live" as const } : {}), ageOnly: true, maxAgeMinutes: 60,
+    observations: rows.map(perpObservation), ...(note ? { note } : {}) };
 }
-
-/** What a capture reads of a row: when it was observed and whether the venue has stopped answering for it. */
-export const perpObservation = (row: Pick<PerpBoardRow, "observedAt" | "stale">) => ({ observedAt: row.observedAt, stale: row.stale });