@sharpe-terminal/mcp-server 1.2.0 → 1.4.0

package/dist/composite-tools.js

@@ -3,6 +3,8 @@
  * and return formatted markdown. Mirrors the Python server's
  * analyze_coin, market_briefing, and find_opportunities.
  */
+import { splitPaginated } from "./tool-runtime.js";
+import { rowsForFundingCoin } from "./tools.js";
 // ── Formatting helpers ────────────────────────────────────────────────
 export function fmtUsd(value) {
     if (value == null)
@@ -29,6 +31,144 @@ export function fmtRate(value) {
         return "N/A";
     return `${(value * 100).toFixed(4)}%`;
 }
+const HOURS_PER_YEAR = 8760;
+/**
+ * A funding row's own settlement interval. Returns null rather than a default
+ * when the venue publishes none — see src/products/funding-rate/lib/
+ * CALCULATIONS.md: a stored rate is never implicitly an 8-hour rate.
+ */
+export function intervalHours(r) {
+    const raw = Number(r.interval_hours ?? r.intervalHours);
+    return Number.isFinite(raw) && raw > 0 ? raw : null;
+}
+function rateVal(r) {
+    return Number(r.rate ?? r.funding_rate ?? 0);
+}
+/** APR for one observation: `rate x (8760 / interval_hours)`. */
+export function aprVal(r) {
+    const hours = intervalHours(r);
+    return hours == null ? Number.NaN : rateVal(r) * (HOURS_PER_YEAR / hours);
+}
+/**
+ * Minimum open interest (USD) for a market to rank in market_briefing and
+ * find_opportunities, and the per-leg OI and volume floor sent to the
+ * cross-exchange scanner. Without it every extreme was a dust market (ESIM
+ * on KuCoin: $33K of OI at -16,862% APR, 2026-09-24 audit). Unknown OI fails
+ * the floor, the same rule the cross-exchange API applies.
+ */
+export const LIQUIDITY_FLOOR_USD = 1_000_000;
+function meetsLiquidityFloor(value) {
+    return value != null && Number(value) >= LIQUIDITY_FLOOR_USD;
+}
+/** FUNDING_RATE_FRESHNESS_SLA_SECONDS in src/products/funding-rate/lib/freshness.ts. */
+export const FUNDING_FRESHNESS_SLA_MS = 10 * 60 * 1000;
+/**
+ * A funding row past its freshness SLA. The free endpoint serves stale rows
+ * flagged `is_stale: true` rather than dropping them, so rankings skip them;
+ * a row without the flag is judged from its `updated_at`.
+ */
+export function isStaleRow(row, nowMs = Date.now()) {
+    if (typeof row.is_stale === "boolean")
+        return row.is_stale;
+    const updatedAt = Date.parse(String(row.updated_at ?? ""));
+    return (Number.isFinite(updatedAt) && nowMs - updatedAt > FUNDING_FRESHNESS_SLA_MS);
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function finiteOrNull(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+/** Sort key for a nullable number: missing sorts last in a descending sort. */
+function sortKey(value) {
+    const n = Number(value);
+    return value != null && Number.isFinite(n) ? n : Number.NEGATIVE_INFINITY;
+}
+/** An annualized fraction (0.25 = 25%) as a percentage, or N/A. */
+function fmtApr(value) {
+    const n = Number(value);
+    return value == null || !Number.isFinite(n)
+        ? "N/A"
+        : `${(n * 100).toFixed(1)}%`;
+}
+function median(values) {
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0
+        ? (sorted[mid - 1] + sorted[mid]) / 2
+        : sorted[mid];
+}
+/** 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;
+}
+/** A venue whose latest reading trails the newest by more than this is not current OI. */
+export const OI_FRESHNESS_WINDOW_MS = 2 * 60 * 60 * 1000;
+/**
+ * Venues the API names in `openInterestExcludedVenues`: their rows are
+ * shown per venue but never summed (MEXC, whose figure moves 7.00x its own
+ * trade flow), keyed to the reason the payload gives.
+ */
+export function excludedOiVenues(payload) {
+    const excluded = new Map();
+    const listed = isRecord(payload)
+        ? payload.openInterestExcludedVenues
+        : undefined;
+    if (!Array.isArray(listed))
+        return excluded;
+    for (const item of listed) {
+        if (isRecord(item) && typeof item.exchange === "string") {
+            excluded.set(item.exchange, typeof item.reason === "string" ? item.reason : "");
+        }
+    }
+    return excluded;
+}
+/**
+ * Each venue's latest open-interest reading, split into venues that are
+ * current (within OI_FRESHNESS_WINDOW_MS of the newest reading), venues
+ * that stopped reporting, and venues the API excludes from totals. Totals
+ * sum every current venue: summing only the ten listed understated BTC by
+ * 9.4% (2026-09-24 audit).
+ */
+export function summarizeVenueOi(rows, excludedVenues = new Map()) {
+    const latest = new Map();
+    for (const item of rows) {
+        if (!isRecord(item))
+            continue;
+        const value = Number(item.open_interest_value ?? item.value ?? item.oi ?? item.open_interest);
+        const at = Date.parse(String(item.timestamp ?? item.snapshot_at ?? ""));
+        if (!(value > 0) || !Number.isFinite(at))
+            continue;
+        const exchange = String(item.exchange ?? "Unknown");
+        const prev = latest.get(exchange);
+        if (!prev || at >= prev.at)
+            latest.set(exchange, { exchange, value, at });
+    }
+    const all = [...latest.values()];
+    const newest = Math.max(...all.map((venue) => venue.at));
+    const byValue = (a, b) => b.value - a.value;
+    const venues = all.filter((venue) => !excludedVenues.has(venue.exchange));
+    return {
+        current: venues
+            .filter((venue) => newest - venue.at <= OI_FRESHNESS_WINDOW_MS)
+            .sort(byValue),
+        stale: venues
+            .filter((venue) => newest - venue.at > OI_FRESHNESS_WINDOW_MS)
+            .sort(byValue),
+        excluded: all
+            .filter((venue) => excludedVenues.has(venue.exchange))
+            .sort(byValue),
+    };
+}
+function fundingHighlightLine(r) {
+    const coinName = (r.base_coin ?? r.coin ?? r.symbol ?? "?");
+    const exchange = (r.exchange ?? "?");
+    const aprStr = `${(aprVal(r) * 100).toFixed(1)}%`;
+    return `  ${coinName} on ${exchange}: ${aprStr} APR (${fmtRate(rateVal(r))} per ${intervalHours(r)}h)`;
+}
 function safeGet(obj, ...keys) {
     let current = obj;
     for (const k of keys) {
@@ -51,129 +191,164 @@ 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",
-};
+// ── 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 ──────────────────────────────────────────────────────
 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/funding/rates", "/api/funding/rates", 
+        // Narrow server-side: the unfiltered accumulated book is ~16k rows, and
+        // slicing it client-side left every coin past the alphabetical head
+        // reporting "No funding rates found" (2026-08-01 audit).
+        { type: "accumulated", coin: coinUpper }, "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"),
+        // 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 dollar value actually paid at the next settlement -- funding
+        // rates above show the rate, not the OI-weighted amount that changes
+        // hands. Coin-scoped, so this reads the coin's own row below, never
+        // `totals` (which stays scoped to the whole class regardless of the
+        // `coin` filter -- see settlement-query.ts).
+        safeCall(callApi, "/api/v1/funding/settlement", "/api/funding/settlement", { coin: coinUpper, window: "current" }, "settlement"),
     ];
     const results = await Promise.allSettled(tasks);
     const settled = results.map((r) => r.status === "fulfilled"
         ? r.value
         : { data: null, error: "Promise rejected" });
-    const [funding, oi, prediction] = settled;
+    const [funding, oi, prediction, settlement] = settled;
     const errors = settled
         .filter((s) => s.error)
         .map((s) => s.error);
     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(", ")}`);
-                }
-            }
+    // Price prediction. The coverage list already carries the full score row for
+    // every covered coin, so the matched row is the answer — no second call.
+    const predictionRow = prediction.data
+        ? findPredictionRow(prediction.data, coinUpper)
+        : null;
+    if (predictionRow) {
+        const finalPred = predictionRow;
+        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(", ")}`);
         }
     }
