bykaranteli-mcp 0.9.0 → 0.9.1

package/README.md

@@ -2,12 +2,12 @@
 
 MCP (Model Context Protocol) server for **live crypto derivatives data**: funding rates, cross-exchange funding arbitrage, open interest pressure, Fear & Greed, BTC dominance and a verified signal track record.
 
-20 read-only tools over the free, no-auth public JSON API of [bykaranteli.com](https://bykaranteli.com/developers). No API key, no account, no rate-limit registration. Data covers Binance USDT-M perpetuals (funding arbitrage additionally compares OKX, Bybit, Gate, HTX and BingX).
+34 read-only tools over the free, no-auth public JSON API of [bykaranteli.com](https://bykaranteli.com/developers). No API key, no account, no rate-limit registration. Data covers Binance USDT-M perpetuals (funding arbitrage additionally compares OKX, Bybit, Gate, HTX, BingX, Kraken, MEXC and Bitget).
 
 ## Hosted endpoint (no install)
 
 Paste `https://mcp.bykaranteli.com` as a custom connector in any MCP-capable
-assistant. Same 23 tools, nothing to install, no key.
+assistant. Same 34 tools, nothing to install, no key.
 
 ## Quick start
 
@@ -62,6 +62,20 @@ Requires Node.js 18 or newer.
 | `get_liquidation_cascades` | "What caused that flush?", "Who got liquidated this week?" |
 | `get_open_interest` | "Is leverage entering the market?", "Are shorts building in XRP?" |
 | `get_psi_charge` | "What liquidity state is the market in?", "Is parked money deploying?" |
+| `get_theme_indices` | "Which crypto narrative is leading: AI, RWA, DePIN, memes, L2s, DeFi?" |
+| `get_factor_board` | "Which indicators sit in an unusual band today, and what followed historically?" |
+| `get_venue_markets` | "Total BTC open interest across exchanges?", "What is the DEX share of perp OI?", "Is USDT off peg anywhere?" |
+| `get_lead_lag` | "Does Coinbase or Binance move first?" |
+| `get_iv_surface` | "What is BTC implied vol by expiry?", "Is downside protection expensive (skew)?" |
+| `get_whale_tape` | "Are whales buying or selling right now?" |
+| `get_correlations` | "How correlated is SOL to BTC over 30 days?" |
+| `get_new_listings` | "Which perpetuals were listed this week, and where first?" |
+| `get_macro_liquidity` | "What is the Fed balance sheet / RRP / stablecoin supply doing?" |
+| `get_network_health` | "Bitcoin hashrate, difficulty, fees, mempool right now?" |
+| `get_altseason` | "Is it altseason?", "What is the altcoin season index?" |
+| `get_metric_context` | "Is today's funding extreme historically?", "Where does this reading sit in its distribution?" |
+| `get_quantum_exposure` | "How much Bitcoin is quantum-vulnerable?", "What is the P2PK exposure?" |
+| `get_liqmap` | "Where are the BTC liquidation clusters?", "Where would leveraged longs get liquidated?" |
 
 All responses are JSON and carry a `generatedAt` timestamp plus a `source` URL to the human-readable page. Symbols accept both `BTCUSDT` and bare `BTC`.
 
@@ -91,7 +105,7 @@ MIT. Attribution appreciated: "ByKaranteli (bykaranteli.com)".
 
 ## Paid depth (optional)
 
-The 23 tools above are free and stay free. For recorded history and raw records
+The 34 tools above are free and stay free. For recorded history and raw records
 beyond the live snapshots, bykaranteli.com also exposes pay-per-call x402
 endpoints (USDC on Solana or Base, priced per call, no account):
 <https://bykaranteli.com/developers#x402> · machine catalog:

package/dist/tools.js

@@ -26,7 +26,7 @@ export function registerByKaranteliTools(server, options) {
             if (!res.ok) {
                 /* Carry the route's own error body (audit P3 #412): "HTTP 400" alone
                  * hid the actual reason (unknown metric, bad symbol...). */
-                const body = (await res.text().catch(() => "")).replace(/\s+/g, " ").slice(0, 240);
+                const body = (await res.text().catch(() => "")).replace(/\s+/g, " ").slice(0, 2000);
                 throw new Error(`${path} returned HTTP ${res.status}${body ? `: ${body}` : ""}`);
             }
             return await res.json();
@@ -106,7 +106,7 @@ export function registerByKaranteliTools(server, options) {
     });
     server.registerTool("get_liquidations", {
         title: "Crypto liquidations: daily long/short totals per symbol and exchange",
-        description: "Call this when the user asks how much was liquidated in crypto futures, whether longs or shorts got flushed, or for liquidation history. Returns daily long and short liquidation totals in USD per symbol and exchange, recorded from ByKaranteli's own Binance, Bybit, OKX, Gate and HTX stream collectors (recorded events, a floor, not estimates). One row per finalized UTC day, symbol and exchange; history begins 2026-07-30 and grows daily.",
+        description: "Call this when the user asks how much was liquidated in crypto futures, whether longs or shorts got flushed, or for liquidation history. Returns daily long and short liquidation totals in USD per symbol and exchange, recorded from ByKaranteli's own Binance, Bybit, OKX, Gate, HTX and dYdX stream collectors (recorded events, a floor, not estimates). One row per finalized UTC day, symbol and exchange; history begins 2026-07-30 and grows daily.",
         inputSchema: {
             symbol: z
                 .string()
@@ -209,9 +209,24 @@ export function registerByKaranteliTools(server, options) {
             const d = (await fetchJson("/api/v1/public/datasets/etf-flows.json"));
             const rows = Array.isArray(d.rows) ? d.rows : [];
             const filtered = rows.filter((r) => !asset || String(r.asset) === asset);
+            /* Window by DATE like get_liquidations (audit D14-03): the old row-count
+             * slice could cut one asset's day in half and reported no totals and no
+             * truncation flag, so partial sums read as full ones. */
+            const wantDays = days ?? 10;
+            const dates = [...new Set(filtered.map((r) => String(r.date)))].sort().reverse().slice(0, wantDays);
+            const dateSet = new Set(dates);
+            const windowed = filtered.filter((r) => dateSet.has(String(r.date)));
+            const totals = {};
+            for (const r of windowed) {
+                const a = String(r.asset);
+                totals[a] = (totals[a] ?? 0) + (Number(r.net_inflow_usd) || 0);
+            }
             return ok({
-                rows: filtered.slice(0, (days ?? 10) * (asset ? 1 : 2)),
-                note: "Finalized US trading days only; a positive net_inflow_usd means the funds bought more of the asset than they sold that day.",
+                rows: windowed,
+                window_days: dates.length,
+                window_net_inflow_usd: totals,
+                truncated: dates.length < new Set(filtered.map((r) => String(r.date))).size,
+                note: "Finalized US trading days only; a positive net_inflow_usd means the funds bought more of the asset than they sold that day. window_net_inflow_usd sums the returned window per asset.",
                 source: `${PUBLIC_URL}/etf`,
             });
         }
@@ -377,6 +392,7 @@ export function registerByKaranteliTools(server, options) {
             return ok({
                 ...d,
                 daily_points: Array.isArray(daily) ? daily.slice(-30) : daily,
+                daily_points_truncated: Array.isArray(daily) ? daily.length > 30 : false,
                 source: `${PUBLIC_URL}/symbols/${want}`,
             });
         }
@@ -669,7 +685,7 @@ export function registerByKaranteliTools(server, options) {
     server.registerTool("get_new_listings", {
         title: "New and delisted perpetual contracts",
         description: "Call this when the user asks what new perpetuals were listed, which exchange listed a coin first, or about delistings. Returns listings and delistings across six exchanges from the hourly scan.",
-        inputSchema: { days: z.number().optional().describe("number, optional window in days, default 30") },
+        inputSchema: { days: z.number().int().min(1).max(30).optional().describe("Window in days, 1-30 (default 30). Longer listing history is the paid x402 dataset.") },
         annotations: READ_ONLY,
     }, async (args) => {
         try {
@@ -683,7 +699,7 @@ export function registerByKaranteliTools(server, options) {
     server.registerTool("get_macro_liquidity", {
         title: "Macro liquidity: Fed funds, 10y, balance sheet, RRP, stablecoin supply",
         description: "Call this when the user asks about macro liquidity, the Fed balance sheet, reverse repo, rates or stablecoin supply in relation to crypto. Returns the recorded daily series and latest values.",
-        inputSchema: { days: z.number().optional().describe("number, optional window in days, default 365") },
+        inputSchema: { days: z.number().int().min(1).max(730).optional().describe("Window in days, 1-730 (default 365).") },
         annotations: READ_ONLY,
     }, async (args) => {
         try {
@@ -697,7 +713,7 @@ export function registerByKaranteliTools(server, options) {
     server.registerTool("get_network_health", {
         title: "Bitcoin network health from our own node",
         description: "Call this when the user asks about Bitcoin hashrate, difficulty, fees or mempool congestion. Returns the recorded daily series and latest values measured on ByKaranteli's own node.",
-        inputSchema: { days: z.number().optional().describe("number, optional window in days, default 365") },
+        inputSchema: { days: z.number().int().min(1).max(730).optional().describe("Window in days, 1-730 (default 365).") },
         annotations: READ_ONLY,
     }, async (args) => {
         try {
@@ -708,4 +724,29 @@ export function registerByKaranteliTools(server, options) {
             return fail(err);
         }
     });
+    server.registerTool("get_liqmap", {
+        title: "LiqMap: estimated liquidation clusters with real prints overlaid",
+        description: "Call this when the user asks where liquidation clusters or liquidity pools sit for a perpetual, where leveraged longs/shorts would get liquidated, or for a liquidation heatmap reading. Returns the public LiqMap snapshot for one symbol: modeled liquidation levels by price, zone aggregates and real liquidation prints from six venues. Public tier serves the 24h view; other intervals are a member feature at the source page.",
+        inputSchema: {
+            symbol: z
+                .string()
+                .trim()
+                .toUpperCase()
+                .regex(/^[A-Z0-9]{2,20}$/)
+                .optional()
+                .describe("Symbol like BTCUSDT (bare BTC accepted). Default BTCUSDT."),
+        },
+        annotations: READ_ONLY,
+    }, async ({ symbol }) => {
+        try {
+            const raw = symbol ?? "BTCUSDT";
+            const sym = raw.endsWith("USDT") ? raw : `${raw}USDT`;
+            const path = `/api/liqmap/public?symbol=${encodeURIComponent(sym)}&timeframe=24h`;
+            const data = await fetchJson(path);
+            return ok({ ...data, source: `${PUBLIC_URL}/liqmap/${sym.replace(/USDT$/, "").toLowerCase()}` });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bykaranteli-mcp",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "MCP server for live crypto derivatives data from bykaranteli.com: funding rates, funding arbitrage, open interest pressure, Fear & Greed, BTC dominance and verified signal performance. Free, no API key.",
   "type": "module",
   "bin": {