bykaranteli-mcp 0.32.0 → 0.34.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 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.0] - 2026-10-07
+
+67 tools.
+
+### Changed
+
+- `get_series`: `metric` accepts `funding_agg`, the 8h funding rate weighted by open interest across every perp venue the 10-minute venue recorder reports (the SuperChart's all-venue funding pane); the description names it next to the single-venue `funding`.
+
+## [0.33.0] - 2026-10-07
+
+67 tools.
+
+### Added
+
+- Provenance: every answer whose route has a chart twin carries `chart_url` (the SuperChart address that opens on the same symbol, period and layers) and `chart_image_url` (a 1200 x 630 PNG of that view) next to `source_page` and `api_path`. Routes with a twin: series, the liquidation map and liquidation routes, options, funding and the funding heatmap, open interest, positioning, ETF flows and Hyperliquid whales.
+
 ## [0.32.0] - 2026-10-06
 
 67 tools.

package/dist/provenance.d.ts

@@ -2,6 +2,10 @@ export declare const PROOF_URL = "https://bykaranteli.com/proof";
 export type ProvenanceCoverage = "full" | "sampled" | "mixed";
 export type Provenance = {
     source_page: string;
+    /** The SuperChart address that opens on what this answer holds, when the route has a chart twin (2026-10-07). */
+    chart_url?: string;
+    /** A PNG of that chart view (1200 x 630, candles, heatmap, prints), for clients that show images. */
+    chart_image_url?: string;
     api_path: string;
     /** The answer's own timestamp (generatedAt, generated_at, as_of); null when the route does not stamp one. */
     generated_at: string | null;
@@ -15,6 +19,7 @@ export type Provenance = {
 };
 /** The site page a route's numbers are shown on. */
 export declare function pageForApiPath(path: string): string;
+export declare function chartUrlForApiPath(path: string): string | null;
 export declare function buildProvenance(data: unknown, at: {
     apiPath: string;
     sourcePage: string;

package/dist/provenance.js

@@ -50,6 +50,43 @@ function venueId(item) {
     const id = str(item.exchange) ?? str(item.venue_id) ?? str(item.id) ?? str(item.key) ?? str(item.venue);
     return id && VENUE_TOKEN.test(id) ? id : undefined;
 }
+/* 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. */
+const CHART_BASE = "https://bykaranteli.com/chart";
+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`;
+}
+export function chartUrlForApiPath(path) {
+    const [clean, query = ""] = path.split("?");
+    const q = new URLSearchParams(query);
+    const s = chartSymbol(q);
+    if (clean === "/api/series" || clean.startsWith("/api/series/")) {
+        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`;
+    }
+    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`;
+    }
+    if (clean.startsWith("/api/public/options"))
+        return `${CHART_BASE}?s=${s}&panes=oi&lv=1&heat=1&pr=0`;
+    if (clean.startsWith("/api/public/funding") || clean.startsWith("/api/public/heatmap"))
+        return `${CHART_BASE}?s=${s}&panes=funding,oi&heat=1&pr=0`;
+    if (clean.startsWith("/api/public/oi"))
+        return `${CHART_BASE}?s=${s}&panes=oi,funding&heat=1&pr=0`;
+    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`;
+    if (clean.startsWith("/api/public/hyperliquid-whales"))
+        return `${CHART_BASE}?s=${s}&panes=whale_net,oi&heat=1&pr=1`;
+    return null;
+}
 export function buildProvenance(data, at) {
     const d = isRec(data) ? data : {};
     const meta = isRec(d.meta) ? d.meta : {};
@@ -115,6 +152,7 @@ export function buildProvenance(data, at) {
     const since = str(d.recorded_since) ?? str(d.history_since) ?? str(meta.recorded_since) ?? str(meta.history_since);
     return {
         source_page: at.sourcePage,
+        ...(chartUrlForApiPath(at.apiPath) ? { chart_url: chartUrlForApiPath(at.apiPath), chart_image_url: chartUrlForApiPath(at.apiPath).replace("/chart?", "/api/og/chart?") } : {}),
         api_path: at.apiPath,
         generated_at: str(d.generatedAt) ?? str(d.generated_at) ?? str(d.as_of) ?? str(d.asOf) ?? str(meta.generatedAt) ?? str(meta.generated_at) ?? str(meta.as_of) ?? null,
         fetched_at: at.fetchedAt,

package/dist/tools.js

@@ -1296,7 +1296,7 @@ export function registerByKaranteliTools(server, options) {
     /* API contract values the account and series tools use (0.31.0). They mirror the web registries (series metrics,
      * recipe fields, operators, channels and limits); the web test mcp-extra-tools.test.ts fails when they drift, and
      * GET /api/series/metrics lists the metrics with their units and floors at runtime. */
-    const SERIES_METRIC_KEYS = ["price", "volume", "cvd_perp", "cvd_spot", "oi", "funding", "liquidations", "long_short", "top_traders", "rsi", "premium", "etf_flow", "borrow", "whale_net"];
+    const SERIES_METRIC_KEYS = ["price", "volume", "cvd_perp", "cvd_spot", "oi", "funding", "funding_agg", "liquidations", "long_short", "top_traders", "rsi", "premium", "etf_flow", "borrow", "whale_net"];
     const SERIES_METRICS = Object.fromEntries(SERIES_METRIC_KEYS.map((k) => [k, true]));
     const SERIES_PERIODS = ["5m", "15m", "1h", "4h", "1d"];
     const PERIOD_MS = { "5m": 300_000, "15m": 900_000, "1h": 3_600_000, "4h": 14_400_000, "1d": 86_400_000 };
@@ -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, 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 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.`,
         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.32.0",
+  "version": "0.34.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. 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": {