@sharpe-terminal/mcp-server 1.2.0 → 1.5.0

package/dist/tools.js

@@ -1,7 +1,55 @@
 import { z } from "zod";
 import { FUTURES_CHARTS } from "./resources.js";
+import { MAX_ITEMS, paginateRows, paginateSnapshotPayload, rowTimeMs, } from "./tool-runtime.js";
 // -- Tool schemas (Zod shapes for McpServer.tool()) --
 const FUTURES_CHART_IDS = FUTURES_CHARTS.map((chart) => chart.id);
+const pageCursorSchema = z
+    .string()
+    .optional()
+    .describe("Pagination cursor returned by the previous page. Only meaningful alongside limit.");
+export const globalOverviewSchema = {
+    tab: z
+        .enum(["crypto", "equity", "preipo", "etf", "index", "commodity", "fx"])
+        .default("crypto")
+        .describe("Universe to return rows for. 'crypto' = crypto perps; the rest are RWA perp classes. The market-wide metric block is identical on every tab. The 'basket' asset class has no tab and is rejected."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(1000)
+        .optional()
+        .describe("Rows per page (1-1000). A paged response is { data, pagination } holding only the ranked rows; the market-wide metric block comes back on unpaged calls. Responses are additionally capped at 200 items, so pass limit together with cursor to page through every row."),
+    cursor: pageCursorSchema,
+};
+export const rwaPerpRatesSchema = {
+    type: z
+        .enum(["current", "history", "stats"])
+        .default("current")
+        .describe("Type of rwa-perp data. 'current' = latest funding/rollover snapshot per venue market, 'history' = session-tagged settlement time-series for one symbol (Hyperliquid + Kraken), 'stats' = best carry, top cross-venue spread, weekend premium, and tracked open interest."),
+    symbol: z
+        .string()
+        .optional()
+        .describe("Underlying equity ticker (e.g. TSLA, NVDA, MSTR). Required for type=history. GOOG (Ostium) and GOOGL (Hyperliquid/Kraken) are distinct share classes."),
+    venue: z
+        .string()
+        .optional()
+        .describe("Filter results to a single venue, e.g. Binance, Bybit, OKX, Bitget, Gate, Kraken, Coinbase, Aster, Lighter, Extended, GRVT, ApeX, Pacifica, Orderly, Ostium, Avantis, or a Hyperliquid HIP-3 builder market (Hyperliquid, Felix, Kinetiq, dreamcash, Paragon, Ventuals). Free-form because the venue list is registry-driven and grows."),
+    days: z
+        .number()
+        .min(1)
+        .max(90)
+        .default(7)
+        .optional()
+        .describe("Days of settlement history to retrieve (type=history only). Range: 1-90."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(5000)
+        .optional()
+        .describe("Rows per page for type=current and type=history (1-5000); a paged response is { data, pagination }. Responses are additionally capped at 200 items, so pass limit together with cursor to page through every row."),
+    cursor: pageCursorSchema,
+};
 export const fundingRatesSchema = {
     type: z
         .enum(["current", "accumulated", "history"])
@@ -10,7 +58,19 @@ export const fundingRatesSchema = {
     coin: z
         .string()
         .optional()
-        .describe("Base coin ticker (e.g. BTC, ETH, SOL). Filters results to this base coin across all exchanges. Required for type=history; optional for current/accumulated."),
+        .describe("Coin ticker, lot spelling or full name (e.g. BTC, PEPE, 1000PEPE, kPEPE, bitcoin). Returns every contract of that asset across all exchanges, whatever its base_coin spelling: PEPE also returns the 1000PEPE and KPEPE lot contracts (read lot_multiplier). Required for type=history; optional for current/accumulated."),
+    exchange: z
+        .string()
+        .optional()
+        .describe("Filter to a single venue. Values are title case exactly as returned in the `exchange` field (e.g. Binance, Bybit, OKX, Gate.io, Hyperliquid, Kraken, Aster, Lighter, dYdX, Crypto.com, edgeX, tradeXYZ); lowercase slugs such as 'gate-io' also resolve. Free-form because the venue list is registry-driven and grows. Read sharpe://exchanges for the current list."),
+    margin: z
+        .enum(["linear", "inverse"])
+        .optional()
+        .describe("Collateral convention: 'linear' = quote-margined (USDT/USDC), 'inverse' = coin-margined. Unfiltered by default."),
+    asset_class: z
+        .enum(["crypto", "equity", "commodity", "fx", "index"])
+        .optional()
+        .describe("Underlying category of the perpetual. Unfiltered by default, so tokenized-equity, commodity, index and FX perps are returned alongside crypto; pass 'crypto' to rank crypto only."),
     days: z
         .number()
         .min(1)
@@ -18,6 +78,66 @@ export const fundingRatesSchema = {
         .default(30)
         .optional()
         .describe("Number of days of history to retrieve (type=history only). Range: 1-1095."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(5000)
+        .optional()
+        .describe("Maximum rows to return. Responses are additionally capped at 200 items to protect the agent context window, so pass limit together with cursor to page through the whole book."),
+    cursor: z
+        .string()
+        .optional()
+        .describe("Pagination cursor returned by the previous page. Only meaningful alongside limit."),
+    sort: z
+        .enum(["open_interest", "-open_interest"])
+        .optional()
+        .describe("type=current only: order the rows by their open_interest, ascending, or descending with the leading '-'. Rows with unknown open interest come last either way. Applied before limit/cursor."),
+    extremes: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe("type=current only: answer with the N highest and N lowest markets by rate_8h (extremes.highest, extremes.lowest, each row with rate_8h and apr) among fresh rows with a usable interval, and how many rows each check left out (extremes.omitted: stale, no_interval, below_floor). The other filters narrow the rows first. Returns an object instead of rows: do not pass limit, cursor or sort with it."),
+    min_oi_usd: z
+        .number()
+        .min(0)
+        .optional()
+        .describe("With extremes only: leave out markets whose open interest in USD is below this floor. A market with unknown open interest fails a floor above 0."),
+    stats: z
+        .enum(["1"])
+        .optional()
+        .describe("type=current only: '1' answers with the whole book's funding (market.funding_apr_mean and market.funding_apr_oi_weighted, APR fractions over one primary contract per venue and asset with a fresh rate; market.positive and market.negative counts). Returns an object instead of rows; cannot be combined with coin, exchange, margin, asset_class, limit, cursor or sort."),
+    summary: z
+        .enum(["1"])
+        .optional()
+        .describe("type=current with coin only: '1' answers with the coin's funding across venues, one summary entry per base_coin spelling and asset class: funding_avg_8h (the funding grid's Avg Rate: open-interest-weighted over each venue's fresh primary contract, or their median; funding_method says which), funding_median_8h, funding_venues_used, funding_venues_stale, funding_all_stale. Returns an object instead of rows; cannot be combined with limit, cursor or sort."),
+};
+export const fundingSettlementSchema = {
+    window: z
+        .enum(["current", "1d", "3d", "7d"])
+        .default("current")
+        .describe("Settlement window. 'current' is the next settlement, priced live off open interest and the forward-looking rate (predicted_rate when a venue publishes one, else the in-progress rate) -- always estimated, never realised yet. '1d'/'3d'/'7d' are realised windows; one whose coverage is below 90% carries partial: true in its window value because its history is still accruing, not a completed total."),
+    class: z
+        .enum(["all", "crypto", "rwa"])
+        .default("all")
+        .describe("Asset universe. 'rwa' = tokenized equity, commodity, FX and index perps. crypto + rwa always equal the all totals."),
+    coin: z
+        .string()
+        .optional()
+        .describe("Comma-separated base coin tickers (e.g. 'BTC' or 'BTC,ETH,SOL') to filter rows to. `totals` stays scoped to the selected class regardless of this filter -- read a filtered coin's own row for its number, not totals."),
+    exchange: z
+        .string()
+        .optional()
+        .describe("Keep only coins that have a contract on this venue. Each row's windows and open interest stay all-venue totals, not this venue's own figures. Free-form because the venue list is registry-driven and grows; an unresolvable value is rejected rather than silently returning an empty book."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(1000)
+        .optional()
+        .describe("Maximum rows to return, in market-cap rank order (unranked coins follow alphabetically). Defaults to 100."),
 };
 export const futuresDataSchema = {
     chart: z
@@ -37,6 +157,14 @@ export const futuresDataSchema = {
         .string()
         .optional()
         .describe("Comma-separated list of exchanges to include (e.g. Binance,Bybit,OKX,Deribit,Hyperliquid)."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(10000)
+        .optional()
+        .describe("Rows per page (1-10000), oldest first, returned with a pagination cursor. Paged rows are raw chart rows, oi-snapshot included. Responses are additionally capped at 200 items, so pass limit together with cursor to page through the full window."),
+    cursor: pageCursorSchema,
 };
 export const futuresCoinsSchema = {};
 export const correlationMatrixSchema = {
@@ -48,7 +176,7 @@ export const correlationMatrixSchema = {
     ids: z
         .string()
         .optional()
-        .describe("Comma-separated list of crypto asset IDs (e.g. bitcoin,ethereum,solana). If omitted, returns the default set of top assets."),
+        .describe("Comma-separated asset IDs. Use CoinGecko IDs for crypto (e.g. bitcoin,ethereum) and Sharpe IDs for TradFi (e.g. sp500,gold,nvda). If omitted, returns the default mixed set."),
 };
 export const arbitrageSpotPerpSchema = {
     exchange: z
@@ -60,13 +188,38 @@ export const arbitrageSpotPerpSchema = {
         .enum(["all", "long", "short"])
         .default("all")
         .optional()
-        .describe("Filter by trade direction."),
+        .describe("Filter by perpetual-leg direction: short for positive funding capture, long for negative funding capture."),
+    minOiUsd: z
+        .number()
+        .min(0)
+        .optional()
+        .describe("Minimum open interest in USD on the perp leg (perpOpenInterestUsd). A row whose open interest is unknown fails a floor above 0. Default 0 (no floor). The board order is kept."),
 };
 export const arbitrageCrossExchangeSchema = {
     exchanges: z
         .string()
         .optional()
-        .describe("Comma-separated list of exchanges to compare (e.g. Binance,Bybit,OKX)."),
+        .describe("Comma-separated list of venues to compare (e.g. Binance,Bybit,Hyperliquid). Omit for all 32 funding venues."),
+    minOiUsd: z
+        .number()
+        .min(0)
+        .optional()
+        .describe("Minimum open interest in USD on the smaller leg. Legs with unknown OI fail the floor. Default 0 (no floor)."),
+    minVolUsd: z
+        .number()
+        .min(0)
+        .optional()
+        .describe("Minimum 24h volume in USD on the smaller leg. Legs with unknown volume fail the floor. Default 0 (no floor)."),
+    assetClass: z
+        .enum(["all", "crypto", "rwa"])
+        .optional()
+        .describe('Underlying filter: "all" (default), "crypto", or "rwa" (equity, commodity, FX and index perps). Pairs never cross asset classes.'),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe("At most this many rows, the first ones in the board's order (executable first). Default: every row."),
 };
 export const arbitrageScannerSchema = {
     coin: z
@@ -80,17 +233,26 @@ export const arbitrageScannerSchema = {
     minApr: z
         .number()
         .optional()
-        .describe("Minimum APR or carry edge in percentage points."),
+        .describe("Minimum product-specific fee-adjusted net APR in percentage points."),
     minOiUsd: z
         .number()
         .min(0)
         .optional()
         .describe("Minimum open interest in USD."),
+    minVolumeUsd: z
+        .number()
+        .min(0)
+        .optional()
+        .describe("Minimum 24-hour volume in USD."),
     minDepthUsd: z
         .number()
         .min(0)
         .optional()
         .describe("Minimum executable depth in USD when available."),
+    marginType: z
+        .enum(["linear", "inverse", "both"])
+        .optional()
+        .describe("Futures margin type filter."),
     notional: z
         .number()
         .positive()
@@ -112,7 +274,10 @@ export const arbitrageScannerSchema = {
 export const cexSpotTransferScannerSchema = {
     coin: arbitrageScannerSchema.coin,
     exchanges: arbitrageScannerSchema.exchanges,
-    minApr: arbitrageScannerSchema.minApr,
+    minApr: z
+        .number()
+        .optional()
+        .describe("Minimum fee-adjusted transfer profit in percentage points (legacy parameter name)."),
     minDepthUsd: arbitrageScannerSchema.minDepthUsd,
     notional: arbitrageScannerSchema.notional,
     limit: arbitrageScannerSchema.limit,
@@ -128,21 +293,7 @@ export const heatmapSchema = {
         .string()
         .default("top-100")
         .optional()
-        .describe("Category filter (e.g. top-100, defi, layer-1, memes)."),
-};
-export const dexScreenerDataSchema = {
-    category: z
-        .enum(["volume", "trending", "gainers", "losers", "new_pairs"])
-        .default("trending")
-        .optional()
-        .describe("DEX Screener category."),
-    network: z.string().optional().describe("Optional chain/network slug."),
-    phrase: z.string().optional().describe("Optional search phrase."),
-    limit: z.number().min(1).max(100).default(50).optional(),
-};
-export const dexScreenerSecuritySchema = {
-    address: z.string().describe("Token contract address."),
-    chainId: z.number().int().positive().describe("Codex network ID."),
+        .describe("One of 34 category slugs (e.g. top-100, defi, layer-1, memes). The legacy top-100 slug returns the Top 50 universe."),
 };
 export const tokenScannerSchema = {
     mode: z
@@ -156,18 +307,30 @@ export const tokenScannerSchema = {
         .describe("Comma-separated Dexscreener chain IDs."),
     chain: z.string().optional().describe("Single chain for top-new mode."),
     profile: z
-        .enum(["discovery", "balanced", "strict", "custom"])
+        .enum(["discovery", "balanced", "strict"])
         .optional()
         .describe("Scanner profile."),
-    limit: z.number().min(1).max(200).default(50).optional(),
+    days: z.number().min(1).optional().describe("Top-new lookback in days."),
+    limit: z.number().min(1).max(72).default(50).optional(),
     minLiquidityUsd: z.number().min(0).optional(),
     minVolumeH24: z.number().min(0).optional(),
     minTxnsH1: z.number().min(0).optional(),
+    minTxnsH24: z.number().min(0).optional(),
     maxAgeHours: z.number().min(0).optional(),
+    includeUnknownAge: z.boolean().optional(),
+    sortBy: z.enum(["score", "readiness", "rs", "volume", "momentum"]).optional(),
+    minBreakoutReadiness: z.number().min(0).optional(),
+    minRelativeStrength: z.number().optional(),
+    maxVolLiqRatio: z.number().min(0).optional(),
+    minPriceChangeH1: z.number().optional(),
 };
 export const rugCheckSecuritySchema = {
     address: z.string().describe("Token contract address."),
-    chainId: z.number().int().positive().describe("Chain/network ID."),
+    chainId: z
+        .number()
+        .int()
+        .positive()
+        .describe("EVM chain ID (1 Ethereum, 56 BNB Smart Chain, 8453 Base, 42161 Arbitrum, 137 Polygon, 10 Optimism, 43114 Avalanche, 146 Sonic, 80094 Berachain, and 29 more), or 1399811149 for Solana and 728126428 for Tron. An unsupported chain returns 400."),
 };
 export const rugCheckTrendingSchema = {
     limit: z.number().min(1).max(100).default(50).optional(),
@@ -205,7 +368,7 @@ export const webTrafficSchema = {
         .optional()
         .describe("Entity type."),
     mode: z
-        .enum(["rankings", "trends", "snapshots", "market"])
+        .enum(["rankings", "snapshots", "market"])
         .optional()
         .describe("Payload mode."),
     tf: z
@@ -218,23 +381,40 @@ export const webTrafficSchema = {
         .optional()
         .describe("Market sub-mode when mode=market."),
 };
-export const katanaSchema = {};
 export const narrativesSchema = {
     narrative: z
         .string()
         .optional()
-        .describe("Narrative slug to filter by (e.g. layer-1, layer-2, defi, ai-agents, defai, depin, desci, gaming, dex, cex, lending, memes, nfts, oracles, privacy, rwa, stablecoins, restaking, liquid-staking, modular, socialfi, intent). Omit for all narratives."),
+        .describe("Narrative to filter by, as the id the API matches (layer-1, layer-2, defi, ai-agents, defai, depin, desci, gaming, dex, cex, lending, memes, nfts, oracles, privacy, rwa, stablecoins, restaking, liquid-staking, modular, socialfi, intent, prediction-markets, perps, bridges, account-abstraction, tap-to-earn, telegram-apps, zk, yield-farming). Page slugs such as dex-tokens or cex-tokens return no coins; use dex or cex. Omit for all narratives."),
     correlation: z
         .string()
         .optional()
         .describe('Set to "true" to include correlation data between the narrative\'s tokens.'),
     timeframe: z.string().optional().describe("Timeframe for correlation data."),
+    sort: z
+        .enum(["-change24h", "change24h"])
+        .optional()
+        .describe("Order the narratives list by 24h change: '-change24h' highest first, 'change24h' lowest first. A narrative without a 24h change comes last either way."),
+    top: z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .optional()
+        .describe("Add `top`: the N narratives with the highest 24h change, highest first. A narrative without a 24h change is never ranked."),
+    bottom: z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .optional()
+        .describe("Add `bottom`: the N narratives with the lowest 24h change, lowest first. A narrative without a 24h change is never ranked."),
 };
 export const ecosystemsSchema = {
     ecosystem: z
         .string()
         .optional()
-        .describe("Ecosystem slug to filter by (e.g. ethereum, solana, bnb-chain, arbitrum, base, bitcoin, avalanche, optimism, cosmos, polkadot, sui, aptos, ton, tron). Omit for all ecosystems."),
+        .describe("Ecosystem to filter by, as the id the API matches (e.g. ethereum, solana, bnb, arbitrum, base, bitcoin, avalanche, optimism, cosmos, polkadot, sui, aptos, ton, tron); read sharpe://ecosystems for all of them. Page slugs such as bnb-chain or toncoin return no coins; use bnb or ton. Omit for all ecosystems."),
     excludeNative: z
         .string()
         .optional()
@@ -291,6 +471,13 @@ export const newsSchema = {
         .string()
         .optional()
         .describe("ISO 8601 timestamp. Only return articles published after this time."),
+    q: z
+        .string()
+        .trim()
+        .min(1)
+        .max(200)
+        .optional()
+        .describe("Search article titles across the stored news corpus."),
     offset: z
         .number()
         .int()
@@ -298,36 +485,19 @@ export const newsSchema = {
         .optional()
         .describe("Offset for pagination; skip this many articles before returning results."),
 };
-export const curatedNewsSchema = {
-    limit: z
-        .number()
-        .min(1)
-        .max(100)
-        .default(20)
-        .optional()
-        .describe("Maximum number of curated stories to return (1-100)."),
-    category: z
-        .enum(["all", "crypto", "ai", "markets", "geopolitics"])
-        .optional()
-        .describe("Filter by category: all, crypto, ai, markets, geopolitics."),
-    cursor: z
-        .string()
-        .optional()
-        .describe("Pagination cursor (ISO date or 'date|id') from a previous response."),
-};
 export const marketOverviewSchema = {};
 export const pricePredictionSchema = {
     coin: z
         .string()
         .optional()
-        .describe("Canonical coin slug (e.g. bitcoin, ethereum, solana)."),
+        .describe("Ticker or canonical coin slug (e.g. BTC, bitcoin, solana). Omit for all coins."),
 };
 export const searchMarketCapSchema = {
     q: z
         .string()
         .min(2)
         .max(100)
-        .describe("Search query (2-100 characters). Can be a coin name or ticker."),
+        .describe("Crypto or supported TradFi asset name/symbol (2-100 characters)."),
 };
 export const gemFinderSchema = {
     limit: z
@@ -337,6 +507,10 @@ export const gemFinderSchema = {
         .default(100)
         .optional()
         .describe("Maximum number of tokens to return (1-1000)."),
+    cursor: z
+        .string()
+        .optional()
+        .describe("Snapshot-bound pagination cursor returned by the previous Gem Finder page."),
 };
 export const derivativesOverviewSchema = {};
 export const apiCoverageSchema = {};
@@ -375,15 +549,25 @@ const listingExchangeIds = [
     "dydx",
     "aevo",
 ];
+// /listings/data validates only the legacy compatibility venues
+// (legacyListingExchangeIds in src/lib/api/schemas.ts) and 400s the rest;
+// the recent/events feeds accept every id in listingExchangeIds.
+const legacyListingExchangeIds = [
+    "binance",
+    "okx",
+    "bybit",
+    "gateio",
+    "mexc",
+];
 export const listingsDataSchema = {
     narrative: z
         .string()
         .optional()
         .describe("Filter to a single narrative slug (e.g. 'ai-agents', 'memes', 'layer-1', 'rwa', 'defi'). Uses the Sharpe narrative taxonomy."),
     exchange: z
-        .enum(listingExchangeIds)
+        .enum(legacyListingExchangeIds)
         .optional()
-        .describe("Filter to a single exchange."),
+        .describe("Filter to a single exchange. The aggregate hub covers the compatibility venues only; use get_recent_listings or get_listing_events for the other venues."),
 };
 export const listingsRecentSchema = {
     narrative: z
@@ -531,6 +715,10 @@ export const listingsExchangesSchema = {
         .optional()
         .describe("Filter to enabled or disabled connectors."),
 };
+const signalCoinParam = z
+    .string()
+    .optional()
+    .describe("One coin's row by its CoinGecko id (e.g. bitcoin, pepe), exactly as the scorer wrote it: a coin that stopped qualifying answers score null with its sub-scores cleared instead of being absent; an unknown id answers no rows. limit, min_score and phase do not apply to it.");
 export const signalScoreSchema = {
     limit: z
         .number()
@@ -547,6 +735,7 @@ export const signalScoreSchema = {
         .default(0)
         .optional()
         .describe("Minimum 0-10 risk/pressure score to include."),
+    coin: signalCoinParam,
 };
 // get_pump_dump adds a manipulation-lifecycle phase filter on top of the shared
 // signal-score params. get_insider_selling stays on signalScoreSchema (no phase).
@@ -572,63 +761,173 @@ export const pumpDumpSchema = {
         .enum(["setup", "markup", "distribution", "dump", "dumping"])
         .optional()
         .describe("Filter to one manipulation lifecycle phase."),
+    coin: signalCoinParam,
 };
+// -- Keyless-path post-processing helpers --
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function cursorArg(args) {
+    return typeof args.cursor === "string" && args.cursor
+        ? args.cursor
+        : undefined;
+}
+/**
+ * oi-snapshot is documented as current open interest by exchange, but both
+ * routes return the whole ascending window (up to 5,000 raw rows). Keep each
+ * exchange's newest reading, largest first, so "current" means current.
+ */
+export function latestRowPerExchange(rows) {
+    const latest = new Map();
+    for (const row of rows) {
+        const at = rowTimeMs(row);
+        if (!isRecord(row) || at == null)
+            continue;
+        const exchange = String(row.exchange ?? "");
+        const prev = latest.get(exchange);
+        if (!prev || at >= prev.at)
+            latest.set(exchange, { row, at });
+    }
+    const oiOf = (row) => {
+        const value = Number(row.open_interest_value);
+        return Number.isFinite(value) ? value : Number.NEGATIVE_INFINITY;
+    };
+    return [...latest.values()]
+        .map((entry) => entry.row)
+        .sort((a, b) => oiOf(b) - oiOf(a));
+}
 export const TOOL_DEFS = [
+    {
+        name: "get_global_overview",
+        description: "Get the whole-market derivatives board in one call: total open interest with its crypto-versus-RWA split, 24h liquidations, average Wilder RSI(14) across the top 100 crypto perps by market cap, the Altcoin Season Index (share of the top 50 by market cap beating BTC over 90 days, excluding stablecoins and wrapped/staked derivatives), open interest broken down by asset class, and a ranked per-asset row table. The tab parameter selects the universe: crypto, equity, preipo, etf, index, commodity or fx. Rows carry price, 24h price change, funding rate (interval-true, never assumed 8h), 24h volume, market cap, open interest with 1h and 24h changes, plus liquidations on crypto or a venue count on RWA tabs. Ranks are by open interest descending. Liquidations are crypto-only because no RWA venue publishes a liquidation feed. Use this for 'what is the market doing' questions; use get_funding_rates for per-venue crypto funding detail and get_rwa_perp_funding for RWA carry and cross-venue spreads.",
+        schema: globalOverviewSchema,
+        apiPath: "/api/v1/global/overview",
+        fallbackPath: "/api/global/overview",
+        // The free route ignores limit/cursor and always returns every row with
+        // the metric block. Page its rows into the v1 paged shape ({ data,
+        // pagination }, rows only) so a keyless caller can reach all of them.
+        postProcess: (data, args, context) => {
+            if (context?.paginated || typeof args.limit !== "number")
+                return data;
+            if (!isRecord(data) || !Array.isArray(data.rows))
+                return data;
+            return paginateRows(data.rows, args.limit, cursorArg(args));
+        },
+    },
+    {
+        name: "get_rwa_perp_funding",
+        description: "Get funding and carry for real-world-asset perpetuals (RWA perps: stocks, pre-IPO, ETFs, indices, commodities, FX) across 19 venues: CEXs (Binance, Bybit, OKX, Bitget, Gate, Kraken xStocks, Coinbase INTX), perp DEXs (Aster, Lighter, Extended, GRVT, ApeX, Pacifica, Orderly), Hyperliquid HIP-3 builder markets, and the rollover venues Ostium and Avantis. Rates are interval-true and mechanism-true: funding_apr annualizes each venue's own settlement interval (never an assumed 8h), and a both-sides rollover is reported separately as borrow_apr_annual (a cost, never mixed into funding spreads). Marks more than 2% off the cross-venue median are flagged is_price_suspect and excluded from stats and spreads. type=history returns session-tagged settlements (market/after_hours/weekend/holiday); type=stats returns best carry, top cross-venue spread, weekend premium, and open interest.",
+        schema: rwaPerpRatesSchema,
+        apiPath: "/api/v1/rwa-perps/rates",
+        fallbackPath: "/api/rwa-perps/rates",
+        // The free route returns current/history rows as a bare array and
+        // ignores limit/cursor; page it the way v1 does. type=stats is an object
+        // and passes through.
+        postProcess: (data, args, context) => {
+            if (context?.paginated || typeof args.limit !== "number")
+                return data;
+            if (!Array.isArray(data))
+                return data;
+            return paginateRows(data, args.limit, cursorArg(args));
+        },
+    },
     {
         name: "get_funding_rates",
-        description: "Get perpetual funding rates across all supported exchanges. Returns current snapshots, accumulated rates over multiple windows, or per-coin historical rates. The coin parameter filters to a single base coin in any mode (required for history).",
+        description: "Get perpetual funding rates across every supported venue (see sharpe://exchanges for the current list). Returns current snapshots, accumulated rates over multiple windows, or per-coin historical rates. Units: `rate` is a decimal fraction settled over that row's own `interval_hours` (1h, 2h, 4h, 8h or 24h depending on venue and market). It is not a percent and never implicitly 8h, so compare or rank venues on the served rate_8h (rate × 8 / interval_hours) or apr (rate × 8760 / interval_hours), both null when the row has no usable interval. Accumulated rows carry realized sums (acc_1d/acc_7d/acc_30d/acc_90d/acc_1y) instead of a per-interval rate. Filter with coin, exchange, margin (linear/inverse) and asset_class; asset_class is unfiltered by default, so tokenized-equity, commodity, index and FX perps are included alongside crypto. `coin` names an asset: PEPE returns every PEPE contract, the 1000PEPE and KPEPE lot contracts included. Current and accumulated rows carry asset_id, asset_symbol, lot_multiplier (asset units per contract unit, e.g. 1000 on 1000PEPEUSDT), instrument_status (the venue's own status) and is_live (null = unknown). Page the full book with limit and cursor, or order it by open interest with sort. For type=current the API also answers with aggregates instead of rows: extremes (the highest and lowest markets by rate_8h above an optional min_oi_usd floor), stats (the whole book's mean and OI-weighted funding APR and the positive/negative counts) and summary (with coin: the coin's average and median funding across venues, the funding grid's Avg Rate).",
         schema: fundingRatesSchema,
         apiPath: "/api/v1/funding/rates",
         fallbackPath: "/api/funding/rates",
-        // The free /api/funding/rates endpoint ignores the `coin` param for
-        // current/accumulated modes. Filter client-side so the target rows
-        // survive MAX_ITEMS truncation.
-        postProcess: (data, args) => {
-            const coin = args.coin;
-            const type = args.type;
-            if (typeof coin !== "string" || coin === "" || type === "history") {
-                return data;
-            }
-            if (!Array.isArray(data)) {
+        // The unpaged book is ~13,000 rows (6MB) of which MAX_ITEMS survive
+        // truncation: page it server-side instead, so the rows come with a cursor
+        // (0.3s instead of 1.8s, 2026-09-26). A coin filter or history is small,
+        // and an aggregate (extremes, stats, summary) answers without rows and
+        // refuses a page. The API scopes every filter itself: the rows are served
+        // as it answered them, never re-filtered here.
+        prepareArgs: (args) => args.limit == null &&
+            args.coin == null &&
+            args.type !== "history" &&
+            args.extremes == null &&
+            args.stats == null &&
+            args.summary == null
+            ? { ...args, limit: MAX_ITEMS }
+            : args,
+    },
+    {
+        name: "get_funding_settlement",
+        description: "Get the dollar value of funding actually paid at each settlement -- not just the rate -- and which side, longs or shorts, paid it. Every response carries both the per-coin row breakdown and a totals block (net/long_paid/short_paid) for the requested window and class, so 'who paid funding today' is read directly from totals rather than summed from a page of rows; totals always reflects the full requested class regardless of any coin/exchange filter on the rows. window=current (the default) is the next settlement, priced live off open interest and the forward-looking rate -- always estimated, never realised. 1d/3d/7d are realised windows; one whose coverage is below 90% carries partial: true (complete: false) because its history is still accruing, not a completed total, and halted_within_window says a contract stopped settling inside the window (listed_within_window is always null: no listing time is known). Sign convention: a window's net = long_paid - short_paid; positive means longs paid more than they received (a cost to longs), negative means shorts paid more. Both long_paid and short_paid are always non-negative magnitudes. Missing is null, never 0. class splits crypto perps from RWA perps (tokenized equity, commodity, FX, index); crypto + rwa totals always equal the all totals.",
+        schema: fundingSettlementSchema,
+        apiPath: "/api/v1/funding/settlement",
+        fallbackPath: "/api/funding/settlement",
+        // The v1 payload nests rows/totals/settlementMeta inside the envelope's
+        // `data` field; the free fallback puts the row array directly under
+        // `data` with `totals` riding alongside it (api-client.ts preserves that
+        // sibling instead of discarding it). Normalize both shapes into one
+        // `{ rows, totals, meta }` result so callers never branch on which tier
+        // answered, and `totals` is always the API's own aggregate -- never
+        // recomputed from a possibly-truncated page of rows.
+        postProcess: (data) => {
+            if (!data || typeof data !== "object" || Array.isArray(data)) {
                 return data;
             }
-            const needle = coin.toUpperCase();
-            return data.filter((row) => typeof row === "object" &&
-                row !== null &&
-                String(row.base_coin ?? "").toUpperCase() === needle);
+            const obj = data;
+            const result = {
+                rows: obj.rows ?? obj.data,
+                totals: obj.totals,
+            };
+            const meta = obj.settlementMeta ?? obj.meta;
+            if (meta !== undefined)
+                result.meta = meta;
+            return result;
         },
     },
     {
         name: "get_futures_data",
-        description: "Get futures chart data including open interest, volume, funding rate history, liquidations, long/short ratios, basis, term structure, and OHLCV.",
+        description: "Get futures chart data including open interest, volume, funding rate history, liquidations, long/short ratios, basis, term structure, and OHLCV. Time series are oldest-first; when one exceeds the response cap its newest rows are kept (truncated_fields marks kept: latest). Without limit, oi-snapshot returns each exchange's latest reading; pass limit/cursor to page raw rows oldest-first.",
         schema: futuresDataSchema,
         apiPath: "/api/v1/futures/data",
         fallbackPath: "/api/futures/data",
+        postProcess: (data, args, context) => {
+            if (context?.paginated || !isRecord(data) || !Array.isArray(data.data)) {
+                return data;
+            }
+            if (typeof args.limit === "number") {
+                // The free route ignores limit/cursor: page the same oldest-first
+                // rows v1 pages.
+                return {
+                    ...data,
+                    ...paginateRows(data.data, args.limit, cursorArg(args)),
+                };
+            }
+            if (args.chart === "oi-snapshot") {
+                return { ...data, data: latestRowPerExchange(data.data) };
+            }
+            return data;
+        },
     },
     {
         name: "get_futures_coins",
-        description: "Get the list of coins with futures data available, including capability flags for open interest, liquidations, and long/short ratios per exchange.",
+        description: "Get up to 1,000 coins with futures data, including funding, open-interest, liquidation, long/short, CVD, and dated-basis capability flags plus observed venue coverage and market-cap rank.",
         schema: futuresCoinsSchema,
         apiPath: "/api/v1/futures/coins",
         fallbackPath: "/api/futures/coins",
     },
     {
         name: "get_correlation_matrix",
-        description: "Get a price correlation matrix for crypto assets over a specified period. Useful for portfolio analysis and diversification.",
+        description: "Get a price correlation matrix for crypto and supported TradFi assets over a specified calendar period. Useful for portfolio analysis and diversification.",
         schema: correlationMatrixSchema,
         apiPath: "/api/v1/correlation/matrix",
         fallbackPath: "/api/correlation/matrix",
     },
     {
         name: "get_arbitrage_spot_perp",
-        description: "Get current spot-perpetual funding rate arbitrage opportunities across exchanges. Shows the spread between spot and perp prices that can be captured via basis trading.",
+        description: "Get structurally executable spot-perpetual funding-capture rows with live funding, verified spot or margin availability, diagnostic basis, gross APR, and fee-adjusted net APR, in the board's order (rows with a net APR first by net APR, then by gross APR). Each row carries perpSymbol, perpOpenInterestUsd, fundingIsStale, executionStatus, pairStatus (price_gap when the spot and perp prices are more than 20% apart: no net APR), fundingAsOf and pricesAsOf. minOiUsd floors the perp leg's open interest (unknown fails a positive floor).",
         schema: arbitrageSpotPerpSchema,
         apiPath: "/api/v1/arbitrage/spot-perp",
         fallbackPath: "/api/arbitrage/spot-perp",
     },
     {
         name: "get_arbitrage_cross_exchange",
-        description: "Get cross-exchange price discrepancies and arbitrage opportunities. Shows where the same asset trades at different prices across exchanges.",
+        description: "Get cross-exchange funding arbitrage across every funding venue and asset class (crypto plus RWA perps: equity, commodity, FX, index — pairs never cross classes), ranked with executable rows (book-priced netApr) first by netApr, then indicative rows by gross annualized funding differential (apr); pairs whose two legs' prices differ by more than 20% are indicative (likely different instruments). Spread uses real books where available (spreadSource: book) or reference prices (reference); netApr is present only on book-priced rows; unknown spread/OI/volume are null, never zero. Rows carry pairStatus, fundingAsOf (the older leg's funding write) and pricesAsOf; limit keeps the first N rows of the board.",
         schema: arbitrageCrossExchangeSchema,
         apiPath: "/api/v1/arbitrage/cross-exchange",
         fallbackPath: "/api/arbitrage/cross-exchange",
@@ -656,42 +955,28 @@ export const TOOL_DEFS = [
     },
     {
         name: "get_arbitrage_cex_spot_transfer",
-        description: "Get live CEX spot-transfer arbitrage rows after common network, fee, status, depth, slippage, and spread-lifetime checks.",
+        description: "Get live CEX spot-transfer arbitrage rows after common network and token-contract matching, fee, status, depth, slippage, and spread-lifetime checks.",
         schema: cexSpotTransferScannerSchema,
         apiPath: "/api/v1/arbitrage/cex-spot-transfer",
         fallbackPath: "/api/arbitrage/cex-spot-transfer",
     },
     {
         name: "get_heatmap",
-        description: "Get market heatmap data for coins, narratives, or ecosystems. Visualizes relative performance across the market.",
+        description: "Get market heatmap data for coins, narratives, or ecosystems. The legacy top-100 slug returns the Top 50 universe; aggregate modes expose complete or partial category coverage.",
         schema: heatmapSchema,
         apiPath: "/api/v1/heatmap/data",
         fallbackPath: "/api/heatmap/data",
     },
-    {
-        name: "get_dexscreener_data",
-        description: "Get live DEX Screener rows by category, network, or search phrase. Use this for pair-level discovery across DEX markets. Requires API key (SHARPE_API_KEY) — not available on the free tier.",
-        schema: dexScreenerDataSchema,
-        apiPath: "/api/v1/dexscreener/data",
-        fallbackPath: "/api/v1/dexscreener/data",
-    },
-    {
-        name: "get_dexscreener_security",
-        description: "Get token contract security signals for a DEX Screener token by address and chain ID.",
-        schema: dexScreenerSecuritySchema,
-        apiPath: "/api/v1/dexscreener/security",
-        fallbackPath: "/api/dexscreener/security",
-    },
     {
         name: "get_token_scanner",
-        description: "Run read-only token scanner modes: hot tokens, new runners, alpha drops, AI tokens, or top new pairs. Requires API key (SHARPE_API_KEY) — not available on the free tier.",
+        description: "Run read-only token scanner modes for hot tokens, new runners, alpha drops, AI tokens, and top-new pairs. Responses expose source coverage; valuation and risk fields stay null when unavailable. Requires an API key (SHARPE_API_KEY; the free tier works). No keyless fallback.",
         schema: tokenScannerSchema,
         apiPath: "/api/v1/token-scanner/scan",
         fallbackPath: "/api/v1/token-scanner/scan",
     },
     {
         name: "get_rug_check_security",
-        description: "Get rug-check token contract security and liquidity risk signals.",
+        description: "Get rug-check token contract security and liquidity risk signals, and the Rug Check score the /rug-check page shows, computed by the API: score.value (0-100, higher is safer; null only when no provider answered), score.verdict, score.data_completeness and score.engine_version, with the checks[] behind it.",
         schema: rugCheckSecuritySchema,
         apiPath: "/api/v1/rug-check/security",
         fallbackPath: "/api/rug-check/security",
@@ -705,7 +990,7 @@ export const TOOL_DEFS = [
     },
     {
         name: "get_narratives",
-        description: "Get narrative-level market data (L1, L2, DeFi, AI Agents, DePIN, RWA, Gaming, etc.) including market cap, volume, performance, and social metrics.",
+        description: "Get narrative-level market data (L1, L2, DeFi, AI Agents, DePIN, RWA, Gaming, etc.) including market cap, volume, performance, and social metrics. sort orders the list by 24h change and top/bottom add the N highest and lowest narratives by 24h change (a narrative without one is never ranked).",
         schema: narrativesSchema,
         apiPath: "/api/v1/narratives/data",
         fallbackPath: "/api/narratives/data",
@@ -726,14 +1011,14 @@ export const TOOL_DEFS = [
     },
     {
         name: "get_memecoin_launches",
-        description: "Get recently launched memecoin pairs screened by age, liquidity, volume, and transaction count.",
+        description: "Get recently launched tokens from recognized memecoin launchpads, screened by age, liquidity, volume, and transactions. Generic new DEX pairs are excluded; response includes complete/partial chain coverage.",
         schema: memecoinLaunchesSchema,
         apiPath: "/api/v1/memecoins/launches",
         fallbackPath: "/api/memecoins/launches",
     },
     {
         name: "get_stablecoins",
-        description: "Get stablecoin overview, detail, or yield data including market cap, peg deviation, mechanism mix, and chain supply. Requires API key (SHARPE_API_KEY) — not available on the free tier.",
+        description: "Get stablecoin overview, detail, or yield data including nominal supply at peg, marked value, nullable peg metrics, mechanism mix, chain supply, velocity coverage, freshness, and APY risk flags. Requires an API key (SHARPE_API_KEY; the free tier works). No keyless fallback.",
         schema: stablecoinsSchema,
         apiPath: "/api/v1/stablecoins/data",
         fallbackPath: "/api/v1/stablecoins/data",
@@ -747,63 +1032,65 @@ export const TOOL_DEFS = [
     },
     {
         name: "get_web_traffic",
-        description: "Get attention rankings, search trends, social snapshots, or market-level traffic signals for exchanges, coins, and narratives.",
+        description: "Get attention rankings, social snapshots, or market-level signals for coins and narratives, plus CoinGecko trust-score rankings for exchanges.",
         schema: webTrafficSchema,
         apiPath: "/api/v1/web-traffic/data",
         fallbackPath: "/api/web-traffic/data",
     },
-    {
-        name: "get_katana",
-        description: "Get Katana Network TVL, token, holder, sentiment, pool, mover, and ecosystem analytics.",
-        schema: katanaSchema,
-        apiPath: "/api/v1/katana/data",
-        fallbackPath: "/api/products/katana/data",
-    },
     {
         name: "get_news",
-        description: "Get aggregated crypto news articles from multiple sources, with optional filtering by category or coin. Articles are deduplicated so only the best source per story is shown.",
+        description: "Get aggregated crypto news articles from multiple sources, with optional title search and filtering by category or coin. Articles are deduplicated so only the best source per story is shown.",
         schema: newsSchema,
         apiPath: "/api/v1/news/feed",
         fallbackPath: "/api/news/feed",
     },
-    {
-        name: "get_curated_news",
-        description: "Get AI-curated crypto news highlights across crypto, AI, markets, and geopolitics. Updated every 15 minutes.",
-        schema: curatedNewsSchema,
-        apiPath: "/api/v1/news/curated",
-        fallbackPath: "/api/news/curated",
-    },
     {
         name: "get_market_overview",
-        description: "Get a broad market overview including total market cap, 24h volume, BTC dominance, top gainers/losers, and trending coins.",
+        description: "Get BTC and ETH price/change, total crypto market cap and 24h volume, BTC dominance, market-cap change, and the Fear & Greed Index. Auxiliary source fields may be null when unavailable.",
         schema: marketOverviewSchema,
         apiPath: "/api/v1/tracker/market-overview",
         fallbackPath: "/api/tracker/market-overview",
     },
     {
         name: "get_price_prediction",
-        description: "Get ML-based price prediction data for a specified coin, including predicted price targets and confidence intervals.",
+        description: "Get deterministic directional scores and sub-signal breakdowns for a coin. Optional 7D/30D values are volatility-scaled heuristic scenarios, not calibrated targets or probabilities.",
         schema: pricePredictionSchema,
         apiPath: "/api/v1/price-prediction/data",
         fallbackPath: "/api/price-prediction/data",
     },
     {
         name: "search_market_cap",
-        description: "Search for coins by name or ticker. Returns matching coins with market cap, price, and 24h change.",
+        description: "Search crypto and supported TradFi assets by name or ticker. Returns matching assets with asset class, market cap, and nullable price, 24h change, FDV, ATH, and estimated ATH market cap fields.",
         schema: searchMarketCapSchema,
         apiPath: "/api/v1/market-cap/search",
         fallbackPath: "/api/market-cap/search",
     },
     {
         name: "get_gem_finder",
-        description: "Get a curated list of low-cap, high-potential tokens identified by the gem finder algorithm.",
+        description: "Get market-ranked token rows with market cap, volume, price and market-cap change, circulating supply, ATH and ATL history, nullable FDV/MCap, the preferred chain plus every supported chain the asset is deployed on (chainSlugs), observed exchange availability, quote freshness, and enrichment coverage. Delisted or halted markets whose upstream quote is over 24 hours old are excluded rather than reporting a weeks-old price change as current. Ambiguous same-ticker assets do not receive symbol-only exchange attribution. No wallet signal or proprietary score is returned.",
         schema: gemFinderSchema,
         apiPath: "/api/v1/gem-finder/data",
         fallbackPath: "/api/gem-finder/data",
+        postProcess: (data, args) => {
+            // Authenticated v1 calls are already an array with pagination reattached
+            // by the runtime. The free fallback returns the complete cache payload,
+            // so apply the same snapshot-bound paging semantics client-side.
+            if (!data ||
+                typeof data !== "object" ||
+                Array.isArray(data) ||
+                !Array.isArray(data.coins)) {
+                return data;
+            }
+            const limit = typeof args.limit === "number" && Number.isInteger(args.limit)
+                ? args.limit
+                : 100;
+            const cursor = typeof args.cursor === "string" ? args.cursor : undefined;
+            return paginateSnapshotPayload(data, limit, cursor);
+        },
     },
     {
         name: "get_derivatives_overview",
-        description: "Get a derivatives market overview including aggregated open interest, funding rates, and volume across top perpetual futures exchanges. Requires API key (SHARPE_API_KEY) — not available on the free tier.",
+        description: "Get a derivatives market overview including aggregated open interest, 8-hour-equivalent funding rates, top coins by open interest (each top_coins_oi entry is an asset, its lot spellings included), and exchange/coin counts. Requires an API key (SHARPE_API_KEY; the free tier works). No keyless fallback.",
         schema: derivativesOverviewSchema,
         apiPath: "/api/v1/market/derivatives-overview",
         fallbackPath: "/api/v1/market/derivatives-overview",
@@ -817,21 +1104,21 @@ export const TOOL_DEFS = [
     },
     {
         name: "get_exchange_listings",
-        description: "Get the New Listings hub payload — weekly + monthly aggregated counts by narrative and exchange, plus the last-90-day recent listings. Optionally filter by narrative slug or single exchange. Useful for tracking where venues are adding listing slots.",
+        description: "Get the New Listings hub payload: weekly + monthly aggregated counts by narrative and exchange, plus the last-90-day recent listings. Optionally filter by narrative slug or single exchange. Useful for tracking where venues are adding listing slots.",
         schema: listingsDataSchema,
         apiPath: "/api/v1/listings/data",
         fallbackPath: "/api/listings/data",
     },
     {
         name: "get_recent_listings",
-        description: "Get a flat feed of recent token listings. Defaults remain backward-compatible with the legacy spot listing feed, and optional event filters can narrow by venue type, market type, event type, status, and source confidence.",
+        description: "Get a flat feed of recent token listings. Defaults remain backward-compatible with the legacy spot listing feed. Event filters add source-observation freshness, partial status, and provider coverage so agents can reject incomplete opportunity scans.",
         schema: listingsRecentSchema,
         apiPath: "/api/v1/listings/recent",
         fallbackPath: "/api/listings/recent",
     },
     {
         name: "get_listing_events",
-        description: "Get canonical listing lifecycle events across CEXs and Perp DEXs, including Spot listings, Perp listings, delistings, suspensions, resumptions, scheduled trading starts, source URLs, and source confidence.",
+        description: "Get canonical listing lifecycle events across CEXs and Perp DEXs, including source URLs, confidence, real source-observation freshness, partial status, and per-provider coverage. Pass the opaque cursor through unchanged.",
         schema: listingsEventsSchema,
         apiPath: "/api/v1/listings/events",
         fallbackPath: "/api/listings/events",
@@ -845,14 +1132,14 @@ export const TOOL_DEFS = [
     },
     {
         name: "get_insider_selling",
-        description: "Get insider selling pressure signals across crypto assets. Scores require cross-venue negative funding and combine OI, basis, CVD, sell-side flow, and supporting wallet/supply context.",
+        description: "Get insider selling pressure signals across crypto assets. Scores require cross-venue negative funding and combine OI, basis, CVD, sell-side flow, and supporting wallet/supply context; read signal_coverage_pct because partial-input scores are conservative lower bounds. coin returns one coin's row as the scorer wrote it (score null once it stopped qualifying).",
         schema: signalScoreSchema,
         apiPath: "/api/v1/insider-selling/data",
         fallbackPath: "/api/insider-selling/data",
     },
     {
         name: "get_pump_dump",
-        description: "Get pump-and-dump manipulation risk signals across crypto assets. Scores combine derivatives pressure, holder concentration, liquidity quality, DEX flow, and price behavior.",
+        description: "Get pump-and-dump manipulation risk signals across crypto assets. Scores combine derivatives pressure, holder concentration, liquidity quality, DEX flow, and price behavior; read signal_coverage_pct because partial-input scores are conservative lower bounds. coin returns one coin's row as the scorer wrote it (score null once it stopped qualifying).",
         schema: pumpDumpSchema,
         apiPath: "/api/v1/pump-dump/data",
         fallbackPath: "/api/pump-dump/data",