bykaranteli-mcp 0.25.0 → 0.26.1

package/README.md

@@ -2,19 +2,21 @@
 
 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.
 
@@ -94,6 +97,7 @@ 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
@@ -112,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
@@ -749,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 {
@@ -790,7 +802,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 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.",
+        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.",
         inputSchema: {
             symbol: z
                 .string()
@@ -799,13 +811,17 @@ export function registerByKaranteliTools(server, options) {
                 .regex(/^[A-Z0-9]{2,20}$/)
                 .optional()
                 .describe("Symbol like BTCUSDT (bare BTC accepted). Default BTCUSDT."),
+            timeframe: z
+                .enum(["1h", "4h", "12h", "24h", "3d", "1w", "30d"])
+                .optional()
+                .describe("Model window. Default 24h, the only one served without a Builder or higher key."),
         },
         annotations: READ_ONLY,
-    }, async ({ symbol }) => {
+    }, async ({ symbol, timeframe }) => {
         try {
             const raw = symbol ?? "BTCUSDT";
             const sym = raw.endsWith("USDT") ? raw : `${raw}USDT`;
-            const path = `/api/liqmap/public?symbol=${encodeURIComponent(sym)}&timeframe=24h`;
+            const path = `/api/liqmap/public?symbol=${encodeURIComponent(sym)}&timeframe=${encodeURIComponent(timeframe ?? "24h")}`;
             const data = await fetchJson(path);
             return ok({ ...data, source: `${PUBLIC_URL}/liqmap/${sym.replace(/USDT$/, "").toLowerCase()}` });
         }

package/package.json

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