@sharpe-terminal/mcp-server 1.2.0 → 1.5.0

package/dist/composite-tools.js

@@ -1,8 +1,16 @@
 /**
- * Composite tools that call multiple API endpoints concurrently
- * and return formatted markdown. Mirrors the Python server's
- * analyze_coin, market_briefing, and find_opportunities.
+ * Composite tools that call several API endpoints concurrently and return
+ * formatted markdown. Mirrors the Python server's analyze_coin,
+ * market_briefing and find_opportunities line for line.
+ *
+ * Every number a composite prints is a field the API serves, the value the web
+ * page and /api/v1 give for the same request (engine L4 WP-D14): the
+ * rankings, floors, averages and APRs are request parameters and response
+ * fields, never recomputed here. A report ends with the freshness of every
+ * answer it read.
  */
+import { freshnessOf } from "./api-client.js";
+import { splitPaginated } from "./tool-runtime.js";
 // ── Formatting helpers ────────────────────────────────────────────────
 export function fmtUsd(value) {
     if (value == null)
@@ -29,6 +37,44 @@ export function fmtRate(value) {
         return "N/A";
     return `${(value * 100).toFixed(4)}%`;
 }
+/** An annualized fraction (0.25 = 25%) as a percentage, or N/A. */
+export function fmtApr(value) {
+    const n = finiteOrNull(value);
+    return n == null ? "N/A" : `${(n * 100).toFixed(1)}%`;
+}
+/**
+ * The open-interest floor (USD) the composites ask the API to apply: funding
+ * extremes (`min_oi_usd`), the spot-perp perp leg and both cross-exchange legs
+ * (`minOiUsd`, `minVolUsd`). Unfloored, every extreme was a dust market (ESIM
+ * on KuCoin: $33K of OI at -16,862% APR, 2026-09-24 audit). The API applies
+ * it; unknown open interest fails it there.
+ */
+export const LIQUIDITY_FLOOR_USD = 1_000_000;
+/**
+ * `max_age_h` on the funding calls: v1 leaves out rows not written for six
+ * hours (V1_MAX_AGE_HOURS in the funding read model), so a keyless answer
+ * counts the same rows as a keyed one. v1 ignores the parameter.
+ */
+export const FUNDING_MAX_AGE_HOURS = 6;
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function finiteOrNull(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function text(value) {
+    return typeof value === "string" && value !== "" ? value : null;
+}
+/** Rows of a list payload that may be wrapped as `{ data, pagination }` or `{ items }`. */
+function listRows(payload) {
+    let rows = splitPaginated(payload).rows;
+    if (isRecord(rows) && "items" in rows)
+        rows = rows.items;
+    return Array.isArray(rows) ? rows.filter(isRecord) : null;
+}
+function records(value) {
+    return Array.isArray(value) ? value.filter(isRecord) : [];
+}
 function safeGet(obj, ...keys) {
     let current = obj;
     for (const k of keys) {
@@ -41,6 +87,51 @@ function safeGet(obj, ...keys) {
     }
     return current;
 }
+/** A market's name with its asset class when it is not a token (TSLL is a stock, not a coin). */
+function marketLabel(row) {
+    const coin = text(row.base_coin) ?? text(row.symbol) ?? "?";
+    const assetClass = text(row.asset_class);
+    return assetClass == null || assetClass === "crypto"
+        ? coin
+        : `${coin} (${assetClass})`;
+}
+// ── Freshness ─────────────────────────────────────────────────────────
+/** One answer's freshness, as the Python server prints it: `dataset · as of … · status[ · degraded] (warnings)`. */
+export function freshnessLine(freshness) {
+    const parts = [
+        freshness.dataset_id || "data",
+        freshness.as_of ? `as of ${freshness.as_of}` : "as of unknown",
+        freshness.freshness_status,
+    ];
+    if (freshness.runtime_status === "degraded")
+        parts.push("degraded");
+    const line = parts.join(" · ");
+    return freshness.warnings.length > 0
+        ? `${line} (${freshness.warnings.join("; ")})`
+        : line;
+}
+/**
+ * The report with a closing line naming the freshness of every answer it read
+ * (engine L5 WP-S12), each once, in the order the calls were made. Nothing
+ * changes when no answer said anything.
+ */
+export function withFreshnessReport(report, answers) {
+    const seen = [];
+    const keys = new Set();
+    for (const answer of answers) {
+        const freshness = freshnessOf(answer);
+        if (freshness === null)
+            continue;
+        const key = JSON.stringify(freshness);
+        if (keys.has(key))
+            continue;
+        keys.add(key);
+        seen.push(freshness);
+    }
+    return seen.length === 0
+        ? report
+        : `${report}\n\n**Data freshness:** ${seen.map(freshnessLine).join("; ")}`;
+}
 async function safeCall(callApi, apiPath, fallbackPath, args, label) {
     try {
         const data = await callApi(apiPath, fallbackPath, args);
@@ -51,384 +142,416 @@ async function safeCall(callApi, apiPath, fallbackPath, args, label) {
         return { data: null, error: `[${label}] ${msg}` };
     }
 }
-// ── CoinGecko slug map ────────────────────────────────────────────────
-const CG_SLUGS = {
-    BTC: "bitcoin",
-    ETH: "ethereum",
-    SOL: "solana",
-    DOGE: "dogecoin",
-    XRP: "ripple",
-    ADA: "cardano",
-    AVAX: "avalanche-2",
-    DOT: "polkadot",
-    LINK: "chainlink",
-    MATIC: "matic-network",
-    SUI: "sui",
-    APT: "aptos",
-};
-// ── analyze_coin ──────────────────────────────────────────────────────
-export async function analyzeCoin(callApi, coin) {
-    const coinUpper = coin.toUpperCase();
-    const cgSlug = CG_SLUGS[coinUpper] ?? coin.toLowerCase();
-    const tasks = [
-        safeCall(callApi, "/api/v1/funding/rates", "/api/funding/rates", { type: "accumulated" }, "funding"),
-        safeCall(callApi, "/api/v1/futures/data", "/api/futures/data", { chart: "oi-snapshot", coin: coinUpper, timeframe: "3M" }, "oi"),
-        safeCall(callApi, "/api/v1/price-prediction/data", "/api/price-prediction/data", { coin: cgSlug }, "prediction"),
-    ];
+async function settleAll(tasks) {
     const results = await Promise.allSettled(tasks);
-    const settled = results.map((r) => r.status === "fulfilled"
+    return results.map((r) => r.status === "fulfilled"
         ? r.value
         : { data: null, error: "Promise rejected" });
-    const [funding, oi, prediction] = settled;
-    const errors = settled
-        .filter((s) => s.error)
-        .map((s) => s.error);
+}
+function finish(lines, settled) {
+    const errors = settled.filter((s) => s.error).map((s) => s.error);
+    if (errors.length > 0) {
+        lines.push("");
+        lines.push(`**Data gaps:** ${errors.join("; ")}`);
+    }
+    return withFreshnessReport(lines.join("\n"), settled.map((s) => s.data));
+}
+// ── Price-prediction coin resolution ──────────────────────────────────
+/**
+ * Find the prediction row for a ticker in the endpoint's own coverage list.
+ *
+ * The price-prediction endpoint is keyed by CoinGecko slug ("bitcoin",
+ * "avalanche-2", "matic-network"), never by ticker, and a lowercased ticker is
+ * not a slug. Guessing one either 404s or — far worse — resolves to whichever
+ * unrelated asset happens to own that slug, and tickers are shared across
+ * thousands of assets in this dataset. So the guess is a silent wrong-coin
+ * risk, never a convenience: it is resolve-or-say-so here.
+ *
+ * The list response (`GET .../price-prediction/data` with no `coin`) carries
+ * both the ticker (`coin`) and the `slug` for every covered asset, so an exact
+ * ticker match against it is the endpoint's own documented contract.
+ */
+export function findPredictionRow(payload, ticker) {
+    let rows = payload;
+    if (typeof rows === "object" && rows !== null && !Array.isArray(rows)) {
+        rows = rows.coins;
+    }
+    if (!Array.isArray(rows))
+        return null;
+    const wanted = ticker.toUpperCase();
+    for (const row of rows) {
+        if (typeof row !== "object" || row === null)
+            continue;
+        const rec = row;
+        if (String(rec.coin ?? "").toUpperCase() === wanted)
+            return rec;
+    }
+    return null;
+}
+// ── analyze_coin ──────────────────────────────────────────────────────
+function capitalize(value) {
+    return value.charAt(0).toUpperCase() + value.slice(1).toLowerCase();
+}
+function predictionLines(prediction, coinUpper) {
+    const row = prediction.data
+        ? findPredictionRow(prediction.data, coinUpper)
+        : null;
+    if (!row) {
+        return prediction.data
+            ? [
+                `\n*No price prediction for ${coinUpper}: this ticker is not in the price-prediction coverage universe. Call get_price_prediction with no coin to list covered tickers and their slugs.*`,
+            ]
+            : ["\n*Price prediction data unavailable*"];
+    }
+    const bias = String(row.direction ?? row.bias ?? "unknown");
+    const score = finiteOrNull(row.consensusScore ?? row.score);
+    const price = finiteOrNull(row.spotPrice ?? row.price);
+    const change24h = finiteOrNull(row.priceChange24h ?? row.price_change_24h);
+    const lines = [
+        "",
+        `**Price:** ${fmtUsd(price)} | **24h:** ${change24h != null ? fmtPct(change24h) : ""}`,
+        `**Prediction:** ${capitalize(bias)} (score: ${score != null ? `${score}/100` : "N/A"})`,
+    ];
+    const signals = row.signals ?? row.technical;
+    if (Array.isArray(signals)) {
+        const parts = records(signals)
+            .map((s) => {
+            const label = text(s.label ?? s.name);
+            const sigBias = text(s.bias);
+            return label && sigBias ? `${label}: ${sigBias}` : null;
+        })
+            .filter((part) => part !== null)
+            .slice(0, 6);
+        if (parts.length > 0)
+            lines.push(`**Signals:** ${parts.join(", ")}`);
+    }
+    else if (isRecord(signals)) {
+        const parts = [];
+        if (signals.rsi != null)
+            parts.push(`RSI ${Number(signals.rsi).toFixed(0)}`);
+        if (signals.ema_trend)
+            parts.push(`EMA ${signals.ema_trend}`);
+        if (parts.length > 0)
+            lines.push(`**Technicals:** ${parts.join(", ")}`);
+    }
+    return lines;
+}
+function fundingRowLine(row) {
+    const market = [text(row.exchange) ?? "Unknown", text(row.symbol)]
+        .filter(Boolean)
+        .join(" ");
+    return `  ${market}: ${fmtRate(finiteOrNull(row.rate_8h))} per 8h (${fmtApr(row.apr)} APR) | OI ${fmtUsd(finiteOrNull(row.open_interest))}`;
+}
+/** One asset of a `summary=1` answer: the API's average and median across venues. */
+function fundingSummaryLine(entry) {
+    const stale = finiteOrNull(entry.funding_venues_stale) ?? 0;
+    const parts = [
+        `  **Average (${marketLabel(entry)}):** ${fmtRate(finiteOrNull(entry.funding_avg_8h))} per 8h (${text(entry.funding_method) ?? "n/a"})`,
+        `**Median:** ${fmtRate(finiteOrNull(entry.funding_median_8h))} per 8h`,
+        `${finiteOrNull(entry.funding_venues_used) ?? 0} venues`,
+    ];
+    let line = parts.join(" | ");
+    if (stale > 0)
+        line += `, ${stale} stale venues left out`;
+    if (entry.funding_all_stale === true)
+        line += " *(every venue is stale: the figures are over stale rates)*";
+    return line;
+}
+export async function analyzeCoin(callApi, coin) {
+    const coinUpper = coin.toUpperCase();
+    const fundingScope = {
+        type: "current",
+        coin: coinUpper,
+        max_age_h: FUNDING_MAX_AGE_HOURS,
+    };
+    const settled = await settleAll([
+        // No `coin` param: the endpoint is slug-keyed and the caller gives us a
+        // ticker, so ask for the coverage list and match the ticker in it rather
+        // than shipping a guessed slug that can resolve to another asset.
+        safeCall(callApi, "/api/v1/price-prediction/data", "/api/price-prediction/data", {}, "prediction"),
+        // The API resolves `coin` to an asset (PEPE brings its 1000PEPE and KPEPE
+        // contracts) and orders the markets by their own open interest.
+        safeCall(callApi, "/api/v1/funding/rates", "/api/funding/rates", { ...fundingScope, sort: "-open_interest" }, "funding"),
+        // The asset's funding across venues: the funding grid's Avg Rate.
+        safeCall(callApi, "/api/v1/funding/rates", "/api/funding/rates", { ...fundingScope, summary: "1" }, "funding-summary"),
+        // The asset's open-interest total (L4 oi.asset_total_usd): /global's row,
+        // every contract of the asset once, lots included, venues the API keeps
+        // out of totals left out, latest reading within six hours.
+        safeCall(callApi, "/api/v1/global/overview", "/api/global/overview", {}, "open-interest"),
+        // The dollar value paid at the next settlement: the coin's own rows, never
+        // `totals` (which stays scoped to the whole class).
+        safeCall(callApi, "/api/v1/funding/settlement", "/api/funding/settlement", { coin: coinUpper, window: "current" }, "settlement"),
+    ]);
+    const [prediction, funding, summary, global, settlement] = settled;
     const lines = [`## ${coinUpper} Analysis`];
-    // Price prediction
-    if (prediction.data) {
-        let pred = prediction.data;
-        if (Array.isArray(pred) && pred.length > 0)
-            pred = pred[0];
-        if (typeof pred === "object" && pred !== null) {
-            const coinObj = (pred.coin ?? pred);
-            if (typeof coinObj === "object" && coinObj !== null) {
-                const finalPred = coinObj;
-                const bias = (safeGet(finalPred, "direction") ??
-                    safeGet(finalPred, "bias") ??
-                    "unknown");
-                const score = (safeGet(finalPred, "consensusScore") ??
-                    safeGet(finalPred, "score"));
-                const price = (safeGet(finalPred, "spotPrice") ??
-                    safeGet(finalPred, "price"));
-                const change24h = (safeGet(finalPred, "priceChange24h") ??
-                    safeGet(finalPred, "price_change_24h"));
-                lines.push("");
-                lines.push(`**Price:** ${price != null ? fmtUsd(price) : "N/A"} | **24h:** ${change24h != null ? fmtPct(change24h) : ""}`);
-                lines.push(`**Prediction:** ${String(bias).charAt(0).toUpperCase() + String(bias).slice(1)} (score: ${score != null ? `${score}/100` : "N/A"})`);
-                const signals = (safeGet(finalPred, "signals") ??
-                    safeGet(finalPred, "technical"));
-                if (Array.isArray(signals) && signals.length > 0) {
-                    const parts = signals
-                        .filter((s) => typeof s === "object" && s !== null)
-                        .map((s) => {
-                        const label = (s.label ?? s.name ?? "");
-                        const sigBias = (s.bias ?? "");
-                        return label && sigBias ? `${label}: ${sigBias}` : null;
-                    })
-                        .filter(Boolean)
-                        .slice(0, 6);
-                    if (parts.length > 0)
-                        lines.push(`**Signals:** ${parts.join(", ")}`);
-                }
-                else if (typeof signals === "object" && signals !== null) {
-                    const sigObj = signals;
-                    const parts = [];
-                    if (sigObj.rsi != null)
-                        parts.push(`RSI ${Number(sigObj.rsi).toFixed(0)}`);
-                    if (sigObj.ema_trend)
-                        parts.push(`EMA ${sigObj.ema_trend}`);
-                    if (parts.length > 0)
-                        lines.push(`**Technicals:** ${parts.join(", ")}`);
-                }
-            }
-        }
+    lines.push(...predictionLines(prediction, coinUpper));
+    // Funding: the markets in the API's open-interest order, then its summary.
+    const fundingRows = funding.data ? (listRows(funding.data) ?? []) : null;
+    if (fundingRows === null) {
+        lines.push("\n*Funding rate data unavailable*");
+    }
+    else if (fundingRows.length === 0) {
+        lines.push("\n*No funding rates found for this coin*");
     }
     else {
-        lines.push("\n*Price prediction data unavailable*");
+        lines.push("");
+        lines.push("**Funding (current, largest markets by open interest):**");
+        for (const row of fundingRows.slice(0, 10))
+            lines.push(fundingRowLine(row));
+        for (const entry of records(safeGet(summary.data, "summary"))) {
+            lines.push(fundingSummaryLine(entry));
+        }
     }
-    // Funding rates
-    if (funding.data) {
-        let ratesList = funding.data;
-        if (typeof ratesList === "object" &&
-            ratesList !== null &&
-            !Array.isArray(ratesList) &&
-            "items" in ratesList) {
-            ratesList = ratesList.items;
+    // Open interest: the asset's row on the global board, found by the asset
+    // symbol the funding answer resolved (coin=1000PEPE files under PEPE).
+    if (global.data) {
+        const assetSymbol = fundingRows?.map((row) => text(row.asset_symbol)).find(Boolean) ??
+            coinUpper;
+        const row = records(safeGet(global.data, "rows")).find((candidate) => text(candidate.symbol) === assetSymbol);
+        lines.push("");
+        lines.push("**Open Interest:**");
+        if (row) {
+            lines.push(`  **Total:** ${fmtUsd(finiteOrNull(row.openInterestUsd))} across ${finiteOrNull(row.venueCount) ?? "N/A"} venues | 1h ${fmtPct(finiteOrNull(row.oiChange1hPct))} | 24h ${fmtPct(finiteOrNull(row.oiChange24hPct))}`);
         }
-        if (Array.isArray(ratesList)) {
-            const coinRates = ratesList.filter((r) => {
-                if (typeof r !== "object" || r === null)
-                    return false;
-                const rec = r;
-                const baseCoin = String(rec.base_coin ?? rec.coin ?? "").toUpperCase();
-                const symbol = String(rec.symbol ?? "").toUpperCase();
-                return baseCoin === coinUpper || symbol.startsWith(coinUpper);
-            });
-            if (coinRates.length > 0) {
-                lines.push("");
-                lines.push("**Funding Rates:**");
-                const rateValues = [];
-                for (const r of coinRates.slice(0, 10)) {
-                    const rec = r;
-                    const exchange = String(rec.exchange ?? "Unknown");
-                    const rate = (rec.rate ?? rec.acc_1d ?? rec.funding_rate);
-                    const acc7d = rec.acc_7d;
-                    if (rate != null) {
-                        rateValues.push(rate);
-                        let label = `  ${exchange}: ${fmtRate(rate)}`;
-                        if (acc7d != null)
-                            label += ` (7d: ${fmtRate(acc7d)})`;
-                        lines.push(label);
-                    }
-                }
-                if (rateValues.length > 0) {
-                    const avg = rateValues.reduce((a, b) => a + b, 0) / rateValues.length;
-                    lines.push(`  **Avg:** ${fmtRate(avg)} across ${rateValues.length} exchanges`);
-                }
-            }
-            else {
-                lines.push("\n*No funding rates found for this coin*");
-            }
+        else {
+            lines.push(`  *No open-interest total for ${assetSymbol} on the global board.*`);
+        }
+        const excluded = records(safeGet(global.data, "metrics", "openInterestExcludedVenues"))
+            .map((venue) => {
+            const exchange = text(venue.exchange);
+            const reason = text(venue.reason);
+            return exchange ? `${exchange}${reason ? ` (${reason})` : ""}` : null;
+        })
+            .filter((venue) => venue !== null);
+        if (excluded.length > 0) {
+            lines.push(`  *Left out of the total: ${excluded.join("; ")}*`);
         }
     }
     else {
-        lines.push("\n*Funding rate data unavailable*");
+        lines.push("\n*Open interest data unavailable*");
     }
-    // Open interest
-    if (oi.data) {
-        let oiData = oi.data;
-        if (typeof oiData === "object" &&
-            oiData !== null &&
-            !Array.isArray(oiData) &&
-            "data" in oiData) {
-            oiData = oiData.data;
-        }
+    // Settlement: dollar value actually paid at the next settlement.
+    if (settlement.data) {
+        const payload = settlement.data;
+        const rows = records(payload.rows ?? payload.data);
         lines.push("");
-        lines.push("**Open Interest:**");
-        if (Array.isArray(oiData)) {
-            const latestByExchange = new Map();
-            const latestTsByExchange = new Map();
-            for (const item of oiData) {
-                if (typeof item !== "object" || item === null)
-                    continue;
-                const rec = item;
-                const exchange = String(rec.exchange ?? "Unknown");
-                const oiVal = Number(rec.open_interest_value ??
-                    rec.value ??
-                    rec.oi ??
-                    rec.open_interest ??
-                    0);
-                const ts = String(rec.timestamp ?? rec.snapshot_at ?? "");
-                if (oiVal > 0 && ts >= (latestTsByExchange.get(exchange) ?? "")) {
-                    latestByExchange.set(exchange, oiVal);
-                    latestTsByExchange.set(exchange, ts);
-                }
+        lines.push("**Settlement (next, estimated):**");
+        if (rows.length === 0) {
+            lines.push("  No funding data for the next settlement.");
+        }
+        for (const row of rows) {
+            const net = finiteOrNull(safeGet(row, "windows", "current", "net"));
+            const prefix = rows.length > 1 ? `${marketLabel(row)}: ` : "";
+            if (net == null) {
+                lines.push(`  ${prefix}No funding data for the next settlement.`);
+            }
+            else if (net > 0) {
+                lines.push(`  ${prefix}Longs pay ${fmtUsd(net)} to shorts.`);
             }
-            let totalOi = 0;
-            const sorted = [...latestByExchange.entries()]
-                .sort((a, b) => b[1] - a[1])
-                .slice(0, 10);
-            for (const [exchange, oiVal] of sorted) {
-                totalOi += oiVal;
-                lines.push(`  ${exchange}: ${fmtUsd(oiVal)}`);
+            else if (net < 0) {
+                lines.push(`  ${prefix}Shorts pay ${fmtUsd(-net)} to longs.`);
             }
-            if (latestByExchange.size > 0) {
-                lines.push(`  **Total:** ${fmtUsd(totalOi)} across ${latestByExchange.size} exchanges`);
+            else {
+                lines.push(`  ${prefix}No net funding at the next settlement.`);
             }
         }
     }
     else {
-        lines.push("\n*Open interest data unavailable*");
+        lines.push("\n*Settlement data unavailable*");
     }
-    if (errors.length > 0) {
-        lines.push("");
-        lines.push(`**Data gaps:** ${errors.join("; ")}`);
-    }
-    return lines.join("\n");
+    return finish(lines, settled);
 }
 // ── market_briefing ───────────────────────────────────────────────────
+function fundingExtremeLine(row) {
+    return `  ${marketLabel(row)} on ${text(row.exchange) ?? "?"}: ${fmtApr(row.apr)} APR (${fmtRate(finiteOrNull(row.rate_8h))} per 8h; raw ${fmtRate(finiteOrNull(row.rate))} per ${finiteOrNull(row.interval_hours) ?? "?"}h)`;
+}
 export async function marketBriefing(callApi) {
-    const results = await Promise.allSettled([
+    const settled = await settleAll([
         safeCall(callApi, "/api/v1/tracker/market-overview", "/api/tracker/market-overview", {}, "market-overview"),
-        safeCall(callApi, "/api/v1/narratives/data", "/api/narratives/data", {}, "narratives"),
-        safeCall(callApi, "/api/v1/funding/rates", "/api/funding/rates", { type: "current" }, "funding"),
+        // Ranked by the API: missing 24h changes are never ranked.
+        safeCall(callApi, "/api/v1/narratives/data", "/api/narratives/data", { sort: "-change24h", top: 5, bottom: 3 }, "narratives"),
+        // The book's extremes, ranked by the API on the 8h-equivalent rate among
+        // fresh markets with a usable interval above the floor.
+        safeCall(callApi, "/api/v1/funding/rates", "/api/funding/rates", {
+            type: "current",
+            extremes: 3,
+            min_oi_usd: LIQUIDITY_FLOOR_USD,
+            max_age_h: FUNDING_MAX_AGE_HOURS,
+        }, "funding"),
+        // No coin filter, so `totals` reflects the whole requested class.
+        safeCall(callApi, "/api/v1/funding/settlement", "/api/funding/settlement", { window: "current" }, "settlement"),
     ]);
-    const settled = results.map((r) => r.status === "fulfilled"
-        ? r.value
-        : { data: null, error: "Promise rejected" });
-    const [overview, narratives, funding] = settled;
-    const errors = settled
-        .filter((s) => s.error)
-        .map((s) => s.error);
+    const [overview, narratives, funding, settlement] = settled;
     const lines = ["## Market Briefing"];
     // Market overview
-    if (overview.data && typeof overview.data === "object") {
+    if (isRecord(overview.data)) {
         const d = overview.data;
-        const mcap = d.total_market_cap;
-        const vol = (d.total_volume_24h ?? d.total_volume);
-        const btcDom = d.btc_dominance;
-        const fg = (d.fgi ?? d.fear_greed_index ?? d.fear_greed);
+        const mcap = finiteOrNull(d.total_market_cap);
+        const vol = finiteOrNull(d.total_volume_24h ?? d.total_volume);
+        // Served in percent (57.3 = 57.3%); `btc_dominance` is the same figure.
+        const btcDom = finiteOrNull(d.btc_dominance_pct ?? d.btc_dominance);
+        const fg = d.fgi ?? d.fear_greed_index ?? d.fear_greed;
         lines.push("");
         lines.push("### Market Stats");
         if (mcap != null)
             lines.push(`**Total Market Cap:** ${fmtUsd(mcap)}`);
         if (vol != null)
             lines.push(`**24h Volume:** ${fmtUsd(vol)}`);
-        if (btcDom != null) {
-            const pct = btcDom > 1 ? btcDom : btcDom * 100;
-            lines.push(`**BTC Dominance:** ${pct.toFixed(1)}%`);
-        }
+        if (btcDom != null)
+            lines.push(`**BTC Dominance:** ${btcDom.toFixed(1)}%`);
         if (fg != null) {
-            const fgVal = typeof fg === "object" ? fg.value : fg;
-            let fgLabel = typeof fg === "object" ? (fg.label ?? "") : "";
+            const fgVal = isRecord(fg) ? fg.value : fg;
+            let fgLabel = isRecord(fg) ? (text(fg.label) ?? "") : "";
             if (!fgLabel)
-                fgLabel = (d.fgi_classification ?? "");
+                fgLabel = text(d.fgi_classification) ?? "";
             lines.push(`**Fear & Greed:** ${fgVal} ${fgLabel}`);
         }
-        // Top gainers
-        const gainers = (d.top_gainers ?? []);
-        if (Array.isArray(gainers) && gainers.length > 0) {
-            lines.push("");
-            lines.push("### Top Gainers (24h)");
-            for (const g of gainers.slice(0, 5)) {
-                const sym = (g.symbol ?? g.name ?? "?");
-                const chg = (g.price_change_24h ?? g.change);
-                lines.push(`  ${sym}: ${fmtPct(chg)}`);
-            }
-        }
-        // Top losers
-        const losers = (d.top_losers ?? []);
-        if (Array.isArray(losers) && losers.length > 0) {
+        for (const [key, heading] of [
+            ["top_gainers", "### Top Gainers (24h)"],
+            ["top_losers", "### Top Losers (24h)"],
+        ]) {
+            const movers = records(d[key]);
+            if (movers.length === 0)
+                continue;
             lines.push("");
-            lines.push("### Top Losers (24h)");
-            for (const l of losers.slice(0, 5)) {
-                const sym = (l.symbol ?? l.name ?? "?");
-                const chg = (l.price_change_24h ?? l.change);
-                lines.push(`  ${sym}: ${fmtPct(chg)}`);
+            lines.push(heading);
+            for (const m of movers.slice(0, 5)) {
+                const sym = text(m.symbol) ?? text(m.name) ?? "?";
+                lines.push(`  ${sym}: ${fmtPct(finiteOrNull(m.price_change_24h ?? m.change))}`);
             }
         }
     }
     else {
         lines.push("\n*Market overview data unavailable*");
     }
-    // Narratives
-    if (narratives.data) {
-        let narrList = narratives.data;
-        if (typeof narrList === "object" &&
-            narrList !== null &&
-            !Array.isArray(narrList)) {
-            const obj = narrList;
-            narrList = obj.narratives ?? obj.items ?? narrList;
-        }
-        if (Array.isArray(narrList) && narrList.length > 0) {
-            const typed = narrList.filter((n) => typeof n === "object" && n !== null);
-            const sortedNarr = [...typed].sort((a, b) => {
-                const aChg = Number(a.change24h ?? a.price_change_24h ?? a.change_24h ?? 0);
-                const bChg = Number(b.change24h ?? b.price_change_24h ?? b.change_24h ?? 0);
-                return bChg - aChg;
-            });
+    // Narratives, as the API ranked them.
+    if (isRecord(narratives.data)) {
+        const top = narratives.data.top;
+        const bottom = narratives.data.bottom;
+        if (Array.isArray(top) && Array.isArray(bottom)) {
             lines.push("");
             lines.push("### Top Narratives (24h)");
-            for (const n of sortedNarr.slice(0, 5)) {
-                const name = (n.name ?? n.narrative ?? "?");
-                const chg = (n.change24h ?? n.price_change_24h ?? n.change_24h);
-                const mcapN = (n.marketCap ?? n.market_cap);
-                lines.push(`  **${name}:** ${fmtPct(chg)} (mcap: ${fmtUsd(mcapN)})`);
+            for (const n of records(top)) {
+                lines.push(`  **${text(n.name) ?? "?"}:** ${fmtPct(finiteOrNull(n.change24h))} (mcap: ${fmtUsd(finiteOrNull(n.marketCap))})`);
             }
             lines.push("");
             lines.push("### Worst Narratives (24h)");
-            for (const n of sortedNarr.slice(-3)) {
-                const name = (n.name ?? n.narrative ?? "?");
-                const chg = (n.change24h ?? n.price_change_24h ?? n.change_24h);
-                lines.push(`  **${name}:** ${fmtPct(chg)}`);
+            for (const n of records(bottom)) {
+                lines.push(`  **${text(n.name) ?? "?"}:** ${fmtPct(finiteOrNull(n.change24h))}`);
             }
         }
+        else {
+            lines.push("\n*Narrative ranking unavailable*");
+        }
     }
     else {
         lines.push("\n*Narrative data unavailable*");
     }
-    // Funding highlights
-    if (funding.data) {
-        let ratesList = funding.data;
-        if (typeof ratesList === "object" &&
-            ratesList !== null &&
-            !Array.isArray(ratesList) &&
-            "items" in ratesList) {
-            ratesList = ratesList.items;
+    // Funding highlights: the API's extremes, never re-ranked here.
+    const extremes = safeGet(funding.data, "extremes");
+    if (isRecord(extremes)) {
+        const highest = records(extremes.highest);
+        const lowest = records(extremes.lowest);
+        lines.push("");
+        lines.push("### Funding Rate Highlights");
+        lines.push(`*Ranked by the API on the 8h-equivalent rate (rate x 8 / interval_hours) among fresh markets with at least ${fmtUsd(LIQUIDITY_FLOOR_USD)} open interest; APR = rate x 8760 / interval_hours.*`);
+        const omitted = isRecord(extremes.omitted) ? extremes.omitted : {};
+        for (const [key, reason] of [
+            ["stale", "stale, past the funding freshness SLA"],
+            ["no_interval", "no rate or no published settlement interval"],
+            [
+                "below_floor",
+                `open interest below ${fmtUsd(LIQUIDITY_FLOOR_USD)} or unknown`,
+            ],
+        ]) {
+            const count = finiteOrNull(omitted[key]);
+            if (count)
+                lines.push(`*${count} markets left out: ${reason}.*`);
         }
-        if (Array.isArray(ratesList) && ratesList.length > 0) {
-            const valid = ratesList.filter((r) => {
-                if (typeof r !== "object" || r === null)
-                    return false;
-                const rec = r;
-                return (rec.rate ?? rec.funding_rate) != null;
-            });
-            if (valid.length > 0) {
-                const rateVal = (r) => Number(r.rate ?? r.funding_rate ?? 0);
-                const sorted = [...valid].sort((a, b) => rateVal(b) - rateVal(a));
-                lines.push("");
-                lines.push("### Funding Rate Highlights");
-                lines.push("**Highest (longs paying most):**");
-                for (const r of sorted.slice(0, 3)) {
-                    const coinName = (r.base_coin ?? r.coin ?? r.symbol ?? "?");
-                    const exchange = (r.exchange ?? "?");
-                    lines.push(`  ${coinName} on ${exchange}: ${fmtRate(rateVal(r))}`);
-                }
-                lines.push("**Lowest (shorts paying most):**");
-                for (const r of sorted.slice(-3)) {
-                    const coinName = (r.base_coin ?? r.coin ?? r.symbol ?? "?");
-                    const exchange = (r.exchange ?? "?");
-                    lines.push(`  ${coinName} on ${exchange}: ${fmtRate(rateVal(r))}`);
-                }
-            }
+        if (highest.length === 0 && lowest.length === 0) {
+            lines.push("*No market clears the floor.*");
+        }
+        else {
+            lines.push("**Highest (longs paying most):**");
+            for (const row of highest)
+                lines.push(fundingExtremeLine(row));
+            lines.push("**Lowest (shorts paying most):**");
+            for (const row of lowest)
+                lines.push(fundingExtremeLine(row));
         }
     }
     else {
         lines.push("\n*Funding rate data unavailable*");
     }
-    if (errors.length > 0) {
+    // Funding settlement: whole-market dollar total, not a per-row rate.
+    if (settlement.data) {
+        const totals = settlement.data.totals;
+        const net = finiteOrNull(safeGet(totals, "current", "net"));
+        const longPaid = finiteOrNull(safeGet(totals, "current", "long_paid"));
+        const shortPaid = finiteOrNull(safeGet(totals, "current", "short_paid"));
         lines.push("");
-        lines.push(`**Data gaps:** ${errors.join("; ")}`);
+        lines.push("### Funding Settlement (next, estimated)");
+        if (net == null) {
+            lines.push("*No funding data for the next settlement.*");
+        }
+        else if (net > 0) {
+            lines.push(`Longs will pay ${fmtUsd(net)} to shorts (long ${fmtUsd(longPaid)} / short ${fmtUsd(shortPaid)}).`);
+        }
+        else if (net < 0) {
+            lines.push(`Shorts will pay ${fmtUsd(-net)} to longs (long ${fmtUsd(longPaid)} / short ${fmtUsd(shortPaid)}).`);
+        }
+        else {
+            lines.push("No net funding expected at the next settlement.");
+        }
+    }
+    else {
+        lines.push("\n*Funding settlement data unavailable*");
     }
-    return lines.join("\n");
+    return finish(lines, settled);
 }
 // ── find_opportunities ────────────────────────────────────────────────
+/** A row's own status flags, printed only when they say something. */
+function statusSuffix(row) {
+    const parts = [text(row.executionStatus) ?? "n/a"];
+    const pair = text(row.pairStatus);
+    if (pair && pair !== "eligible")
+        parts.push(pair);
+    if (row.fundingIsStale === true)
+        parts.push("funding stale");
+    return parts.join(" | ");
+}
 export async function findOpportunities(callApi) {
-    const results = await Promise.allSettled([
-        safeCall(callApi, "/api/v1/arbitrage/spot-perp", "/api/arbitrage/spot-perp", { exchange: "all", direction: "all" }, "spot-perp-arb"),
-        safeCall(callApi, "/api/v1/arbitrage/cross-exchange", "/api/arbitrage/cross-exchange", {}, "cross-exchange-arb"),
-        safeCall(callApi, "/api/v1/funding/rates", "/api/funding/rates", { type: "current" }, "funding"),
+    const settled = await settleAll([
+        // The API floors the perp leg's open interest (unknown fails it) and
+        // keeps its board order: net APR first, then gross APR.
+        safeCall(callApi, "/api/v1/arbitrage/spot-perp", "/api/arbitrage/spot-perp", { exchange: "all", direction: "all", minOiUsd: LIQUIDITY_FLOOR_USD }, "spot-perp-arb"),
+        // Both legs must clear the floor; the API ranks executable rows first and
+        // cuts the board to the rows shown.
+        safeCall(callApi, "/api/v1/arbitrage/cross-exchange", "/api/arbitrage/cross-exchange", {
+            minOiUsd: LIQUIDITY_FLOOR_USD,
+            minVolUsd: LIQUIDITY_FLOOR_USD,
+            limit: 10,
+        }, "cross-exchange-arb"),
+        // The whole book's funding stats (the v1 derivatives overview's
+        // computation, as APRs).
+        safeCall(callApi, "/api/v1/funding/rates", "/api/funding/rates", { type: "current", stats: "1" }, "funding"),
     ]);
-    const settled = results.map((r) => r.status === "fulfilled"
-        ? r.value
-        : { data: null, error: "Promise rejected" });
     const [spotPerp, crossEx, funding] = settled;
-    const errors = settled
-        .filter((s) => s.error)
-        .map((s) => s.error);
+    const floorLabel = fmtUsd(LIQUIDITY_FLOOR_USD);
     const lines = ["## Arbitrage Opportunities"];
     // Spot-perp basis trades
     if (spotPerp.data) {
-        let arbList = spotPerp.data;
-        if (typeof arbList === "object" &&
-            arbList !== null &&
-            !Array.isArray(arbList) &&
-            "items" in arbList) {
-            arbList = arbList.items;
-        }
-        if (Array.isArray(arbList) && arbList.length > 0) {
-            const typed = arbList.filter((a) => typeof a === "object" && a !== null);
-            const sorted = [...typed].sort((a, b) => {
-                return (Math.abs(Number(b.apr ?? b.annualized_apr ?? 0)) -
-                    Math.abs(Number(a.apr ?? a.annualized_apr ?? 0)));
-            });
-            lines.push("");
-            lines.push("### Spot-Perp Basis Trades (Top 10 by APR)");
-            lines.push("*Long spot + short perp (or vice versa) to capture funding*");
-            lines.push("");
-            for (const a of sorted.slice(0, 10)) {
-                const symbol = (a.symbol ?? a.coin ?? "?");
-                const exchange = (a.exchange ?? "?");
-                const apr = (a.apr ?? a.annualized_apr ?? 0);
-                const rate = (a.fundingRate ?? a.rate ?? a.funding_rate);
-                const direction = (a.direction ?? "?");
-                const aprStr = apr != null ? `${apr.toFixed(1)}%` : "N/A";
-                const rateStr = rate != null ? fmtRate(rate) : "";
-                lines.push(`  **${symbol}** on ${exchange} | APR: ${aprStr} | Rate: ${rateStr} | Dir: ${direction}`);
-            }
+        const rows = listRows(spotPerp.data) ?? [];
+        lines.push("");
+        lines.push("### Spot-Perp Basis Trades (Top 10)");
+        lines.push("*Long spot + short perp (or vice versa) to capture funding*");
+        lines.push(`*Perp legs with at least ${floorLabel} open interest, in the API's order: net APR first, then gross APR.*`);
+        lines.push("");
+        if (rows.length === 0) {
+            lines.push("  *No spot-perp row clears the liquidity floor.*");
         }
-        else {
-            lines.push("\n*No spot-perp opportunities found*");
+        for (const a of rows.slice(0, 10)) {
+            lines.push(`  **${text(a.symbol) ?? "?"}** on ${text(a.exchange) ?? "?"} | Net APR: ${fmtApr(a.netApr)} | Gross APR: ${fmtApr(a.apr)} | Rate: ${fmtRate(finiteOrNull(a.fundingRate))} per ${finiteOrNull(a.intervalHours) ?? "?"}h | Dir: ${text(a.direction) ?? "?"} | OI ${fmtUsd(finiteOrNull(a.perpOpenInterestUsd))} | ${statusSuffix(a)}`);
         }
     }
     else {
@@ -436,85 +559,34 @@ export async function findOpportunities(callApi) {
     }
     // Cross-exchange funding arb
     if (crossEx.data) {
-        let cxList = crossEx.data;
-        if (typeof cxList === "object" &&
-            cxList !== null &&
-            !Array.isArray(cxList) &&
-            "items" in cxList) {
-            cxList = cxList.items;
-        }
-        if (Array.isArray(cxList) && cxList.length > 0) {
-            const typed = cxList.filter((a) => typeof a === "object" && a !== null);
-            const sorted = [...typed].sort((a, b) => {
-                return (Math.abs(Number(b.apr ?? b.spread_apr ?? b.annualized_apr ?? 0)) -
-                    Math.abs(Number(a.apr ?? a.spread_apr ?? a.annualized_apr ?? 0)));
-            });
-            lines.push("");
-            lines.push("### Cross-Exchange Funding Arb (Top 10 by APR)");
-            lines.push("*Long on low-rate exchange, short on high-rate exchange*");
-            lines.push("");
-            for (const a of sorted.slice(0, 10)) {
-                const symbol = (a.symbol ?? a.coin ?? "?");
-                const longEx = (a.longExchange ??
-                    a.long_exchange ??
-                    a.exchange_long ??
-                    "?");
-                const shortEx = (a.shortExchange ??
-                    a.short_exchange ??
-                    a.exchange_short ??
-                    "?");
-                const apr = (a.apr ?? a.spread_apr ?? a.annualized_apr ?? 0);
-                const spread = (a.spreadRate ?? a.spread ?? a.spread_rate);
-                const aprStr = apr != null ? `${apr.toFixed(1)}%` : "N/A";
-                const spreadStr = spread != null ? fmtRate(spread) : "";
-                lines.push(`  **${symbol}** | Long ${longEx} / Short ${shortEx} | APR: ${aprStr} | Spread: ${spreadStr}`);
-            }
+        const rows = listRows(crossEx.data) ?? [];
+        lines.push("");
+        lines.push("### Cross-Exchange Funding Arb (Top 10)");
+        lines.push("*Long on low-rate exchange, short on high-rate exchange*");
+        lines.push(`*Both legs have at least ${floorLabel} open interest and 24h volume, in the API's order: executable (book-priced) rows first by net APR, then indicative rows by gross APR.*`);
+        lines.push("");
+        if (rows.length === 0) {
+            lines.push("  *No cross-exchange row clears the liquidity floor.*");
         }
-        else {
-            lines.push("\n*No cross-exchange opportunities found*");
+        for (const a of rows.slice(0, 10)) {
+            lines.push(`  **${text(a.symbol) ?? "?"}** | Long ${text(a.longExchange) ?? "?"} / Short ${text(a.shortExchange) ?? "?"} | Net APR: ${fmtApr(a.netApr)} | Gross APR: ${fmtApr(a.apr)} | Spread: ${fmtRate(finiteOrNull(a.spreadRate))} | ${statusSuffix(a)}`);
         }
     }
     else {
         lines.push("\n*Cross-exchange arbitrage data unavailable*");
     }
-    // Funding rate summary
-    if (funding.data) {
-        let ratesList = funding.data;
-        if (typeof ratesList === "object" &&
-            ratesList !== null &&
-            !Array.isArray(ratesList) &&
-            "items" in ratesList) {
-            ratesList = ratesList.items;
-        }
-        if (Array.isArray(ratesList) && ratesList.length > 0) {
-            const valid = ratesList.filter((r) => {
-                if (typeof r !== "object" || r === null)
-                    return false;
-                const rec = r;
-                return (rec.rate ?? rec.funding_rate) != null;
-            });
-            if (valid.length > 0) {
-                const allRates = valid.map((r) => Number(r.rate ?? r.funding_rate ?? 0));
-                const avg = allRates.reduce((a, b) => a + b, 0) / allRates.length;
-                const positive = allRates.filter((r) => r > 0).length;
-                const negative = allRates.filter((r) => r < 0).length;
-                lines.push("");
-                lines.push("### Funding Rate Summary");
-                lines.push(`**Avg Rate:** ${fmtRate(avg)}`);
-                lines.push(`**Positive (longs pay):** ${positive} | **Negative (shorts pay):** ${negative}`);
-                const sentiment = positive > negative * 1.5
-                    ? "bullish"
-                    : negative > positive * 1.5
-                        ? "bearish"
-                        : "neutral";
-                lines.push(`**Market Sentiment:** ${sentiment} (based on funding rate skew)`);
-            }
-        }
-    }
-    if (errors.length > 0) {
+    // Funding rate summary: the API's market stats.
+    const market = safeGet(funding.data, "market");
+    if (isRecord(market)) {
         lines.push("");
-        lines.push(`**Data gaps:** ${errors.join("; ")}`);
+        lines.push("### Funding Rate Summary");
+        lines.push("*The API's market stats: the fresh primary contract of every (venue, asset), all asset classes.*");
+        lines.push(`**Avg APR:** ${fmtApr(market.funding_apr_mean)} | **OI-weighted APR:** ${fmtApr(market.funding_apr_oi_weighted)}`);
+        lines.push(`**Positive (longs pay):** ${finiteOrNull(market.positive) ?? "N/A"} | **Negative (shorts pay):** ${finiteOrNull(market.negative) ?? "N/A"}`);
+    }
+    else {
+        lines.push("\n*Funding rate data unavailable*");
     }
-    return lines.join("\n");
+    return finish(lines, settled);
 }
 //# sourceMappingURL=composite-tools.js.map