bykaranteli-mcp 0.34.1 → 0.34.3

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 Notable changes to the `bykaranteli-mcp` package. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Dates are UTC and come from the git tag of each release (the version commit where no tag exists). The tool count is the number of tools the server registers in that release.
 
+## [0.34.3] - 2026-10-08
+
+67 tools.
+
+### Fixed
+
+- `chart_url` of `get_liquidations` and `get_etf_flows` opens the symbol or asset the call filtered on (the dataset path carried no filter, so every link opened BTCUSDT).
+- `chart_url` of `get_options_snapshot` with a venue sets the options levels' own key (`lvv`), not the OI and funding panes' venue (`v`), so the chart draws the same venue's levels the answer reports.
+
+## [0.34.2] - 2026-10-08
+
+67 tools.
+
+### Changed
+
+- Provenance `chart_url`: the venue asked for rides on the link as `v`, a bounded window (`to` plus `limit` bars, or `from` and `to`) as `r=from..to` in unix seconds, and the routes behind `get_liquidations`, `get_etf_flows` and `get_liquidation_cascades` (the dataset and incident routes) now have chart twins too; the liquidation twins open the recorded event marks (`rv=1`).
+- `get_series`: the description says which periods stay member depth on a key (1m, 3m, 5m, 10m) and that the answer names the venue it was read from (`venue`) and every venue a market-wide series sums (`venues`).
+
 ## [0.34.1] - 2026-10-07
 
 67 tools.

package/dist/provenance.js

@@ -52,14 +52,35 @@ function venueId(item) {
 }
 /* Chart block phase 2 (2026-10-07): the SuperChart address that shows what an answer holds, so an agent can hand the
  * reader a chart that opens on the same symbol, period and layers (chart-url-state.ts keys: s, p, panes, heat, pr,
- * lv). Null for routes with no chart twin. The symbol defaults to BTCUSDT when the query names none. */
+ * lv, v, r, rv). Null for routes with no chart twin. The symbol defaults to BTCUSDT when the query names none. Since
+ * 2026-10-08 (the desk's MCP test): the venue asked for rides as v, a bounded window (to plus limit bars, or from
+ * and to) as r=from..to in unix seconds, and the dataset and incident routes have their twins too. */
 const CHART_BASE = "https://bykaranteli.com/chart";
+const CHART_PERIOD_MS = { "1m": 60_000, "3m": 180_000, "5m": 300_000, "10m": 600_000, "15m": 900_000, "30m": 1_800_000, "1h": 3_600_000, "2h": 7_200_000, "4h": 14_400_000, "6h": 21_600_000, "8h": 28_800_000, "12h": 43_200_000, "1d": 86_400_000, "3d": 259_200_000, "1w": 604_800_000, "1M": 2_592_000_000 };
 function chartSymbol(q) {
     const raw = (q.get("symbol") ?? q.get("coin") ?? q.get("currency") ?? q.get("asset") ?? "BTC").toUpperCase().replace(/[^A-Z0-9]/g, "");
     if (!raw)
         return "BTCUSDT";
     return /USDT$|USD$|PERP$/.test(raw) ? raw : `${raw}USDT`;
 }
