@blockrun/clawrouter 0.12.268 → 0.12.270

package/dist/index.js

@@ -783,8 +783,8 @@ var init_models = __esm({
         id: "openai/gpt-5.6-sol",
         name: "GPT-5.6 Sol",
         version: "5.6",
-        inputPrice: 5,
-        outputPrice: 30,
+        inputPrice: 4,
+        outputPrice: 20,
         contextWindow: 105e4,
         maxOutput: 128e3,
         reasoning: true,
@@ -825,8 +825,8 @@ var init_models = __esm({
         id: "openai/gpt-5.6-sol-pro",
         name: "GPT-5.6 Sol Pro",
         version: "5.6",
-        inputPrice: 5,
-        outputPrice: 30,
+        inputPrice: 4,
+        outputPrice: 20,
         contextWindow: 105e4,
         maxOutput: 128e3,
         reasoning: true,
@@ -1264,8 +1264,8 @@ var init_models = __esm({
         id: "google/gemini-3.6-flash",
         name: "Gemini 3.6 Flash",
         version: "3.6",
-        inputPrice: 1.5,
-        outputPrice: 7.5,
+        inputPrice: 0.75,
+        outputPrice: 3.75,
         contextWindow: 1048576,
         maxOutput: 65536,
         reasoning: true,
@@ -1661,8 +1661,8 @@ var init_models = __esm({
         id: "xai/grok-4.5",
         name: "Grok 4.5",
         version: "4.5",
-        inputPrice: 2.5,
-        outputPrice: 9,
+        inputPrice: 2,
+        outputPrice: 6,
         contextWindow: 5e5,
         maxOutput: 16384,
         reasoning: true,
@@ -1676,8 +1676,8 @@ var init_models = __esm({
         id: "xai/grok-4.3",
         name: "Grok 4.3",
         version: "4.3",
-        inputPrice: 1.5,
-        outputPrice: 4,
+        inputPrice: 1.25,
+        outputPrice: 2.5,
         contextWindow: 1e6,
         maxOutput: 16384,
         reasoning: true,
@@ -1689,8 +1689,8 @@ var init_models = __esm({
         id: "xai/grok-build-0.1",
         name: "Grok Build 0.1",
         version: "0.1",
-        inputPrice: 1.5,
-        outputPrice: 3,
+        inputPrice: 1,
+        outputPrice: 2,
         contextWindow: 256e3,
         maxOutput: 16384,
         agentic: true,
@@ -34446,6 +34446,11 @@ function canonicalLimits(limits) {
     Object.fromEntries(Object.entries(limits).sort(([a], [b]) => a < b ? -1 : 1))
   );
 }
+function getSharedSpendControl() {
+  const host = sharedControlHost();
+  host.__clawrouterSharedSpendControl ??= new SpendControl();
+  return host.__clawrouterSharedSpendControl;
+}
 function parseQuotedAmountUsd(selected) {
   const raw = selected.amount ?? selected.maxAmountRequired;
   if (typeof raw !== "string" || !CANONICAL_AMOUNT.test(raw)) {
@@ -34521,7 +34526,7 @@ function formatDuration(seconds) {
     return mins > 0 ? `${hours}h ${mins}m` : `${hours}h`;
   }
 }
-var WALLET_DIR, HOUR_MS, DAY_MS, CAIP2_BASE, CAIP2_SOLANA_MAINNET, PAYABLE_NETWORKS, POLICY_LISTS, ADDRESS_LISTS, EVM_ADDRESS, MalformedSpendPolicyError, SpendPolicyConflictError, FileSpendControlStorage, InMemorySpendControlStorage, RESERVATION_TTL_MS, SpendControl, SpendPolicyError, CANONICAL_AMOUNT;
+var WALLET_DIR, HOUR_MS, DAY_MS, CAIP2_BASE, CAIP2_SOLANA_MAINNET, PAYABLE_NETWORKS, POLICY_LISTS, ADDRESS_LISTS, EVM_ADDRESS, UnreadableSpendPolicyError, MalformedSpendPolicyError, SpendPolicyConflictError, FileSpendControlStorage, InMemorySpendControlStorage, RESERVATION_TTL_MS, SpendControl, sharedControlHost, SpendPolicyError, CANONICAL_AMOUNT;
 var init_spend_control = __esm({
   "src/spend-control.ts"() {
     "use strict";
@@ -34540,6 +34545,12 @@ var init_spend_control = __esm({
     ];
     ADDRESS_LISTS = ["allowedPayees", "blockedPayees", "allowedAssets"];
     EVM_ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+    UnreadableSpendPolicyError = class extends Error {
+      constructor(cause) {
+        super(`[ClawRouter] Failed to load spending data: ${cause}`);
+        this.name = "UnreadableSpendPolicyError";
+      }
+    };
     MalformedSpendPolicyError = class extends Error {
       constructor(key2) {
         super(
@@ -34600,9 +34611,7 @@ var init_spend_control = __esm({
           if (err instanceof MalformedSpendPolicyError) {
             throw err;
           }
-          console.error(
-            `[ClawRouter] Failed to load spending data, starting fresh (any configured spend policy is NOT in effect until this file is repaired): ${err}`
-          );
+          throw new UnreadableSpendPolicyError(err);
         }
         return null;
       }
@@ -34743,6 +34752,33 @@ var init_spend_control = __esm({
       getPolicyFileError() {
         return this.policyFileBroken;
       }
+      /**
+       * Re-read limits from storage, keeping this instance's history and open
+       * reservations. Used on an in-process proxy restart so a hand-edit to
+       * spending.json made while the process was running still applies, without
+       * resetting the rolling windows. Fails closed exactly like the constructor:
+       * a malformed file refuses every payment until repaired, and a repaired
+       * file clears that refusal.
+       */
+      reloadLimits() {
+        let data;
+        try {
+          data = this.storage.load();
+        } catch (err) {
+          if (err instanceof UnreadableSpendPolicyError) {
+            console.error(`${err.message} \u2014 keeping the limits already in effect`);
+            return;
+          }
+          if (!(err instanceof MalformedSpendPolicyError)) throw err;
+          this.policyFileBroken = err.message;
+          console.error(`[ClawRouter] ${err.message}`);
+          return;
+        }
+        this.policyFileBroken = void 0;
+        this.limits = data ? cloneLimits(data.limits) : {};
+        this.diskLimits = cloneLimits(this.limits);
+        this.limitsDirty = false;
+      }
       check(estimatedCost2, counterparty) {
         if (this.policyFileBroken !== void 0) {
           return {
@@ -34987,6 +35023,16 @@ var init_spend_control = __esm({
         const records = [...this.history].reverse();
         return limit ? records.slice(0, limit) : records;
       }
+      /**
+       * Reset the session window. `sessionSpent`/`sessionCalls` are instance state
+       * that is never persisted, so this used to happen implicitly: every
+       * startProxy() built a fresh SpendControl. The process-wide ledger outlives
+       * an in-process proxy restart, which would silently redefine `session` as
+       * "since the gateway booted" — docs/configuration.md and the /policy help
+       * both promise "session resets on restart". The restart path in index.ts
+       * calls this to keep that promise. History and the rolling hourly/daily
+       * windows are deliberately untouched.
+       */
       resetSession() {
         this.sessionSpent = 0;
         this.sessionCalls = 0;
@@ -35008,10 +35054,13 @@ var init_spend_control = __esm({
             this.storage.saveLimits(cloneLimits(this.limits), cloneLimits(this.diskLimits));
           } catch (err) {
             if (err instanceof SpendPolicyConflictError) {
-              const current = this.storage.load();
-              this.limits = cloneLimits(current?.limits ?? {});
-              this.diskLimits = cloneLimits(this.limits);
-              this.limitsDirty = false;
+              try {
+                const current = this.storage.load();
+                this.limits = cloneLimits(current?.limits ?? {});
+                this.diskLimits = cloneLimits(this.limits);
+                this.limitsDirty = false;
+              } catch {
+              }
             }
             throw err;
           }
@@ -35029,6 +35078,12 @@ var init_spend_control = __esm({
         try {
           data = this.storage.load();
         } catch (err) {
+          if (err instanceof UnreadableSpendPolicyError) {
+            console.error(
+              `${err.message} \u2014 starting fresh (any configured spend policy is NOT in effect until this file is repaired)`
+            );
+            return;
+          }
           if (!(err instanceof MalformedSpendPolicyError)) throw err;
           this.policyFileBroken = err.message;
           console.error(`[ClawRouter] ${err.message}`);
@@ -35045,6 +35100,7 @@ var init_spend_control = __esm({
         }
       }
     };
+    sharedControlHost = () => process;
     SpendPolicyError = class extends Error {
       blockedBy;
       blockedByPolicy;
@@ -35082,6 +35138,21 @@ function createPayFetchWithPreAuth(baseFetch, client, ttlMs = DEFAULT_TTL_MS, op
       }
     }
     const cacheKey2 = `${urlPath}:${requestModel}`;
+    const notifyAcceptedPayment = (response2, payload2) => {
+      const settled = response2.headers.has("payment-response") || response2.headers.has("x-payment-response");
+      if (!settled || !options?.onPayment) return;
+      try {
+        options.onPayment({
+          model: requestModel,
+          amount: payload2.accepted.amount,
+          network: payload2.accepted.network
+        });
+      } catch (error) {
+        console.error(
+          `[ClawRouter] onPayment callback failed: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    };
     const estimateMicros = () => {
       if (!options?.estimateAmount || !requestModel) return void 0;
       const est = options.estimateAmount(requestModel, bodyLength, maxTokens);
@@ -35102,6 +35173,7 @@ function createPayFetchWithPreAuth(baseFetch, client, ttlMs = DEFAULT_TTL_MS, op
         paymentInFlight = true;
         const response2 = await baseFetch(preAuthRequest);
         if (response2.status !== 402) {
+          notifyAcceptedPayment(response2, payload2);
           return response2;
         }
         paymentInFlight = false;
@@ -35148,7 +35220,9 @@ function createPayFetchWithPreAuth(baseFetch, client, ttlMs = DEFAULT_TTL_MS, op
     for (const [key2, value] of Object.entries(paymentHeaders)) {
       clonedRequest.headers.set(key2, value);
     }
-    return baseFetch(clonedRequest);
+    const paidResponse = await baseFetch(clonedRequest);
+    notifyAcceptedPayment(paidResponse, payload);
+    return paidResponse;
   };
 }
 var DEFAULT_TTL_MS;
@@ -59787,13 +59861,18 @@ async function loadPaymentChain() {
   const core = await readOptional(CORE_CHAIN_FILE);
   if (core === "solana") return "solana";
   if (core === "base") return "base";
-  try {
-    const content = (await readTextFile(CHAIN_FILE)).trim();
-    if (content === "solana") return "solana";
-    return "base";
-  } catch {
-    return "base";
-  }
+  const legacy = await readOptional(CHAIN_FILE);
+  if (legacy === "solana") return "solana";
+  if (legacy === "base") return "base";
+  return await hasExistingWallet() ? "base" : "solana";
+}
+async function hasExistingWallet() {
+  if (process["env"].BLOCKRUN_WALLET_KEY?.trim()) return true;
+  const [core, legacy] = await Promise.all([
+    readOptional(CORE_WALLET_FILE),
+    readOptional(WALLET_FILE)
+  ]);
+  return Boolean(core || legacy);
 }
 async function resolvePaymentChain() {
   if (process["env"].CLAWROUTER_PAYMENT_CHAIN === "solana") return "solana";
@@ -59907,7 +59986,7 @@ var init_api_key = __esm({
     HINTS = {
       401: `Check BLOCKRUN_API_KEY, or mint a new key at ${PORTAL_KEYS_URL}.`,
       402: `Top up your BlockRun credit at ${PORTAL_CREDITS_URL}.`,
-      404: `api.blockrun.ai does not serve this endpoint yet \u2014 it currently carries chat and text completions. For media and partner APIs, run ClawRouter in wallet mode (unset BLOCKRUN_API_KEY and run "clawrouter logout").`
+      404: `api.blockrun.ai does not serve this endpoint. Chat, Anthropic-shaped messages, images, speech, video and the partner APIs (Surf, Exa, prediction markets, phone lookup) all work on an API key. The wallet-only exceptions are the routes that bind a lease or a position to a payer address \u2014 buying/renewing/releasing phone numbers, and Polymarket trading \u2014 which need a wallet to own the thing being bought. For those, unset BLOCKRUN_API_KEY and run "clawrouter logout".`
     };
   }
 });
@@ -91375,7 +91454,7 @@ async function startProxy(options) {
   if (x402 && account) {
     const evmPublicClient = createPublicClient({ chain: base, transport: http() });
     const evmSigner = toClientEvmSigner(account, evmPublicClient);
-    const spendControl = options.spendControl ?? new SpendControl();
+    const spendControl = options.spendControl ?? getSharedSpendControl();
     registerSpendPolicyHook(x402, spendControl);
     registerExactEvmScheme(x402, { signer: evmSigner });
   }
@@ -91407,7 +91486,11 @@ async function startProxy(options) {
     // Per-request cost estimate so pre-auth is only reused when the cached
     // payment still covers the (possibly larger) request — BlockRun prices per
     // token, so one model can cost different amounts across requests.
-    estimateAmount
+    estimateAmount,
+    // Only the wallet rail settles per call. The API-key rail is billed
+    // server-side against account credit, so there is no per-request
+    // settlement for an observer to report.
+    onPayment: options.onPayment
   });
   let balanceMonitor;
   if (options._balanceMonitorOverride) {
@@ -92287,7 +92370,8 @@ async function startProxy(options) {
         }
         return;
       }
-      if (req.url?.match(
+      const isVerbatimGatewayPath = req.url === "/v1/messages" || (req.url?.startsWith("/v1/messages?") ?? false) || req.url === "/v1/audio/speech" || (req.url?.startsWith("/v1/audio/speech?") ?? false);
+      if (isVerbatimGatewayPath || req.url?.match(
         /^\/v1\/(?:partner|pm|exa|modal|stocks|usstock|crypto|fx|commodity|phone|voice|surf)\//
       )) {
         try {
@@ -92319,6 +92403,19 @@ async function startProxy(options) {
         res.end(JSON.stringify({ error: "Not found" }));
         return;
       }
+      if (!req.url.includes("/chat/completions")) {
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(
+          JSON.stringify({
+            error: {
+              message: `ClawRouter does not proxy ${req.url}. It serves /v1/chat/completions, /v1/messages, /v1/models, /v1/images/generations, /v1/images/image2image, /v1/videos/generations, /v1/audio/generations, /v1/audio/speech, and the partner prefixes /v1/{partner,pm,exa,modal,stocks,usstock,crypto,fx,commodity,phone,voice,surf}/. If BlockRun serves this endpoint, call it directly against the gateway.`,
+              type: "invalid_request_error",
+              code: "unsupported_endpoint"
+            }
+          })
+        );
+        return;
+      }
       try {
         await proxyRequest(
           req,
@@ -117475,9 +117572,7 @@ var init_client5 = __esm({
 
 // src/polymarket/spend-policy.ts
 function resolveSpendControl(deps) {
-  if (deps?.spendControl) return deps.spendControl;
-  defaultControl ??= new SpendControl();
-  return defaultControl;
+  return deps?.spendControl ?? getSharedSpendControl();
 }
 function usdToMicros(usd) {
   return String(Math.ceil(usd * 1e6));
@@ -117494,7 +117589,6 @@ async function signUnderSpendPolicy(deps, quote, action, sign4) {
     throw err;
   }
 }
-var defaultControl;
 var init_spend_policy = __esm({
   "src/polymarket/spend-policy.ts"() {
     "use strict";
@@ -226859,7 +226953,7 @@ var init_fund = __esm({
 });
 
 // src/polymarket/tool.ts
-function buildPolymarketTool() {
+function buildPolymarketTool(deps) {
   return {
     name: "blockrun_polymarket",
     description: DESCRIPTION,
@@ -226944,26 +227038,32 @@ function buildPolymarketTool() {
           result = await runSetup({ confirm });
           break;
         case "fund":
-          result = await fundVault({
-            amount_usd: params.amount_usd,
-            confirm
-          });
+          result = await fundVault(
+            {
+              amount_usd: params.amount_usd,
+              confirm
+            },
+            deps
+          );
           break;
         case "buy":
         case "sell":
-          result = await executeTrade({
-            action,
-            token_id: params.token_id,
-            condition_id: params.condition_id,
-            outcome: params.outcome,
-            price: params.price,
-            size: params.size,
-            amount_usd: params.amount_usd,
-            order_type: params.order_type,
-            expires_at: params.expires_at,
-            post_only: params.post_only,
-            confirm
-          });
+          result = await executeTrade(
+            {
+              action,
+              token_id: params.token_id,
+              condition_id: params.condition_id,
+              outcome: params.outcome,
+              price: params.price,
+              size: params.size,
+              amount_usd: params.amount_usd,
+              order_type: params.order_type,
+              expires_at: params.expires_at,
+              post_only: params.post_only,
+              confirm
+            },
+            deps
+          );
           break;
         case "orders":
           result = await listOpenOrders({
@@ -226980,17 +227080,23 @@ function buildPolymarketTool() {
           result = await listPositions();
           break;
         case "redeem":
-          result = await redeemPosition({
-            condition_id: params.condition_id,
-            confirm
-          });
+          result = await redeemPosition(
+            {
+              condition_id: params.condition_id,
+              confirm
+            },
+            deps
+          );
           break;
         case "withdraw":
-          result = await withdrawFunds({
-            amount_usd: params.amount_usd,
-            to_address: params.to_address,
-            confirm
-          });
+          result = await withdrawFunds(
+            {
+              amount_usd: params.amount_usd,
+              to_address: params.to_address,
+              confirm
+            },
+            deps
+          );
           break;
         default:
           throw new Error(`Unknown blockrun_polymarket action: ${action}`);
@@ -228110,12 +228216,18 @@ async function startProxyInBackground(api, startupGeneration) {
       `Cost cap: $${maxCostPerRunUsd.toFixed(2)} per session (mode: ${maxCostPerRunMode})`
     );
   }
+  const sharedControl = getSharedSpendControl();
+  sharedControl.reloadLimits();
+  sharedControl.resetSession();
   const proxy = await startProxy({
     ...apiKey ? { apiKey } : { wallet },
     routingConfig,
     maxCostPerRunUsd,
     maxCostPerRunMode,
-    spendControl: liveSpendControl = new SpendControl(),
+    // The process-wide ledger: the polymarket tool and the /policy command
+    // registered below use the same instance, so hourly/daily/session windows
+    // cover every surface and a /policy write reaches the live signer.
+    spendControl: sharedControl,
     onReady: (port) => {
       api.logger.info(`BlockRun ${apiKey ? "API-key" : "x402"} proxy listening on port ${port}`);
     },
@@ -228858,7 +228970,7 @@ function createWalletCommand(api) {
     }
   };
 }
-var activeProxyHandle, liveSpendControl, pendingConfiguredStartupApi, IMAGE_DIR2, AUDIO_DIR2, VIDEO_DIR2, plugin, index_default2;
+var activeProxyHandle, pendingConfiguredStartupApi, IMAGE_DIR2, AUDIO_DIR2, VIDEO_DIR2, plugin, index_default2;
 var init_index = __esm({
   "src/index.ts"() {
     init_provider();
@@ -228876,10 +228988,10 @@ var init_index = __esm({
     init_stats();
     init_partners();
     init_tool();
+    init_spend_control();
     init_stats2();
     init_exclude();
     init_policy();
-    init_spend_control();
     init_mcp_config();
     init_openclaw_plugin_config();
     init_openclaw_plugin_config();
@@ -228901,7 +229013,6 @@ var init_index = __esm({
     init_response_cache();
     init_partners();
     activeProxyHandle = null;
-    liveSpendControl = null;
     pendingConfiguredStartupApi = null;
     IMAGE_DIR2 = join17(homedir14(), ".openclaw", "blockrun", "images");
     AUDIO_DIR2 = join17(homedir14(), ".openclaw", "blockrun", "audio");
@@ -229217,7 +229328,7 @@ ${errText}`
         api.registerCommand(createExcludeCommand());
         api.registerCommand(
           createPolicyCommand({
-            liveControl: () => activeProxyHandle ? liveSpendControl ?? void 0 : void 0
+            liveControl: () => process.__clawrouterProxyStarted ? getSharedSpendControl() : void 0
           })
         );
         if (shouldLogRegistration) {
@@ -229246,7 +229357,15 @@ ${errText}`
         });
         if (!isGatewayMode()) {
           if (shouldLogRegistration) {
-            resolveOrGenerateWalletKey().then(({ address: address2, source }) => {
+            void (async () => {
+              const keyResolution = await resolveApiKey().catch(() => void 0);
+              if (keyResolution) {
+                api.logger.info(
+                  `Using BlockRun API key ${maskApiKey(keyResolution.key)} (from ${keyResolution.source}) \u2014 billing account credit, no wallet`
+                );
+                return;
+              }
+              const { address: address2, source } = await resolveOrGenerateWalletKey();
               if (source === "generated") {
                 api.logger.warn(`\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550`);
                 api.logger.warn(`  NEW WALLET GENERATED \u2014 BACK UP YOUR KEY NOW!`);
@@ -229263,7 +229382,7 @@ ${errText}`
               } else {
                 api.logger.info(`Using wallet from BLOCKRUN_WALLET_KEY: ${address2}`);
               }
-            }).catch((err) => {
+            })().catch((err) => {
               api.logger.warn(
                 `Failed to initialize wallet: ${err instanceof Error ? err.message : String(err)}`
               );
@@ -229415,6 +229534,7 @@ export {
   SolanaBalanceMonitor,
   SpendControl,
   SpendPolicyError,
+  UnreadableSpendPolicyError,
   VISIBLE_OPENCLAW_MODELS,
   blockrunProvider,
   buildImageGenerationProvider,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/clawrouter",
-  "version": "0.12.268",
+  "version": "0.12.270",
   "description": "Smart LLM router — save 84% on inference costs. 76 models (7 free). Pay by credit card (API key) or USDC (x402 wallet).",
   "type": "module",
   "main": "dist/index.js",

package/skills/clawrouter/SKILL.md

@@ -53,7 +53,7 @@ metadata:
 
 # ClawRouter
 
-Hosted-gateway LLM router that saves <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->% on inference costs by forwarding each request to the blockrun.ai gateway, which picks the cheapest model capable of handling it across <!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> models from 9 providers (<!-- br:models.free -->7<!-- /br:models.free --> free open-weight models). All billing flows through one USDC wallet; you do not hold provider API keys.
+Hosted-gateway LLM router that saves <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->% on inference costs by forwarding each request to the blockrun.ai gateway, which picks the cheapest model capable of handling it across <!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> models from 9 providers (<!-- br:models.free -->7<!-- /br:models.free --> free open-weight models). All billing flows through one BlockRun credential — either a USDC wallet paying x402 per call, or a BlockRun API key drawing on card-funded account credit. Either way you do not hold provider API keys.
 
 **This is not a local-inference tool.** ClawRouter is a thin local proxy. Your prompts are sent over HTTPS to the blockrun.ai gateway for model execution. If your workload requires inference that never leaves your machine, use a local runtime like Ollama — ClawRouter is not the right tool for that use case.
 
@@ -69,7 +69,7 @@ Your app → localhost proxy (ClawRouter) → https://blockrun.ai/api  (or sol.b
                                         Response → back through proxy → your app
 ```
 
-**Sent to blockrun.ai on every request:** the model name, the full prompt/messages body, sampling params (temperature, max_tokens, tools, etc.), and an `X-PAYMENT` header containing a signed x402 USDC micropayment.
+**Sent to blockrun.ai on every request:** the model name, the full prompt/messages body, sampling params (temperature, max_tokens, tools, etc.), and a payment credential — an `X-PAYMENT` header containing a signed x402 USDC micropayment in wallet mode, or an `Authorization: Bearer brk_live_…` header in API-key mode.
 
 **Not sent:** your wallet private key (only the detached payment signature is sent), any other local files, environment variables, or OpenClaw config beyond what's needed for this request.
 
@@ -81,12 +81,12 @@ ClawRouter does **not** collect or forward third-party provider API keys. You do
 
 **What `models.providers.blockrun` stores (fully enumerated):**
 
-| Field       | Sensitive | Purpose                                                                                                                                                                                                    |
-| ----------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `walletKey` | Yes       | EVM private key used to sign USDC micropayments via x402. **Auto-generated locally on first run** — no user input required. Never transmitted over the network; only detached payment signatures are sent. |
-| `solanaKey` | Yes       | Solana keypair (BIP-44 `m/44'/501'/0'/0'`). Auto-derived from the same local mnemonic via `@scure/bip32` + `@scure/bip39`.                                                                                 |
-| `gateway`   | No        | Gateway URL. Defaults: `https://sol.blockrun.ai/api` (Solana, default chain for new installs) · `https://blockrun.ai/api` (Base, default for pre-existing installs).                                       |
-| `routing`   | No        | Optional override of the router-core config (tier chains, `strategy: "rules"` rollback, `shadow` comparison, scorer keywords).                                                                             |
+| Field       | Sensitive           | Purpose                                                                                                                                                                                                                                                                               |
+| ----------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `walletKey` | Only in wallet mode | EVM private key used to sign USDC micropayments via x402. **Auto-generated locally on first run** — no user input required. Never transmitted over the network; only detached payment signatures are sent. Not used, read, or generated at all when a BlockRun API key is configured. |
+| `solanaKey` | Yes                 | Solana keypair (BIP-44 `m/44'/501'/0'/0'`). Auto-derived from the same local mnemonic via `@scure/bip32` + `@scure/bip39`.                                                                                                                                                            |
+| `gateway`   | No                  | Gateway URL. Defaults: `https://sol.blockrun.ai/api` (Solana, default chain for new installs) · `https://blockrun.ai/api` (Base, default for pre-existing installs).                                                                                                                  |
+| `routing`   | No                  | Optional override of the router-core config (tier chains, `strategy: "rules"` rollback, `shadow` comparison, scorer keywords).                                                                                                                                                        |
 
 **How and where keys are stored:**
 

package/skills/imagegen/SKILL.md

@@ -137,8 +137,8 @@ Response is identical to generation:
 
 ## Notes
 
-- Payment is automatic via x402 — deducted from the user's BlockRun wallet
-- If the call fails with a payment error, tell the user to fund their wallet at [blockrun.ai](https://blockrun.ai)
+- Payment is automatic, and which rail it uses depends on how ClawRouter was started: an x402 USDC micropayment from the user's wallet, or a draw on account credit if a BlockRun API key is configured. Either way the agent does nothing.
+- If the call fails with a payment error, check `GET http://localhost:8402/health` and read `authMode` before telling the user how to fix it: `wallet` → fund the wallet at [blockrun.ai](https://blockrun.ai); `api-key` → top up account credit at [user.blockrun.ai/dashboard/credits](https://user.blockrun.ai/dashboard/credits). Naming the wrong one sends the user to a page that cannot fix their error.
 - Google models may return base64 internally — ClawRouter uploads automatically and returns a hosted URL
 - OpenAI image models enforce OpenAI content policy; use `nano-banana` or `grok-imagine` for more flexibility
 - Image editing is only available with `gpt-image-1`; generation supports all listed models

package/skills/phone/SKILL.md

@@ -200,8 +200,9 @@ GET `http://localhost:8402/v1/voice/call/{call_id}`. Returns:
 
 ## Notes
 
-- Payment is automatic via x402 — deducted from the user's BlockRun wallet on every call
-- If a call fails with a 402, tell the user to fund their wallet at [blockrun.ai](https://blockrun.ai)
+- Payment is automatic on every call — an x402 USDC micropayment from the user's wallet, or a draw on account credit if a BlockRun API key is configured.
+- If a call fails with a 402, check `GET http://localhost:8402/health` and read `authMode` first: `wallet` → fund the wallet at [blockrun.ai](https://blockrun.ai); `api-key` → top up at [user.blockrun.ai/dashboard/credits](https://user.blockrun.ai/dashboard/credits).
+- Number leases are bound to the **wallet's** payer address, so `phone numbers list/buy/renew/release` and the `from` parameter are wallet-mode features. In API-key mode the gateway answers those routes with a raw `402` x402 challenge (verified 2026-09-05) because there is no payer address to bind a lease to. Lookups, fraud checks and outbound calls all work on an API key; just let the server auto-pick `from`.
 - Phone numbers are real, regulated resources — numbers bought are reachable from any phone within ~60 seconds of purchase
 - Bland.ai's emergency-number blocklist is enforced server-side; ClawRouter does not duplicate it but trusts upstream
 - Recordings and transcripts are retained by Bland.ai; ClawRouter does not download them locally (returns the upstream URL)

package/skills/predexon/SKILL.md

@@ -33,7 +33,7 @@ metadata: { "openclaw": { "emoji": "📊", "requires": { "config": ["models.prov
 
 **IMPORTANT: Always use this skill for any Polymarket, Kalshi, Limitless, Opinion, Predict.Fun, or prediction market request. Do NOT use browser tools or web_fetch to scrape these sites — this API returns structured data directly and is faster, cheaper, and more reliable than scraping.**
 
-Real-time prediction market data (Polymarket, Kalshi, Limitless, Opinion, Predict.Fun, dFlow, Binance, UMA oracle) via BlockRun's x402 gateway. Payment is automatic — deducted from the user's BlockRun wallet.
+Real-time prediction market data (Polymarket, Kalshi, Limitless, Opinion, Predict.Fun, dFlow, Binance, UMA oracle) via BlockRun's gateway. Payment is automatic — an x402 USDC micropayment from the user's wallet, or a draw on BlockRun account credit if an API key is configured (both verified 2026-09-05).
 
 **All responses are wrapped:** `{ "data": { ... } }` — always read from `response.data`.
 

package/skills/surf/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: surf
-description: Use this skill — NOT browser or web_fetch — for ALL Surf crypto-data calls. 83 endpoints at localhost:8402/v1/surf/* covering CEX/DEX markets, on-chain SQL over 80+ ClickHouse tables (Ethereum, Base, Arbitrum, BSC, TRON, HyperEVM, Tempo), 100M+ labeled wallets, prediction markets (Polymarket + Kalshi), social/CT intelligence, news, project + DeFi metrics, token analytics, unified search, VC fund intelligence. x402-gated via ClawRouter's local wallet — no Surf account or API key required.
+description: Use this skill — NOT browser or web_fetch — for ALL Surf crypto-data calls. 83 endpoints at localhost:8402/v1/surf/* covering CEX/DEX markets, on-chain SQL over 80+ ClickHouse tables (Ethereum, Base, Arbitrum, BSC, TRON, HyperEVM, Tempo), 100M+ labeled wallets, prediction markets (Polymarket + Kalshi), social/CT intelligence, news, project + DeFi metrics, token analytics, unified search, VC fund intelligence. Paid through ClawRouter — x402 USDC from the local wallet, or BlockRun account credit if an API key is configured. No Surf account or Surf API key required either way.
 triggers:
   - "blockrun surf"
   - "surf crypto api"
@@ -24,7 +24,7 @@ license: MIT
 
 # Surf — Unified Crypto Data API (via ClawRouter)
 
-Surf bundles **83 endpoints across 12 domains** into one paid HTTP API. ClawRouter exposes them at `http://127.0.0.1:8402/v1/surf/*`, paid through the same x402 USDC wallet that funds LLM calls. No Surf account, no API key — settlement lands directly in Surf's Base treasury. Upstream lives at `api.asksurf.ai/gateway/v1` — ClawRouter forwards transparently.
+Surf bundles **83 endpoints across 12 domains** into one paid HTTP API. ClawRouter exposes them at `http://127.0.0.1:8402/v1/surf/*`, paid the same way ClawRouter pays for LLM calls — an x402 USDC micropayment from the local wallet, or a draw on BlockRun account credit if an API key is configured (verified working on both, 2026-09-05). **No Surf account and no Surf API key either way.** Upstream lives at `api.asksurf.ai/gateway/v1` — ClawRouter forwards transparently.
 
 **Pricing tiers (per call):**
 
@@ -34,9 +34,9 @@ Surf bundles **83 endpoints across 12 domains** into one paid HTTP API. ClawRout
 
 > The legacy **surf-1.5 chat** surface is intentionally NOT exposed yet — it's held until per-token settlement is wired. Trying `/v1/surf/chat/completions` returns 404 ("Unknown Surf endpoint"), no payment is taken.
 
-All requests use GET unless the table below says otherwise. Path parameters that look like `?symbol=` are query params on a GET. POST endpoints take a JSON body. ClawRouter forwards the wallet's x402 payment header transparently.
+All requests use GET unless the table below says otherwise. Path parameters that look like `?symbol=` are query params on a GET. POST endpoints take a JSON body. ClawRouter attaches payment transparently — an x402 header in wallet mode, a bearer token in API-key mode.
 
-**Required-param pre-check.** 56 of the 83 endpoints have required query params (e.g. `pair`, `symbol`, `address`, `chain`, `q`, `interval`). The route validates them **before settlement** — call with missing params and you get `400 { missing_params, all_required, docs }` and the wallet is NOT charged. Check each row in the catalog below for the correct param name (e.g. mindshare is `q` + `interval`, not `project` + `window`).
+**Required-param pre-check.** 56 of the 83 endpoints have required query params (e.g. `pair`, `symbol`, `address`, `chain`, `q`, `interval`). The route validates them **before settlement** — call with missing params and you get `400 { missing_params, all_required, docs }` and you are NOT charged. Check each row in the catalog below for the correct param name (e.g. mindshare is `q` + `interval`, not `project` + `window`).
 
 ## When to use this skill