bykaranteli-mcp 0.24.1 → 0.26.0

package/README.md

@@ -1,20 +1,22 @@
 # bykaranteli-mcp
 
-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.
+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.
 
-48 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).
+45 read-only tools over the public JSON API of [bykaranteli.com](https://bykaranteli.com/developers). Since 2026-09-17 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 48 tools, nothing to install, no key.
+assistant. Same 45 tools, nothing to install. Without a key it runs on the
+shared Free pool; a connector header `Authorization: Bearer bk_...` (Builder
+and above) brings your own rate limit and member depth.
 
 ## Quick start
 
 ### Claude Code
 
 ```bash
-claude mcp add bykaranteli -- npx -y bykaranteli-mcp
+claude mcp add bykaranteli -e BYKARANTELI_API_KEY=bk_... -- npx -y bykaranteli-mcp
 ```
 
 ### Claude Desktop
@@ -26,7 +28,8 @@ Add to `claude_desktop_config.json`:
   "mcpServers": {
     "bykaranteli": {
       "command": "npx",
-      "args": ["-y", "bykaranteli-mcp"]
+      "args": ["-y", "bykaranteli-mcp"],
+      "env": { "BYKARANTELI_API_KEY": "bk_..." }
     }
   }
 }
@@ -34,7 +37,7 @@ Add to `claude_desktop_config.json`:
 
 ### Cursor / other MCP clients
 
-Any stdio MCP client works: command `npx`, args `["-y", "bykaranteli-mcp"]`.
+Any stdio MCP client works: command `npx`, args `["-y", "bykaranteli-mcp"]`, env `BYKARANTELI_API_KEY`.
 
 Requires Node.js 18 or newer.
 
@@ -47,9 +50,6 @@ Requires Node.js 18 or newer.
 | `get_funding_arbitrage` | "Any funding arb opportunities?", "Best venue to long/short BTC for carry?" |
 | `get_pressure_scores` | "Which coins are over-leveraged / crowded right now?" |
 | `get_top_movers` | "Biggest OI spikes today?", "Most extreme funding right now?" |
-| `get_recent_signals` | "How did the signals do in the last 24h?" |
-| `get_symbol_performance` | "Win rate on ETHUSDT over 90 days?" |
-| `get_strategy_leaderboard` | "Which strategies are performing best?" |
 | `get_liquidations` | "How much was liquidated today?", "Did longs or shorts get flushed 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?" |
@@ -97,11 +97,12 @@ All responses are JSON and carry a `generatedAt` timestamp plus a `source` URL t
 
 | Env var | Default | Purpose |
 |---|---|---|
+| `BYKARANTELI_API_KEY` | none | Account key (`bk_...`) sent as `Authorization: Bearer`. Free at <https://bykaranteli.com/dashboard/api>; required for programs from 2026-09-17 |
 | `BYKARANTELI_BASE_URL` | `https://bykaranteli.com` | Override the API host (testing only) |
 
 ## Data notes
 
