bykaranteli-mcp 0.30.7 → 0.32.0

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 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.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.
+
+### Added
+
+- `get_options_chain`: the option chain hour by hour from ByKaranteli's own capture of every listed venue: open interest and mark IV per expiry and strike, the change over 1h and 24h, the front expiry's ATM IV path.
+- `get_hl_positions`: the liquidation price map of the largest Hyperliquid accounts per coin, with a comparison against the LiqMap model and an hourly archive.
+- `get_venue_share`: each counted exchange's share of the recorded liquidations and of perpetual open interest over 1, 7 or 30 days.
+- `get_tradfi_gaps`: stock, index and commodity perpetuals against the cash close over weekends and nights, checkpoint by checkpoint, with the realised open gap.
+- Account tools for Hyperliquid address tracking (Terminal and above): `list_tracked_addresses`, `add_tracked_address`, `remove_tracked_address`.
+- OAuth 2.1 sign-in on the hosted endpoint: the client registers itself, the user approves once, the token runs on the account's own key; the key path stays.
+
+- `get_series`: the recorded series of one metric for one perpetual (price candles, volume, perp and spot CVD, open interest, funding, liquidations, long/short ratios, RSI, Coinbase premium, ETF flows, borrow rates, Hyperliquid whale net), by period, window (`from`, `to`) or newest bars, on another venue for price, OI, funding and borrow; `/api/series`, metric list at `/api/series/metrics`.
+- Account tools that act on your own account with your key: `list_alert_recipes`, `create_alert_recipe`, `delete_alert_recipe`, `list_watchlists`, `add_watchlist_symbol`, `remove_watchlist_symbol`. The four that change something are annotated `readOnlyHint: false` (the two that remove, `destructiveHint: true`), count on the key's plan, are rate limited per key and recorded on the account; the plan's recipe limit comes back as the tool answer.
+- `parse_alert_text`: a sentence such as "BTC funding above 0.05%" or "tell me when ETH drops 5% in a day" becomes the recipe it describes, with a confidence, a summary and what the text left open; rule based, saves nothing, never invents a threshold.
+- A `provenance` block on every market answer: source page, API path, the answer's own timestamp, fetch time, and when the answer carries them the venues, `full`, `sampled` or `mixed` coverage, stale feeds and first recorded day, plus the proof page.
+
+### Changed
+
+- The README plan table leaves prices to <https://bykaranteli.com/pricing>, and the x402 catalog is included in the monthly fair use of Builder and above (each call counts as 10 requests) instead of a separate monthly allowance.
+
+## [0.30.8] - 2026-09-30
+
+52 tools.
+
+### Added
+
+- `get_market_profile`: the daily TPO Market Profile of a Binance USDT-M perpetual from ByKaranteli's own minute bars (point of control, 70% value area, first-hour initial balance, volume point of control, naked points of control of the last 60 recorded days, the latest day's profile per bucket); `/api/public/market-profile`.
+
 ## [0.30.7] - 2026-09-30
 
 51 tools.

package/README.md

@@ -2,12 +2,12 @@
 
 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.
 