+/** The venue and the window of the request as chart keys (empty when the request names neither). `venueKey` is the
+ * chart key the venue belongs to: v for the OI and funding panes, lvv for the options levels (2026-10-08). */
+function chartExtras(q, periodMs, venueKey = "v") {
+    let out = "";
+    const venue = (q.get("venue") ?? "").toLowerCase().replace(/[^a-z0-9]/g, "");
+    if (venue && venue !== "all" && (venueKey === "lvv" || venue !== "binance"))
+        out += `&${venueKey}=${venue}`;
+    const toRaw = q.get("to");
+    const fromRaw = q.get("from");
+    const to = toRaw ? Date.parse(toRaw) : NaN;
+    const limit = Number(q.get("limit"));
+    let from = fromRaw ? Date.parse(fromRaw) : NaN;
+    if (!Number.isFinite(from) && Number.isFinite(to) && Number.isFinite(limit) && limit > 0 && periodMs > 0)
+        from = to - limit * periodMs;
+    if (Number.isFinite(from) && Number.isFinite(to) && to > from)
+        out += `&r=${Math.floor(from / 1000)}..${Math.floor(to / 1000)}`;
+    return out;
+}
 export function chartUrlForApiPath(path) {
     const [clean, query = ""] = path.split("?");
     const q = new URLSearchParams(query);
@@ -68,23 +89,24 @@ export function chartUrlForApiPath(path) {
         const metric = (q.get("metric") ?? "price").toLowerCase();
         const period = q.get("period") ?? "1h";
         const panes = metric === "price" || metric === "volume" ? "" : `&panes=${encodeURIComponent(metric)}`;
-        return `${CHART_BASE}?s=${s}&p=${encodeURIComponent(period)}${panes}&heat=1&pr=1`;
+        return `${CHART_BASE}?s=${s}&p=${encodeURIComponent(period)}${panes}${chartExtras(q, CHART_PERIOD_MS[period] ?? 0)}&heat=1&pr=1`;
     }
-    if (clean.startsWith("/api/liqmap/") || clean.startsWith("/api/public/liqmap") || clean.startsWith("/api/public/liquidations") || clean.startsWith("/api/public/liquidation-cascades")) {
-        return `${CHART_BASE}?s=${s}&panes=liquidations,oi&heat=1&pr=1`;
+    const x = chartExtras(q, 0);
+    if (clean.startsWith("/api/liqmap/") || clean.startsWith("/api/public/liqmap") || clean.startsWith("/api/public/liquidations") || clean.startsWith("/api/public/liquidation-cascades") || clean.startsWith("/api/v1/public/datasets/liquidation") || clean === "/api/public/incidents") {
+        return `${CHART_BASE}?s=${s}&panes=liquidations,oi&heat=1&pr=1&rv=1${x}`;
     }
     if (clean.startsWith("/api/public/options"))
-        return `${CHART_BASE}?s=${s}&panes=oi&lv=1&heat=1&pr=0`;
+        return `${CHART_BASE}?s=${s}&panes=oi&lv=1&heat=1&pr=0${chartExtras(q, 0, "lvv")}`;
     if (clean.startsWith("/api/public/funding") || clean.startsWith("/api/public/heatmap"))
-        return `${CHART_BASE}?s=${s}&panes=funding,oi&heat=1&pr=0`;
+        return `${CHART_BASE}?s=${s}&panes=funding,oi&heat=1&pr=0${x}`;
     if (clean.startsWith("/api/public/oi"))
-        return `${CHART_BASE}?s=${s}&panes=oi,funding&heat=1&pr=0`;
+        return `${CHART_BASE}?s=${s}&panes=oi,funding&heat=1&pr=0${x}`;
     if (clean.startsWith("/api/public/positioning") || clean.startsWith("/api/public/long-short"))
-        return `${CHART_BASE}?s=${s}&panes=long_short,top_traders&heat=0&pr=0`;
-    if (clean.startsWith("/api/public/etf"))
-        return `${CHART_BASE}?s=${s}&p=1d&panes=etf_flow&heat=0&pr=0`;
+        return `${CHART_BASE}?s=${s}&panes=long_short,top_traders&heat=0&pr=0${x}`;
+    if (clean.startsWith("/api/public/etf") || clean.startsWith("/api/v1/public/datasets/etf"))
+        return `${CHART_BASE}?s=${s}&p=1d&panes=etf_flow&heat=0&pr=0${x}`;
     if (clean.startsWith("/api/public/hyperliquid-whales"))
-        return `${CHART_BASE}?s=${s}&panes=whale_net,oi&heat=1&pr=1`;
+        return `${CHART_BASE}?s=${s}&panes=whale_net,oi&heat=1&pr=1&hw=1${x}`;
     return null;
 }
 export function buildProvenance(data, at) {

package/dist/tools.js

@@ -234,7 +234,7 @@ export function registerByKaranteliTools(server, options) {
                     ? `rows is capped at ${MAX_ROWS} of ${filtered.length} matching rows (largest first). Use summary.totals and summary.by_date for complete figures, or pass a symbol filter. ` + baseNote
                     : baseNote,
                 source: `${PUBLIC_URL}/liquidations`,
-                provenance: provenanceFor(d, "/api/v1/public/datasets/liquidations-daily.json", "/liquidations"),
+                provenance: provenanceFor(d, `/api/v1/public/datasets/liquidations-daily.json${wantSymbol ? `?symbol=${wantSymbol}` : ""}`, "/liquidations"),
             });
         }
         catch (err) {
@@ -273,7 +273,7 @@ export function registerByKaranteliTools(server, options) {
                 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`,
-                provenance: provenanceFor(d, "/api/v1/public/datasets/etf-flows.json", "/etf"),
+                provenance: provenanceFor(d, `/api/v1/public/datasets/etf-flows.json${asset ? `?asset=${asset}` : ""}`, "/etf"),
             });
         }
         catch (err) {
@@ -1390,7 +1390,7 @@ export function registerByKaranteliTools(server, options) {
     /* ---- 0.31.0: recorded series, alert text, alert recipes, watchlists ---- */
     server.registerTool("get_series", {
         title: "Recorded series: bars or points of one metric for one perpetual (price, OI, funding, CVD, liquidations, long/short, RSI and more)",
-        description: `Call this when the user wants the history of one recorded metric for one perpetual as a time series: price candles, volume, perp or spot CVD, open interest, funding (one venue, or OI-weighted across every venue as funding_agg), liquidations, long/short ratios, RSI, the Coinbase premium, US spot ETF flows, borrow rates or Hyperliquid whale net flow, for charting, backtesting or "what did X do over the last N days". Returns the /api/series answer (points as [t, v], or [t, o, h, l, c, v] for price, with unit, kind, source and source_kind, the bars served and whether member depth applied) plus provenance. metric is one of: ${SERIES_METRIC_KEYS.join(", ")} (unit, finest period and venue support of each: https://bykaranteli.com/api/series/metrics). Public depth serves fewer bars and no 5m bars; a Builder key and above get member depth; the bar limits are in the same list. Pass from and to (ISO) for a window, or limit for the newest bars.`,
+        description: `Call this when the user wants the history of one recorded metric for one perpetual as a time series: price candles, volume, perp or spot CVD, open interest, funding (one venue, or OI-weighted across every venue as funding_agg), liquidations, long/short ratios, RSI, the Coinbase premium, US spot ETF flows, borrow rates or Hyperliquid whale net flow, for charting, backtesting or "what did X do over the last N days". Returns the /api/series answer (points as [t, v], or [t, o, h, l, c, v] for price, with unit, kind, source and source_kind, the bars served and whether member depth applied) plus provenance. metric is one of: ${SERIES_METRIC_KEYS.join(", ")} (unit, finest period and venue support of each: https://bykaranteli.com/api/series/metrics). Public depth serves fewer bars and no bars under 15 minutes (1m, 3m, 5m, 10m); a Builder key and above get member depth; the bar limits are in the same list. The answer names the venue it was read from (venue) and every venue a market-wide series sums (venues). Pass from and to (ISO) for a window, or limit for the newest bars.`,
         inputSchema: {
             metric: z.string().describe("string, metric key, e.g. price, oi, funding, liquidations (list: /api/series/metrics)"),
             symbol: z.string().optional().describe("string, optional Binance USDT-M perp or coin, e.g. BTCUSDT or BTC (default BTCUSDT)"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bykaranteli-mcp",
-  "version": "0.34.1",
+  "version": "0.34.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. 67 read-only and account tools (the alert and watchlist tools act on your own account), free account key, paid depth via plans or x402.",
   "type": "module",
   "bin": {