bykaranteli-mcp 0.31.0 → 0.33.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.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.
+
+### Changed
+
+- `get_etf_flows`: `asset` accepts `XRP` next to `BTC`, `ETH` and `SOL` and returns the US spot XRP ETF daily rows (net inflow, total net assets, cumulative inflow since launch, value traded, in USD). The description gives each asset's first day (BTC and ETH since 2025-05-20, SOL since 2025-10-28, XRP since 2026-09-08) instead of one history length for all.
+
 ## [0.31.0] - 2026-09-30
 
 67 tools.

package/README.md

@@ -73,7 +73,7 @@ Requires Node.js 18 or newer.
 | `get_liquidation_leaderboard` | "What was the biggest liquidation today?", "When do liquidations cluster, Asia or US hours?" |
 | `get_insurance_funds` | "How big is the Binance insurance fund?", "Did any exchange insurance fund shrink this week?" |
 | `get_tokenized_stocks` | "How much tokenized Tesla exists onchain?", "Which tokenized stock trades furthest from the real share?", "Which price valued this wrapper's supply?" (`price_source`, `totals.priced_by`) |
-| `get_etf_flows` | "Did the Bitcoin ETFs buy or sell yesterday?", "Cumulative ETH ETF inflow?" |
+| `get_etf_flows` | "Did the Bitcoin ETFs buy or sell yesterday?", "Cumulative ETH ETF inflow?", "XRP ETF flows this week?" |
 | `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?" |
 | `get_coinbase_premium` | "Are US investors buying Bitcoin?", "What does the basis trade pay?" |

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

@@ -242,10 +242,10 @@ export function registerByKaranteliTools(server, options) {
         }
     });
     server.registerTool("get_etf_flows", {
-        title: "US spot Bitcoin and Ethereum ETF daily flows",
-        description: "Call this when the user asks about Bitcoin, Ethereum or Solana spot ETF flows: daily net inflows or outflows, cumulative flow since launch, or total net assets of the US spot ETFs (IBIT, FBTC, ETHA and the rest). Returns one row per finalized US trading day and asset with net inflow, total net assets, cumulative inflow and value traded, all in USD. About 14 months of history.",
+        title: "US spot Bitcoin, Ethereum, Solana and XRP ETF daily flows",
+        description: "Call this when the user asks about Bitcoin, Ethereum, Solana or XRP spot ETF flows: daily net inflows or outflows, cumulative flow since launch, or total net assets of the US spot ETFs (IBIT, FBTC, ETHA, XRPC and the rest). Returns one row per finalized US trading day and asset with net inflow, total net assets, cumulative inflow since launch and value traded, all in USD. History by asset: BTC and ETH since 2025-05-20, SOL since 2025-10-28, XRP since 2026-09-08.",
         inputSchema: {
-            asset: z.enum(["BTC", "ETH", "SOL"]).optional().describe("Filter to one asset (BTC, ETH or SOL, SOL since 2026-09-02). Omit for all."),
+            asset: z.enum(["BTC", "ETH", "SOL", "XRP"]).optional().describe("Filter to one asset (BTC, ETH, SOL or XRP). Omit for all."),
             days: z.number().int().min(1).max(400).optional().describe("How many most recent trading days to return (default 10)."),
         },
         annotations: READ_ONLY,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bykaranteli-mcp",
-  "version": "0.31.0",
+  "version": "0.33.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": {