@blockrun/clawrouter 0.3.1 → 0.3.3

package/dist/index.js

@@ -95,40 +95,260 @@ var envKeyAuth = {
 // src/models.ts
 var BLOCKRUN_MODELS = [
   // Smart routing meta-model — proxy replaces with actual model
-  { id: "blockrun/auto", name: "BlockRun Smart Router", inputPrice: 0, outputPrice: 0, contextWindow: 105e4, maxOutput: 128e3 },
+  {
+    id: "blockrun/auto",
+    name: "BlockRun Smart Router",
+    inputPrice: 0,
+    outputPrice: 0,
+    contextWindow: 105e4,
+    maxOutput: 128e3
+  },
   // OpenAI GPT-5 Family
-  { id: "openai/gpt-5.2", name: "GPT-5.2", inputPrice: 1.75, outputPrice: 14, contextWindow: 4e5, maxOutput: 128e3, reasoning: true, vision: true },
-  { id: "openai/gpt-5-mini", name: "GPT-5 Mini", inputPrice: 0.25, outputPrice: 2, contextWindow: 2e5, maxOutput: 65536 },
-  { id: "openai/gpt-5-nano", name: "GPT-5 Nano", inputPrice: 0.05, outputPrice: 0.4, contextWindow: 128e3, maxOutput: 32768 },
-  { id: "openai/gpt-5.2-pro", name: "GPT-5.2 Pro", inputPrice: 21, outputPrice: 168, contextWindow: 4e5, maxOutput: 128e3, reasoning: true },
+  {
+    id: "openai/gpt-5.2",
+    name: "GPT-5.2",
+    inputPrice: 1.75,
+    outputPrice: 14,
+    contextWindow: 4e5,
+    maxOutput: 128e3,
+    reasoning: true,
+    vision: true
+  },
+  {
+    id: "openai/gpt-5-mini",
+    name: "GPT-5 Mini",
+    inputPrice: 0.25,
+    outputPrice: 2,
+    contextWindow: 2e5,
+    maxOutput: 65536
+  },
+  {
+    id: "openai/gpt-5-nano",
+    name: "GPT-5 Nano",
+    inputPrice: 0.05,
+    outputPrice: 0.4,
+    contextWindow: 128e3,
+    maxOutput: 32768
+  },
+  {
+    id: "openai/gpt-5.2-pro",
+    name: "GPT-5.2 Pro",
+    inputPrice: 21,
+    outputPrice: 168,
+    contextWindow: 4e5,
+    maxOutput: 128e3,
+    reasoning: true
+  },
   // OpenAI GPT-4 Family
-  { id: "openai/gpt-4.1", name: "GPT-4.1", inputPrice: 2, outputPrice: 8, contextWindow: 128e3, maxOutput: 16384, vision: true },
-  { id: "openai/gpt-4.1-mini", name: "GPT-4.1 Mini", inputPrice: 0.4, outputPrice: 1.6, contextWindow: 128e3, maxOutput: 16384 },
-  { id: "openai/gpt-4.1-nano", name: "GPT-4.1 Nano", inputPrice: 0.1, outputPrice: 0.4, contextWindow: 128e3, maxOutput: 16384 },
-  { id: "openai/gpt-4o", name: "GPT-4o", inputPrice: 2.5, outputPrice: 10, contextWindow: 128e3, maxOutput: 16384, vision: true },
-  { id: "openai/gpt-4o-mini", name: "GPT-4o Mini", inputPrice: 0.15, outputPrice: 0.6, contextWindow: 128e3, maxOutput: 16384 },
+  {
+    id: "openai/gpt-4.1",
+    name: "GPT-4.1",
+    inputPrice: 2,
+    outputPrice: 8,
+    contextWindow: 128e3,
+    maxOutput: 16384,
+    vision: true
+  },
+  {
+    id: "openai/gpt-4.1-mini",
+    name: "GPT-4.1 Mini",
+    inputPrice: 0.4,
+    outputPrice: 1.6,
+    contextWindow: 128e3,
+    maxOutput: 16384
+  },
+  {
+    id: "openai/gpt-4.1-nano",
+    name: "GPT-4.1 Nano",
+    inputPrice: 0.1,
+    outputPrice: 0.4,
+    contextWindow: 128e3,
+    maxOutput: 16384
+  },
+  {
+    id: "openai/gpt-4o",
+    name: "GPT-4o",
+    inputPrice: 2.5,
+    outputPrice: 10,
+    contextWindow: 128e3,
+    maxOutput: 16384,
+    vision: true
+  },
+  {
+    id: "openai/gpt-4o-mini",
+    name: "GPT-4o Mini",
+    inputPrice: 0.15,
+    outputPrice: 0.6,
+    contextWindow: 128e3,
+    maxOutput: 16384
+  },
   // OpenAI O-series (Reasoning)
-  { id: "openai/o1", name: "o1", inputPrice: 15, outputPrice: 60, contextWindow: 2e5, maxOutput: 1e5, reasoning: true },
-  { id: "openai/o1-mini", name: "o1-mini", inputPrice: 1.1, outputPrice: 4.4, contextWindow: 128e3, maxOutput: 65536, reasoning: true },
-  { id: "openai/o3", name: "o3", inputPrice: 2, outputPrice: 8, contextWindow: 2e5, maxOutput: 1e5, reasoning: true },
-  { id: "openai/o3-mini", name: "o3-mini", inputPrice: 1.1, outputPrice: 4.4, contextWindow: 128e3, maxOutput: 65536, reasoning: true },
-  { id: "openai/o4-mini", name: "o4-mini", inputPrice: 1.1, outputPrice: 4.4, contextWindow: 128e3, maxOutput: 65536, reasoning: true },
+  {
+    id: "openai/o1",
+    name: "o1",
+    inputPrice: 15,
+    outputPrice: 60,
+    contextWindow: 2e5,
+    maxOutput: 1e5,
+    reasoning: true
+  },
+  {
+    id: "openai/o1-mini",
+    name: "o1-mini",
+    inputPrice: 1.1,
+    outputPrice: 4.4,
+    contextWindow: 128e3,
+    maxOutput: 65536,
+    reasoning: true
+  },
+  {
+    id: "openai/o3",
+    name: "o3",
+    inputPrice: 2,
+    outputPrice: 8,
+    contextWindow: 2e5,
+    maxOutput: 1e5,
+    reasoning: true
+  },
+  {
+    id: "openai/o3-mini",
+    name: "o3-mini",
+    inputPrice: 1.1,
+    outputPrice: 4.4,
+    contextWindow: 128e3,
+    maxOutput: 65536,
+    reasoning: true
+  },
+  {
+    id: "openai/o4-mini",
+    name: "o4-mini",
+    inputPrice: 1.1,
+    outputPrice: 4.4,
+    contextWindow: 128e3,
+    maxOutput: 65536,
+    reasoning: true
+  },
   // Anthropic
-  { id: "anthropic/claude-haiku-4.5", name: "Claude Haiku 4.5", inputPrice: 1, outputPrice: 5, contextWindow: 2e5, maxOutput: 8192 },
-  { id: "anthropic/claude-sonnet-4", name: "Claude Sonnet 4", inputPrice: 3, outputPrice: 15, contextWindow: 2e5, maxOutput: 64e3, reasoning: true },
-  { id: "anthropic/claude-opus-4", name: "Claude Opus 4", inputPrice: 15, outputPrice: 75, contextWindow: 2e5, maxOutput: 32e3, reasoning: true },
-  { id: "anthropic/claude-opus-4.5", name: "Claude Opus 4.5", inputPrice: 15, outputPrice: 75, contextWindow: 2e5, maxOutput: 32e3, reasoning: true },
+  {
+    id: "anthropic/claude-haiku-4.5",
+    name: "Claude Haiku 4.5",
+    inputPrice: 1,
+    outputPrice: 5,
+    contextWindow: 2e5,
+    maxOutput: 8192
+  },
+  {
+    id: "anthropic/claude-sonnet-4",
+    name: "Claude Sonnet 4",
+    inputPrice: 3,
+    outputPrice: 15,
+    contextWindow: 2e5,
+    maxOutput: 64e3,
+    reasoning: true
+  },
+  {
+    id: "anthropic/claude-opus-4",
+    name: "Claude Opus 4",
+    inputPrice: 15,
+    outputPrice: 75,
+    contextWindow: 2e5,
+    maxOutput: 32e3,
+    reasoning: true
+  },
+  {
+    id: "anthropic/claude-opus-4.5",
+    name: "Claude Opus 4.5",
+    inputPrice: 5,
+    outputPrice: 25,
+    contextWindow: 2e5,
+    maxOutput: 32e3,
+    reasoning: true
+  },
   // Google
-  { id: "google/gemini-3-pro-preview", name: "Gemini 3 Pro Preview", inputPrice: 2, outputPrice: 12, contextWindow: 105e4, maxOutput: 65536, reasoning: true, vision: true },
-  { id: "google/gemini-2.5-pro", name: "Gemini 2.5 Pro", inputPrice: 1.25, outputPrice: 10, contextWindow: 105e4, maxOutput: 65536, reasoning: true, vision: true },
-  { id: "google/gemini-2.5-flash", name: "Gemini 2.5 Flash", inputPrice: 0.15, outputPrice: 0.6, contextWindow: 1e6, maxOutput: 65536 },
+  {
+    id: "google/gemini-3-pro-preview",
+    name: "Gemini 3 Pro Preview",
+    inputPrice: 2,
+    outputPrice: 12,
+    contextWindow: 105e4,
+    maxOutput: 65536,
+    reasoning: true,
+    vision: true
+  },
+  {
+    id: "google/gemini-2.5-pro",
+    name: "Gemini 2.5 Pro",
+    inputPrice: 1.25,
+    outputPrice: 10,
+    contextWindow: 105e4,
+    maxOutput: 65536,
+    reasoning: true,
+    vision: true
+  },
+  {
+    id: "google/gemini-2.5-flash",
+    name: "Gemini 2.5 Flash",
+    inputPrice: 0.15,
+    outputPrice: 0.6,
+    contextWindow: 1e6,
+    maxOutput: 65536
+  },
   // DeepSeek
-  { id: "deepseek/deepseek-chat", name: "DeepSeek V3.2 Chat", inputPrice: 0.28, outputPrice: 0.42, contextWindow: 128e3, maxOutput: 8192 },
-  { id: "deepseek/deepseek-reasoner", name: "DeepSeek V3.2 Reasoner", inputPrice: 0.28, outputPrice: 0.42, contextWindow: 128e3, maxOutput: 8192, reasoning: true },
+  {
+    id: "deepseek/deepseek-chat",
+    name: "DeepSeek V3.2 Chat",
+    inputPrice: 0.28,
+    outputPrice: 0.42,
+    contextWindow: 128e3,
+    maxOutput: 8192
+  },
+  {
+    id: "deepseek/deepseek-reasoner",
+    name: "DeepSeek V3.2 Reasoner",
+    inputPrice: 0.28,
+    outputPrice: 0.42,
+    contextWindow: 128e3,
+    maxOutput: 8192,
+    reasoning: true
+  },
+  // Moonshot / Kimi
+  {
+    id: "moonshot/kimi-k2.5",
+    name: "Kimi K2.5",
+    inputPrice: 0.5,
+    outputPrice: 2.4,
+    contextWindow: 262144,
+    maxOutput: 8192,
+    reasoning: true,
+    vision: true
+  },
   // xAI / Grok
-  { id: "xai/grok-3", name: "Grok 3", inputPrice: 3, outputPrice: 15, contextWindow: 131072, maxOutput: 16384, reasoning: true },
-  { id: "xai/grok-3-fast", name: "Grok 3 Fast", inputPrice: 5, outputPrice: 25, contextWindow: 131072, maxOutput: 16384, reasoning: true },
-  { id: "xai/grok-3-mini", name: "Grok 3 Mini", inputPrice: 0.3, outputPrice: 0.5, contextWindow: 131072, maxOutput: 16384 }
+  {
+    id: "xai/grok-3",
+    name: "Grok 3",
+    inputPrice: 3,
+    outputPrice: 15,
+    contextWindow: 131072,
+    maxOutput: 16384,
+    reasoning: true
+  },
+  {
+    id: "xai/grok-3-fast",
+    name: "Grok 3 Fast",
+    inputPrice: 5,
+    outputPrice: 25,
+    contextWindow: 131072,
+    maxOutput: 16384,
+    reasoning: true
+  },
+  {
+    id: "xai/grok-3-mini",
+    name: "Grok 3 Mini",
+    inputPrice: 0.3,
+    outputPrice: 0.5,
+    contextWindow: 131072,
+    maxOutput: 16384
+  }
 ];
 function toOpenClawModel(m) {
   return {
@@ -324,7 +544,16 @@ function createPaymentFetch(privateKey) {
       if (paymentHeader2) {
         return handle402(input, init, url, endpointPath, paymentHeader2);
       }
-      return response2;
+      paymentCache.invalidate(endpointPath);
+      const cleanResponse = await fetch(input, init);
+      if (cleanResponse.status !== 402) {
+        return cleanResponse;
+      }
+      const cleanHeader = cleanResponse.headers.get("x-payment-required");
+      if (!cleanHeader) {
+        throw new Error("402 response missing x-payment-required header");
+      }
+      return handle402(input, init, url, endpointPath, cleanHeader);
     }
     const response = await fetch(input, init);
     if (response.status !== 402) {
@@ -384,10 +613,18 @@ function scoreTokenCount(estimatedTokens, thresholds) {
 function scoreKeywordMatch(text, keywords, name, signalLabel, thresholds, scores) {
   const matches = keywords.filter((kw) => text.includes(kw.toLowerCase()));
   if (matches.length >= thresholds.high) {
-    return { name, score: scores.high, signal: `${signalLabel} (${matches.slice(0, 3).join(", ")})` };
+    return {
+      name,
+      score: scores.high,
+      signal: `${signalLabel} (${matches.slice(0, 3).join(", ")})`
+    };
   }
   if (matches.length >= thresholds.low) {
-    return { name, score: scores.low, signal: `${signalLabel} (${matches.slice(0, 3).join(", ")})` };
+    return {
+      name,
+      score: scores.low,
+      signal: `${signalLabel} (${matches.slice(0, 3).join(", ")})`
+    };
   }
   return { name, score: scores.none, signal: null };
 }
@@ -510,9 +747,7 @@ function classifyByRules(prompt, systemPrompt, estimatedTokens, config) {
     const w = weights[d.name] ?? 0;
     weightedScore += d.score * w;
   }
-  const reasoningMatches = config.reasoningKeywords.filter(
-    (kw) => text.includes(kw.toLowerCase())
-  );
+  const reasoningMatches = config.reasoningKeywords.filter((kw) => text.includes(kw.toLowerCase()));
   if (reasoningMatches.length >= 2) {
     const confidence2 = calibrateConfidence(
       Math.max(weightedScore, 0.3),
@@ -534,10 +769,7 @@ function classifyByRules(prompt, systemPrompt, estimatedTokens, config) {
     distanceFromBoundary = simpleMedium - weightedScore;
   } else if (weightedScore < mediumComplex) {
     tier = "MEDIUM";
-    distanceFromBoundary = Math.min(
-      weightedScore - simpleMedium,
-      mediumComplex - weightedScore
-    );
+    distanceFromBoundary = Math.min(weightedScore - simpleMedium, mediumComplex - weightedScore);
   } else if (weightedScore < complexReasoning) {
     tier = "COMPLEX";
     distanceFromBoundary = Math.min(
@@ -642,15 +874,7 @@ var DEFAULT_ROUTING_CONFIG = {
       "database",
       "infrastructure"
     ],
-    creativeKeywords: [
-      "story",
-      "poem",
-      "compose",
-      "brainstorm",
-      "creative",
-      "imagine",
-      "write a"
-    ],
+    creativeKeywords: ["story", "poem", "compose", "brainstorm", "creative", "imagine", "write a"],
     // New dimension keyword lists
     imperativeVerbs: [
       "build",
@@ -793,15 +1017,10 @@ function route(prompt, systemPrompt, maxOutputTokens, options) {
     );
   }
   const hasStructuredOutput = systemPrompt ? /json|structured|schema/i.test(systemPrompt) : false;
-  const ruleResult = classifyByRules(
-    prompt,
-    systemPrompt,
-    estimatedTokens,
-    config.scoring
-  );
+  const ruleResult = classifyByRules(prompt, systemPrompt, estimatedTokens, config.scoring);
   let tier;
   let confidence;
-  let method = "rules";
+  const method = "rules";
   let reasoning = `score=${ruleResult.score} | ${ruleResult.signals.join(", ")}`;
   if (ruleResult.tier !== null) {
     tier = ruleResult.tier;
@@ -882,14 +1101,16 @@ var RequestDeduplicator = class {
     const entry = this.inflight.get(key);
     if (!entry) return void 0;
     const promise = new Promise((resolve) => {
-      entry.waiters.push(new Promise((r) => {
-        const orig = entry.resolve;
-        entry.resolve = (result) => {
-          orig(result);
-          resolve(result);
-          r(result);
-        };
-      }));
+      entry.waiters.push(
+        new Promise((r) => {
+          const orig = entry.resolve;
+          entry.resolve = (result) => {
+            orig(result);
+            resolve(result);
+            r(result);
+          };
+        })
+      );
     });
     return promise;
   }
@@ -928,11 +1149,182 @@ var RequestDeduplicator = class {
   }
 };
 
+// src/balance.ts
+import { createPublicClient, http, erc20Abi } from "viem";
+import { base } from "viem/chains";
+
+// src/errors.ts
+var InsufficientFundsError = class extends Error {
+  code = "INSUFFICIENT_FUNDS";
+  currentBalanceUSD;
+  requiredUSD;
+  walletAddress;
+  constructor(opts) {
+    super(
+      `Insufficient USDC balance. Current: ${opts.currentBalanceUSD}, Required: ${opts.requiredUSD}. Fund wallet: ${opts.walletAddress}`
+    );
+    this.name = "InsufficientFundsError";
+    this.currentBalanceUSD = opts.currentBalanceUSD;
+    this.requiredUSD = opts.requiredUSD;
+    this.walletAddress = opts.walletAddress;
+  }
+};
+var EmptyWalletError = class extends Error {
+  code = "EMPTY_WALLET";
+  walletAddress;
+  constructor(walletAddress) {
+    super(`No USDC balance. Fund wallet to use ClawRouter: ${walletAddress}`);
+    this.name = "EmptyWalletError";
+    this.walletAddress = walletAddress;
+  }
+};
+function isInsufficientFundsError(error) {
+  return error instanceof Error && error.code === "INSUFFICIENT_FUNDS";
+}
+function isEmptyWalletError(error) {
+  return error instanceof Error && error.code === "EMPTY_WALLET";
+}
+function isBalanceError(error) {
+  return isInsufficientFundsError(error) || isEmptyWalletError(error);
+}
+var RpcError = class extends Error {
+  code = "RPC_ERROR";
+  originalError;
+  constructor(message, originalError) {
+    super(`RPC error: ${message}. Check network connectivity.`);
+    this.name = "RpcError";
+    this.originalError = originalError;
+  }
+};
+function isRpcError(error) {
+  return error instanceof Error && error.code === "RPC_ERROR";
+}
+
+// src/balance.ts
+var USDC_BASE2 = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+var CACHE_TTL_MS = 3e4;
+var BALANCE_THRESHOLDS = {
+  /** Low balance warning threshold: $1.00 */
+  LOW_BALANCE_MICROS: 1000000n,
+  /** Effectively zero threshold: $0.0001 (covers dust/rounding) */
+  ZERO_THRESHOLD: 100n
+};
+var BalanceMonitor = class {
+  client;
+  walletAddress;
+  /** Cached balance (null = not yet fetched) */
+  cachedBalance = null;
+  /** Timestamp when cache was last updated */
+  cachedAt = 0;
+  constructor(walletAddress) {
+    this.walletAddress = walletAddress;
+    this.client = createPublicClient({
+      chain: base,
+      transport: http()
+    });
+  }
+  /**
+   * Check current USDC balance.
+   * Uses cache if valid, otherwise fetches from RPC.
+   */
+  async checkBalance() {
+    const now = Date.now();
+    if (this.cachedBalance !== null && now - this.cachedAt < CACHE_TTL_MS) {
+      return this.buildInfo(this.cachedBalance);
+    }
+    const balance = await this.fetchBalance();
+    this.cachedBalance = balance;
+    this.cachedAt = now;
+    return this.buildInfo(balance);
+  }
+  /**
+   * Check if balance is sufficient for an estimated cost.
+   *
+   * @param estimatedCostMicros - Estimated cost in USDC smallest unit (6 decimals)
+   */
+  async checkSufficient(estimatedCostMicros) {
+    const info = await this.checkBalance();
+    if (info.balance >= estimatedCostMicros) {
+      return { sufficient: true, info };
+    }
+    const shortfall = estimatedCostMicros - info.balance;
+    return {
+      sufficient: false,
+      info,
+      shortfall: this.formatUSDC(shortfall)
+    };
+  }
+  /**
+   * Optimistically deduct estimated cost from cached balance.
+   * Call this after a successful payment to keep cache accurate.
+   *
+   * @param amountMicros - Amount to deduct in USDC smallest unit
+   */
+  deductEstimated(amountMicros) {
+    if (this.cachedBalance !== null && this.cachedBalance >= amountMicros) {
+      this.cachedBalance -= amountMicros;
+    }
+  }
+  /**
+   * Invalidate cache, forcing next checkBalance() to fetch from RPC.
+   * Call this after a payment failure to get accurate balance.
+   */
+  invalidate() {
+    this.cachedBalance = null;
+    this.cachedAt = 0;
+  }
+  /**
+   * Force refresh balance from RPC (ignores cache).
+   */
+  async refresh() {
+    this.invalidate();
+    return this.checkBalance();
+  }
+  /**
+   * Format USDC amount (in micros) as "$X.XX".
+   */
+  formatUSDC(amountMicros) {
+    const dollars = Number(amountMicros) / 1e6;
+    return `$${dollars.toFixed(2)}`;
+  }
+  /**
+   * Get the wallet address being monitored.
+   */
+  getWalletAddress() {
+    return this.walletAddress;
+  }
+  /** Fetch balance from RPC */
+  async fetchBalance() {
+    try {
+      const balance = await this.client.readContract({
+        address: USDC_BASE2,
+        abi: erc20Abi,
+        functionName: "balanceOf",
+        args: [this.walletAddress]
+      });
+      return balance;
+    } catch (error) {
+      throw new RpcError(error instanceof Error ? error.message : "Unknown error", error);
+    }
+  }
+  /** Build BalanceInfo from raw balance */
+  buildInfo(balance) {
+    return {
+      balance,
+      balanceUSD: this.formatUSDC(balance),
+      isLow: balance < BALANCE_THRESHOLDS.LOW_BALANCE_MICROS,
+      isEmpty: balance < BALANCE_THRESHOLDS.ZERO_THRESHOLD,
+      walletAddress: this.walletAddress
+    };
+  }
+};
+
 // src/proxy.ts
 var BLOCKRUN_API = "https://blockrun.ai/api";
 var AUTO_MODEL = "blockrun/auto";
-var USER_AGENT = "clawrouter/0.3.1";
+var USER_AGENT = "clawrouter/0.3.2";
 var HEARTBEAT_INTERVAL_MS = 2e3;
+var DEFAULT_REQUEST_TIMEOUT_MS = 18e4;
 function buildModelPricing() {
   const map = /* @__PURE__ */ new Map();
   for (const m of BLOCKRUN_MODELS) {
@@ -958,13 +1350,14 @@ function estimateAmount(modelId, bodyLength, maxTokens) {
   const estimatedInputTokens = Math.ceil(bodyLength / 4);
   const estimatedOutputTokens = maxTokens || model.maxOutput || 4096;
   const costUsd = estimatedInputTokens / 1e6 * model.inputPrice + estimatedOutputTokens / 1e6 * model.outputPrice;
-  const amountMicros = Math.ceil(costUsd * 1.2 * 1e6);
+  const amountMicros = Math.max(100, Math.ceil(costUsd * 1.2 * 1e6));
   return amountMicros.toString();
 }
 async function startProxy(options) {
   const apiBase = options.apiBase ?? BLOCKRUN_API;
   const account = privateKeyToAccount3(options.walletKey);
-  const { fetch: payFetch, cache: paymentCache } = createPaymentFetch(options.walletKey);
+  const { fetch: payFetch } = createPaymentFetch(options.walletKey);
+  const balanceMonitor = new BalanceMonitor(account.address);
   const routingConfig = mergeRoutingConfig(options.routingConfig);
   const modelPricing = buildModelPricing();
   const routerOpts = {
@@ -973,9 +1366,25 @@ async function startProxy(options) {
   };
   const deduplicator = new RequestDeduplicator();
   const server = createServer(async (req, res) => {
-    if (req.url === "/health") {
+    if (req.url === "/health" || req.url?.startsWith("/health?")) {
+      const url = new URL(req.url, "http://localhost");
+      const full = url.searchParams.get("full") === "true";
+      const response = {
+        status: "ok",
+        wallet: account.address
+      };
+      if (full) {
+        try {
+          const balanceInfo = await balanceMonitor.checkBalance();
+          response.balance = balanceInfo.balanceUSD;
+          response.isLow = balanceInfo.isLow;
+          response.isEmpty = balanceInfo.isEmpty;
+        } catch {
+          response.balanceError = "Could not fetch balance";
+        }
+      }
       res.writeHead(200, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({ status: "ok", wallet: account.address }));
+      res.end(JSON.stringify(response));
       return;
     }
     if (!req.url?.startsWith("/v1")) {
@@ -984,19 +1393,32 @@ async function startProxy(options) {
       return;
     }
     try {
-      await proxyRequest(req, res, apiBase, payFetch, options, routerOpts, deduplicator);
+      await proxyRequest(
+        req,
+        res,
+        apiBase,
+        payFetch,
+        options,
+        routerOpts,
+        deduplicator,
+        balanceMonitor
+      );
     } catch (err) {
       const error = err instanceof Error ? err : new Error(String(err));
       options.onError?.(error);
       if (!res.headersSent) {
         res.writeHead(502, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({
-          error: { message: `Proxy error: ${error.message}`, type: "proxy_error" }
-        }));
+        res.end(
+          JSON.stringify({
+            error: { message: `Proxy error: ${error.message}`, type: "proxy_error" }
+          })
+        );
       } else if (!res.writableEnded) {
-        res.write(`data: ${JSON.stringify({ error: { message: error.message, type: "proxy_error" } })}
+        res.write(
+          `data: ${JSON.stringify({ error: { message: error.message, type: "proxy_error" } })}
 
-`);
+`
+        );
         res.write("data: [DONE]\n\n");
         res.end();
       }
@@ -1013,6 +1435,8 @@ async function startProxy(options) {
       resolve({
         port,
         baseUrl,
+        walletAddress: account.address,
+        balanceMonitor,
         close: () => new Promise((res, rej) => {
           server.close((err) => err ? rej(err) : res());
         })
@@ -1020,7 +1444,7 @@ async function startProxy(options) {
     });
   });
 }
-async function proxyRequest(req, res, apiBase, payFetch, options, routerOpts, deduplicator) {
+async function proxyRequest(req, res, apiBase, payFetch, options, routerOpts, deduplicator, balanceMonitor) {
   const startTime = Date.now();
   const upstreamUrl = `${apiBase}${req.url}`;
   const bodyChunks = [];
@@ -1077,13 +1501,51 @@ async function proxyRequest(req, res, apiBase, payFetch, options, routerOpts, de
     return;
   }
   deduplicator.markInflight(dedupKey);
+  let estimatedCostMicros;
+  if (modelId) {
+    const estimated = estimateAmount(modelId, body.length, maxTokens);
+    if (estimated) {
+      estimatedCostMicros = BigInt(estimated);
+      const sufficiency = await balanceMonitor.checkSufficient(estimatedCostMicros);
+      if (sufficiency.info.isEmpty) {
+        deduplicator.removeInflight(dedupKey);
+        const error = new EmptyWalletError(sufficiency.info.walletAddress);
+        options.onInsufficientFunds?.({
+          balanceUSD: sufficiency.info.balanceUSD,
+          requiredUSD: balanceMonitor.formatUSDC(estimatedCostMicros),
+          walletAddress: sufficiency.info.walletAddress
+        });
+        throw error;
+      }
+      if (!sufficiency.sufficient) {
+        deduplicator.removeInflight(dedupKey);
+        const error = new InsufficientFundsError({
+          currentBalanceUSD: sufficiency.info.balanceUSD,
+          requiredUSD: balanceMonitor.formatUSDC(estimatedCostMicros),
+          walletAddress: sufficiency.info.walletAddress
+        });
+        options.onInsufficientFunds?.({
+          balanceUSD: sufficiency.info.balanceUSD,
+          requiredUSD: balanceMonitor.formatUSDC(estimatedCostMicros),
+          walletAddress: sufficiency.info.walletAddress
+        });
+        throw error;
+      }
+      if (sufficiency.info.isLow) {
+        options.onLowBalance?.({
+          balanceUSD: sufficiency.info.balanceUSD,
+          walletAddress: sufficiency.info.walletAddress
+        });
+      }
+    }
+  }
   let heartbeatInterval;
   let headersSentEarly = false;
   if (isStreaming) {
     res.writeHead(200, {
       "content-type": "text/event-stream",
       "cache-control": "no-cache",
-      "connection": "keep-alive"
+      connection: "keep-alive"
     });
     headersSentEarly = true;
     res.write(": heartbeat\n\n");
@@ -1095,7 +1557,8 @@ async function proxyRequest(req, res, apiBase, payFetch, options, routerOpts, de
   }
   const headers = {};
   for (const [key, value] of Object.entries(req.headers)) {
-    if (key === "host" || key === "connection" || key === "transfer-encoding" || key === "content-length") continue;
+    if (key === "host" || key === "connection" || key === "transfer-encoding" || key === "content-length")
+      continue;
     if (typeof value === "string") {
       headers[key] = value;
     }
@@ -1105,18 +1568,34 @@ async function proxyRequest(req, res, apiBase, payFetch, options, routerOpts, de
   }
   headers["user-agent"] = USER_AGENT;
   let preAuth;
-  if (modelId) {
-    const estimated = estimateAmount(modelId, body.length, maxTokens);
-    if (estimated) {
-      preAuth = { estimatedAmount: estimated };
-    }
+  if (estimatedCostMicros !== void 0) {
+    preAuth = { estimatedAmount: estimatedCostMicros.toString() };
   }
+  let completed = false;
+  res.on("close", () => {
+    if (heartbeatInterval) {
+      clearInterval(heartbeatInterval);
+      heartbeatInterval = void 0;
+    }
+    if (!completed) {
+      deduplicator.removeInflight(dedupKey);
+    }
+  });
+  const timeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
   try {
-    const upstream = await payFetch(upstreamUrl, {
-      method: req.method ?? "POST",
-      headers,
-      body: body.length > 0 ? body : void 0
-    }, preAuth);
+    const upstream = await payFetch(
+      upstreamUrl,
+      {
+        method: req.method ?? "POST",
+        headers,
+        body: body.length > 0 ? body : void 0,
+        signal: controller.signal
+      },
+      preAuth
+    );
+    clearTimeout(timeoutId);
     if (heartbeatInterval) {
       clearInterval(heartbeatInterval);
       heartbeatInterval = void 0;
@@ -1189,11 +1668,21 @@ async function proxyRequest(req, res, apiBase, payFetch, options, routerOpts, de
         completedAt: Date.now()
       });
     }
+    if (estimatedCostMicros !== void 0) {
+      balanceMonitor.deductEstimated(estimatedCostMicros);
+    }
+    completed = true;
   } catch (err) {
+    clearTimeout(timeoutId);
     if (heartbeatInterval) {
       clearInterval(heartbeatInterval);
+      heartbeatInterval = void 0;
     }
     deduplicator.removeInflight(dedupKey);
+    balanceMonitor.invalidate();
+    if (err instanceof Error && err.name === "AbortError") {
+      throw new Error(`Request timed out after ${timeoutMs}ms`);
+    }
     throw err;
   }
   if (routingDecision) {
@@ -1208,6 +1697,62 @@ async function proxyRequest(req, res, apiBase, payFetch, options, routerOpts, de
   }
 }
 
+// src/retry.ts
+var DEFAULT_RETRY_CONFIG = {
+  maxRetries: 2,
+  baseDelayMs: 500,
+  retryableCodes: [429, 502, 503, 504]
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function fetchWithRetry(fetchFn, url, init, config) {
+  const cfg = {
+    ...DEFAULT_RETRY_CONFIG,
+    ...config
+  };
+  let lastError;
+  let lastResponse;
+  for (let attempt = 0; attempt <= cfg.maxRetries; attempt++) {
+    try {
+      const response = await fetchFn(url, init);
+      if (!cfg.retryableCodes.includes(response.status)) {
+        return response;
+      }
+      lastResponse = response;
+      const retryAfter = response.headers.get("retry-after");
+      let delay;
+      if (retryAfter) {
+        const seconds = parseInt(retryAfter, 10);
+        delay = isNaN(seconds) ? cfg.baseDelayMs * Math.pow(2, attempt) : seconds * 1e3;
+      } else {
+        delay = cfg.baseDelayMs * Math.pow(2, attempt);
+      }
+      if (attempt < cfg.maxRetries) {
+        await sleep(delay);
+      }
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+      if (attempt < cfg.maxRetries) {
+        const delay = cfg.baseDelayMs * Math.pow(2, attempt);
+        await sleep(delay);
+      }
+    }
+  }
+  if (lastResponse) {
+    return lastResponse;
+  }
+  throw lastError ?? new Error("Max retries exceeded");
+}
+function isRetryable(errorOrResponse, config) {
+  const retryableCodes = config?.retryableCodes ?? DEFAULT_RETRY_CONFIG.retryableCodes;
+  if (errorOrResponse instanceof Response) {
+    return retryableCodes.includes(errorOrResponse.status);
+  }
+  const message = errorOrResponse.message.toLowerCase();
+  return message.includes("network") || message.includes("timeout") || message.includes("econnreset") || message.includes("econnrefused") || message.includes("socket hang up");
+}
+
 // src/index.ts
 async function startProxyInBackground(api) {
   const { key: walletKey, address, source } = await resolveOrGenerateWalletKey();
@@ -1219,6 +1764,23 @@ async function startProxyInBackground(api) {
   } else {
     api.logger.info(`Using wallet from BLOCKRUN_WALLET_KEY: ${address}`);
   }
+  const startupMonitor = new BalanceMonitor(address);
+  try {
+    const startupBalance = await startupMonitor.checkBalance();
+    if (startupBalance.isEmpty) {
+      api.logger.warn(`[!] No USDC balance. Fund wallet to use ClawRouter: ${address}`);
+    } else if (startupBalance.isLow) {
+      api.logger.warn(
+        `[!] Low balance: ${startupBalance.balanceUSD} remaining. Fund wallet: ${address}`
+      );
+    } else {
+      api.logger.info(`Wallet balance: ${startupBalance.balanceUSD}`);
+    }
+  } catch (err) {
+    api.logger.warn(
+      `Could not check wallet balance: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
   const routingConfig = api.pluginConfig?.routing;
   const proxy = await startProxy({
     walletKey,
@@ -1233,6 +1795,14 @@ async function startProxyInBackground(api) {
       const cost = decision.costEstimate.toFixed(4);
       const saved = (decision.savings * 100).toFixed(0);
       api.logger.info(`${decision.model} $${cost} (saved ${saved}%)`);
+    },
+    onLowBalance: (info) => {
+      api.logger.warn(`[!] Low balance: ${info.balanceUSD}. Fund wallet: ${info.walletAddress}`);
+    },
+    onInsufficientFunds: (info) => {
+      api.logger.error(
+        `[!] Insufficient funds. Balance: ${info.balanceUSD}, Needed: ${info.requiredUSD}. Fund wallet: ${info.walletAddress}`
+      );
     }
   });
   setActiveProxy(proxy);
@@ -1242,7 +1812,7 @@ var plugin = {
   id: "clawrouter",
   name: "ClawRouter",
   description: "Smart LLM router \u2014 30+ models, x402 micropayments, 78% cost savings",
-  version: "0.3.1",
+  version: "0.3.2",
   register(api) {
     api.registerProvider(blockrunProvider);
     api.logger.info("BlockRun provider registered (30+ models via x402)");
@@ -1255,15 +1825,27 @@ var plugin = {
 };
 var index_default = plugin;
 export {
+  BALANCE_THRESHOLDS,
   BLOCKRUN_MODELS,
+  BalanceMonitor,
+  DEFAULT_RETRY_CONFIG,
   DEFAULT_ROUTING_CONFIG,
+  EmptyWalletError,
+  InsufficientFundsError,
   OPENCLAW_MODELS,
   PaymentCache,
   RequestDeduplicator,
+  RpcError,
   blockrunProvider,
   buildProviderModels,
   createPaymentFetch,
   index_default as default,
+  fetchWithRetry,
+  isBalanceError,
+  isEmptyWalletError,
+  isInsufficientFundsError,
+  isRetryable,
+  isRpcError,
   logUsage,
   route,
   startProxy