hive-intelligence 1.8.0 → 1.9.0

package/agent-skills/packs/hive/SKILL.md

@@ -16,9 +16,9 @@ through one MCP server and one CLI, and every answer carries a receipt:
 provider, fetch time, cache state, runtime status, and digests of the input
 and result. Three things Hive has that most crypto data tools do not:
 
-- **History that venues no longer serve.** Perp funding settlements, open
-  interest, basis, long/short ratios, and liquidations for one coin across up
-  to 33 CEX and DEX venues, archived since 2023-11.
+- **History that venues no longer serve.** Perp funding settlements for one
+  coin across up to 33 CEX and DEX venues since 2023-11, plus basis, open
+  interest and liquidations since 2025 and long/short ratios since 2026-03.
 - **Cross-venue views.** One call compares funding or basis across venues
   instead of one exchange at a time.
 - **Provenance you can cite.** The `_hive` block on every material response
@@ -237,13 +237,15 @@ and probability claims are yours and must be labeled as such.
 
 Discovery tools are free; every other tool costs one credit. Keyed lanes debit
 only after validation and client resolution, so a validation error or a
-missing provider key costs 0 and a call that reaches the provider costs 1 even
-when the provider fails. The keyless lane consumes one allowance call per
-material request, valid or not. `report_feedback` is free on every lane.
+missing provider key costs 0, and a call that fails after the debit is
+refunded, so only a call that succeeds costs 1. The keyless lane takes one
+allowance call per material request and gives it back when the call fails.
+`report_feedback` is free on every lane.
 
 Every material response says what it cost: `credit_cost` (0 or 1),
-`credits_used` (what was actually debited), and `credits_remaining` (an
-integer, `null` when unlimited, absent when the lane has no notion of it).
+`credits_used` (what the call cost, 0 when a failed call was refunded), and
+`credits_remaining` (an integer, `null` when unlimited, absent when the lane
+has no notion of it).
 Do not print the balance on every call; mention it when it is low or when the
 user asks.
 

package/agent-skills/packs/hive-mcp/SKILL.md

@@ -27,10 +27,11 @@ file path and shape vary per client.
   interactive path is live.
 - **Cost** — discovery tools are free; every other tool costs one credit.
   Keyed lanes debit only after validation and client resolution, so a
-  validation error or missing provider key costs 0 and a call that reaches the
-  provider costs 1 even when the provider fails. The keyless lane consumes one
-  allowance call per material request, valid or not. Every material response
-  reports `credit_cost`, `credits_used`, and `credits_remaining`.
+  validation error or missing provider key costs 0, and a call that fails
+  after the debit is refunded, so only a call that succeeds costs 1. The
+  keyless lane takes one allowance call per material request and gives it back
+  when the call fails. Every material response reports `credit_cost`,
+  `credits_used`, and `credits_remaining`.
 
 After hosted OAuth activation, interactive MCP setup does not require the user
 to create or paste an API key. Route to `hive-build-onboarding` for direct CLI,

package/build/{chunk-HWV3XFXH.js → chunk-MVO6LL3H.js}

