@gloom-sh/terminal 0.19.2 → 0.19.3

package/src/plugins/builtin/credit-boards/headless.ts

@@ -1,6 +1,7 @@
 import type { HeadlessPaneColumn, HeadlessPaneDefinition, HeadlessPaneRow } from "../../../types/plugin";
 import type { CdxBoardIndex, CreditIndexQuote } from "../../../api-client/credit-boards";
 import { CDX_MAX_DAYS, fetchCdxBoard, fetchSovrBoard, loadCurrencyMoves } from "./client";
+import { readsInBatches } from "../../../market-data/batched-reads";
 import {
   cdxDay,
   cdxRows,
@@ -10,6 +11,7 @@ import {
   formatCurrencyMove,
   formatLevel,
   formatMove,
+  levelKinds,
   partialDayText,
   quoteUnits,
   sovrRows,
@@ -74,6 +76,8 @@ function historySection(index: CdxBoardIndex, days: number, now: number) {
   const priced = index.quote === "price" && index.points.some((point) => point.spreadBp !== undefined);
   const partial = today.partial && latest === index.date;
   const symbol = cdxSeries(index.id);
+  const shown = index.points.filter((point) => point.date > from).reverse();
+  const kinds = levelKinds(shown, (point) => point.kind);
   return {
     title: `${index.name} 5Y daily ${index.quote === "spread" ? "spread" : "price"}`,
     columns: [
@@ -83,11 +87,12 @@ function historySection(index: CdxBoardIndex, days: number, now: number) {
       { key: "prints", header: "Prints", align: "right" as const },
       { key: "maturity", header: "Contract", textFormat: (value: unknown) => formatContract(typeof value === "string" ? value : null) },
       ...(partial ? [dayColumn] : []),
+      ...kinds.columns,
     ],
-    rows: index.points.filter((point) => point.date > from).reverse().map((point) => ({
+    rows: shown.map((point) => ({
       day: point.date, level: point.level, unit,
       ...(priced ? { spreadBp: point.spreadBp ?? null, spreadUnit: "bp" } : {}),
-      prints: point.prints, maturity: point.maturity, series: symbol,
+      prints: point.prints, maturity: point.maturity, series: symbol, ...kinds.row(point),
       ...(partial && point.date === latest ? { session: partialDayText(point.prints, today.lastPrintAt), partial: true, lastPrintAt: today.lastPrintAt } : {}),
     })),
     rowUnitKey: "unit",
@@ -133,6 +138,7 @@ export const cdxHeadless: HeadlessPaneDefinition<"bundle"> = {
     const shown = index ? [index] : payload.indexes;
     // A server that predates the spread equivalent sends none: no column of blanks.
     const spreads = shown.some((entry) => entry.spreadBp !== undefined);
+    const kinds = levelKinds(shown, (entry) => entry.kind);
     const rows = cdxRows(shown, payload.asOf, now).map((row) => {
       const units = quoteUnits(row.index.quote);
       const priced = spreads && row.index.quote === "price";
@@ -151,6 +157,7 @@ export const cdxHeadless: HeadlessPaneDefinition<"bundle"> = {
         contract: formatContract(row.index.maturity),
         date: row.index.date,
         changeDate: row.day.changeDate,
+        ...kinds.row(row.index),
         ...(row.day.partial ? { session: partialDayText(row.index.prints, row.day.lastPrintAt), partial: true, lastPrintAt: row.day.lastPrintAt } : {}),
       };
     });
@@ -158,7 +165,7 @@ export const cdxHeadless: HeadlessPaneDefinition<"bundle"> = {
     return {
       sections: [
         {
-          title: "On the run, 5Y", columns: [...CDX_COLUMNS.filter((column) => spreads || column !== spreadColumn), ...(anyPartial ? [dayColumn] : [])], rows,
+          title: "On the run, 5Y", columns: [...CDX_COLUMNS.filter((column) => spreads || column !== spreadColumn), ...(anyPartial ? [dayColumn] : []), ...kinds.columns], rows,
           rowUnitKey: "unit", rowSymbolKey: "series", rowAsOfKey: "date", interval: "daily",
         },
         ...(index ? [historySection(index, days, now)] : []),
@@ -170,6 +177,15 @@ export const cdxHeadless: HeadlessPaneDefinition<"bundle"> = {
   },
 };
 
+const SOVR_COLUMNS: HeadlessPaneColumn[] = [
+  { key: "name", header: "Sovereign" },
+  levelColumn,
+  moveColumn("change1M", "1M", "unit"),
+  { key: "currency", header: "Ccy 1M", align: "right" },
+  { key: "percentile", header: "Pctl 1Y", align: "right", format: percentile },
+  { key: "date", header: "As of" },
+];
+
 export const sovrHeadless: HeadlessPaneDefinition<"rows"> = {
   discovery: { aliases: ["SOVR", "WCDS"], dataRequirements: ["Gloom Cloud sovereign CDS endpoint"],
     limitations: ["Daily 5Y levels from public DTCC prints; thinly traded names can miss days."] },
@@ -178,14 +194,7 @@ export const sovrHeadless: HeadlessPaneDefinition<"rows"> = {
   argument: { kind: "free-text", optional: true, placeholder: "country",
     description: "A country (Brazil, BR) to list its row alone; omit for every sovereign." },
   options: [],
-  columns: [
-    { key: "name", header: "Sovereign" },
-    levelColumn,
-    moveColumn("change1M", "1M", "unit"),
-    { key: "currency", header: "Ccy 1M", align: "right" },
-    { key: "percentile", header: "Pctl 1Y", align: "right", format: percentile },
-    { key: "date", header: "As of" },
-  ],
+  columns: SOVR_COLUMNS,
   describe: "Sovereign CDS",
   async load(args, ctx) {
     const payload = await fetchSovrBoard(ctx.apiClient);
@@ -193,10 +202,13 @@ export const sovrHeadless: HeadlessPaneDefinition<"rows"> = {
     const country = query ? findSovereign(payload.sovereigns, query) : null;
     if (query && !country) throw new Error(`No sovereign ${query}. Use one of: ${payload.sovereigns.map((entry) => entry.name).join(", ")}.`);
     const sovereigns = country ? [country] : payload.sovereigns;
+    const batch = await readsInBatches(ctx.marketData, "getPriceHistory");
     const moves = await loadCurrencyMoves(sovereigns.map((row) => row.currency),
-      (symbol) => ctx.marketData.getPriceHistory(symbol, "", "3M"));
+      (symbol) => ctx.marketData.getPriceHistory(symbol, "", "3M", batch ? { batch } : undefined), batch);
     const publisher = boardPublisher(payload.source);
+    const kinds = levelKinds(sovereigns, (row) => row.kind);
     return {
+      ...(kinds.columns.length ? { columns: [...SOVR_COLUMNS, ...kinds.columns] } : {}),
       rows: sovrRows(sovereigns, payload.asOf, moves).map((row) => ({
         name: row.label,
         series: sovereignSeries(row.sovereign.id),
@@ -206,6 +218,7 @@ export const sovrHeadless: HeadlessPaneDefinition<"rows"> = {
         currency: formatCurrencyMove(row.sovereign.currency, row.currencyMove),
         percentile: rank(row.percentile),
         date: row.sovereign.date,
+        ...kinds.row(row.sovereign),
       })),
       rowUnitKey: "unit",
       rowSymbolKey: "series",

package/src/plugins/builtin/credit-boards/model.ts

@@ -2,12 +2,14 @@ import type {
   CdxBoardIndex,
   CreditBoardPoint,
   CreditIndexQuote,
+  CreditLevelKind,
   SovrBoardSovereign,
 } from "../../../api-client/credit-boards";
 import { spanAxisFormatter, formatBpAxis } from "../../../components/chart-table/axis";
 import { historyStatistics } from "../../../components/chart/curve/model";
 import type { MarketBoardRow } from "../../../components/market-board";
 import type { PricePoint } from "../../../types/financials";
+import type { HeadlessPaneColumn } from "../../../types/plugin";
 
 const YEAR_DAYS = 365;
 /** A level older than this is not the current market. */
@@ -93,6 +95,33 @@ function utcClock(instant: string): string | null {
   return Number.isFinite(time) ? new Date(time).toISOString().slice(11, 16) : null;
 }
 
+/**
+ * How a level that is the day's settlement price, not its trades, is marked
+ * beside its date.
+ */
+export const SETTLEMENT_TEXT = "settlement";
+
+/**
+ * A report's mark for the levels that are settlement prices: blank for a
+ * level from the day's trades. Shown only when a row is one, and each row
+ * then carries `kind`.
+ */
+const levelKindColumn: HeadlessPaneColumn = {
+  key: "kind", header: "Level",
+  description: "Blank for a level from the day's trades. settlement for the day's end-of-day settlement price, which stands in "
+    + "on a day without enough agreeing trades; its prints are 0.",
+  format: (value) => value === "settlement" ? SETTLEMENT_TEXT : "",
+};
+
+/** `kind` on every row once one level is a settlement; nothing otherwise, so a report without one is unchanged. */
+export function levelKinds<T>(items: readonly T[], kindOf: (item: T) => CreditLevelKind | null | undefined) {
+  const shown = items.some((item) => kindOf(item) === "settlement");
+  return {
+    columns: shown ? [levelKindColumn] : [],
+    row: (item: T) => shown ? { kind: kindOf(item) ?? "traded" } : {},
+  };
+}
+
 /**
  * What a day still trading rests on: `so far, 38 prints, last 08:09 UTC`.
  * The print time is left out when the server does not say it.

package/src/plugins/builtin/credit-boards/sovr-pane.tsx

@@ -25,12 +25,14 @@ import { formatAsOf } from "../cds/model";
 import { FIXED_INCOME_PANE_ID } from "../fixed-income/model";
 import { useCommandValue } from "../shared/command-tab";
 import { getCachedSovrBoard, loadCurrencyMoves, loadSovrBoard } from "./client";
+import { readsInBatches } from "../../../market-data/batched-reads";
 import {
   findSovereign,
   formatContract,
   formatCurrencyMove,
   formatLevel,
   formatMove,
+  SETTLEMENT_TEXT,
   sovrRows,
   type SovrRow,
 } from "./model";
@@ -65,7 +67,7 @@ function SovereignDetail({ row, width, height, focused }: { row: SovrRow; width:
   const { sovereign, year } = row;
   const items: StatItem[] = [
     { id: "level", label: "5Y spread", value: formatLevel("spread", sovereign.level),
-      detail: `${formatPercentileRank(year.percentile, "1Y")} · ${sovereign.date}` },
+      detail: [formatPercentileRank(year.percentile, "1Y"), sovereign.date, ...(sovereign.kind === "settlement" ? [SETTLEMENT_TEXT] : [])].join(" · ") },
     { id: "1m", label: "1M", value: formatMove("spread", sovereign.change1M) },
     { id: "1w", label: "1W", value: formatMove("spread", sovereign.change1W) },
     { id: "fx", label: "Currency 1M", value: formatCurrencyMove(sovereign.currency, row.currencyMove) },
@@ -99,9 +101,12 @@ export function SovrPane({ focused, width, height }: PaneProps) {
   // Each currency's month against the dollar, from the same daily closes the FX panes use.
   const currencies = useMemo(() => [...new Set(payload?.sovereigns.map((row) => row.currency) ?? [])].sort().join(","),
     [payload]);
-  const movesLoader = useCallback(() => provider && currencies
-    ? loadCurrencyMoves(currencies.split(","), (symbol) => provider.getPriceHistory(symbol, "", "3M"))
-    : Promise.resolve(NO_MOVES), [currencies, provider]);
+  const movesLoader = useCallback(async () => {
+    if (!provider || !currencies) return NO_MOVES;
+    // Every currency at once, in batch requests, from a source that batches them; a few at a time otherwise.
+    const batch = await readsInBatches(provider, "getPriceHistory");
+    return loadCurrencyMoves(currencies.split(","), (symbol) => provider.getPriceHistory(symbol, "", "3M", batch ? { batch } : undefined), batch);
+  }, [currencies, provider]);
   const moves = useAsyncResource(movesLoader, { keepPreviousData: true });
   const rows = useMemo(() => payload ? sovrRows(payload.sovereigns, payload.asOf, moves.data ?? NO_MOVES) : EMPTY_ROWS,
     [moves.data, payload]);

package/src/plugins/builtin/crypto-board/bitcoin-network.ts

@@ -0,0 +1,143 @@
+import { apiClient } from "../../../api-client";
+import { ApiRequestError } from "../../../api-client/errors";
+import type { BitcoinNetworkDailyValue, BitcoinNetworkPayload } from "../../../api-client/crypto-markets";
+import { createPluginCache } from "../../../data/plugin-cache";
+import type { SeriesAttribution, SeriesDefinition, SeriesPoint } from "../../../series/types";
+import { isFiniteNumber } from "../../../utils/guards";
+import { loadCloudResource, unavailableOnServer } from "../shared/cloud-resource";
+import { cachedSeriesNote } from "../shared/series-warning";
+
+const bitcoinNetworkCache = createPluginCache<BitcoinNetworkPayload>({
+  kind: "bitcoin-network",
+  source: "gloom-cloud",
+  schemaVersion: 1,
+  // The server reads the estimate every half hour and the daily figures every six hours.
+  policy: { staleMs: 30 * 60_000, expireMs: 30 * 86_400_000 },
+});
+
+export const BITCOIN_NETWORK_CACHES = [bitcoinNetworkCache] as const;
+
+const MAX_DAYS = 20_000;
+const date = (value: unknown): value is string => typeof value === "string" && /^\d{4}-\d{2}-\d{2}$/.test(value);
+const instant = (value: unknown): value is string => typeof value === "string" && Number.isFinite(Date.parse(value));
+const daily = (rows: unknown): rows is BitcoinNetworkDailyValue[] => Array.isArray(rows) && rows.length <= MAX_DAYS
+  && rows.every((row) => !!row && date((row as BitcoinNetworkDailyValue).date) && isFiniteNumber((row as BitcoinNetworkDailyValue).value));
+
+function validateBitcoinNetwork(data: BitcoinNetworkPayload): BitcoinNetworkPayload {
+  const retarget = data?.retarget;
+  if (
+    !data
+    || data.version !== 1
+    || !instant(data.generatedAt)
+    || typeof data.source?.name !== "string" || !data.source.name.trim()
+    || !["available", "stale", "unavailable"].includes(data.status)
+    || !daily(data.hashrate)
+    || !daily(data.hashprice)
+    || !daily(data.retargetHistory)
+    || !Array.isArray(data.difficulty)
+    || !data.difficulty.every((row) => !!row && date(row.date) && isFiniteNumber(row.difficulty) && row.difficulty > 0)
+    || (retarget !== null && (!retarget || !isFiniteNumber(retarget.changePercent) || !instant(retarget.estimatedAt) || !instant(retarget.readAt)))
+    || !Array.isArray(data.warnings)
+  ) {
+    throw new Error("The server returned invalid bitcoin network data");
+  }
+  return data;
+}
+
+async function fetchBitcoinNetwork(client: Pick<typeof apiClient, "getCloudBitcoinNetwork"> = apiClient): Promise<BitcoinNetworkPayload> {
+  try {
+    return validateBitcoinNetwork(await client.getCloudBitcoinNetwork());
+  } catch (error) {
+    if (error instanceof ApiRequestError && error.status === 503) throw unavailableOnServer(error, "Bitcoin network data is temporarily unavailable", [503]);
+    throw unavailableOnServer(error, "Bitcoin network data is not available yet.");
+  }
+}
+
+function loadBitcoinNetwork() {
+  return loadCloudResource(bitcoinNetworkCache, "all", () => fetchBitcoinNetwork(), { validate: validateBitcoinNetwork });
+}
+
+const points = (rows: readonly BitcoinNetworkDailyValue[]): SeriesPoint[] =>
+  rows.map((row) => ({ date: Date.parse(`${row.date}T00:00:00Z`), value: row.value }));
+
+const TAGS = ["bitcoin", "BTC", "BTC-USD", "mining", "miner", "miners", "bitcoin mining", "network", "on-chain"];
+
+/**
+ * A series of the network board: its points, cited as the server names its
+ * source, with the board's warnings about this figure (`concerns`: "Hash
+ * rate, difficulty and hashprice could not refresh" is three series', "The
+ * retarget estimate is unavailable" the estimate's alone) and the
+ * cached-copy note.
+ */
+function networkSeries(
+  definition: Omit<Extract<SeriesDefinition, { load: unknown }>, "load" | "frequency" | "group">
+    & { frequency?: SeriesDefinition["frequency"] },
+  read: (payload: BitcoinNetworkPayload) => SeriesPoint[],
+  { concerns, derived }: { concerns: RegExp; derived?: string },
+): SeriesDefinition {
+  return {
+    frequency: "daily",
+    group: "Crypto",
+    refreshMs: 30 * 60_000,
+    ...definition,
+    load: async () => {
+      const resource = await loadBitcoinNetwork();
+      const found = read(resource.payload);
+      if (!found.length) throw new Error(`${definition.name} is not available yet.`);
+      const note = cachedSeriesNote(resource);
+      const own = resource.payload.warnings.filter((line) => concerns.test(line)).join(" ");
+      const warning = note.warning ?? (own || undefined);
+      const source = resource.payload.source.name.trim();
+      const attribution: SeriesAttribution = { source: derived ? `${source}, ${derived}` : source };
+      return { points: found, attribution, ...note, ...warning ? { warning } : {} };
+    },
+  } as SeriesDefinition;
+}
+
+/**
+ * The bitcoin network for `fn G`: hash rate, difficulty, the next
+ * retarget's estimate and hashprice. `fn G hashrate`, `difficulty`,
+ * `retarget` and `hashprice` chart them by their aliases; `catalog
+ * hashrate`, `hashprice`, `difficulty`, `mining` and `miner` find them by
+ * their tags.
+ */
+export const BITCOIN_NETWORK_SERIES: readonly SeriesDefinition[] = [
+  networkSeries({
+    id: "bitcoin:hashrate",
+    name: "Bitcoin network hash rate",
+    unit: "EH/s",
+    tags: [...TAGS, "hashrate", "hash rate"],
+    aliases: ["hashrate"],
+    description: "The bitcoin network's hash rate in exahashes per second, each UTC day's average, estimated from the blocks found; the newest day is the day so far.",
+  }, (payload) => points(payload.hashrate), { concerns: /\bhash rate\b/i }),
+  networkSeries({
+    id: "bitcoin:difficulty",
+    name: "Bitcoin mining difficulty (trillions)",
+    unit: "number",
+    frequency: "irregular",
+    style: "step",
+    tags: [...TAGS, "difficulty", "retarget", "difficulty adjustment"],
+    aliases: ["difficulty"],
+    description: "The difficulty each retarget set, every 2,016 blocks, in trillions, dated by the block that set it.",
+  }, (payload) => payload.difficulty.map((row) => ({ date: Date.parse(`${row.date}T00:00:00Z`), value: Number((row.difficulty / 1e12).toFixed(4)) })),
+  { concerns: /\bdifficulty\b/i }),
+  networkSeries({
+    id: "bitcoin:retarget-estimate",
+    name: "Bitcoin next difficulty retarget estimate",
+    unit: "%",
+    tags: [...TAGS, "difficulty", "retarget", "difficulty adjustment", "estimate"],
+    aliases: ["retarget"],
+    description: "The estimated change in difficulty at the next retarget, in percent, as read each UTC day since Gloom began keeping it in October 2026.",
+  }, (payload) => points(payload.retargetHistory), { concerns: /\bretarget\b/i }),
+  networkSeries({
+    id: "bitcoin:hashprice",
+    name: "Bitcoin hashprice (derived)",
+    unit: "USD/PH/s/day",
+    tags: [...TAGS, "hashprice", "hash price", "miner revenue"],
+    aliases: ["hashprice"],
+    description: "Derived, not quoted: what 1 PH/s is expected to earn in a day, in USD, at the day's difficulty, average block reward (subsidy and fees) and BTC price.",
+  }, (payload) => points(payload.hashprice), {
+    concerns: /\bhashprice\b/i,
+    derived: "derived from the block rewards, the BTC price and the difficulty",
+  }),
+];

package/src/plugins/builtin/crypto-board/headless.ts

@@ -31,15 +31,16 @@ const COIN_COLUMNS: HeadlessPaneColumn[] = [
   { key: "rank", header: "#", align: "right" },
   { key: "code", header: "Coin" },
   { key: "name", header: "Name" },
-  { key: "price", header: "Price", align: "right", format: (_value, row) => String(row.priceText ?? "—") },
+  // Every coin is priced, traded and valued in US dollars: the text headers say so; an export keeps its headers.
+  { key: "price", header: "Price", textHeader: "Price USD", align: "right", format: (_value, row) => String(row.priceText ?? "—") },
   // Since 00:00 UTC, the day `quote` gives a coin (CRYPTO_CHANGE_BASIS_LABEL): the text says so, as the pane's
   // CHG% UTC does, and an export keeps the header it has always had.
   { key: "changePercent", header: "Chg %", textHeader: "Chg % UTC", align: "right", format: percent },
   { key: "return7d", header: "7D %", align: "right", format: percent },
   { key: "return30d", header: "30D %", align: "right", format: percent },
   { key: "return1y", header: "1Y %", align: "right", format: percent },
-  { key: "volume24h", header: "Vol 24h", align: "right", format: compact },
-  { key: "marketCap", header: "Market cap", align: "right", format: compact },
+  { key: "volume24h", header: "Vol 24h", textHeader: "Vol 24h USD", align: "right", format: compact },
+  { key: "marketCap", header: "Market cap", textHeader: "Market cap USD", align: "right", format: compact },
 ];
 
 /**

package/src/plugins/builtin/crypto-board/index.tsx

@@ -1,8 +1,8 @@
 import type { PluginModule } from "../plugin-module";
 import { LIVE_STREAMING_QUICK_SETTING, withLiveStreamingSetting } from "../../../state/hooks/live-streaming";
 import { cryptoMarketsCache, DEFI_TVL_CACHES, STABLECOIN_SUPPLY_CACHES } from "./client";
+import { BITCOIN_NETWORK_CACHES } from "./bitcoin-network";
 import { cryptoBoardHeadless } from "./headless";
-import { CryptoBoardPane } from "./pane";
 import { CRYPTO_SERIES } from "./series";
 
 export const cryptoBoardModule: PluginModule = {
@@ -12,7 +12,7 @@ export const cryptoBoardModule: PluginModule = {
       id: "crypto-board",
       name: "Crypto",
       icon: "C",
-      component: CryptoBoardPane,
+      get component(): typeof import("./pane").CryptoBoardPane { const { CryptoBoardPane } = require("./pane"); return CryptoBoardPane; },
       defaultPosition: "right",
       defaultMode: "floating",
       defaultFloatingSize: { width: 120, height: 32 },
@@ -40,10 +40,12 @@ export const cryptoBoardModule: PluginModule = {
     cryptoMarketsCache.attach(ctx.persistence);
     for (const cache of STABLECOIN_SUPPLY_CACHES) cache.attach(ctx.persistence);
     for (const cache of DEFI_TVL_CACHES) cache.attach(ctx.persistence);
+    for (const cache of BITCOIN_NETWORK_CACHES) cache.attach(ctx.persistence);
   },
   dispose() {
     cryptoMarketsCache.reset();
     for (const cache of STABLECOIN_SUPPLY_CACHES) cache.reset();
     for (const cache of DEFI_TVL_CACHES) cache.reset();
+    for (const cache of BITCOIN_NETWORK_CACHES) cache.reset();
   },
 };

package/src/plugins/builtin/crypto-board/series.ts

@@ -1,6 +1,7 @@
 import type { SeriesDefinition, SeriesPoint } from "../../../series/types";
 import { cachedSeriesNote } from "../shared/series-warning";
 import { loadDefiTvl, loadStablecoinSupply, loadStablecoinSupplyHistory } from "./client";
+import { BITCOIN_NETWORK_SERIES } from "./bitcoin-network";
 
 const DAY_MS = 86_400_000;
 
@@ -114,4 +115,5 @@ export const CRYPTO_SERIES: readonly SeriesDefinition[] = [
   },
   ...STABLECOIN_SUPPLY_SERIES,
   DEFI_TVL_SERIES,
+  ...BITCOIN_NETWORK_SERIES,
 ];

package/src/plugins/builtin/crypto-etf-flows/client.ts

@@ -18,7 +18,9 @@ const textOrNull = (value: unknown) => value === null || text(value);
 /**
  * The flows as served, or an error: the asset asked for, its funds once each,
  * every day newest first with a figure or none for each fund, and where they
- * are from. A payload that breaks any of it is not drawn.
+ * are from. A payload that breaks any of it is not drawn. A day's price move
+ * that is not a number or null is dropped from that day alone: the flows
+ * stand without it.
  */
 export function validateCryptoEtfFlows(payload: CryptoEtfFlowsPayload, asset: CryptoEtfFlowAsset): CryptoEtfFlowsPayload {
   const invalid = (): never => { throw new Error("The server returned invalid crypto ETF flows"); };
@@ -35,7 +37,12 @@ export function validateCryptoEtfFlows(payload: CryptoEtfFlowsPayload, asset: Cr
       || !Array.isArray(day.pending) || day.pending.some((ticker) => !known.has(ticker))) return invalid();
   }
   if (payload.days[0] && payload.days[0].date !== payload.asOf) return invalid();
-  return payload;
+  if (payload.days.every((day) => day.priceChangePct === undefined || flow(day.priceChangePct))) return payload;
+  return { ...payload, days: payload.days.map((day) => {
+    if (day.priceChangePct === undefined || flow(day.priceChangePct)) return day;
+    const { priceChangePct: _dropped, ...rest } = day;
+    return rest;
+  }) };
 }
 
 export async function fetchCryptoEtfFlows(

package/src/plugins/builtin/crypto-etf-flows/headless.ts

@@ -2,6 +2,7 @@ import type { CryptoEtfFlowsPayload } from "../../../api-client/crypto-etf-flows
 import type { HeadlessPaneColumn } from "../../../types/headless";
 import type { HeadlessPaneDefinition } from "../../../types/plugin";
 import { REPORT_ROWS } from "../shared/headless-options";
+import { readPriceWindow, type PriceWindow } from "../../../utils/price-window";
 import { fetchCryptoEtfFlows } from "./client";
 import {
   cryptoEtfFlowAsset,
@@ -9,16 +10,22 @@ import {
   cryptoEtfFlowSummary,
   formatFlow,
   formatFlowAmount,
+  formatPriceChange,
+  hasFundPriceChanges,
   pendingText,
 } from "./model";
 
 const flowCell = (value: unknown) => formatFlow(typeof value === "number" ? value : null);
+const optionText = (value: unknown) => typeof value === "string" && value.trim() ? value : undefined;
 
-/** Date, the day's total and each fund, in US$ millions as published. */
+/** Date, the day's total, the funds' price move when served, and each fund, in US$ millions as published. */
 function flowColumns(payload: CryptoEtfFlowsPayload): HeadlessPaneColumn[] {
   return [
     { key: "date", header: "Date", shrink: false },
     { key: "total", header: "Total", align: "right", format: flowCell },
+    ...hasFundPriceChanges(payload)
+      ? [{ key: "priceChangePct", header: "Price %", literalHeader: true, align: "right" as const, format: (value: unknown) => formatPriceChange(typeof value === "number" ? value : null) }]
+      : [],
     // A fund the day still waits on reads "pending", as in the pane; none at all is a dash.
     ...payload.funds.map((fund): HeadlessPaneColumn => ({
       key: fund.ticker, header: fund.ticker, literalHeader: true, align: "right",
@@ -28,6 +35,13 @@ function flowColumns(payload: CryptoEtfFlowsPayload): HeadlessPaneColumn[] {
   ];
 }
 
+/** "Net flows of the US spot bitcoin ETFs in US$ millions. 2026-10-19 to 2026-10-23: +$301.20M over 5 trading days." */
+function windowSummaryLine(payload: CryptoEtfFlowsPayload, window: PriceWindow, days: CryptoEtfFlowsPayload["days"]): string {
+  const total = days.some((day) => day.total != null) ? days.reduce((sum, day) => sum + (day.total ?? 0), 0) : null;
+  return `Net flows of the US spot ${cryptoEtfFlowAssetLabel(payload.asset).toLowerCase()} ETFs in US$ millions. ${window.from} to ${window.to}: `
+    + `${formatFlowAmount(total)} over ${days.length} trading ${days.length === 1 ? "day" : "days"}.`;
+}
+
 /** "Net flows of the US spot bitcoin ETFs in US$ millions. 2026-10-20: -$6.70M (IBIT pending); 5 days ..., since 2024-01-11 +$57.47B." */
 function summaryLine(payload: CryptoEtfFlowsPayload): string {
   const summary = cryptoEtfFlowSummary(payload);
@@ -43,6 +57,15 @@ function summaryLine(payload: CryptoEtfFlowsPayload): string {
   ].join(" ");
 }
 
+/**
+ * "Funds: IBIT iShares Bitcoin Trust ETF, ..., BTC Grayscale Bitcoin Mini Trust ETF.": a column is headed by
+ * the fund's ticker, and BTC or ETH there is Grayscale's mini fund, not the coin. Null when no fund is named.
+ */
+function fundsLine(payload: CryptoEtfFlowsPayload): string | null {
+  const named = payload.funds.flatMap((fund) => fund.name ? [`${fund.ticker} ${fund.name}`] : []);
+  return named.length ? `Funds: ${named.join(", ")}.` : null;
+}
+
 export const cryptoEtfFlowsHeadless: HeadlessPaneDefinition<"rows"> = {
   shape: "rows",
   argument: { kind: "none" },
@@ -69,6 +92,22 @@ export const cryptoEtfFlowsHeadless: HeadlessPaneDefinition<"rows"> = {
       minimum: 1,
       maximum: 2000,
     },
+    {
+      key: "from",
+      type: "string",
+      placeholder: "year|date",
+      description: "First US trading day listed, as a year (2024) or a date (2026-10-19); lists every day of the window in place of --limit.",
+      example: "--from 2026-10-19 --to 2026-10-23",
+      shot: { reportOnly: "lists the report's days for those dates" },
+      replaces: ["limit"],
+    },
+    {
+      key: "to",
+      type: "string",
+      placeholder: "year|date",
+      description: "Last US trading day listed, with --from (default the newest).",
+      shot: { reportOnly: "lists the report's days for those dates" },
+    },
   ],
   columns: [
     { key: "date", header: "Date" },
@@ -81,24 +120,36 @@ export const cryptoEtfFlowsHeadless: HeadlessPaneDefinition<"rows"> = {
     limitations: [
       "US spot bitcoin and ether ETFs only, net creations and redemptions in US$ millions as Farside Investors publishes them.",
       "The newest day fills in fund by fund; a fund that has not reported shows as pending.",
+      "0.0 is the publisher's zero for the fund that day; a dash is a day it published no figure for.",
+      "Price % is the funds' price move that day: the median of their close-to-close changes.",
     ],
   },
-  freshness: { source: "Farside Investors", publisher: "Farside Investors", status: "not-a-feed", basis: "daily fund flows", cadence: "daily", tradingDayMarket: "US" },
+  // Stale once a trading day's flows are missing (the load's `cadence`), except in a window that ended before the newest day.
+  freshness: { source: "Farside Investors", publisher: "Farside Investors", status: "not-a-feed", basis: "daily fund flows", tradingDayMarket: "US" },
   async load(args, ctx) {
     const asset = cryptoEtfFlowAsset(args.options.asset);
+    // --from 2026-10-19 --to 2026-10-23 lists those days, every one of them, in place of the newest --limit.
+    const window = readPriceWindow(optionText(args.options.from), optionText(args.options.to));
     const payload = await fetchCryptoEtfFlows(asset, ctx.apiClient);
     const limit = Math.max(1, Number(args.options.limit) || 20);
-    const rows = payload.days.slice(0, limit).map((day) => ({
+    const days = window ? payload.days.filter((day) => day.date >= window.from && day.date <= window.to) : payload.days.slice(0, limit);
+    const priced = hasFundPriceChanges(payload);
+    const rows = days.map((day) => ({
       date: day.date,
       total: day.total,
+      ...(priced ? { priceChangePct: day.priceChangePct ?? null } : {}),
       ...Object.fromEntries(payload.funds.map((fund) => [fund.ticker, day.flows[fund.ticker] ?? null])),
       pending: day.pending,
     }));
     const summary = cryptoEtfFlowSummary(payload);
+    const funds = fundsLine(payload);
+    // A window that ends before the newest day is dated by its own last day.
+    const asOf = window ? days[0]?.date ?? null : payload.asOf;
     return {
       rows,
       columns: flowColumns(payload),
-      notes: [summaryLine(payload), `Source: ${payload.source.publisher}, ${payload.source.url}`],
+      ...(window && !days.length ? { errors: [`No US trading day with flows from ${window.from} to ${window.to}.`] } : {}),
+      notes: [window ? windowSummaryLine(payload, window, days) : summaryLine(payload), ...funds ? [funds] : [], `Source: ${payload.source.publisher}, ${payload.source.url}`],
       complete: !payload.stale,
       ...(payload.stale ? { warnings: [`The flows were last read ${payload.fetchedAt.slice(0, 10)}; newer days may be missing.`] } : {}),
       freshness: {
@@ -106,10 +157,12 @@ export const cryptoEtfFlowsHeadless: HeadlessPaneDefinition<"rows"> = {
         publisher: payload.source.publisher,
         status: "not-a-feed",
         basis: "daily fund flows",
-        cadence: "daily",
+        ...(window && asOf !== payload.asOf ? {} : { cadence: "daily" as const }),
         tradingDayMarket: "US",
-        asOf: payload.asOf,
+        ...(asOf ? { asOf } : {}),
         oldest: null,
+        // When the server last read the publisher's table, which is what this report retrieved.
+        retrievedAt: payload.fetchedAt,
       },
       metadata: {
         asset,
@@ -117,6 +170,8 @@ export const cryptoEtfFlowsHeadless: HeadlessPaneDefinition<"rows"> = {
         asOf: payload.asOf,
         fetchedAt: payload.fetchedAt,
         stale: payload.stale,
+        ...(window ? { requestedWindow: window } : {}),
+        ...(priced ? { priceChangeBasis: "median of the funds' close-to-close price changes, percent" } : {}),
         source: payload.source,
         funds: payload.funds,
         summary: {

package/src/plugins/builtin/crypto-etf-flows/index.tsx

@@ -2,7 +2,6 @@ import type { PluginModule } from "../plugin-module";
 import { cryptoEtfFlowsCache } from "./client";
 import { cryptoEtfFlowsHeadless } from "./headless";
 import { CRYPTO_ETF_FLOWS_PANE_ID } from "./model";
-import { CryptoEtfFlowsPane } from "./pane";
 
 /** ETFF: the daily net flows of the US spot bitcoin and ether ETFs, per fund. */
 export const cryptoEtfFlowsModule: PluginModule = {
@@ -11,7 +10,7 @@ export const cryptoEtfFlowsModule: PluginModule = {
       id: CRYPTO_ETF_FLOWS_PANE_ID,
       name: "Crypto ETF Flows",
       icon: "F",
-      component: CryptoEtfFlowsPane,
+      get component(): typeof import("./pane").CryptoEtfFlowsPane { const { CryptoEtfFlowsPane } = require("./pane"); return CryptoEtfFlowsPane; },
       defaultPosition: "right",
       defaultMode: "floating",
       defaultFloatingSize: { width: 120, height: 32 },

package/src/plugins/builtin/crypto-etf-flows/model.ts

@@ -103,11 +103,24 @@ export function pendingText(day: CryptoEtfFlowDay | null | undefined): string |
 
 export type CryptoEtfFlowColumn = Omit<DataTableColumn, "id"> & { id: string };
 
-/** Date and the day's total, then each fund in the publisher's order. */
+/** Whether the server sent the funds' daily price move beside the flows. */
+export const hasFundPriceChanges = (payload: CryptoEtfFlowsPayload | null | undefined) =>
+  !!payload?.days.some((day) => day.priceChangePct !== undefined);
+
+/** A day's price move as the table shows it: `+2.15%`, `-0.40%`, `—` for none. */
+export function formatPriceChange(value: number | null | undefined): string {
+  if (value == null || !Number.isFinite(value)) return "—";
+  return `${value > 0 ? "+" : ""}${value.toFixed(2)}%`;
+}
+
+/** Date, the day's total and the funds' price move that day, then each fund in the publisher's order. */
 export function cryptoEtfFlowColumns(payload: CryptoEtfFlowsPayload | null | undefined): CryptoEtfFlowColumn[] {
   return [
     { id: "date", label: "Date", width: 12, align: "left" },
     { id: "total", label: "Total", width: 9, align: "right", title: "The day's net flow across the funds, US$ millions" },
+    ...hasFundPriceChanges(payload)
+      ? [{ id: "price", label: "Price %", width: 9, align: "right" as const, title: "The funds' price move that day: the median of their close-to-close changes" }]
+      : [],
     ...(payload?.funds ?? []).map((fund): CryptoEtfFlowColumn => ({
       id: `fund:${fund.ticker}`,
       label: fund.ticker,