+    else if (prediction.data) {
+        lines.push(`\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.*`);
+    }
     else {
         lines.push("\n*Price prediction data unavailable*");
     }
-    // Funding rates
+    // Open interest per venue. Read before the funding section, which lists
+    // venues in open-interest order.
+    let oiRows = oi.data;
+    const oiExcluded = excludedOiVenues(oiRows);
+    if (isRecord(oiRows) && "data" in oiRows)
+        oiRows = oiRows.data;
+    const venueOi = Array.isArray(oiRows)
+        ? summarizeVenueOi(oiRows, oiExcluded)
+        : null;
+    // Funding. type=accumulated rows carry realised sums of settled funding
+    // (acc_1d, acc_7d), not a per-interval rate, and arrive ordered by
+    // exchange name. List the largest venues by open interest and summarise
+    // every row: averaging the first ten alphabetical rows skipped Bybit, OKX
+    // and Hyperliquid (2026-09-24 audit).
     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)) {
-            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);
-            });
+        const ratesList = listRows(funding.data);
+        if (ratesList) {
+            // Exact identity match only: a `symbol.startsWith` prefix test folded
+            // unrelated markets in (BTC pulling BTCDOM, SOL pulling SOLAYER/SOLV).
+            // The API scopes `coin` to an asset, so PEPE's rows include its
+            // 1000PEPE and KPEPE lot contracts; rowsForFundingCoin keeps them.
+            const coinRates = rowsForFundingCoin(ratesList, coinUpper);
             if (coinRates.length > 0) {
+                const oiByExchange = new Map((venueOi?.current ?? []).map((venue) => [
+                    venue.exchange,
+                    venue.value,
+                ]));
+                const venueOiOf = (rec) => oiByExchange.get(String(rec.exchange ?? "")) ?? -1;
+                const listed = [...coinRates].sort((a, b) => venueOiOf(b) - venueOiOf(a) ||
+                    String(a.exchange ?? "").localeCompare(String(b.exchange ?? "")));
                 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);
-                    }
+                lines.push("**Funding (realised 1d / 7d sums, largest venues by OI):**");
+                for (const rec of listed.slice(0, 10)) {
+                    const market = [rec.exchange ?? "Unknown", rec.symbol]
+                        .filter(Boolean)
+                        .join(" ");
+                    lines.push(`  ${market}: 1d ${fmtRate(finiteOrNull(rec.acc_1d))} | 7d ${fmtRate(finiteOrNull(rec.acc_7d))}`);
                 }