-51 read-only tools over the public JSON API of [bykaranteli.com](https://bykaranteli.com/developers). Since 2026-09-10 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 and 15,000 a month, public depth), and the Builder, Business and Scale plans raise the rate and the monthly fair use and unlock member depth (LiqMap on seven timeframes, 5-minute series, a monthly x402 catalog allowance). Set it as `BYKARANTELI_API_KEY`. Data covers Binance USDT-M perpetuals; funding arbitrage, liquidations, order book depth, options, positioning and insurance funds add the other venues each board lists on bykaranteli.com/coverage.
+67 read-only and account tools over the public JSON API of [bykaranteli.com](https://bykaranteli.com/developers): the market data tools only read, and the alert and watchlist tools act on your own account through your key ([Account tools](#account-tools-alerts-and-watchlist)). Since 2026-09-10 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 and 15,000 a month, public depth), and the Builder, Business and Scale plans raise the rate and the monthly fair use and unlock member depth (LiqMap on seven timeframes, 5-minute series, the x402 catalog included in the monthly fair use). Set it as `BYKARANTELI_API_KEY`. Data covers Binance USDT-M perpetuals; funding arbitrage, liquidations, order book depth, options, positioning and insurance funds add the other venues each board lists on bykaranteli.com/coverage.
 
 ## Hosted endpoint (no install)
 
 Paste `https://mcp.bykaranteli.com` as a custom connector in any MCP-capable
-assistant. Same 51 tools, nothing to install. Every tool call needs your
+assistant. The same tools, nothing to install. Every tool call needs your
 account key (free at <https://bykaranteli.com/dashboard/api>); connecting and
 listing the tools work without one. The key travels one of three ways:
 
@@ -18,6 +18,13 @@ listing the tools work without one. The key travels one of three ways:
   send headers (ChatGPT). Treat that address like a password and revoke the key
   if it leaks.
 
+Or sign in with OAuth 2.1 where the client offers it (claude.ai custom
+connectors: Authentication, Sign in; ChatGPT connectors: OAuth): the client
+registers itself (RFC 7591, PKCE S256), you approve it once on bykaranteli.com
+and it runs on a key of your own account, which the Data and API page lists
+under connected apps. Discovery:
+<https://mcp.bykaranteli.com/.well-known/oauth-protected-resource>.
+
 A free account covers the API and the hosted MCP on one monthly counter;
 Builder and above bring higher rates and member depth.
 
@@ -66,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?" |
@@ -108,15 +115,43 @@ Requires Node.js 18 or newer.
 | `get_metric_context` | "Is today's funding extreme historically?", "Where does this reading sit in its distribution?" |
 | `get_quantum_exposure` | "How much Bitcoin is quantum-vulnerable?", "What is the P2PK exposure?" |
 | `get_liqmap` | "Where are the BTC liquidation clusters?", "Where would leveraged longs get liquidated?" |
+| `get_market_profile` | "Where is the BTC point of control today?", "What was yesterday's value area?", "Which naked POCs are still untested?" |
+| `get_options_chain` | "How did BTC open interest move by strike today?", "Where is ETH ATM IV hour by hour?", "Which expiry gained the most open interest in 24h?" |
+| `get_hl_positions` | "Where do Hyperliquid whales get liquidated on BTC?", "How much tracked notional sits below price?", "Does the model agree with the tracked positions?" |
+| `get_venue_share` | "Which exchange had the most liquidations this week?", "How is perp open interest split by venue?" |
+| `get_tradfi_gaps` | "What did the TSLA perp do over the weekend?", "How big was the Monday open gap on NVDA?", "How far apart were the venues overnight?" |
+| `get_series` | "BTC open interest by hour for the last week?", "ETH funding on OKX since 1 September?", "Daily Coinbase premium this month?" (metric list, units and finest periods: <https://bykaranteli.com/api/series/metrics>) |
+
+All market answers are JSON and carry a `generatedAt` timestamp, a `source` URL to the human-readable page and a `provenance` block: `source_page`, `api_path`, the answer's own `generated_at`, `fetched_at`, and when the answer carries them the `venues` behind the number, `coverage` (`full`, `sampled` or `mixed`), `stale_venues` and `recorded_since`, plus the `proof` page (<https://bykaranteli.com/proof>). A field the answer does not carry is left out, never filled in. Symbols accept both `BTCUSDT` and bare `BTC`.
+
+## Account tools (alerts and watchlist)
 
-All responses are JSON and carry a `generatedAt` timestamp plus a `source` URL to the human-readable page. Symbols accept both `BTCUSDT` and bare `BTC`.
+These tools read and change your own ByKaranteli account with the same key: the alert recipes that notify you on Telegram, email, push or webhook, and your watchlists. They never trade, move funds or touch another account.
+
+| Tool | What it does |
+|---|---|
+| `parse_alert_text` | Turns "BTC funding above 0.05%" or "tell me when ETH drops 5% in a day" into the exact recipe, with a confidence and what the text left open. Rule based; saves nothing, never invents a threshold. |
+| `list_alert_recipes` | Lists your alert recipes with their conditions, scope, channels and when each last fired. |
+| `create_alert_recipe` | Saves an alert recipe (writes to your account). |
+| `delete_alert_recipe` | Deletes one of your alert recipes by id (writes to your account). |
+| `list_watchlists` | Lists your watchlists and the symbols on each. |
+| `add_watchlist_symbol` | Adds a symbol to your default list or the list you name (writes to your account). |
+| `remove_watchlist_symbol` | Removes a symbol from a list (writes to your account). |
+| `list_tracked_addresses` | Lists the Hyperliquid addresses you follow, with their last positions (reads your account). |
+| `add_tracked_address` | Follows a Hyperliquid address for position alerts (writes to your account; Terminal and above). |
+| `remove_tracked_address` | Stops following an address (writes to your account). |
+
+- The write tools carry `readOnlyHint: false` (and `destructiveHint: true` for the two that remove something), so clients that ask before a change will ask.
+- How many recipes an account keeps follows its plan; past it, `create_alert_recipe` answers with the limit instead of saving.
+- Every call counts on the key's plan like any other request; writes are also rate limited per key, and each write is recorded on the account with the key that made it.
+- Recipes and watchlist changes show up at once on <https://bykaranteli.com/dashboard/alerts> and <https://bykaranteli.com/dashboard/watchlist>.
 
 ## Configuration
 
 | 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-10 |
-| `BYKARANTELI_BASE_URL` | `https://bykaranteli.com` | Override the API host (testing only) |
+| `BYKARANTELI_BASE_URL` | `https://bykaranteli.com` | Override the API host (testing only). The key is sent to whatever host this names, so point it only at a server you trust. |
 
 ## Data notes
 
@@ -140,13 +175,15 @@ Server: MIT. Data: personal and research use with attribution "ByKaranteli (byka
 
 ## Plans and paid depth
 
-| Plan | Price | Rate | Monthly | Depth |
-|---|---|---|---|---|
-| Free API | $0 | 30 / min | 15,000 | public pages |
-| Terminal | $29 / mo | 60 / min | 150,000 | public pages |
-| Builder | $49 / mo | 300 / min | 1,000,000 fair use | member depth, 1,000 x402 catalog calls a month |
-| Business | $149 / mo | 1,200 / min | 3,000,000 fair use | member depth, commercial licence, 10,000 x402 catalog calls a month, monthly bulk |
-| Scale | $399 / mo | 3,000 / min | 10,000,000 fair use | member depth, derived redistribution, x402 catalog with no ceiling, daily raw |
+| Plan | Rate | Monthly | Depth |
+|---|---|---|---|
+| Free API | 30 / min | 15,000 | public pages |
+| Terminal | 60 / min | 150,000 | public pages |
+| Builder | 300 / min | 1,000,000 fair use | member depth, x402 catalog included, each call counts as 10 requests of the monthly fair use |
+| Business | 1,200 / min | 3,000,000 fair use | member depth, commercial licence, x402 catalog included, each call counts as 10 requests of the monthly fair use, monthly bulk |
+| Scale | 3,000 / min | 10,000,000 fair use | member depth, derived redistribution, x402 catalog included, each call counts as 10 requests of the monthly fair use, daily raw |
+
+Prices: https://bykaranteli.com/pricing
 
 A Free or Terminal key past its monthly figure gets 429 until
 the month resets. A paid key past its fair use is never stopped: it answers at
@@ -157,6 +194,5 @@ 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 keys call those routes unpaid up to
-1,000 calls a month, Business up to 10,000, Scale with no ceiling; past the
-allowance a key pays per call like an anonymous agent or moves up a plan.
+<https://bykaranteli.com/api/x402>. Builder, Business and Scale keys call those
+routes unpaid; each call counts as 10 requests of the monthly fair use.

package/dist/provenance.d.ts

@@ -0,0 +1,22 @@
+export declare const PROOF_URL = "https://bykaranteli.com/proof";
+export type ProvenanceCoverage = "full" | "sampled" | "mixed";
+export type Provenance = {
+    source_page: 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;
+    fetched_at: string;
+    venues?: string[];
+    /** full: every counted feed is a complete record; sampled: every one is sampled; mixed: both. */
+    coverage?: ProvenanceCoverage;
+    stale_venues?: string[];
+    recorded_since?: string;
+    proof: string;
+};
+/** The site page a route's numbers are shown on. */
+export declare function pageForApiPath(path: string): string;
+export declare function buildProvenance(data: unknown, at: {
+    apiPath: string;
+    sourcePage: string;
+    fetchedAt: string;
+}): Provenance;

package/dist/provenance.js

@@ -0,0 +1,127 @@
+/* Provenance of one tool answer (0.31.0): where it came from, when, from which venues, whether the record behind it
+ * is complete or sampled, and where the proof lives. Read only from fields the API answer already carries
+ * (generatedAt or as_of, venues, sources, coverage kinds, stale feeds, recorded_since or history_since); a field the
+ * answer does not carry is left out, never filled in.
+ *
+ * The same code runs in the hosted bridge as web/src/lib/mcp-provenance.ts; the web test mcp-provenance.test.ts runs
+ * both copies on the same answers and fails when they drift. No imports, so both sides can load it as is. */
+export const PROOF_URL = "https://bykaranteli.com/proof";
+/* API stems whose public page has a different name (2026-09-04 audit: stripping /api/public gave nine tools a source
+ * that 404s on the site). */
+const PAGE_FOR_STEM = {
+    "/borrow-rates": "/borrow",
+    "/oi": "/oi-leaderboard",
+    "/venues/markets": "/venues",
+    "/venues/lead-lag": "/venues",
+    "/venues/profile": "/venues",
+    "/venues/oi-history": "/venues",
+    "/options/surface": "/options",
+    "/context": "/methodology",
+    "/leverage-tiers": "/leverage",
+    "/datasets/etf-flows": "/etf",
+    "/datasets/liquidations-daily": "/liquidations",
+    "/jupiter": "/jupiter-perps",
+    "/market-profile": "/symbols",
+    "/liquidation-leaderboard": "/liquidations",
+};
+/** The site page a route's numbers are shown on. */
+export function pageForApiPath(path) {
+    const clean = path.split("?")[0] || "/";
+    if (clean === "/api/v1/proof" || clean.startsWith("/api/v1/proof/"))
+        return "/proof";
+    if (clean === "/api/series" || clean.startsWith("/api/series/"))
+        return "/chart";
+    const stem = clean.replace(/^\/api\/(?:v1\/)?public/, "").replace(/\.(?:json|csv)$/, "") || "/";
+    return PAGE_FOR_STEM[stem] ?? stem;
+}
+const isRec = (v) => Boolean(v) && typeof v === "object" && !Array.isArray(v);
+const str = (v) => (typeof v === "string" && v.trim() ? v : undefined);
+/* Coverage kinds of the liquidation registry. "delayed" is a complete record that arrives late, so it reads as full;
+ * "shadow" and "none" are feeds we hold but do not count, so they are not a source of the number. */
+const COUNTED_KINDS = new Set(["full", "sampled", "delayed"]);
+const UNCOUNTED_KINDS = new Set(["shadow", "none"]);
+const VENUE_TOKEN = /^[A-Za-z0-9][A-Za-z0-9 ._()-]{0,39}$/;
+const MAX_VENUES = 100;
+function venueId(item) {
+    if (typeof item === "string")
+        return VENUE_TOKEN.test(item) ? item : undefined;
+    if (!isRec(item))
+        return undefined;
+    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;
+}
+export function buildProvenance(data, at) {
+    const d = isRec(data) ? data : {};
+    const meta = isRec(d.meta) ? d.meta : {};
+    const coverageRec = isRec(d.coverage) ? d.coverage : {};
+    const estimate = isRec(d.market_estimate) ? d.market_estimate : {};
+    const venues = [];
+    const kinds = new Set();
+    const stale = [];
+    let staleKnown = false;
+    const addVenue = (id) => {
+        if (!venues.includes(id) && venues.length < MAX_VENUES)
+            venues.push(id);
+    };
+    const addStale = (id) => {
+        if (!stale.includes(id))
+            stale.push(id);
+    };
+    const addList = (list) => {
+        if (!Array.isArray(list))
+            return;
+        for (const item of list.slice(0, 1000)) {
+            const kind = isRec(item) ? str(item.kind) ?? str(item.coverage) : undefined;
+            if (kind && UNCOUNTED_KINDS.has(kind))
+                continue;
+            const id = venueId(item);
+            if (!id)
+                continue;
+            addVenue(id);
+            if (kind && COUNTED_KINDS.has(kind))
+                kinds.add(kind === "delayed" ? "full" : kind);
+            if (isRec(item) && typeof item.stale === "boolean") {
+                staleKnown = true;
+                if (item.stale)
+                    addStale(id);
+            }
+        }
+    };
+    const addStaleList = (list) => {
+        if (!Array.isArray(list))
+            return;
+        staleKnown = true;
+        for (const item of list) {
+            const id = venueId(item);
+            if (id)
+                addStale(id);
+        }
+    };
+    const single = str(d.venue);
+    if (single && VENUE_TOKEN.test(single))
+        addVenue(single);
+    addList(d.venues);
+    addList(d.by_exchange);
+    addList(d.coverage);
+    addList(coverageRec.counted);
+    addList(d.sources);
+    addList(meta.venues);
+    addStaleList(d.stale_venues);
+    addStaleList(coverageRec.stale);
+    addStaleList(estimate.stale_venues);
+    const coverageWord = str(d.coverage);
+    if (coverageWord && COUNTED_KINDS.has(coverageWord))
+        kinds.add(coverageWord === "delayed" ? "full" : coverageWord);
+    const since = str(d.recorded_since) ?? str(d.history_since) ?? str(meta.recorded_since) ?? str(meta.history_since);
+    return {
+        source_page: at.sourcePage,
+        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,
+        ...(venues.length > 0 ? { venues } : {}),
+        ...(kinds.size > 0 ? { coverage: kinds.size > 1 ? "mixed" : kinds.values().next().value } : {}),
+        ...(staleKnown ? { stale_venues: stale } : {}),
+        ...(since ? { recorded_since: since } : {}),
+        proof: PROOF_URL,
+    };
+}

package/dist/tools.js

@@ -5,6 +5,7 @@
  * instance, so all 20 tools have exactly one definition.
  */
 import { z } from "zod/v4";
+import { buildProvenance, pageForApiPath } from "./provenance.js";
 export function registerByKaranteliTools(server, options) {
     const BASE_URL = (options?.baseUrl ?? process.env.BYKARANTELI_BASE_URL ?? "https://bykaranteli.com").replace(/\/+$/, "");
     const PUBLIC_URL = (options?.publicUrl ?? process.env.BYKARANTELI_PUBLIC_URL ?? "https://bykaranteli.com").replace(/\/+$/, "");
@@ -12,9 +13,11 @@ export function registerByKaranteliTools(server, options) {
     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;
+        /* A host that forwards its callers' keys (authorizationProvider) never falls back to a static key: on the
+         * hosted endpoint that fallback would have let every keyless caller act as whatever key the process held
+         * (security review 2026-09-30). The static key is for a local stdio server with one owner. */
+        if (options?.authorizationProvider)
+            return options.authorizationProvider() || undefined;
         return STATIC_KEY ? `Bearer ${STATIC_KEY}` : undefined;
     };
     // Read-only GET tools over an open-world public API, all of them.
@@ -48,26 +51,14 @@ export function registerByKaranteliTools(server, options) {
         }
     }
     /* Every answer carries where it came from and when (README promise; audit
-     * P3 #416): routes that already emit these keep their own values. */
-    /* API stems whose public page has a different name. Stripping /api/public off
-     * the route gave nine tools a `source` that 404s on the site (2026-09-04
-     * audit: /borrow-rates, /oi, /recent, /venues/markets ...). */
-    const PAGE_FOR_STEM = {
-        "/borrow-rates": "/borrow",
-        "/oi": "/oi-leaderboard",
-        "/venues/markets": "/venues",
-        "/venues/lead-lag": "/venues",
-        "/venues/profile": "/venues",
-        "/venues/oi-history": "/venues",
-        "/options/surface": "/options",
-        "/context": "/methodology",
-        "/leverage-tiers": "/leverage",
-        "/datasets/etf-flows": "/etf",
-        "/datasets/liquidations-daily": "/liquidations",
-    };
-    function pageForApiPath(path) {
-        const stem = path.replace(/^\/api\/(?:v1\/)?public/, "").split("?")[0] || "/";
-        return PAGE_FOR_STEM[stem] ?? stem;
+     * P3 #416): routes that already emit these keep their own values. Since
+     * 0.31.0 a provenance block rides along too (src/provenance.ts): source page,
+     * API path, the answer's own timestamp, fetch time, venues, full or sampled
+     * coverage, stale feeds, first recorded day and the proof page, each only
+     * when the answer carries it. The page map (stems whose page has another
+     * name) moved there as well. */
+    function provenanceFor(data, path, page) {
+        return buildProvenance(data, { apiPath: path, sourcePage: `${PUBLIC_URL}${page ?? pageForApiPath(path)}`, fetchedAt: new Date().toISOString() });
     }
     function withProvenance(data, path) {
         if (!data || typeof data !== "object" || Array.isArray(data))
@@ -77,6 +68,7 @@ export function registerByKaranteliTools(server, options) {
             ...record,
             generatedAt: typeof record.generatedAt === "string" ? record.generatedAt : new Date().toISOString(),
             source: typeof record.source === "string" ? record.source : `${PUBLIC_URL}${pageForApiPath(path)}`,
+            provenance: provenanceFor(record, path),
         };
     }
     /* Compact JSON (pretty-printing cost ~35% of the budget) and a hard ceiling:
@@ -149,6 +141,7 @@ export function registerByKaranteliTools(server, options) {
                     }
                     : undefined,
                 source: `${PUBLIC_URL}/indices`,
+                provenance: provenanceFor(d, "/api/public/indices", "/indices"),
             });
         }
         catch (err) {
@@ -241,6 +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"),
             });
         }
         catch (err) {
@@ -248,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,
@@ -279,6 +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"),
             });
         }
         catch (err) {
@@ -307,9 +302,9 @@ export function registerByKaranteliTools(server, options) {
                         note: `${want} is not in the heatmap set. Tracked symbols: ${d.rows.map((r) => r.symbol).join(", ")}`,
                     });
                 }
-                return ok({ generatedAt: d.generatedAt, row, source: `${PUBLIC_URL}/heatmap` });
+                return ok({ generatedAt: d.generatedAt, row, source: `${PUBLIC_URL}/heatmap`, provenance: provenanceFor(d, "/api/public/heatmap") });
             }
-            return ok({ ...d, source: `${PUBLIC_URL}/heatmap` });
+            return ok({ ...d, source: `${PUBLIC_URL}/heatmap`, provenance: provenanceFor(d, "/api/public/heatmap") });
         }
         catch (err) {
             return fail(err);
@@ -323,7 +318,7 @@ export function registerByKaranteliTools(server, options) {
     }, async () => {
         try {
             const d = (await fetchJson("/api/public/funding-arb"));
-            return ok({ ...d, source: `${PUBLIC_URL}/funding-arb` });
+            return ok({ ...d, source: `${PUBLIC_URL}/funding-arb`, provenance: provenanceFor(d, "/api/public/funding-arb") });
         }
         catch (err) {
             return fail(err);
@@ -369,13 +364,14 @@ export function registerByKaranteliTools(server, options) {
                         note: `${want} is not in the tracked pressure universe right now.`,
                     });
                 }
-                return ok({ generatedAt: d.generatedAt, item: slim(item), source: `${PUBLIC_URL}/pressure` });
+                return ok({ generatedAt: d.generatedAt, item: slim(item), source: `${PUBLIC_URL}/pressure`, provenance: provenanceFor(d, "/api/public/pressure") });
             }
             return ok({
                 generatedAt: d.generatedAt,
                 items: d.items.slice(0, limit ?? 20).map(slim),
                 totalTracked: d.items.length,
                 source: `${PUBLIC_URL}/pressure`,
+                provenance: provenanceFor(d, "/api/public/pressure"),
             });
         }
         catch (err) {
@@ -390,7 +386,7 @@ export function registerByKaranteliTools(server, options) {
     }, async () => {
         try {
             const d = (await fetchJson("/api/public/top-movers"));
-            return ok({ ...d, source: `${PUBLIC_URL}/top-movers` });
+            return ok({ ...d, source: `${PUBLIC_URL}/top-movers`, provenance: provenanceFor(d, "/api/public/top-movers") });
         }
         catch (err) {
             return fail(err);
@@ -867,7 +863,7 @@ export function registerByKaranteliTools(server, options) {
     server.registerTool("get_macro_liquidity", {
         title: "Macro liquidity: Fed funds, 10y, balance sheet, RRP, stablecoin supply",
         description: "Call this when the user asks about macro liquidity, the Fed balance sheet, reverse repo, rates or stablecoin supply in relation to crypto. Returns the recorded daily series and latest values.",
-        inputSchema: { days: z.number().int().min(1).max(730).optional().describe("Window in days, 1-730 (default 365).") },
+        inputSchema: { days: z.number().int().min(30).max(4000).optional().describe("Window in days, 30-4000 (default 365); the route clamps to that range.") },
         annotations: READ_ONLY,
     }, async (args) => {
         try {
@@ -881,7 +877,7 @@ export function registerByKaranteliTools(server, options) {
     server.registerTool("get_network_health", {
         title: "Bitcoin network health from our own node",
         description: "Call this when the user asks about Bitcoin hashrate, difficulty or block fees (our node runs blocksonly, so there is no mempool series). Returns the recorded daily series and latest values measured on ByKaranteli's own node.",
-        inputSchema: { days: z.number().int().min(1).max(730).optional().describe("Window in days, 1-730 (default 365).") },
+        inputSchema: { days: z.number().int().min(30).max(4000).optional().describe("Window in days, 30-4000 (default 365); the route clamps to that range.") },
         annotations: READ_ONLY,
     }, async (args) => {
         try {
@@ -915,7 +911,8 @@ export function registerByKaranteliTools(server, options) {
             const sym = raw.endsWith("USDT") ? raw : `${raw}USDT`;
             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()}` });
+            const page = `/liqmap/${sym.replace(/USDT$/, "").toLowerCase()}`;
+            return ok({ ...data, source: `${PUBLIC_URL}${page}`, provenance: provenanceFor(data, path, page) });
         }
         catch (err) {
             return fail(err);
@@ -1115,6 +1112,122 @@ export function registerByKaranteliTools(server, options) {
             return fail(err);
         }
     });
+    server.registerTool("get_market_profile", {
+        title: "Market Profile: daily TPO profile of a perpetual, point of control, value area, initial balance, naked POCs",
+        description: "Call this when the user asks about a perpetual's Market Profile, TPO profile, point of control (POC), value area (VAH, VAL), initial balance or naked (untested) points of control. Returns one row per closed UTC day from ByKaranteli's own one-minute bars of the Binance USDT-M perpetual (30-minute TPO periods, buckets of 0.05% of the day's open, 70% value area, first-hour initial balance, volume point of control), the naked points of control of the last 60 recorded days and the latest day's profile per price bucket. Symbols without recorded minute bars return no_profile.",
+        inputSchema: {
+            symbol: z.string().trim().toUpperCase().regex(/^[A-Z0-9]{2,20}$/).optional().describe("Ticker such as BTC or BTCUSDT (default BTC)"),
+            days: z.number().int().min(1).max(30).optional().describe("Closed UTC days, newest first, 1..30 (default 7)"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ symbol, days }) => {
+        try {
+            const q = new URLSearchParams();
+            q.set("symbol", symbol ?? "BTC");
+            if (days)
+                q.set("days", String(days));
+            const path = `/api/public/market-profile?${q.toString()}`;
+            return ok(withProvenance(await fetchJson(path), path));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool("get_options_chain", {
+        title: "Options chain hour by hour: open interest and IV per expiry and strike, the change over 1h and 24h, the ATM IV path",
+        description: "Call this when the user asks how the BTC or ETH option chain moved today or over the last day: open interest and mark IV per expiry and strike from ByKaranteli's own hourly capture of every listed venue, the change over the last hour and the last 24 hours, and the front expiry's ATM IV hour by hour. Anonymous depth lists the largest strikes; a key with member depth lists every strike. Recorded from 2026-09-30, so the first days carry a short history.",
+        inputSchema: {
+            currency: z.enum(["BTC", "ETH"]).optional().describe("BTC or ETH (default BTC)"),
+            venue: z.enum(["all", "deribit", "bybit", "binance", "okx", "delta"]).optional().describe("One venue or all (default all)"),
+            expiry: z.string().trim().toUpperCase().regex(/^\d{1,2}[A-Z]{3}\d{2}$/).optional().describe("Expiry as DDMONYY, e.g. 31OCT26 (default: every expiry)"),
+            strikes: z.enum(["top", "all"]).optional().describe("top (largest strikes) or all (member depth)"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ currency, venue, expiry, strikes }) => {
+        try {
+            const q = new URLSearchParams();
+            if (currency !== undefined)
+                q.set("currency", String(currency));
+            if (venue !== undefined)
+                q.set("venue", String(venue));
+            if (expiry !== undefined)
+                q.set("expiry", String(expiry));
+            if (strikes !== undefined)
+                q.set("strikes", String(strikes));
+            const qs = q.toString();
+            const path = `/api/public/options/chain${qs ? `?${qs}` : ""}`;
+            return ok(withProvenance(await fetchJson(path), path));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool("get_hl_positions", {
+        title: "Hyperliquid tracked positions: the liquidation price map of the largest accounts per coin, against the LiqMap model",
+        description: "Call this when the user asks where Hyperliquid whales would be liquidated, how much tracked notional sits at each price, how the largest accounts lean on a coin, or how their liquidation prices compare with the LiqMap model. The universe is the largest accounts by equity on Hyperliquid's public leaderboard, scanned every five minutes; the levels are their own liquidation prices bucketed around the mark. hours returns the hourly archive of level totals.",
+        inputSchema: {
+            coin: z.string().trim().toUpperCase().regex(/^[A-Z0-9]{1,24}$/).optional().describe("Coin as Hyperliquid names it, e.g. BTC, ETH, SOL (default BTC)"),
+            hours: z.number().int().min(1).max(720).optional().describe("Hours of archive to return, 1..720 (default 24)"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ coin, hours }) => {
+        try {
+            const q = new URLSearchParams();
+            if (coin !== undefined)
+                q.set("coin", String(coin));
+            if (hours !== undefined)
+                q.set("hours", String(hours));
+            const qs = q.toString();
+            const path = `/api/public/hyperliquid-positions${qs ? `?${qs}` : ""}`;
+            return ok(withProvenance(await fetchJson(path), path));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool("get_venue_share", {
+        title: "Venue share: each counted exchange's share of the recorded liquidations and of perpetual open interest",
+        description: "Call this when the user asks which exchange sees the most liquidations, how that share moved this week or this month, or how perpetual open interest splits between venues. Shares over one, seven or thirty days from ByKaranteli's own hourly liquidation record (counted venues only, each with the day its record started) and the hourly open interest record.",
+        inputSchema: {
+            days: z.number().int().optional().describe("Window in days: 1, 7 or 30 (default 7)"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ days }) => {
+        try {
+            const q = new URLSearchParams();
+            if (days !== undefined)
+                q.set("days", String(days));
+            const qs = q.toString();
+            const path = `/api/public/venue-share${qs ? `?${qs}` : ""}`;
+            return ok(withProvenance(await fetchJson(path), path));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool("get_tradfi_gaps", {
+        title: "Weekend and overnight gaps: stock, index and commodity perpetuals against the cash close, checkpoint by checkpoint",
+        description: "Call this when the user asks what a stock, index or commodity perpetual did over the weekend or overnight while the cash market was closed, how far it sat from the last cash close at each checkpoint, how the venues disagreed, and what gap the next open then realised. From ByKaranteli's own ten-minute venue record; window weekend or night; one symbol or the whole board.",
+        inputSchema: {
+            window: z.enum(["weekend", "night"]).optional().describe("weekend (Friday close to Monday open) or night (cash close to next open); default weekend"),
+            symbol: z.string().trim().toUpperCase().regex(/^[A-Z0-9.]{1,24}$/).optional().describe("One underlying, e.g. TSLA or XAU (default: the whole board)"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ window, symbol }) => {
+        try {
+            const q = new URLSearchParams();
+            if (window !== undefined)
+                q.set("window", String(window));
+            if (symbol !== undefined)
+                q.set("symbol", String(symbol));
+            const qs = q.toString();
+            const path = `/api/public/tradfi-gaps${qs ? `?${qs}` : ""}`;
+            return ok(withProvenance(await fetchJson(path), path));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
     server.registerTool("get_solana_perps", {
         title: "Solana Perps board: open interest, 24h volume and hourly rates across six Solana perpetual venues (Jupiter, Pacifica, Phoenix, GM Trade, Velocity, Bullet)",
         description: "Call this when the user asks about perpetuals on Solana as a whole, which Solana perp DEX has the most open interest or volume, a market on Pacifica, Phoenix, GM Trade (GMX on Solana), Velocity (the Drift relaunch) or Bullet (funding, open interest, 24h volume, mark), or how Jupiter compares with the order-book venues. Returns the board read every 10 minutes: per-venue totals (one-sided open interest, both sides on pool venues, 24h volume, market count, median hourly rate, as_of), every market of every venue largest first with instrument type (perpetual, equity, index, commodity, fx), and optional hourly history of one market on any venue but Jupiter (7 days free, 30 with member depth; Jupiter history is get_jupiter_perps).",
@@ -1180,4 +1293,360 @@ export function registerByKaranteliTools(server, options) {
             return fail(err);
         }
     });
+    /* 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_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 };
+    const SERIES_MEMBER_BAR_LIMIT = 5000;
+    const RECIPE_FIELD_KEYS = ["mark_price", "pressure_score", "funding_rate_pct", "oi24h_pct", "basis_pct", "price_change_24h_pct", "liq_cluster_distance_pct", "usdt_peg_min_usd", "usdc_peg_min_usd", "liq_1h_usd", "rsi_4h", "ls_ratio_global", "book_imbalance_2pct_pct", "withdrawal_paused_venues", "max_leverage_min", "borrow_apr_pct", "hl_whale_long_share_pct"];
+    const RECIPE_OPS = [">=", ">", "<=", "<", "=="];
+    const RECIPE_CHANNELS = ["telegram", "email", "push", "webhook"];
+    const RECIPE_LIMITS = { MAX_CONDITIONS: 6, MAX_SYMBOLS: 20, NAME_MAX: 64 };
+    const ALERT_TEXT_MAX_CHARS = 500;
+    /* GET a market route with provenance, and extra fields the tool adds (get_series' requested window). */
+    async function tool(path, extra) {
+        try {
+            const data = withProvenance(await fetchJson(path), path);
+            return ok(extra && data && typeof data === "object" && !Array.isArray(data) ? { ...data, ...extra } : data);
+        }
+        catch (err) {
+            return fail(err);
+        }
+    }
+    const ACCOUNT_READ = { readOnlyHint: true, openWorldHint: false };
+    const ACCOUNT_WRITE = { readOnlyHint: false, openWorldHint: false, destructiveHint: false, idempotentHint: false };
+    const ACCOUNT_WRITE_IDEMPOTENT = { readOnlyHint: false, openWorldHint: false, destructiveHint: false, idempotentHint: true };
+    const ACCOUNT_DELETE = { readOnlyHint: false, openWorldHint: false, destructiveHint: true, idempotentHint: true };
+    const errorResult = (text) => ({ content: [{ type: "text", text }], isError: true });
+    const okResult = (data) => ({ content: [{ type: "text", text: JSON.stringify(data) }] });
+    const KEY_NEEDED = "This tool reads or changes your own account, so it needs your account key (x-api-key: bk_... or Authorization: Bearer bk_...). Free key: https://bykaranteli.com/dashboard/api";
+    /* One call to a member route with the caller's key. The route's own error (limit reached, unknown id, rate) is passed
+     * through as the tool error so the model can say what happened. */
+    async function account(method, path, body) {
+        const authorization = authorizationFor();
+        if (!authorization)
+            return { ok: false, result: errorResult(KEY_NEEDED) };
+        try {
+            const res = await fetch(`${BASE_URL}${path}`, {
+                method,
+                headers: {
+                    accept: "application/json",
+                    "user-agent": USER_AGENT,
+                    authorization,
+                    ...(body === undefined ? {} : { "content-type": "application/json" }),
+                },
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: AbortSignal.timeout(TIMEOUT_MS),
+            });
+            const text = await res.text();
+            let data = {};
+            try {
+                const parsed = JSON.parse(text);
+                if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+                    data = parsed;
+            }
+            catch {
+                // non-JSON body: the status line below still says what happened
+            }
+            if (!res.ok) {
+                const reason = typeof data.message === "string" ? data.message : typeof data.error === "string" ? data.error : text.replace(/\s+/g, " ").slice(0, 300);
+                return { ok: false, result: errorResult(`${method} ${path.split("?")[0]} returned HTTP ${res.status}: ${reason}`) };
+            }
+            return { ok: true, data };
+        }
+        catch (err) {
+            return { ok: false, result: errorResult(`Failed: ${err instanceof Error ? err.message : String(err)}`) };
+        }
+    }
+    const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    function seriesSymbol(raw) {
+        const s = (typeof raw === "string" && raw.trim() ? raw : "BTCUSDT").trim().toUpperCase().replace(/[\s/_-]+/g, "");
+        const expanded = s.endsWith("USDT") ? s : `${s}USDT`;
+        return /^[A-Z0-9]{5,20}$/.test(expanded) ? expanded : null;
+    }
+    /* The list a symbol goes to: the one named, else "default", else the only list the account has. */
+    async function resolveWatchlist(watchlistId) {
+        const lists = await account("GET", "/api/member/watchlists");
+        if (!lists.ok)
+            return lists;
+        const rows = (Array.isArray(lists.data.watchlists) ? lists.data.watchlists : []);
+        if (typeof watchlistId === "string" && watchlistId.trim()) {
+            const hit = rows.find((w) => w.id === watchlistId.trim());
+            return hit ? { ok: true, list: hit } : { ok: false, result: errorResult(`No watchlist with id ${watchlistId.trim()} on this account. Lists: ${rows.map((w) => `${w.name} (${w.id})`).join(", ") || "none"}.`) };
+        }
+        const pick = rows.find((w) => w.name === "default") ?? (rows.length === 1 ? rows[0] : undefined);
+        if (pick)
+            return { ok: true, list: pick };
+        return {
+            ok: false,
+            result: errorResult(rows.length === 0
+                ? "This account has no watchlist yet. Open https://bykaranteli.com/dashboard/watchlist once to create the default list, then call again."
+                : `Pass watchlist_id: this account has ${rows.length} lists: ${rows.map((w) => `${w.name} (${w.id})`).join(", ")}.`),
+        };
+    }
+    /* ---- 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.`,
+        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)"),
+            period: z.enum(SERIES_PERIODS).optional().describe(`string, optional bar period: ${SERIES_PERIODS.join(" | ")} (default 1h; each metric has a finest period)`),
+            venue: z.string().optional().describe("string, optional venue id for price, oi, funding or borrow, e.g. okx (default binance)"),
+            from: z.string().optional().describe("string, optional ISO start, e.g. 2026-09-01T00:00:00Z"),
+            to: z.string().optional().describe("string, optional ISO end (default now)"),
+            limit: z.number().optional().describe(`number, optional newest bars, 10..${SERIES_MEMBER_BAR_LIMIT}; the key's depth caps it`),
+        },
+        annotations: READ_ONLY,
+    }, async (args = {}) => {
+        const metric = typeof args.metric === "string" ? args.metric.trim().toLowerCase() : "";
+        if (!Object.hasOwn(SERIES_METRICS, metric))
+            return errorResult(`Invalid input: metric must be one of ${SERIES_METRIC_KEYS.join(", ")}.`);
+        const symbol = seriesSymbol(args.symbol);
+        if (!symbol)
+            return errorResult("Invalid input: symbol looks like BTCUSDT or BTC.");
+        const period = (typeof args.period === "string" && SERIES_PERIODS.includes(args.period) ? args.period : "1h");
+        const to = typeof args.to === "string" && args.to.trim() ? new Date(args.to) : null;
+        const from = typeof args.from === "string" && args.from.trim() ? new Date(args.from) : null;
+        if ((to && Number.isNaN(to.getTime())) || (from && Number.isNaN(from.getTime())))
+            return errorResult("Invalid input: from and to are ISO dates, e.g. 2026-09-01T00:00:00Z.");
+        const end = to ?? new Date();
+        if (from && from.getTime() >= end.getTime())
+            return errorResult("Invalid input: from must be before to.");
+        let limit = typeof args.limit === "number" && Number.isFinite(args.limit) && args.limit > 0 ? Math.floor(args.limit) : undefined;
+        const bars = from ? Math.ceil((end.getTime() - from.getTime()) / PERIOD_MS[period]) : undefined;
+        if (bars !== undefined)
+            limit = Math.min(limit ?? bars, bars);
+        if (limit !== undefined)
+            limit = Math.max(10, Math.min(SERIES_MEMBER_BAR_LIMIT, limit));
+        const q = new URLSearchParams({ metric, symbol, period });
+        if (limit !== undefined)
+            q.set("limit", String(limit));
+        if (to)
+            q.set("to", to.toISOString());
+        if (typeof args.venue === "string" && /^[a-z0-9]{2,20}$/i.test(args.venue.trim()))
+            q.set("venue", args.venue.trim().toLowerCase());
+        /* The route answers the newest `limit` bars up to `to`; `requested` lets the caller compare with the bars served. */
+        return tool(`/api/series?${q.toString()}`, from ? { requested: { from: from.toISOString(), to: end.toISOString(), bars } } : undefined);
+    });
+    server.registerTool("parse_alert_text", {
+        title: "Alert text to an alert recipe: turn a sentence like \"BTC funding above 0.05%\" into the recipe it describes",
+        description: `Call this when the user describes an alert in words ("tell me when ETH drops 5% in a day", "BTC funding above 5 bps", "liquidations over $20M in an hour") and you want the exact recipe before creating it. Rule based, nothing is saved: returns recipe (name, scope, symbols, conditions of field, op, value, cooldownHours, channels) or null, confidence 0..1, a one-line summary to confirm with the user, and unresolved (what the text left open or what was assumed; timing words are not part of a recipe). A threshold the text does not state is never invented. English and tickers; at most ${ALERT_TEXT_MAX_CHARS} characters. Pass the returned conditions, scope, symbols and channels to create_alert_recipe once the user agrees.`,
+        inputSchema: {
+            text: z.string().describe("string, the alert in plain English, e.g. \"SOL funding below -0.01% or OI up 10%\""),
+        },
+        annotations: ACCOUNT_READ,
+    }, async (args = {}) => {
+        const text = typeof args.text === "string" ? args.text.trim() : "";
+        if (!text)
+            return errorResult("Invalid input: text is required, e.g. \"BTC funding above 0.05%\".");
+        if (text.length > ALERT_TEXT_MAX_CHARS)
+            return errorResult(`Invalid input: at most ${ALERT_TEXT_MAX_CHARS} characters.`);
+        const r = await account("POST", "/api/member/alert-recipes/parse", { text });
+        return r.ok ? okResult(r.data) : r.result;
+    });
+    server.registerTool("list_alert_recipes", {
+        title: "Your alert recipes: every alert on your account with its conditions, scope, channels and when it last fired",
+        description: "Call this when the user asks which alerts they have, whether an alert fired, or before deleting or changing one. Returns the account's alert recipes (id, name, scope, symbols, conditions, cooldown in hours, enabled, last fired, fire count, channels). Needs the account key; reads nothing but this account.",
+        inputSchema: {},
+        annotations: ACCOUNT_READ,
+    }, async () => {
+        const r = await account("GET", "/api/member/alert-recipes");
+        return r.ok ? okResult({ ...r.data, page: "https://bykaranteli.com/dashboard/alerts" }) : r.result;
+    });
+    server.registerTool("create_alert_recipe", {
+        title: "Create an alert recipe (writes to your account)",
+        description: `Call this when the user asks to be alerted when a metric crosses a threshold and has agreed to the exact condition (parse_alert_text turns their words into one). Saves an alert recipe on the account: it fires when every condition holds, delivers by Telegram first with email as fallback unless channels says otherwise, and waits cooldown_hours before it fires again for the same symbol. field is one of: ${RECIPE_FIELD_KEYS.join(", ")}; op is one of ${RECIPE_OPS.join(" ")}; percent fields take percent values (0.05 means 0.05%). Pass field, op and threshold for one condition, or conditions for up to ${RECIPE_LIMITS.MAX_CONDITIONS}. scope: watchlist (default), any, or symbols with symbols. The plan sets how many recipes an account keeps; past it the tool answers with the limit. Writes are rate limited per key and each one is recorded on the account.`,
+        inputSchema: {
+            field: z.string().optional().describe("string, one condition's metric, e.g. funding_rate_pct"),
+            op: z.enum(RECIPE_OPS).optional().describe(`string, one condition's comparison: ${RECIPE_OPS.join(" | ")}`),
+            threshold: z.number().optional().describe("number, one condition's threshold, e.g. 0.05"),
+            conditions: z.array(z.object({ field: z.string(), op: z.enum(RECIPE_OPS), value: z.number() })).optional().describe(`array, optional up to ${RECIPE_LIMITS.MAX_CONDITIONS} conditions {field, op, value}, all must hold (instead of field, op, threshold)`),
+            scope: z.enum(["watchlist", "any", "symbols"]).optional().describe("string, optional: watchlist (default), any, symbols"),
+            symbols: z.array(z.string()).optional().describe(`array, optional up to ${RECIPE_LIMITS.MAX_SYMBOLS} symbols, e.g. [\"BTCUSDT\", \"ETH\"]; implies scope symbols`),
+            channels: z.array(z.enum(RECIPE_CHANNELS)).optional().describe(`array, optional delivery channels: ${RECIPE_CHANNELS.join(" | ")}; empty means Telegram first, email as fallback`),
+            cooldown_hours: z.number().optional().describe("number, optional 1..168 hours before it fires again (default 24)"),
+            name: z.string().optional().describe("string, optional name; default describes the condition"),
+        },
+        annotations: ACCOUNT_WRITE,
+    }, async (args = {}) => {
+        const rawConds = Array.isArray(args.conditions) && args.conditions.length > 0
+            ? args.conditions
+            : args.field !== undefined || args.threshold !== undefined
+                ? [{ field: args.field, op: args.op, value: args.threshold }]
+                : [];
+        if (rawConds.length === 0)
+            return errorResult("Invalid input: pass field, op and threshold, or conditions.");
+        if (rawConds.length > RECIPE_LIMITS.MAX_CONDITIONS)
+            return errorResult(`Invalid input: at most ${RECIPE_LIMITS.MAX_CONDITIONS} conditions.`);
+        const conditions = [];
+        for (const c of rawConds) {
+            const field = typeof c?.field === "string" ? c.field.trim() : "";
+            const op = typeof c?.op === "string" ? c.op.trim() : "";
+            const value = typeof c?.value === "number" ? c.value : Number.NaN;
+            if (!RECIPE_FIELD_KEYS.includes(field))
+                return errorResult(`Invalid input: field "${field}" is not one of ${RECIPE_FIELD_KEYS.join(", ")}.`);
+            if (!RECIPE_OPS.includes(op))
+                return errorResult(`Invalid input: op must be one of ${RECIPE_OPS.join(" ")}.`);
+            if (!Number.isFinite(value))
+                return errorResult(`Invalid input: the threshold of ${field} must be a number.`);
+            conditions.push({ field, op, value });
+        }
+        const symbolsIn = Array.isArray(args.symbols) ? args.symbols : [];
+        if (symbolsIn.length > RECIPE_LIMITS.MAX_SYMBOLS)
+            return errorResult(`Invalid input: at most ${RECIPE_LIMITS.MAX_SYMBOLS} symbols.`);
+        const symbols = [];
+        for (const raw of symbolsIn) {
+            const sym = seriesSymbol(raw);
+            if (!sym || typeof raw !== "string")
+                return errorResult(`Invalid input: "${String(raw)}" is not a symbol like BTCUSDT or BTC.`);
+            if (!symbols.includes(sym))
+                symbols.push(sym);
+        }
+        const scope = args.scope === "any" || args.scope === "watchlist" || args.scope === "symbols" ? args.scope : symbols.length > 0 ? "symbols" : "watchlist";
+        if (scope === "symbols" && symbols.length === 0)
+            return errorResult("Invalid input: scope symbols needs symbols.");
+        const channels = Array.isArray(args.channels) ? args.channels.filter((c) => typeof c === "string") : [];
+        if (channels.some((c) => !RECIPE_CHANNELS.includes(c)))
+            return errorResult(`Invalid input: channels are ${RECIPE_CHANNELS.join(", ")}.`);
+        const cooldownHours = typeof args.cooldown_hours === "number" && Number.isFinite(args.cooldown_hours) ? Math.max(1, Math.min(168, Math.round(args.cooldown_hours))) : 24;
+        const fallbackName = `${scope === "symbols" ? `${symbols.slice(0, 3).map((x) => x.replace(/USDT$/, "")).join(", ")} · ` : ""}${conditions.map((c) => `${c.field} ${c.op} ${c.value}`).join(" and ")}`;
+        const name = (typeof args.name === "string" && args.name.trim() ? args.name.trim() : fallbackName).slice(0, RECIPE_LIMITS.NAME_MAX);
+        const body = { name, scope, symbols: scope === "symbols" ? symbols : [], conditions, cooldownHours, channels: [...new Set(channels)], enabled: true };
+        const r = await account("POST", "/api/member/alert-recipes", body);
+        return r.ok ? okResult({ ok: true, id: r.data.id, recipe: body, page: "https://bykaranteli.com/dashboard/alerts" }) : r.result;
+    });
+    server.registerTool("delete_alert_recipe", {
+        title: "Delete one of your alert recipes (writes to your account)",
+        description: "Call this when the user asks to remove an alert. Deletes the alert recipe with this id from the account (list_alert_recipes shows the ids); an id that is not one of the account's recipes changes nothing and says so. Writes are rate limited per key and each one is recorded on the account.",
+        inputSchema: {
+            id: z.string().describe("string, the recipe id from list_alert_recipes"),
+        },
+        annotations: ACCOUNT_DELETE,
+    }, async (args = {}) => {
+        const id = typeof args.id === "string" ? args.id.trim() : "";
+        if (!UUID_RE.test(id))
+            return errorResult("Invalid input: id is a recipe id from list_alert_recipes.");
+        const r = await account("DELETE", `/api/member/alert-recipes/${id}`);
+        if (!r.ok)
+            return r.result;
+        if (r.data.deleted === 0)
+            return errorResult(`No alert recipe with id ${id} on this account; list_alert_recipes shows the ids.`);
+        return okResult({ ok: true, id, deleted: true });
+    });
+    server.registerTool("list_watchlists", {
+        title: "Your watchlists and the symbols on each",
+        description: "Call this when the user asks what is on their watchlist, which lists they have, or before adding or removing a symbol. Returns the account's watchlists (id, name, symbol count) and, unless include_symbols is false, the symbols on each list in order. Needs the account key; reads nothing but this account.",
+        inputSchema: {
+            include_symbols: z.boolean().optional().describe("boolean, optional: include each list's symbols (default true)"),
+        },
+        annotations: ACCOUNT_READ,
+    }, async (args = {}) => {
+        const lists = await account("GET", "/api/member/watchlists");
+        if (!lists.ok)
+            return lists.result;
+        const rows = (Array.isArray(lists.data.watchlists) ? lists.data.watchlists : []);
+        if (args.include_symbols === false)
+            return okResult({ watchlists: rows, page: "https://bykaranteli.com/dashboard/watchlist" });
+        const out = [];
+        for (const w of rows.slice(0, 20)) {
+            const items = await account("GET", `/api/member/watchlists/${encodeURIComponent(w.id)}/items`);
+            if (!items.ok)
+                return items.result;
+            out.push({ ...w, symbols: Array.isArray(items.data.symbols) ? items.data.symbols : [] });
+        }
+        return okResult({ watchlists: out, page: "https://bykaranteli.com/dashboard/watchlist" });
+    });
+    server.registerTool("add_watchlist_symbol", {
+        title: "Add a symbol to your watchlist (writes to your account)",
+        description: "Call this when the user asks to watch, follow or add a coin to their watchlist. Adds the symbol to the list named by watchlist_id, else to the default list (or the only list the account has); a symbol already on the list stays once. Returns the list's symbols after the change. Writes are rate limited per key and each one is recorded on the account.",
+        inputSchema: {
+            symbol: z.string().describe("string, a Binance USDT-M perp or coin, e.g. SOLUSDT or SOL"),
+            watchlist_id: z.string().optional().describe("string, optional list id from list_watchlists (default: the default list)"),
+        },
+        annotations: ACCOUNT_WRITE_IDEMPOTENT,
+    }, async (args = {}) => {
+        const symbol = typeof args.symbol === "string" ? args.symbol.trim() : "";
+        if (!symbol || symbol.length > 30)
+            return errorResult("Invalid input: symbol looks like SOLUSDT or SOL.");
+        const list = await resolveWatchlist(args.watchlist_id);
+        if (!list.ok)
+            return list.result;
+        const r = await account("POST", `/api/member/watchlists/${encodeURIComponent(list.list.id)}/items`, { symbol });
+        if (!r.ok)
+            return r.result;
+        return okResult({ ...r.data, watchlist: { id: list.list.id, name: list.list.name }, note: r.data.created === false ? "Already on this list." : undefined });
+    });
+    server.registerTool("remove_watchlist_symbol", {
+        title: "Remove a symbol from your watchlist (writes to your account)",
+        description: "Call this when the user asks to stop watching a coin or remove it from their watchlist. Removes the symbol from the list named by watchlist_id, else from the default list (or the only list the account has); a symbol that is not on the list changes nothing. Returns the list's symbols after the change. Writes are rate limited per key and each one is recorded on the account.",
+        inputSchema: {
+            symbol: z.string().describe("string, the symbol to remove, e.g. SOLUSDT or SOL"),
+            watchlist_id: z.string().optional().describe("string, optional list id from list_watchlists (default: the default list)"),
+        },
+        annotations: ACCOUNT_DELETE,
+    }, async (args = {}) => {
+        const symbol = typeof args.symbol === "string" ? args.symbol.trim() : "";
+        if (!symbol || symbol.length > 30)
+            return errorResult("Invalid input: symbol looks like SOLUSDT or SOL.");
+        const list = await resolveWatchlist(args.watchlist_id);
+        if (!list.ok)
+            return list.result;
+        const r = await account("DELETE", `/api/member/watchlists/${encodeURIComponent(list.list.id)}/items?symbol=${encodeURIComponent(symbol)}`);
+        if (!r.ok)
+            return r.result;
+        return okResult({ ...r.data, watchlist: { id: list.list.id, name: list.list.name }, note: r.data.deleted === false ? "Was not on this list." : undefined });
+    });
+    /* Hyperliquid address tracking (Terminal feature, 2026-09-30): the member routes /api/member/hl-addresses take the
+     * account key like the alert and watchlist routes. */
+    const HL_ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+    const TRACKED_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    server.registerTool("list_tracked_addresses", {
+        title: "List the Hyperliquid addresses you follow (reads your account)",
+        description: "Call this when the user asks which Hyperliquid addresses they follow, or what those addresses hold right now. Returns every followed address with its label, the positions last seen on it and the plan's address limit; following addresses is part of Terminal and the plans above it.",
+        inputSchema: {},
+        annotations: ACCOUNT_READ,
+    }, async () => {
+        const r = await account("GET", "/api/member/hl-addresses");
+        if (!r.ok)
+            return r.result;
+        return okResult(r.data);
+    });
+    server.registerTool("add_tracked_address", {
+        title: "Follow a Hyperliquid address for position alerts (writes to your account)",
+        description: "Call this when the user asks to follow, track or get alerts for a Hyperliquid address (0x followed by 40 hex characters). Every later position change of the address (opened, closed, increased, reduced, flipped) reaches the user's alert channels; the first sight is the baseline and sends nothing. Counted against the plan's address limit; the route answers terminal_required or limit_reached when it cannot add.",
+        inputSchema: {
+            address: z.string().describe("string, 0x followed by 40 hex characters"),
+            label: z.string().optional().describe("string, optional name for the address, up to 40 characters"),
+        },
+        annotations: ACCOUNT_WRITE_IDEMPOTENT,
+    }, async (args = {}) => {
+        const address = typeof args.address === "string" ? args.address.trim().toLowerCase() : "";
+        if (!HL_ADDRESS_RE.test(address))
+            return errorResult("Invalid input: address is 0x followed by 40 hex characters.");
+        const label = typeof args.label === "string" ? args.label.trim().slice(0, 40) : undefined;
+        const r = await account("POST", "/api/member/hl-addresses", { address, ...(label ? { label } : {}) });
+        if (!r.ok)
+            return r.result;
+        return okResult(r.data);
+    });
+    server.registerTool("remove_tracked_address", {
+        title: "Stop following a Hyperliquid address (writes to your account)",
+        description: "Call this when the user asks to stop following or tracking a Hyperliquid address. Takes the id from list_tracked_addresses; the address's alerts stop, its recorded events stay.",
+        inputSchema: {
+            id: z.string().describe("string, the id from list_tracked_addresses"),
+        },
+        annotations: ACCOUNT_DELETE,
+    }, async (args = {}) => {
+        const id = typeof args.id === "string" ? args.id.trim() : "";
+        if (!TRACKED_ID_RE.test(id))
+            return errorResult("Invalid input: id is the value list_tracked_addresses returns.");
+        const r = await account("DELETE", `/api/member/hl-addresses/${encodeURIComponent(id)}`);
+        if (!r.ok)
+            return r.result;
+        return okResult(r.data);
+    });
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bykaranteli-mcp",
-  "version": "0.30.7",
-  "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. 51 read-only tools, free account key, paid depth via plans or x402.",
+  "version": "0.32.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": {
     "bykaranteli-mcp": "dist/index.js"