bykaranteli-mcp 0.28.1 → 0.28.3

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).
+48 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).
 
 ## 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 48 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,7 @@ 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_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

@@ -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 () => {
@@ -496,6 +496,32 @@ 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_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.",
@@ -934,8 +960,8 @@ export function registerByKaranteliTools(server, options) {
         }
     });
     server.registerTool("get_positioning", {
-        title: "Positioning: long/short ratios, taker buy/sell and CVD on Binance, Bybit, OKX",
-        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 (Binance global and top-trader ratios, Bybit share long, OKX ratios and taker volume) and CVD series for BTC, ETH and SOL; refreshed every 15 minutes.",
+        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.",
         inputSchema: {
             symbol: z.string().trim().toUpperCase().regex(/^[A-Z0-9]{2,24}$/).optional().describe("One Binance symbol, e.g. BTCUSDT"),
         },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bykaranteli-mcp",
-  "version": "0.28.1",
-  "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.28.3",
+  "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. 48 read-only tools, free account key, paid depth via plans or x402.",
   "type": "module",
   "bin": {
     "bykaranteli-mcp": "dist/index.js"