-                if (rateValues.length > 0) {
-                    const avg = rateValues.reduce((a, b) => a + b, 0) / rateValues.length;
-                    lines.push(`  **Avg:** ${fmtRate(avg)} across ${rateValues.length} exchanges`);
+                const settled = coinRates.filter((rec) => finiteOrNull(rec.acc_1d) != null);
+                if (settled.length > 0) {
+                    // Row count and venue count differ: one venue can list the same coin
+                    // as both a linear and an inverse market.
+                    const exchanges = new Set(settled.map((rec) => String(rec.exchange ?? "Unknown")));
+                    const oneDay = median(settled.map((rec) => rec.acc_1d));
+                    lines.push(`  **Median 1d realised funding:** ${fmtRate(oneDay)} across ${settled.length} markets on ${exchanges.size} exchanges`);
                 }
             }
             else {
@@ -186,50 +361,65 @@ export async function analyzeCoin(callApi, coin) {
     }
     // Open interest
     if (oi.data) {
-        let oiData = oi.data;
-        if (typeof oiData === "object" &&
-            oiData !== null &&
-            !Array.isArray(oiData) &&
-            "data" in oiData) {
-            oiData = oiData.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);
-                }
+        if (venueOi) {
+            for (const venue of venueOi.current.slice(0, 10)) {
+                lines.push(`  ${venue.exchange}: ${fmtUsd(venue.value)}`);
             }
-            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)}`);
+            if (venueOi.current.length > 0) {
+                const total = venueOi.current.reduce((sum, venue) => sum + venue.value, 0);
+                const listedNote = venueOi.current.length > 10 ? " (top 10 listed)" : "";
+                lines.push(`  **Total:** ${fmtUsd(total)} across ${venueOi.current.length} exchanges${listedNote}`);
             }
-            if (latestByExchange.size > 0) {
-                lines.push(`  **Total:** ${fmtUsd(totalOi)} across ${latestByExchange.size} exchanges`);
+            if (venueOi.excluded.length > 0) {
+                const excludedVenues = venueOi.excluded
+                    .map((venue) => {
+                    const reason = oiExcluded.get(venue.exchange);
+                    return `${venue.exchange} ${fmtUsd(venue.value)}${reason ? ` (${reason})` : ""}`;
+                })
+                    .join("; ");
+                lines.push(`  *Excluded from the total, per-venue value only: ${excludedVenues}.*`);
+            }
+            if (venueOi.stale.length > 0) {
+                const staleVenues = venueOi.stale
+                    .map((venue) => `${venue.exchange} (${new Date(venue.at).toISOString().slice(0, 16)}Z)`)
+                    .join(", ");
+                lines.push(`  *Excluded from the total, latest reading over 2h older than the newest: ${staleVenues}.*`);
             }
         }
     }
     else {
         lines.push("\n*Open interest data unavailable*");
     }
+    // Settlement: dollar value actually paid at the next settlement.
+    if (settlement.data) {
+        const payload = settlement.data;
+        const rows = payload.rows ?? payload.data;
+        const row = Array.isArray(rows)
+            ? rows.find((r) => typeof r === "object" &&
+                r !== null &&
+                String(r.base_coin ?? "").toUpperCase() === coinUpper)
+            : undefined;
+        const net = safeGet(row, "windows", "current", "net");
+        lines.push("");
+        lines.push("**Settlement (next, estimated):**");
+        if (net == null) {
+            lines.push("  No funding data for the next settlement.");
+        }
+        else if (net > 0) {
+            lines.push(`  Longs pay ${fmtUsd(net)} to shorts.`);
+        }
+        else if (net < 0) {
+            lines.push(`  Shorts pay ${fmtUsd(-net)} to longs.`);
+        }
+        else {
+            lines.push("  No net funding at the next settlement.");
+        }
+    }
+    else {
+        lines.push("\n*Settlement data unavailable*");
+    }
     if (errors.length > 0) {
         lines.push("");
         lines.push(`**Data gaps:** ${errors.join("; ")}`);
@@ -242,11 +432,14 @@ export async function marketBriefing(callApi) {
         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"),
+        // No coin filter, so `totals` correctly reflects the whole requested
+        // class (all, by default) rather than one coin's row.
+        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 [overview, narratives, funding, settlement] = settled;
     const errors = settled
         .filter((s) => s.error)
         .map((s) => s.error);
@@ -339,7 +532,7 @@ export async function marketBriefing(callApi) {
     }
     // Funding highlights
     if (funding.data) {
-        let ratesList = funding.data;
+        let ratesList = splitPaginated(funding.data).rows;
         if (typeof ratesList === "object" &&
             ratesList !== null &&
             !Array.isArray(ratesList) &&
@@ -353,22 +546,42 @@ export async function marketBriefing(callApi) {
                 const rec = r;
                 return (rec.rate ?? rec.funding_rate) != null;
             });
+            // A stale rate is not where funding is now; skip it before ranking.
+            const fresh = valid.filter((r) => !isStaleRow(r));
+            // `rate` is settled over the row's own interval (1h/2h/4h/8h/24h), so
+            // raw rates are not comparable across venues: ranking them un-normalized
+            // understated every 1h venue by 8x. Rank on APR instead. A row with no
+            // usable interval cannot be annualized honestly and is never assumed 8h.
+            const rankable = fresh.filter((r) => intervalHours(r) != null);
+            // Only markets someone can hold rank: unfloored, the extremes were
+            // always dust (HFT on Kraken, $2.5K of OI at -17,404% APR).
+            const liquid = rankable.filter((r) => meetsLiquidityFloor(r.open_interest));
             if (valid.length > 0) {
-                const rateVal = (r) => Number(r.rate ?? r.funding_rate ?? 0);
-                const sorted = [...valid].sort((a, b) => rateVal(b) - rateVal(a));
+                const sorted = [...liquid].sort((a, b) => aprVal(b) - aprVal(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(`*Ranked by APR = rate x (8760 / interval_hours), so 1h, 4h and 8h venues are comparable, across the ${liquid.length} markets with at least ${fmtUsd(LIQUIDITY_FLOOR_USD)} open interest.*`);
+                if (sorted.length > 0) {
+                    lines.push("**Highest (longs paying most):**");
+                    for (const r of sorted.slice(0, 3)) {
+                        lines.push(fundingHighlightLine(r));
+                    }
+                    lines.push("**Lowest (shorts paying most):**");
+                    for (const r of sorted.slice(-3)) {
+                        lines.push(fundingHighlightLine(r));
+                    }
+                }
+                const stale = valid.length - fresh.length;
+                if (stale > 0) {
+                    lines.push(`*${stale} row(s) omitted: stale, past the 10-minute funding freshness SLA.*`);
                 }
-                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))}`);
+                const skipped = fresh.length - rankable.length;
+                if (skipped > 0) {
+                    lines.push(`*${skipped} row(s) omitted: no settlement interval published, so their rate cannot be annualized.*`);
+                }
+                const thin = rankable.length - liquid.length;
+                if (thin > 0) {
+                    lines.push(`*${thin} row(s) omitted: open interest below ${fmtUsd(LIQUIDITY_FLOOR_USD)} or unknown.*`);
                 }
             }
         }