@@ -49029,7 +49029,14 @@ function getArchiveClient() {
 // src/tools/archive/api.ts
 var DEFAULT_LIMIT2 = 100;
 var MAX_LIMIT2 = 500;
-var ARCHIVE_SINCE_NOTE = "archive since 2023-11";
+var ARCHIVE_SINCE = {
+  funding: "2023-11",
+  open_interest: "2025-04",
+  basis: "2025-03",
+  long_short: "2026-03",
+  liquidations: "2025-04"
+};
+var ARCHIVE_SINCE_NOTE = `archive since ${ARCHIVE_SINCE.funding}`;
 var QUERY_TIMEOUT_MS = 1e4;
 var VENUE_SCAN_MAX_STEPS = 64;
 var COVERAGE_CACHE_TTL_MS = 10 * 60 * 1e3;
@@ -49323,7 +49330,7 @@ function historyHandler(toolName, dataset, options) {
         dataset: spec.table,
         runtime_status: "ok",
         fetched_at: (/* @__PURE__ */ new Date()).toISOString(),
-        note: options?.extraNote ? `${ARCHIVE_SINCE_NOTE}. ${options.extraNote}` : ARCHIVE_SINCE_NOTE,
+        note: options?.extraNote ? `archive since ${ARCHIVE_SINCE[dataset]}. ${options.extraNote}` : `archive since ${ARCHIVE_SINCE[dataset]}`,
         filters,
         order: `${spec.tsColumn} desc`,
         returnedCount: mapped.length,
@@ -54132,7 +54139,7 @@ var PROVIDER_CATALOG = [
     id: "archive",
     name: "Hive Archive",
     prefix: "archive_",
-    type: "Cross-venue crypto derivatives history since 2023-11 (33 CEX+DEX venues): funding-rate settlements, open interest, basis, long/short ratio, and liquidations from Hive's own archive store",
+    type: "Cross-venue crypto derivatives history from Hive's own archive store: funding-rate settlements across 33 CEX+DEX venues since 2023-11, basis since 2025-03, open interest and liquidations since 2025-04, and long/short ratio since 2026-03",
     clientStrategy: "internal",
     credentialRequirement: {
       label: "SHARPE_ARCHIVE_SUPABASE_URL and SHARPE_ARCHIVE_SUPABASE_SERVICE_ROLE_KEY",
@@ -55266,7 +55273,7 @@ var ToolRegistry = [
   {
     category: "Market Data and Price",
     name: "get_market_and_price_endpoints",
-    description: "Endpoints to retrieve real-time and historical cryptocurrency prices, market caps, trading volumes, OHLC data, global market statistics, supported currencies, basic market performance metrics across different timeframes and asset platforms, stablecoin market analytics, stablecoin price tracking, comprehensive stablecoin market cap data across multiple chains, centralized exchange (CEX) trading data including real-time tickers, order books, recent trades, candlestick charts, best bid/ask prices, CEX exchange metadata and volume charts, derivatives pricing (index, mark, and premium), perpetual futures funding rates, leverage tiers, options trading analytics, and available trading markets/currencies across major exchanges. Provider guide: Use coingecko tools for market-wide price data. Use ccxt_ tools for CEX trading data. Use alchemy_ tools for supported token price reads and EVM gas data. Use archive_ tools for cross-venue derivatives HISTORY (funding settlements, open interest, basis, long/short ratio, liquidations) since 2023-11.",
+    description: "Endpoints to retrieve real-time and historical cryptocurrency prices, market caps, trading volumes, OHLC data, global market statistics, supported currencies, basic market performance metrics across different timeframes and asset platforms, stablecoin market analytics, stablecoin price tracking, comprehensive stablecoin market cap data across multiple chains, centralized exchange (CEX) trading data including real-time tickers, order books, recent trades, candlestick charts, best bid/ask prices, CEX exchange metadata and volume charts, derivatives pricing (index, mark, and premium), perpetual futures funding rates, leverage tiers, options trading analytics, and available trading markets/currencies across major exchanges. Provider guide: Use coingecko tools for market-wide price data. Use ccxt_ tools for CEX trading data. Use alchemy_ tools for supported token price reads and EVM gas data. Use archive_ tools for cross-venue derivatives HISTORY: funding settlements since 2023-11; open interest, basis, long/short ratio and liquidations over shorter windows (archive_get_coverage gives exact depth).",
     tools: [
       "get_coins_index",
       "get_coins_market_data",
@@ -57665,6 +57672,27 @@ function createHiveExecutionMetadata(endpoint, durationMs, runtimeStatus, source
 function unchargedCredit(context) {
   return context.creditCost === void 0 ? {} : { creditCost: context.creditCost, creditsUsed: 0 };
 }
+var FAILED_CALL_REFUND_WARNING = "This call failed, so the credit it used was refunded.";
+async function refundFailedCall(billing, toolName, runtimeStatus, warnings) {
+  if (!billing?.refund || billing.credits_used <= 0) return billing;
+  try {
+    const outcome = await billing.refund({ toolName, runtimeStatus });
+    if (!outcome.refunded) return billing;
+    warnings.push(FAILED_CALL_REFUND_WARNING);
+    return {
+      ...billing,
+      credits_used: 0,
+      ...outcome.creditsRemaining !== void 0 && {
+        credits_remaining: outcome.creditsRemaining
+      }
+    };
+  } catch (error) {
+    secureLogger.error("Credit refund for a failed call failed", error, {
+      toolName
+    });
+    return billing;
+  }
+}
 function chargedCredit(context, billing) {
   if (context.creditCost === void 0 && !billing) return {};
   return {
@@ -58261,6 +58289,14 @@ async function executeEndpoint(endpoint, args, context) {
         );
       }
     }
+    if (normalized.isError) {
+      billing = await refundFailedCall(
+        billing,
+        endpoint.tool.name,
+        runtimeStatus,
+        guardWarnings
+      );
+    }
     const durationMs = Date.now() - start;
     const hive = createHiveExecutionMetadata(
       endpoint,
@@ -58340,12 +58376,21 @@ async function executeEndpoint(endpoint, args, context) {
       endpoint.tool.name,
       args
     );
+    const thrownWarnings = [
+      "Tool execution threw before returning a provider result."
+    ];
+    billing = await refundFailedCall(
+      billing,
+      endpoint.tool.name,
+      runtimeStatus,
+      thrownWarnings
+    );
     const hive = createHiveExecutionMetadata(
       endpoint,
       durationMs,
       runtimeStatus,
       "unavailable",
-      ["Tool execution threw before returning a provider result."],
+      thrownWarnings,
       void 0,
       {
         input: args ?? {},

package/build/{chunk-ORJIFYF4.js → chunk-WQE3B64R.js}

@@ -7,7 +7,7 @@ import {
   getSupabaseAdmin,
   resolveEndpoint,
   secureLogger
-} from "./chunk-HWV3XFXH.js";
+} from "./chunk-MVO6LL3H.js";
 
 // src/services/wallet-service.ts
 async function consumeCredits(args) {
@@ -34,6 +34,29 @@ async function consumeCredits(args) {
     cycleEnd: row.cycle_end ?? null
   };
 }
+async function refundCredits(args) {
+  const { userId, debitIdempotencyKey, detail } = args;
+  const { data, error } = await getSupabaseAdmin().rpc("refund_credits", {
+    p_user_id: userId,
+    p_debit_idempotency_key: debitIdempotencyKey,
+    p_detail: detail ?? {}
+  });
+  if (error) {
+    secureLogger.error("refund_credits RPC failed", error, { userId });
+    throw new Error(`refund_credits failed: ${error.message}`);
+  }
+  const row = Array.isArray(data) ? data[0] : data;
+  if (!row) {
+    throw new Error("refund_credits returned no row");
+  }
+  return {
+    code: row.code,
+    balance: row.balance ?? null
+  };
+}
+function refundSettled(code) {
+  return code === "ok" || code === "unlimited" || code === "already_refunded";
+}
 async function ensureWallet(userId, planId) {
   const { error } = await getSupabaseAdmin().rpc("ensure_wallet", {
     p_user_id: userId,
@@ -175,6 +198,8 @@ async function executeToolByName(toolName, args, options) {
 
 export {
   consumeCredits,
+  refundCredits,
+  refundSettled,
   ensureWallet,
   getWalletStatus,
   applyPlanChange,

package/build/cli.js

@@ -3453,7 +3453,7 @@ program2.hook("preAction", (thisCommand) => {
   setCliFlags({ apiKey: opts.apiKey, noRetry: opts.retry === false });
 });
 program2.action(async () => {
-  const { startStdio } = await import("./serve-MOP4WYH6.js");
+  const { startStdio } = await import("./serve-BCKB6DMI.js");
   await startStdio(program2.opts().envFile);
 });
 program2.command("serve").description("Start the MCP server").option("--http", "Start HTTP server instead of stdio").option("--port <number>", "HTTP server port", "8080").action(async (opts) => {
@@ -3466,10 +3466,10 @@ program2.command("serve").description("Start the MCP server").option("--http", "
       );
       process.exit(ExitCode.INVALID_ARGS);
     }
-    const { startHttp } = await import("./serve-MOP4WYH6.js");
+    const { startHttp } = await import("./serve-BCKB6DMI.js");
     await startHttp(port, program2.opts().envFile);
   } else {
-    const { startStdio } = await import("./serve-MOP4WYH6.js");
+    const { startStdio } = await import("./serve-BCKB6DMI.js");
     await startStdio(program2.opts().envFile);
   }
 });
@@ -3734,7 +3734,7 @@ program2.command("feedback <message>").description(
   await runFeedback(message, { tool: opts.tool, receipt: opts.receipt });
 });
 program2.command("doctor").description("Diagnose environment and server connectivity").option("--probe", "Run live API probes (slower)").action(async (opts) => {
-  const { runDoctor } = await import("./doctor-5HAAZU4R.js");
+  const { runDoctor } = await import("./doctor-O2OQX6EX.js");
   await runDoctor(opts);
 });
 program2.command("upgrade").description("Update Hive to the latest published version").action(async () => {
@@ -3782,7 +3782,7 @@ program2.command("usage").description("Show your API usage and plan limits").act
   await runUsage();
 });
 program2.command("status").description("Quick health and version check").action(async () => {
-  const { runStatus } = await import("./doctor-5HAAZU4R.js");
+  const { runStatus } = await import("./doctor-O2OQX6EX.js");
   await runStatus();
 });
 program2.command("open [target]").description("Open Hive dashboard, docs, status, or GitHub in browser").action(async (target) => {

package/build/{doctor-5HAAZU4R.js → doctor-O2OQX6EX.js}

@@ -240,7 +240,7 @@ ${fails === 0 ? "All checks passed" : `${fails} issues found`}${warns ? ` (${war
   if (fails > 0) process.exit(1);
 }
 async function runStatus() {
-  const { SERVER_VERSION } = await import("./mcpServer-LNRRWXSV.js");
+  const { SERVER_VERSION } = await import("./mcpServer-FXQPSDDC.js");
   const { resolveApiKey, resolveApiUrl } = await import("./config-dir-2QLA5PXD.js");
   const { getActiveProfile, maskKey } = await import("./auth-6XVL5CE3.js");
   const apiUrl = resolveApiUrl();

package/build/{mcpServer-LNRRWXSV.js → mcpServer-FXQPSDDC.js}

@@ -9,7 +9,7 @@ import {
   getToolsForScope,
   memoizedJsonSchemaToZodInputSchema,
   memoizedJsonSchemaToZodOutputSchema
-} from "./chunk-HWV3XFXH.js";
+} from "./chunk-MVO6LL3H.js";
 import "./chunk-4QDGA6GP.js";
 import "./chunk-EPF36Q3Z.js";
 import {

package/build/monitor-worker.js

@@ -1,8 +1,10 @@
 import { createRequire } from 'node:module'; const require = createRequire(import.meta.url);
 import {
   consumeCredits,
-  executeToolByName
-} from "./chunk-ORJIFYF4.js";
+  executeToolByName,
+  refundCredits,
+  refundSettled
+} from "./chunk-WQE3B64R.js";
 import {
   HyperliquidAPI,
   MIN_MONITOR_CADENCE_MS,
@@ -15,7 +17,7 @@ import {
   monitorCadenceIntervalMs,
   runScheduledHealthCanaries,
   secureLogger
-} from "./chunk-HWV3XFXH.js";
+} from "./chunk-MVO6LL3H.js";
 import "./chunk-4QDGA6GP.js";
 import "./chunk-EPF36Q3Z.js";
 import "./chunk-ZXKFJQDE.js";
@@ -640,6 +642,29 @@ async function defaultConsumeCredit(args) {
     requestId: args.runId
   });
 }
+async function defaultRefundCredit(args) {
+  const refund = await refundCredits({
+    userId: args.userId,
+    debitIdempotencyKey: `monitor-run:${args.runId}`,
+    detail: { monitor_run: args.runId, reason: args.reason }
+  });
+  return refundSettled(refund.code);
+}
+async function refundMonitorRunCredit(args) {
+  try {
+    return await args.refundCredit({
+      userId: args.monitor.user_id,
+      runId: args.runId,
+      reason: args.reason
+    });
+  } catch (error) {
+    secureLogger.error("Monitor run credit refund failed", error, {
+      monitorId: args.monitor.id,
+      runId: args.runId
+    });
+    return false;
+  }
+}
 async function debitMonitorRunCredit(args) {
   try {
     const debit = await args.consumeCredit({
@@ -976,6 +1001,7 @@ async function processMonitor(monitor, options) {
   });
   const completedAt = options.now.toISOString();
   const nextRunAt = computeNextRunAt(monitor.cadence, options.now);
+  let charged = false;
   try {
     const debit = await debitMonitorRunCredit({
       monitor,
@@ -1007,6 +1033,7 @@ async function processMonitor(monitor, options) {
         alerts: 0
       };
     }
+    charged = true;
     const previous = await options.store.getLatestSnapshot(monitor.id);
     const workflow = await executeMonitorWorkflow(
       monitor,
@@ -1101,6 +1128,13 @@ async function processMonitor(monitor, options) {
       });
       observations++;
     }
+    const everyCallFailed = workflow.toolCalls.length > 0 && workflow.failedCalls.length === workflow.toolCalls.length;
+    const creditRefunded = everyCallFailed ? await refundMonitorRunCredit({
+      monitor,
+      runId: run.id,
+      reason: "every tool call failed",
+      refundCredit: options.refundCredit
+    }) : false;
     await options.store.finishRun({
       runId: run.id,
       status: "completed",
@@ -1109,7 +1143,8 @@ async function processMonitor(monitor, options) {
       metadata: {
         fingerprint: workflow.fingerprint,
         failed_call_count: workflow.failedCalls.length,
-        rule_evaluation_count: ruleEvaluations.length
+        rule_evaluation_count: ruleEvaluations.length,
+        ...creditRefunded && { credit_refunded: true }
       }
     });
     await options.store.releaseMonitor({
@@ -1129,6 +1164,14 @@ async function processMonitor(monitor, options) {
     };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
+    if (charged) {
+      await refundMonitorRunCredit({
+        monitor,
+        runId: run.id,
+        reason: "run failed",
+        refundCredit: options.refundCredit
+      });
+    }
     await options.store.finishRun({
       runId: run.id,
       status: "failed",
@@ -1165,6 +1208,7 @@ async function runDueMonitors(options = {}) {
   const now = options.now ?? /* @__PURE__ */ new Date();
   const executeTool = options.executeTool ?? executeToolByName;
   const consumeCredit = options.consumeCredit ?? defaultConsumeCredit;
+  const refundCredit = options.refundCredit ?? defaultRefundCredit;
   const source = options.source ?? "scheduled";
   const claimed = await store.claimDueMonitors({
     batchSize,
@@ -1191,7 +1235,8 @@ async function runDueMonitors(options = {}) {
         now,
         source,
         executeTool,
-        consumeCredit
+        consumeCredit,
+        refundCredit
       })
     );
   }

package/build/release.json

@@ -1,8 +1,8 @@
 {
   "package": "hive-intelligence",
-  "version": "1.8.0",
-  "buildSha": "eac2d1b060973dfe826ff082d35708e2b80ac05c",
-  "imageDigest": "sha256:cbc418fc3433b677d78aeef00b1b7b37ccaa440e00c6cab390ed327fd31f6669",
+  "version": "1.9.0",
+  "buildSha": "b157f6642120d33dd3c241c366731f0174a56902",
+  "imageDigest": "sha256:103576df07830e955af1f472dc39b365862c8b5a6965d2a944be363ea4e8b976",
   "deployedUrl": "https://mcp.hiveintelligence.xyz",
-  "manifest": "https://raw.githubusercontent.com/hive-intel/hive-sdk/v1.8.0/releases/v1.8.0.json"
+  "manifest": "https://raw.githubusercontent.com/hive-intel/hive-sdk/v1.9.0/releases/v1.9.0.json"
 }

package/build/{serve-MOP4WYH6.js → serve-BCKB6DMI.js}

@@ -7,7 +7,7 @@ async function startStdio(envFile) {
   dotenv.config({ path: envFile || ".env", quiet: true });
   console.log = (...args) => console.error("[LOG]", ...args);
   const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
-  const { createHiveMcpServer, SERVER_NAME, SERVER_VERSION } = await import("./mcpServer-LNRRWXSV.js");
+  const { createHiveMcpServer, SERVER_NAME, SERVER_VERSION } = await import("./mcpServer-FXQPSDDC.js");
   const { getPendingUpdateVersion } = await import("./update-check-36QU6PKA.js");
   const transport = new StdioServerTransport();
   const pendingUpdate = getPendingUpdateVersion();

package/build/server.js

@@ -5,8 +5,10 @@ import {
   consumeCredits,
   ensureWallet,
   executeToolByName,
-  getWalletStatus
-} from "./chunk-ORJIFYF4.js";
+  getWalletStatus,
+  refundCredits,
+  refundSettled
+} from "./chunk-WQE3B64R.js";
 import {
   CategoryEndpoints,
   HERO_TOOL_NAMES,
@@ -102,7 +104,7 @@ import {
   validateEndpointArgs,
   verifyApiKey,
   waitForRedisAvailability
-} from "./chunk-HWV3XFXH.js";
+} from "./chunk-MVO6LL3H.js";
 import {
   HIVE_AGENT_SKILLS
 } from "./chunk-4QDGA6GP.js";
@@ -2598,10 +2600,11 @@ async function debitApiKeyCreditForExecution(req, res) {
   const result = authReq.unkeyResult;
   if (!result || !authReq.userId) return;
   try {
+    const idempotencyKey = authReq.creditDebitIdempotencyKey ?? randomUUID();
     const consumeResult = await consumeCredits({
       userId: authReq.userId,
       cost: REQUEST_COST,
-      idempotencyKey: authReq.creditDebitIdempotencyKey ?? randomUUID(),
+      idempotencyKey,
       requestId: req.requestId,
       keyId: authReq.unkeyKeyId
     });
@@ -2627,6 +2630,7 @@ async function debitApiKeyCreditForExecution(req, res) {
       };
     }
     authReq.quotaRemaining = consumeResult.balance ?? void 0;
+    authReq.creditDebitedKey = idempotencyKey;
     authReq.idempotencyExecutionStarted = true;
     res.setHeader(
       "X-Quota-Remaining",
@@ -5556,6 +5560,23 @@ async function consumeAnonMaterialQuota(ipHash, overrides = {}) {
     return { allowed: false, reason: "unavailable" };
   }
 }
+async function refundAnonMaterialQuota(ipHash) {
+  try {
+    if (!isSupabaseConfigured()) return void 0;
+    const { data, error } = await getSupabaseAdmin().rpc(
+      "refund_anon_daily_quota",
+      { p_ip_hash: ipHash, p_ip_limit: getAnonDailyMaterialCap() }
+    );
+    if (error) throw new Error(error.message);
+    const row = Array.isArray(data) ? data[0] : data;
+    return typeof row?.remaining === "number" ? row.remaining : void 0;
+  } catch (err) {
+    secureLogger.warn("Anonymous quota refund failed", {
+      error: err instanceof Error ? err.message : String(err)
+    });
+    return void 0;
+  }
+}
 
 // src/serverCard.ts
 function buildServerCard() {
@@ -6925,10 +6946,11 @@ function buildMcpQuotaExhaustedCopy(args) {
 }
 async function debitMcpCredits(args) {
   try {
+    const idempotencyKey = randomUUID4();
     const debit = await consumeCredits({
       userId: args.userId,
       cost: 1,
-      idempotencyKey: randomUUID4(),
+      idempotencyKey,
       requestId: args.requestId,
       keyId: args.keyId
     });
@@ -6952,7 +6974,7 @@ async function debitMcpCredits(args) {
         rateLimited: true
       };
     }
-    return { ok: true, balance: debit.balance };
+    return { ok: true, balance: debit.balance, idempotencyKey };
   } catch (err) {
     secureLogger.warn("MCP consume_credits debit failed", {
       error: err instanceof Error ? err.message : String(err)
@@ -6963,6 +6985,32 @@ async function debitMcpCredits(args) {
     };
   }
 }
+async function refundKeyedCredit(res, args) {
+  const refund = await refundCredits({
+    userId: args.userId,
+    debitIdempotencyKey: args.debitIdempotencyKey,
+    detail: {
+      tool: args.toolName,
+      runtime_status: args.runtimeStatus,
+      transport: args.transport
+    }
+  });
+  if (!refundSettled(refund.code)) return { refunded: false };
+  if (!res.headersSent) {
+    res.setHeader(
+      "X-Quota-Remaining",
+      refund.balance === null ? "unlimited" : String(refund.balance)
+    );
+  }
+  return { refunded: true, creditsRemaining: refund.balance };
+}
+async function refundAnonCall(res, ipHash) {
+  const remaining = await refundAnonMaterialQuota(ipHash);
+  if (remaining !== void 0 && !res.headersSent) {
+    res.setHeader("X-Quota-Remaining", String(remaining));
+  }
+  return remaining;
+}
 function extractApiKey(req) {
   return req.headers["x-api-key"] ?? (req.headers.authorization?.startsWith("Bearer ") ? req.headers.authorization.slice(7) : void 0);
 }
@@ -7412,10 +7460,10 @@ function createStatelessMcpHandler(scope) {
     if (!auth.ok && !mcpCredentialPresented(req)) {
       const decision = await authorizeAnonymousMcpRequest(req);
       if (decision.kind === "allow") {
+        const ipHash = anonymousIpHash(ipRateLimitKeyFromRequest(req));
         anonymousLane = {
-          principalRaw: `anon:${anonymousIpHash(
-            ipRateLimitKeyFromRequest(req)
-          )}`,
+          principalRaw: `anon:${ipHash}`,
+          ipHash,
           materialGranted: decision.materialGranted,
           quotaRemaining: decision.quotaRemaining
         };
@@ -7641,6 +7689,8 @@ function createStatelessMcpHandler(scope) {
         clientName: resolveMcpClientName(req, body),
         isInternal: isMonitorSecretRequest(req)
       };
+      let anonCallHeld = anonymousLane?.materialGranted === true;
+      let anonCallBilled = false;
       const server = createHiveMcpServer(scope, {
         requestId: req.requestId,
         analytics,
@@ -7698,6 +7748,7 @@ function createStatelessMcpHandler(scope) {
         beforeToolExecution: keyedAuth?.userId ? async (executedToolName) => {
           const creditCost = getMcpCreditCost(executedToolName);
           let keyedBalance;
+          let debitKey;
           res.setHeader("X-Hive-Credit-Cost", String(creditCost));
           if (creditCost > 0) {
             const debit = await debitMcpCredits({
@@ -7741,10 +7792,22 @@ function createStatelessMcpHandler(scope) {
               debit.balance === null ? "unlimited" : String(debit.balance)
             );
             keyedBalance = debit.balance;
+            debitKey = debit.idempotencyKey;
           }
+          const refund = debitKey ? (reason) => refundKeyedCredit(res, {
+            userId: keyedAuth.userId,
+            debitIdempotencyKey: debitKey,
+            toolName: reason.toolName,
+            runtimeStatus: reason.runtimeStatus,
+            transport: "mcp"
+          }) : void 0;
           if (subjectContext) {
             const materialized = await materializeSubjectContext(subjectContext);
             if (!materialized.ok) {
+              await refund?.({
+                toolName: executedToolName,
+                runtimeStatus: "failing"
+              }).catch(() => void 0);
               return {
                 type: materialized.status === 403 ? "authentication_error" : "internal_error",
                 code: materialized.code,
@@ -7768,7 +7831,8 @@ function createStatelessMcpHandler(scope) {
           return {
             type: "billing",
             credits_used: creditCost,
-            ...creditCost > 0 && { credits_remaining: keyedBalance }
+            ...creditCost > 0 && { credits_remaining: keyedBalance },
+            ...refund && { refund }
           };
         } : anonymousLane ? async (executedToolName) => {
           const creditCost = getMcpCreditCost(executedToolName);
@@ -7790,10 +7854,36 @@ function createStatelessMcpHandler(scope) {
               runtimeStatus: "failing"
             };
           }
+          if (!anonCallHeld) {
+            const quota = await consumeAnonMaterialQuota(
+              anonymousLane.ipHash
+            );
+            if (!quota.allowed) {
+              return {
+                type: "rate_limit_error",
+                code: "ANON_QUOTA_EXCEEDED",
+                message: ANON_QUOTA_EXHAUSTED_MESSAGE,
+                runtimeStatus: "rate_limited"
+              };
+            }
+            anonCallHeld = true;
+            anonymousLane.quotaRemaining = quota.remaining;
+          }
+          anonCallBilled = true;
           return {
             type: "billing",
             credits_used: creditCost,
-            credits_remaining: anonymousLane.quotaRemaining ?? null
+            credits_remaining: anonymousLane.quotaRemaining ?? null,
+            refund: async () => {
+              const remaining = await refundAnonCall(
+                res,
+                anonymousLane.ipHash
+              );
+              if (remaining === void 0) return { refunded: false };
+              anonCallHeld = false;
+              anonymousLane.quotaRemaining = remaining;
+              return { refunded: true, creditsRemaining: remaining };
+            }
           };
         } : void 0
       }).getServer();
@@ -7820,6 +7910,10 @@ function createStatelessMcpHandler(scope) {
           () => transport.handleRequest(req, res, body)
         )
       );
+      if (anonymousLane && anonCallHeld && !anonCallBilled) {
+        anonCallHeld = false;
+        await refundAnonCall(res, anonymousLane.ipHash);
+      }
       secureLogger.debug("MCP request completed", {
         sessionId: sessionCorrelationId,
         scope: scope.kind === "root" ? "root" : `category:${scope.category}`
@@ -8341,6 +8435,7 @@ var anonymousHeroExecuteMiddleware = asyncHandler(
       return;
     }
     res.setHeader("X-Quota-Remaining", String(quota.remaining));
+    let refundAttempted = false;
     const result = await executeEndpoint(heroEndpoint, body?.args ?? {}, {
       transport: "rest",
       requestId: req.requestId,
@@ -8349,7 +8444,12 @@ var anonymousHeroExecuteMiddleware = asyncHandler(
       beforeExecution: async () => ({
         type: "billing",
         credits_used: getMcpCreditCost(toolName),
-        credits_remaining: quota.remaining
+        credits_remaining: quota.remaining,
+        refund: async () => {
+          refundAttempted = true;
+          const remaining = await refundAnonCall(res, ipHash);
+          return remaining === void 0 ? { refunded: false } : { refunded: true, creditsRemaining: remaining };
+        }
       }),
       analytics: {
         principalRaw: `anon:${ipHash}`,
@@ -8358,6 +8458,9 @@ var anonymousHeroExecuteMiddleware = asyncHandler(
         isInternal: isMonitorSecretRequest(req)
       }
     });
+    if (!result.ok && !refundAttempted) {
+      await refundAnonCall(res, ipHash);
+    }
     const meta = buildRestExecutionMeta(
       toolName,
       result.durationMs,
@@ -8413,6 +8516,14 @@ app.post(
     const endpointArgs = authReq.resolvedRestToolArgs ?? { ...args ?? {} };
     const keyedBeforeExecution = async (endpoint) => {
       const blocked = await debitApiKeyCreditForExecution(req, res);
+      const debitKey = authReq.creditDebitedKey;
+      const refund = debitKey && authReq.userId ? (reason) => refundKeyedCredit(res, {
+        userId: authReq.userId,
+        debitIdempotencyKey: debitKey,
+        toolName: reason.toolName,
+        runtimeStatus: reason.runtimeStatus,
+        transport: "rest"
+      }) : void 0;
       if (blocked) {
         if (blocked.code === "QUOTA_EXCEEDED") {
           recordPaywall(req, {
@@ -8431,6 +8542,10 @@ app.post(
           authReq.hiveSubjectContext
         );
         if (!materialized.ok) {
+          await refund?.({
+            toolName: endpoint.tool.name,
+            runtimeStatus: "failing"
+          }).catch(() => void 0);
           return {
             type: materialized.status === 403 ? "authentication_error" : "internal_error",
             code: materialized.code,
@@ -8458,7 +8573,8 @@ app.post(
         credits_used: creditCost,
         ...creditCost > 0 && remainingHeader !== void 0 && {
           credits_remaining: String(remainingHeader) === "unlimited" ? null : Number(remainingHeader)
-        }
+        },
+        ...refund && { refund }
       };
     };
     const heroEndpoint = HERO_TOOL_NAMES.has(executionToolName) ? getRestHeroEndpoint(executionToolName) : void 0;

package/build/stdio.js

@@ -6,7 +6,7 @@ import {
 import {
   createHiveMcpServer,
   secureLogger
-} from "./chunk-HWV3XFXH.js";
+} from "./chunk-MVO6LL3H.js";
 import "./chunk-4QDGA6GP.js";
 import "./chunk-EPF36Q3Z.js";
 import {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hive-intelligence",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Evidence-backed crypto due diligence for AI agents, with sources, freshness, and a runtime receipt on every call.",
   "mcpName": "xyz.hiveintelligence/mcp",
   "type": "module",