bykaranteli-mcp 0.28.2 → 0.29.0

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, liquidations, options, ETF flows, Fear & Greed and BTC dominance.
 
-47 read-only tools over the public JSON API of [bykaranteli.com](https://bykaranteli.com/developers). Since 2026-09-10 the API asks programs for an account key: a **free key** comes with any verified account at <https://bykaranteli.com/dashboard/api> (30 requests a minute, public depth), and the Builder, Business and Scale plans raise the rate and unlock member depth (LiqMap on seven timeframes, 5-minute series, the x402 catalog included). Set it as `BYKARANTELI_API_KEY`. Data covers Binance USDT-M perpetuals (funding arbitrage additionally compares OKX, Bybit, Gate, HTX, BingX, Kraken, MEXC and Bitget).
+49 read-only tools over the public JSON API of [bykaranteli.com](https://bykaranteli.com/developers). Since 2026-09-10 the API asks programs for an account key: a **free key** comes with any verified account at <https://bykaranteli.com/dashboard/api> (30 requests a minute, public depth), and the Builder, Business and Scale plans raise the rate and unlock member depth (LiqMap on seven timeframes, 5-minute series, the x402 catalog included). Set it as `BYKARANTELI_API_KEY`. Data covers Binance USDT-M perpetuals; funding arbitrage, liquidations, order book depth, options, positioning and insurance funds add the other venues each board lists on bykaranteli.com/coverage.
 
 ## Hosted endpoint (no install)
 
 Paste `https://mcp.bykaranteli.com` as a custom connector in any MCP-capable
-assistant. Same 47 tools, nothing to install. Without a key it runs on the
+assistant. Same 49 tools, nothing to install. Without a key it runs on the
 shared Free pool; a connector header with your account key, `x-api-key: bk_...`
 (claude.ai custom connectors) or `Authorization: Bearer bk_...` (Builder and
 above), brings your own rate limit and member depth.
@@ -52,6 +52,8 @@ Requires Node.js 18 or newer.
 | `get_pressure_scores` | "Which coins are over-leveraged / crowded right now?" |
 | `get_top_movers` | "Biggest OI spikes today?", "Most extreme funding right now?" |
 | `get_liquidations` | "How much was liquidated today?", "Did longs or shorts get flushed this week?" |
+| `get_liquidation_leaderboard` | "What was the biggest liquidation today?", "When do liquidations cluster, Asia or US hours?" |
+| `get_insurance_funds` | "How big is the Binance insurance fund?", "Did any exchange insurance fund shrink this week?" |
 | `get_etf_flows` | "Did the Bitcoin ETFs buy or sell yesterday?", "Cumulative ETH ETF inflow?" |
 | `get_cot_positioning` | "Are hedge funds long or short Bitcoin?", "What did the COT report show?" |
 | `get_options_snapshot` | "Where are the BTC option walls?", "What is DVOL / the zero-gamma level?" |

package/dist/tools.js

@@ -153,7 +153,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, 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.",
+        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 stream collectors on every liquidation venue it counts, listed on bykaranteli.com/coverage (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()
@@ -313,7 +313,7 @@ export function registerByKaranteliTools(server, options) {
     });
     server.registerTool("get_funding_arbitrage", {
         title: "Cross-exchange funding arbitrage opportunities",
-        description: "Call this when the user asks about funding arbitrage, funding rate differences between exchanges, or delta-neutral carry trades. Compares funding across Binance, OKX, Bybit, Gate, HTX and BingX for 12 major perps and returns the best long/short venue per symbol with gross and net annualized APR (net of taker fees and weekly rebalance cost).",
+        description: "Call this when the user asks about funding arbitrage, funding rate differences between exchanges, or delta-neutral carry trades. Compares funding across every venue on the board, from Binance, OKX and Bybit to Hyperliquid, dYdX and the smaller perp venues fed by the venue snapshot, for 12 major perps and returns the best long/short venue per symbol with gross and net annualized APR (net of taker fees and weekly rebalance cost).",
         inputSchema: {},
         annotations: READ_ONLY,
     }, async () => {
@@ -407,12 +407,15 @@ export function registerByKaranteliTools(server, options) {
     });
     server.registerTool("get_options_snapshot", {
         title: "Options walls, gamma exposure and DVOL (BTC + ETH)",
-        description: "Call this when the user asks where the big options bets sit, about call/put walls, gamma exposure (GEX), the zero-gamma level, implied volatility (DVOL) or the IV term structure for Bitcoin or Ethereum. Daily snapshot of listed crypto options: top strikes by open interest, put/call ratio, dealer hedging map and ATM IV by expiry.",
-        inputSchema: {},
+        description: "Call this when the user asks where the big options bets sit, about call/put walls, gamma exposure (GEX), the zero-gamma level, implied volatility (DVOL) or the IV term structure for Bitcoin or Ethereum, across options venues or on one venue. Daily snapshot of the listed option chains of every options venue we record, summed by default or one venue with venue: top strikes by open interest, put/call ratio, dealer hedging map, ATM IV by expiry and each venue's open interest (venues_included). DVOL is Deribit's index whatever the venue.",
+        inputSchema: {
+            venue: z.enum(["all", "deribit", "bybit", "binance", "okx", "delta"]).optional().describe("all (default) sums every options venue; or one venue id: deribit, bybit, binance, okx or delta (Delta Exchange India)."),
+        },
         annotations: READ_ONLY,
-    }, async () => {
+    }, async ({ venue }) => {
         try {
-            return ok(withProvenance(await fetchJson("/api/public/options"), "/api/public/options"));
+            const path = venue && venue !== "all" ? `/api/public/options?venue=${venue}` : "/api/public/options";
+            return ok(withProvenance(await fetchJson(path), path));
         }
         catch (err) {
             return fail(err);
@@ -496,6 +499,56 @@ export function registerByKaranteliTools(server, options) {
             return fail(err);
         }
     });
+    server.registerTool("get_liquidation_leaderboard", {
+        title: "Largest single liquidations and a 30-day session heatmap (counted venue feeds)",
+        description: "Call this when the user asks for the biggest liquidation today or this week, who got liquidated for the most, the largest single liquidation print, or when in the day or week liquidations cluster (Asia, Europe or US hours, weekday by UTC hour). Returns the largest single liquidation prints of the last 24h, 7d or 30d (rank, symbol, venue, side where SELL means a long was liquidated, price, quantity, notional, millisecond time) recorded from the counted venues' public feeds, plus a 30-day weekday by UTC hour heatmap with hour, weekday and session totals. Binance publishes at most one print per second per symbol, so its rows are a floor.",
+        inputSchema: {
+            window: z.enum(["24h", "7d", "30d"]).optional().describe("Ranking window: 24h (default), 7d or 30d."),
+            limit: z.number().int().min(1).max(100).optional().describe("Rows to return (default 25, max 100)."),
+            days: z.number().int().min(7).max(90).optional().describe("Days folded into the session heatmap (default 30)."),
+        },
+        annotations: READ_ONLY,
+    }, async ({ window, limit, days }) => {
+        try {
+            const params = new URLSearchParams();
+            if (window)
+                params.set("window", window);
+            if (limit)
+                params.set("limit", String(limit));
+            if (days)
+                params.set("days", String(days));
+            const qs = params.toString();
+            const path = `/api/public/liquidation-leaderboard${qs ? `?${qs}` : ""}`;
+            return ok(withProvenance(await fetchJson(path), path));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool("get_insurance_funds", {
+        title: "Exchange insurance funds: size, 24h and 7d change, fund against open interest, daily history",
+        description: "Call this when the user asks how big an exchange's insurance fund is, whether a fund is shrinking or was used after a crash, how much exchanges hold to absorb bankrupt liquidations, or how a fund compares with the venue's open interest. Returns the latest hourly reading per covered venue (every exchange the insurance fund board lists): the fund in USD (OKX's own published total, the sum of priced pools elsewhere), per asset, 24h and 7d change, the fund as a percent of the venue's perpetual open interest on the coins ByKaranteli tracks, and daily closes per venue. Set pools to include every pool row (the contracts it covers, asset, balance, USD). A fund is a balance the venue reports, not an audit of its reserves.",
+        inputSchema: {
+            venue: z.enum(["binance", "bybit", "okx", "gate"]).optional().describe("One venue; omit for every covered venue."),
+            history_days: z.number().int().min(1).max(366).optional().describe("Days of daily closes (default 30, max 366)."),
+            pools: z.boolean().optional().describe("Include every pool row (large for Binance and Bybit). Default false."),
+        },
+        annotations: READ_ONLY,
+    }, async ({ venue, history_days, pools }) => {
+        try {
+            const params = new URLSearchParams();
+            if (venue)
+                params.set("venue", venue);
+            params.set("days", String(history_days ?? 30));
+            if (!pools)
+                params.set("pools", "0");
+            const path = `/api/public/insurance-funds?${params.toString()}`;
+            return ok(withProvenance(await fetchJson(path), path));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
     server.registerTool("get_open_interest", {
         title: "Intraday open interest and leverage regimes (10 major perps)",
         description: "Call this when the user asks whether leverage is entering or leaving the market, about open interest changes, or whether longs or shorts are building in a major coin. Returns 5-minute-resolution OI with 24h OI and price deltas and a four-regime read per symbol: longs building, shorts building, long squeeze, short squeeze, or quiet.",
@@ -763,7 +816,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.",
+        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 every exchange the hourly scan covers.",
         inputSchema: { days: z.number().int().min(1).max(30).optional().describe("Window in days, 1-30 (default 30). Longer listing history is the listings dataset at bykaranteli.com/data.") },
         annotations: READ_ONLY,
     }, async (args) => {
@@ -805,7 +858,7 @@ export function registerByKaranteliTools(server, options) {
     });
     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 LiqMap snapshot for one symbol: modeled liquidation levels by price, zone aggregates and real liquidation prints from six venues. Without an account key (or on the Free plan) the 24h view; with a Builder or higher key (BYKARANTELI_API_KEY) every timeframe from 1h to 30d.",
+        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 LiqMap snapshot for one symbol: modeled liquidation levels by price, zone aggregates and real liquidation prints from every liquidation venue ByKaranteli counts (listed on bykaranteli.com/coverage). Without an account key (or on the Free plan) the 24h view; with a Builder or higher key (BYKARANTELI_API_KEY) every timeframe from 1h to 30d.",
         inputSchema: {
             symbol: z
                 .string()
@@ -934,8 +987,8 @@ export function registerByKaranteliTools(server, options) {
         }
     });
     server.registerTool("get_positioning", {
-        title: "Positioning: long/short ratios, taker buy/sell and CVD on Binance, Bybit, OKX, Gate, HTX, Bitget",
-        description: "Call this when the user asks about the long/short ratio, whether retail or top traders are net long or short, the taker buy/sell ratio, or CVD (cumulative volume delta) for a perpetual. Returns exchange-published statistics for the 30 most traded Binance USDT perps on Binance, Bybit, OKX, Gate, HTX and Bitget (Binance global and top-trader ratios, Bybit share long, OKX ratios and taker volume, Gate account and top-trader ratios, HTX elite ratios, Bitget account and position ratios) and CVD series for BTC, ETH and SOL; refreshed every 15 minutes.",
+        title: "Positioning: long/short ratios, taker buy/sell and CVD across exchanges",
+        description: "Call this when the user asks about the long/short ratio, whether retail or top traders are net long or short, the taker buy/sell ratio, or CVD (cumulative volume delta) for a perpetual. Returns exchange-published statistics for the 30 most traded Binance USDT perps on every perpetual venue the positioning board records (Binance global and top-trader ratios, Bybit share long, OKX ratios and taker volume, Gate account and top-trader ratios, HTX elite ratios, Bitget account and position ratios) and CVD series for BTC, ETH and SOL; refreshed every 15 minutes.",
         inputSchema: {
             symbol: z.string().trim().toUpperCase().regex(/^[A-Z0-9]{2,24}$/).optional().describe("One Binance symbol, e.g. BTCUSDT"),
         },
@@ -1041,8 +1094,8 @@ export function registerByKaranteliTools(server, options) {
         }
     });
     server.registerTool("get_orderbook_depth", {
-        title: "Spot order book depth: walls and 2% depth across Binance, Coinbase, Kraken, Bybit, OKX",
-        description: "Call this when the user asks where the bid or ask walls are, how deep the spot order book is, whether buyers or sellers have more resting orders near price, or for an order book heatmap. Returns the five venues' books binned into 0.1% buckets within 5% of mid (USD notional), the largest walls with venue split, 2% depth and book reach per venue, and optionally the summed 5-minute history; coins: BTC, ETH, SOL, XRP, DOGE, ADA, LINK, AVAX, LTC, BNB.",
+        title: "Spot order book depth: walls and 2% depth from every spot venue on the coverage page",
+        description: "Call this when the user asks where the bid or ask walls are, how deep the spot order book is, whether buyers or sellers have more resting orders near price, or for an order book heatmap. Returns the books of every spot venue with a public book that the coverage page lists, binned into 0.1% buckets within 20% of mid (USD notional), the largest walls with venue split, 2% depth and book reach per venue, and optionally the summed 5-minute history; coins: BTC, ETH, SOL, XRP, DOGE, ADA, LINK, AVAX, LTC, BNB. Books whose size is not corroborated are recorded and returned per venue with in_aggregate false (listed in held_out) but not summed into the walls, 2% depth or history.",
         inputSchema: {
             symbol: z.string().trim().toUpperCase().regex(/^[A-Z0-9]{2,12}$/).optional().describe("One coin, e.g. BTC (default BTC)"),
             hours: z.number().int().min(1).max(24).optional().describe("Include the summed 5-minute history for this many hours"),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bykaranteli-mcp",
-  "version": "0.28.2",
-  "description": "MCP server for live crypto derivatives data from bykaranteli.com: funding rates, funding arbitrage, open interest pressure, liquidations, options, ETF flows, Fear & Greed and BTC dominance. 47 read-only tools, free account key, paid depth via plans or x402.",
+  "version": "0.29.0",
+  "description": "MCP server for live crypto derivatives data from bykaranteli.com: funding rates, funding arbitrage, open interest pressure, liquidations, options, ETF flows, Fear & Greed and BTC dominance. 49 read-only tools, free account key, paid depth via plans or x402.",
   "type": "module",
   "bin": {
     "bykaranteli-mcp": "dist/index.js"