@@ -376,6 +589,31 @@ export async function marketBriefing(callApi) {
     else {
         lines.push("\n*Funding rate data unavailable*");
     }
+    // Funding settlement: whole-market dollar total, not a per-row rate.
+    if (settlement.data) {
+        const payload = settlement.data;
+        const totals = payload.totals;
+        const net = safeGet(totals, "current", "net");
+        const longPaid = safeGet(totals, "current", "long_paid");
+        const shortPaid = safeGet(totals, "current", "short_paid");
+        lines.push("");
+        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*");
+    }
     if (errors.length > 0) {
         lines.push("");
         lines.push(`**Data gaps:** ${errors.join("; ")}`);
@@ -383,10 +621,31 @@ export async function marketBriefing(callApi) {
     return lines.join("\n");
 }
 // ── find_opportunities ────────────────────────────────────────────────
+/**
+ * Largest non-stale market open interest per `${exchange}:${base_coin}` in
+ * the current funding book. The spot-perp feed carries neither OI nor a
+ * staleness flag, so its perp legs are checked against this.
+ */
+function perpOpenInterest(rows) {
+    const byPair = new Map();
+    for (const row of rows) {
+        if (isStaleRow(row))
+            continue;
+        const oi = Number(row.open_interest);
+        if (!(oi > 0))
+            continue;
+        const key = `${String(row.exchange ?? "")}:${String(row.base_coin ?? "").toUpperCase()}`;
+        if (oi > (byPair.get(key) ?? 0))
+            byPair.set(key, oi);
+    }
+    return byPair;
+}
 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"),
+        // The scanner applies no floor by default, which let a leg with $10K of
+        // OI lead at 8,492% APR (2026-09-24 audit). Both legs must clear it.
+        safeCall(callApi, "/api/v1/arbitrage/cross-exchange", "/api/arbitrage/cross-exchange", { minOiUsd: LIQUIDITY_FLOOR_USD, minVolUsd: LIQUIDITY_FLOOR_USD }, "cross-exchange-arb"),
         safeCall(callApi, "/api/v1/funding/rates", "/api/funding/rates", { type: "current" }, "funding"),
     ]);
     const settled = results.map((r) => r.status === "fulfilled"
@@ -397,34 +656,37 @@ export async function findOpportunities(callApi) {
         .filter((s) => s.error)
         .map((s) => s.error);
     const lines = ["## Arbitrage Opportunities"];
+    const fundingRows = funding.data ? listRows(funding.data) : null;
+    const perpOi = fundingRows ? perpOpenInterest(fundingRows) : null;
+    const floorLabel = fmtUsd(LIQUIDITY_FLOOR_USD);
     // 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)));
-            });
+        const arbList = listRows(spotPerp.data);
+        if (arbList && arbList.length > 0) {
+            // A perp leg whose OI is unknown, stale or under the floor is not an
+            // executable trade; unfiltered, frozen CoinEx rows at the +/-1.5% cap
+            // filled nine of the top ten.
+            const liquid = perpOi
+                ? arbList.filter((a) => (perpOi.get(`${String(a.exchange ?? "")}:${String(a.symbol ?? a.coin ?? "").toUpperCase()}`) ?? 0) >= LIQUIDITY_FLOOR_USD)
+                : arbList;
+            // Rank on the fee-adjusted net APR the route itself sorts by.
+            const sorted = [...liquid].sort((a, b) => sortKey(b.netApr ?? b.apr) - sortKey(a.netApr ?? a.apr));
             lines.push("");
-            lines.push("### Spot-Perp Basis Trades (Top 10 by APR)");
+            lines.push("### Spot-Perp Basis Trades (Top 10 by net APR)");
             lines.push("*Long spot + short perp (or vice versa) to capture funding*");
+            lines.push(perpOi
+                ? `*Perp legs with at least ${floorLabel} open interest in the funding book: ${liquid.length} of ${arbList.length} rows.*`
+                : "*Liquidity floor not applied: funding book unavailable.*");
             lines.push("");
+            if (sorted.length === 0) {
+                lines.push("  *No spot-perp row clears the liquidity floor.*");
+            }
             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 symbol = String(a.symbol ?? a.coin ?? "?");
+                const exchange = String(a.exchange ?? "?");
+                const rate = finiteOrNull(a.fundingRate ?? a.rate ?? a.funding_rate);
+                const direction = String(a.direction ?? "?");
+                lines.push(`  **${symbol}** on ${exchange} | Net APR: ${fmtApr(a.netApr)} | Gross APR: ${fmtApr(a.apr ?? a.annualized_apr)} | Rate: ${fmtRate(rate)} | Dir: ${direction}`);
             }
         }
         else {
@@ -436,38 +698,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)));
+        const cxList = listRows(crossEx.data);
+        if (cxList && cxList.length > 0) {
+            // Executable rows (book-priced and fresh) rank first on net APR, which
+            // prices the entry spread; indicative rows follow on gross APR.
+            const executable = (a) => a.executionStatus != null
+                ? a.executionStatus === "executable"
+                : a.netApr != null;
+            const grossApr = (a) => a.apr ?? a.spread_apr ?? a.annualized_apr;
+            const sorted = [...cxList].sort((a, b) => {
+                const aExec = executable(a);
+                const bExec = executable(b);
+                if (aExec !== bExec)
+                    return aExec ? -1 : 1;
+                return aExec
+                    ? sortKey(b.netApr) - sortKey(a.netApr)
+                    : sortKey(grossApr(b)) - sortKey(grossApr(a));
             });
             lines.push("");
-            lines.push("### Cross-Exchange Funding Arb (Top 10 by APR)");
+            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. Executable (book-priced) rows rank first by net APR, then indicative rows by gross APR.*`);
             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 symbol = String(a.symbol ?? a.coin ?? "?");
+                const longEx = String(a.longExchange ?? a.long_exchange ?? a.exchange_long ?? "?");
+                const shortEx = String(a.shortExchange ?? a.short_exchange ?? a.exchange_short ?? "?");
+                const spread = finiteOrNull(a.spreadRate ?? a.spread ?? a.spread_rate);
+                lines.push(`  **${symbol}** | Long ${longEx} / Short ${shortEx} | Net APR: ${fmtApr(a.netApr)} | Gross APR: ${fmtApr(grossApr(a))} | Spread: ${fmtRate(spread)} | ${executable(a) ? "executable" : "indicative"}`);
             }
         }
         else {
@@ -477,38 +735,29 @@ export async function findOpportunities(callApi) {
     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)`);
-            }
+    // Funding rate summary. `rate` is per the row's own interval, so a raw
+    // average mixed 1h, 4h and 8h units; average APR over liquid markets.
+    if (fundingRows && fundingRows.length > 0) {
+        const valid = fundingRows.filter((r) => (r.rate ?? r.funding_rate) != null);
+        const liquid = valid.filter((r) => !isStaleRow(r) &&
+            intervalHours(r) != null &&
+            meetsLiquidityFloor(r.open_interest));
+        if (liquid.length > 0) {
+            const aprs = liquid.map(aprVal);
+            const avg = aprs.reduce((a, b) => a + b, 0) / aprs.length;
+            const positive = aprs.filter((v) => v > 0).length;
+            const negative = aprs.filter((v) => v < 0).length;
+            lines.push("");
+            lines.push("### Funding Rate Summary");
+            lines.push(`*${liquid.length} of ${valid.length} markets: fresh, with at least ${floorLabel} open interest and a published settlement interval.*`);
+            lines.push(`**Avg APR:** ${fmtApr(avg)} (rate x 8760 / interval_hours, averaged across markets)`);
+            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) {