-- Signal performance is a **live-only** track record: real published signals with SHA-256 receipts, evaluated net of fees, slippage and funding. Never backtests. Verify any signal at [bykaranteli.com/verify](https://bykaranteli.com/verify).
+- The signal engine was retired in September 2026; this server publishes recorded market data only, no trading signals or performance claims.
 - Funding, OI and pressure data refresh every 15 to 30 minutes; indices every 30 minutes.
 - Nothing here is financial advice. See [bykaranteli.com/risk-guide](https://bykaranteli.com/risk-guide).
 
@@ -115,12 +116,20 @@ node dist/index.js   # speaks MCP over stdio
 
 ## License
 
-MIT. Attribution appreciated: "ByKaranteli (bykaranteli.com)".
+Server: MIT. Data: personal and research use with attribution "ByKaranteli (bykaranteli.com)"; commercial use with the Business plan. Licence text: <https://bykaranteli.com/data#license>.
 
-## Paid depth (optional)
+## Plans and paid depth
 
-The 48 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:
-<https://bykaranteli.com/api/x402>
+| Plan | Price | Rate | Depth |
+|---|---|---|---|
+| Free API | $0 | 30 / min | public pages |
+| Builder | $49 / mo | 300 / min | member depth, x402 catalog included |
+| Business | $149 / mo | 1,200 / min | member depth, commercial licence, monthly bulk |
+| Scale | $399 / mo | 3,000 / min | member depth, derived redistribution, daily raw |
+
+Full table: <https://bykaranteli.com/developers#tiers>. For recorded history and
+raw records beyond the live snapshots, bykaranteli.com also exposes pay-per-call
+x402 endpoints for anonymous agents (USDC on Solana or Base, priced per call,
+no account): <https://bykaranteli.com/developers#x402> · machine catalog:
+<https://bykaranteli.com/api/x402>. Builder and higher keys call those routes
+unpaid within their plan limits.

package/dist/tools.d.ts

@@ -15,5 +15,14 @@ export type RegisterOptions = {
     publicUrl?: string;
     /** Version string for the outbound user-agent. */
     version?: string;
+    /** Account API key (bk_...) sent as Authorization: Bearer on every fetch.
+     * Since 2026-09-17 the public API asks programs for one; a free key comes
+     * with any verified account (https://bykaranteli.com/dashboard/api) and paid
+     * plans raise the rate and unlock member depth. Falls back to the
+     * BYKARANTELI_API_KEY environment variable. */
+    apiKey?: string;
+    /** Per-call Authorization value, for hosts that forward their caller's key
+     * (the hosted endpoint). Takes precedence over apiKey when it returns one. */
+    authorizationProvider?: () => string | undefined;
 };
 export declare function registerByKaranteliTools(server: McpServer, options?: RegisterOptions): void;

package/dist/tools.js

@@ -10,6 +10,13 @@ export function registerByKaranteliTools(server, options) {
     const PUBLIC_URL = (options?.publicUrl ?? process.env.BYKARANTELI_PUBLIC_URL ?? "https://bykaranteli.com").replace(/\/+$/, "");
     const USER_AGENT = `bykaranteli-mcp/${options?.version ?? "dev"} (+https://github.com/bykarantelicom/bykaranteli-mcp)`;
     const TIMEOUT_MS = 15_000;
+    const STATIC_KEY = (options?.apiKey ?? process.env.BYKARANTELI_API_KEY ?? "").trim();
+    const authorizationFor = () => {
+        const forwarded = options?.authorizationProvider?.();
+        if (forwarded)
+            return forwarded;
+        return STATIC_KEY ? `Bearer ${STATIC_KEY}` : undefined;
+    };
     // Read-only GET tools over an open-world public API, all of them.
     const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
     /** Invalid tool input (not a network problem): no retry hint in the error. */
@@ -19,9 +26,14 @@ export function registerByKaranteliTools(server, options) {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(new Error(`${path} timed out after ${TIMEOUT_MS / 1000}s`)), TIMEOUT_MS);
         try {
+            const authorization = authorizationFor();
             const res = await fetch(`${BASE_URL}${path}`, {
                 signal: controller.signal,
-                headers: { accept: "application/json", "user-agent": USER_AGENT },
+                headers: {
+                    accept: "application/json",
+                    "user-agent": USER_AGENT,
+                    ...(authorization ? { authorization } : {}),
+                },
             });
             if (!res.ok) {
                 /* Carry the route's own error body (audit P3 #412): "HTTP 400" alone
@@ -43,8 +55,6 @@ export function registerByKaranteliTools(server, options) {
     const PAGE_FOR_STEM = {
         "/borrow-rates": "/borrow",
         "/oi": "/oi-leaderboard",
-        "/recent": "/signals",
-        "/leaderboard": "/strategies",
         "/venues/markets": "/venues",
         "/venues/lead-lag": "/venues",
         "/venues/profile": "/venues",
@@ -379,78 +389,6 @@ export function registerByKaranteliTools(server, options) {
             return fail(err);
         }
     });
-    server.registerTool("get_recent_signals", {
-        title: "Recent closed trading signals with verified outcomes",
-        description: "Call this when the user asks how the ByKaranteli signal engine is doing today, or wants recent closed LONG/SHORT signals with real outcomes (TP1, SL or TIMEOUT) and net basis-point results. Includes a 24h summary (wins, losses, net bps). Every signal is published with a SHA-256 receipt and results are net of fees, slippage and funding; live signals only, never backtests.",
-        inputSchema: {},
-        annotations: READ_ONLY,
-    }, async () => {
-        try {
-            const d = (await fetchJson("/api/public/recent"));
-            return ok({ ...d, source: `${PUBLIC_URL}/signals` });
-        }
-        catch (err) {
-            return fail(err);
-        }
-    });
-    server.registerTool("get_symbol_performance", {
-        title: "Per-symbol signal performance and recent trades",
-        description: "Call this when the user asks how signals performed on a specific coin (win rate, profit factor, net PnL, best/worst trade) or wants that coin's recent closed signals. Data is the live verified track record for one Binance USDT-M perp over a 30, 90 or 180 day window.",
-        inputSchema: {
-            symbol: z.string().describe("The symbol, e.g. BTCUSDT, or a coin name like BTC."),
-            window_days: z
-                .preprocess((v) => (typeof v === "string" && v.trim() !== "" && Number.isFinite(Number(v)) ? Number(v) : v), z.number().int().min(1).max(365))
-                .optional()
-                .describe("Optional lookback window in days, 1 to 365 (the API accepts any integer in that range). Default 90."),
-        },
-        annotations: READ_ONLY,
-    }, async ({ symbol, window_days }) => {
-        try {
-            const want = normalizeSymbol(symbol);
-            const w = window_days ?? 90;
-            let d;
-            try {
-                d = (await fetchJson(`/api/v1/public/symbols/${want}?window=${w}`));
-            }
-            catch (err) {
-                // The API 404s when the symbol has no closed signals in the chosen
-                // window (data-dependent, not an invalid request). Say so plainly.
-                if (err instanceof Error && err.message.includes("HTTP 404")) {
-                    return ok({
-                        symbol: want,
-                        window_days: w,
-                        note: `No closed signals recorded for ${want} in the last ${w} days (or the symbol is not tracked). Try window_days: 180, or check ${PUBLIC_URL}/symbols/${want}.`,
-                    });
-                }
-                throw err;
-            }
-            // daily_points can be long; the stats + recent signals carry the answer.
-            const daily = d.daily_points;
-            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}`,
-            });
-        }
-        catch (err) {
-            return fail(err);
-        }
-    });
-    server.registerTool("get_strategy_leaderboard", {
-        title: "Strategy leaderboard with verified live results",
-        description: "Call this when the user asks which trading strategies are performing best, or wants win rate, profit factor, drawdown and Sharpe per strategy. Rankings are computed from live closed signals only (no backtests), net of fees.",
-        inputSchema: {},
-        annotations: READ_ONLY,
-    }, async () => {
-        try {
-            const d = (await fetchJson("/api/v1/public/leaderboard"));
-            return ok({ ...d, source: `${PUBLIC_URL}/leaderboard` });
-        }
-        catch (err) {
-            return fail(err);
-        }
-    });
     server.registerTool("get_cot_positioning", {
         title: "CME futures positioning (weekly COT report, BTC + ETH)",
         description: "Call this when the user asks how hedge funds or institutions are positioned in Bitcoin or Ethereum, or about the CFTC Commitments of Traders report. Returns net positions in contracts, week-over-week changes, open interest and notable extremes/streaks, from official CFTC data updated every Friday. Note: a large share of hedge fund shorts is the market-neutral basis trade, so the weekly change carries more signal than the level.",
@@ -823,7 +761,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().int().min(1).max(30).optional().describe("Window in days, 1-30 (default 30). Longer listing history is the paid x402 dataset.") },
+        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) => {
         try {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bykaranteli-mcp",
-  "version": "0.24.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.",
+  "version": "0.26.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. Free, no API key.",
   "type": "module",
   "bin": {
     "bykaranteli-mcp": "dist/index.js"