@blockrun/clawrouter 0.12.269 → 0.12.271

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,
@@ -40581,6 +40581,18 @@ function isBalanceError(error) {
 function isRpcError(error) {
   return error instanceof Error && error.code === "RPC_ERROR";
 }
+function describeFetchError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const cause = error?.cause;
+  if (!(cause instanceof Error)) return message;
+  const detail = cause;
+  const host = detail.hostname || detail.address;
+  const where = host && detail.port ? `${host}:${detail.port}` : host;
+  const parts = [detail.code, where, detail.code ? void 0 : detail.message].filter(
+    (part) => typeof part === "string" && part !== ""
+  );
+  return parts.length > 0 ? `${message} (${parts.join(" ")})` : message;
+}
 var InsufficientFundsError2, EmptyWalletError, RpcError2;
 var init_errors5 = __esm({
   "src/errors.ts"() {
@@ -59861,13 +59873,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";
@@ -59934,6 +59951,40 @@ async function resolveApiKey() {
   }
   return void 0;
 }
+async function fetchCreditBalance(apiKey, timeoutMs = 5e3) {
+  try {
+    const controller = new AbortController();
+    const timer2 = setTimeout(() => controller.abort(), timeoutMs);
+    const res = await fetch(`${BLOCKRUN_API_KEY_API}/v1/credits`, {
+      headers: { authorization: `Bearer ${apiKey}` },
+      signal: controller.signal
+    });
+    clearTimeout(timer2);
+    if (!res.ok) return void 0;
+    const b = await res.json();
+    const num2 = (v) => typeof v === "number" ? v : null;
+    return {
+      accountId: typeof b.account_id === "string" ? b.account_id : void 0,
+      billingMode: typeof b.billing_mode === "string" ? b.billing_mode : void 0,
+      currency: typeof b.currency === "string" ? b.currency : "USD",
+      grantedUsd: num2(b.granted_usd),
+      spentUsd: num2(b.spent_usd),
+      remainingUsd: num2(b.remaining_usd),
+      blocked: b.blocked === true,
+      blockedReason: typeof b.blocked_reason === "string" ? b.blocked_reason : void 0
+    };
+  } catch {
+    return void 0;
+  }
+}
+function formatCreditBalance(b) {
+  const money = (v) => v === null ? void 0 : `$${v.toFixed(v < 0.01 && v > 0 ? 6 : 2)}`;
+  const remaining = money(b.remainingUsd);
+  const spent = money(b.spentUsd);
+  if (remaining) return `${remaining} remaining${spent ? ` (spent ${spent})` : ""}`;
+  const mode = b.billingMode === "ungated" ? "no prepaid limit" : b.billingMode ?? "unknown";
+  return `${spent ? `spent ${spent}` : "unknown"} \u2014 ${mode}`;
+}
 function createApiKeyFetch(apiKey, baseFetch = fetch) {
   return async (input, init2) => {
     const headers = new Headers(init2?.headers);
@@ -59981,7 +60032,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".`
     };
   }
 });
@@ -90455,6 +90506,24 @@ var init_client3 = __esm({
   }
 });
 
+// node_modules/@x402/svm/dist/esm/v1/index.mjs
+var v1_exports = {};
+__export(v1_exports, {
+  ExactSvmSchemeV1: () => ExactSvmSchemeV1,
+  NETWORKS: () => NETWORKS2
+});
+var init_v1 = __esm({
+  "node_modules/@x402/svm/dist/esm/v1/index.mjs"() {
+    "use strict";
+    init_chunk_WWACQNRQ();
+    init_chunk_MNNIECS4();
+    init_chunk_WIPN332D();
+    init_chunk_FVTMOTG6();
+    init_chunk_FJ6REVHH();
+    init_chunk_QEBTC3LJ();
+  }
+});
+
 // src/proxy.ts
 import { AsyncLocalStorage } from "async_hooks";
 import { createHmac } from "crypto";
@@ -91209,6 +91278,23 @@ function estimateImageCost(model, size5, n = 1) {
   const pricePerImage = sizePrice ?? pricing.default;
   return pricePerImage * n * 1.05;
 }
+function blockrunRequestId(response) {
+  if (!response) return void 0;
+  for (const name of ["x-blockrun-request-id", "x-request-id", "request-id"]) {
+    const value = response.headers.get(name)?.trim();
+    if (value) return value;
+  }
+  return void 0;
+}
+function gatewaySettledCostUsd(response) {
+  const raw = response?.headers.get("x-blockrun-cost-usd");
+  if (raw === null || raw === void 0) return void 0;
+  const trimmed = raw.trim();
+  if (trimmed === "") return void 0;
+  const value = Number(trimmed);
+  if (!Number.isFinite(value) || value < 0) return void 0;
+  return value;
+}
 async function proxyPaidApiRequest(req, res, apiBase, payFetch, getActualPaymentUsd) {
   const startTime = Date.now();
   const upstreamUrl = `${apiBase}${req.url}`;
@@ -91258,8 +91344,9 @@ async function proxyPaidApiRequest(req, res, apiBase, payFetch, getActualPayment
   res.end();
   const latencyMs = Date.now() - startTime;
   console.log(`[ClawRouter] ${requestLabel} response: ${upstream.status} (${latencyMs}ms)`);
-  const paidAmount = getActualPaymentUsd();
-  const requestCost = resolvePhoneTelemetryCost({
+  const settledCostUsd = gatewaySettledCostUsd(upstream);
+  const paidAmount = settledCostUsd ?? getActualPaymentUsd();
+  const requestCost = settledCostUsd !== void 0 ? settledCostUsd : resolvePhoneTelemetryCost({
     paidAmount,
     isPhone,
     upstreamStatus: upstream.status,
@@ -91268,6 +91355,7 @@ async function proxyPaidApiRequest(req, res, apiBase, payFetch, getActualPayment
   });
   logUsage({
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    ...blockrunRequestId(upstream) ? { requestId: blockrunRequestId(upstream) } : {},
     model: isBlockrunExa ? "blockrun-exa" : isModalSandbox ? "modal-sandbox" : isPhone ? (req.url ?? "").replace(/^\/v1\//, "").split("?")[0] : isSurf ? (req.url ?? "").replace(/^\/v1\//, "").split("?")[0] : "partner",
     tier: isPhone ? "PHONE" : isSurf ? "SURF" : "PARTNER",
     cost: requestCost,
@@ -91459,8 +91547,20 @@ async function startProxy(options) {
     const { createKeyPairSignerFromPrivateKeyBytes: createKeyPairSignerFromPrivateKeyBytes2 } = await Promise.resolve().then(() => (init_index_node37(), index_node_exports));
     const solanaSigner = await createKeyPairSignerFromPrivateKeyBytes2(solanaPrivateKeyBytes);
     solanaAddress = solanaSigner.address;
+    const solanaRpcUrl = process["env"].CLAWROUTER_SOLANA_RPC_URL;
     registerExactSvmScheme2(x402, { signer: solanaSigner });
+    if (solanaRpcUrl) {
+      const { ExactSvmScheme: ExactSvmScheme2 } = await Promise.resolve().then(() => (init_client3(), client_exports));
+      const { ExactSvmSchemeV1: ExactSvmSchemeV12, NETWORKS: SVM_V1_NETWORKS } = await Promise.resolve().then(() => (init_v1(), v1_exports));
+      x402.register("solana:*", new ExactSvmScheme2(solanaSigner, { rpcUrl: solanaRpcUrl }));
+      for (const network of SVM_V1_NETWORKS) {
+        x402.registerV1(network, new ExactSvmSchemeV12(solanaSigner, { rpcUrl: solanaRpcUrl }));
+      }
+    }
     console.log(`[ClawRouter] Solana wallet: ${solanaAddress}`);
+    if (solanaRpcUrl) {
+      console.log(`[ClawRouter] Solana RPC (payment signing + balance): ${solanaRpcUrl}`);
+    }
   }
   x402?.onAfterPaymentCreation(async (context) => {
     if (!context.selectedRequirements.network.startsWith("eip155")) return;
@@ -91560,7 +91660,15 @@ async function startProxy(options) {
               )
             ]);
             if (authMode === "api-key") {
-              response.balance = null;
+              const credit = await fetchCreditBalance(apiKey, BALANCE_CHECK_TIMEOUT_MS);
+              response.balance = credit?.remainingUsd ?? null;
+              response.creditSpent = credit?.spentUsd ?? null;
+              response.creditGranted = credit?.grantedUsd ?? null;
+              response.billingMode = credit?.billingMode ?? null;
+              response.creditSummary = credit ? formatCreditBalance(credit) : null;
+              response.blocked = credit?.blocked ?? false;
+              if (credit?.blockedReason) response.blockedReason = credit.blockedReason;
+              response.isEmpty = credit?.remainingUsd !== null && (credit?.remainingUsd ?? 1) <= 0;
               response.billing = "BlockRun account credit";
               response.topUpUrl = PORTAL_CREDITS_URL;
             } else {
@@ -92365,7 +92473,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 {
@@ -92397,6 +92506,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,
@@ -92651,7 +92773,8 @@ async function tryModelRequest(upstreamUrl, method, headers, body, modelId, maxT
         errorBody,
         errorStatus: response.status,
         isProviderError: category !== null,
-        errorCategory: category ?? void 0
+        errorCategory: category ?? void 0,
+        upstreamRequestId: blockrunRequestId(response)
       };
     }
     const contentType = response.headers.get("content-type") || "";
@@ -92688,9 +92811,12 @@ async function tryModelRequest(upstreamUrl, method, headers, body, modelId, maxT
         errorCategory: "payment_error"
       };
     }
+    const networkMsg = describeFetchError(err);
+    const solanaSigningHint = upstreamUrl.startsWith(BLOCKRUN_SOLANA_API) && networkMsg.startsWith("fetch failed") ? " \u2014 on the Solana rail this may be the RPC that signs the payment rather than the gateway; if api.mainnet-beta.solana.com is unreachable from this host, set CLAWROUTER_SOLANA_RPC_URL to your own endpoint" : "";
+    console.error(`[ClawRouter] ${modelId} network error: ${networkMsg}${solanaSigningHint}`);
     return {
       success: false,
-      errorBody: errorMsg,
+      errorBody: `${networkMsg}${solanaSigningHint}`,
       errorStatus: 500,
       isProviderError: true
       // Network errors are retryable
@@ -92723,6 +92849,7 @@ async function proxyRequest(req, res, apiBase, payFetch, options, routerOpts, de
   let accumulatedContent = "";
   let responseInputTokens;
   let responseOutputTokens;
+  let upstreamRequestId;
   let requestHadError = false;
   let requestSummaryForStore = "";
   const isChatCompletion = req.url?.includes("/chat/completions");
@@ -94129,7 +94256,8 @@ data: [DONE]
       }
       lastError = {
         body: result.errorBody || "Unknown error",
-        status: result.errorStatus || 500
+        status: result.errorStatus || 500,
+        requestId: result.upstreamRequestId
       };
       failedAttempts.push({
         model: tryModel,
@@ -94201,7 +94329,8 @@ data: [DONE]
           }
           lastError = {
             body: retryResult.errorBody || lastError?.body || "Unknown error",
-            status: retryResult.errorStatus || lastError?.status || 500
+            status: retryResult.errorStatus || lastError?.status || 500,
+            requestId: retryResult.upstreamRequestId ?? lastError?.requestId
           };
           failedAttempts.push({
             model: tryModel,
@@ -94343,10 +94472,13 @@ data: [DONE]
         }
       }
     }
+    upstreamRequestId = blockrunRequestId(upstream);
     if (!upstream) {
       const attemptSummary = failedAttempts.length > 0 ? failedAttempts.map((a) => `${a.model} (${a.reason})`).join(", ") : "unknown";
       const structuredMessage = failedAttempts.length > 0 ? `All ${failedAttempts.length} models failed. Tried: ${attemptSummary}` : "All models in fallback chain failed";
-      console.log(`[ClawRouter] ${structuredMessage}`);
+      console.log(
+        `[ClawRouter] ${structuredMessage}${lastError?.requestId ? ` | gateway request id: ${lastError.requestId}` : ""}`
+      );
       const rawErrBody = lastError?.body || structuredMessage;
       const errStatus = lastError?.status || 502;
       const transformedErr = transformPaymentError(rawErrBody);
@@ -94384,7 +94516,8 @@ data: [DONE]
         res.writeHead(errStatus, {
           "Content-Type": "application/json",
           "x-context-used-kb": String(originalContextSizeKB),
-          "x-context-limit-kb": String(CONTEXT_LIMIT_KB)
+          "x-context-limit-kb": String(CONTEXT_LIMIT_KB),
+          ...lastError?.requestId ? { "x-blockrun-request-id": lastError.requestId } : {}
         });
         res.end(transformedErr);
         deduplicator.complete(dedupKey, {
@@ -94848,12 +94981,24 @@ data: [DONE]
         maxTokens,
         routingProfile ?? void 0
       );
-      logCost = FREE_MODELS.has(logModel) ? 0 : costs.costEstimate;
+      const apiKeyPricing = options.apiKey ? routerOpts.modelPricing.get(logModel) : void 0;
+      if (FREE_MODELS.has(logModel)) {
+        logCost = 0;
+        logSavings = 1;
+      } else if (apiKeyPricing) {
+        const inTokens = responseInputTokens ?? chargedInputTokens;
+        const outTokens = responseOutputTokens ?? 0;
+        logCost = (inTokens * (apiKeyPricing.inputPrice ?? 0) + outTokens * (apiKeyPricing.outputPrice ?? 0)) / 1e6;
+        logSavings = costs.baselineCost > 0 ? Math.max(0, (costs.baselineCost - logCost) / costs.baselineCost) : 0;
+      } else {
+        logCost = costs.costEstimate;
+        logSavings = costs.savings;
+      }
       logBaseline = costs.baselineCost;
-      logSavings = FREE_MODELS.has(logModel) ? 1 : costs.savings;
     }
     const entry = {
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      ...upstreamRequestId ? { requestId: upstreamRequestId } : {},
       model: logModel,
       tier: routingDecision?.tier ?? "DIRECT",
       cost: logCost,
@@ -94893,6 +95038,7 @@ var init_proxy = __esm({
     init_api_key();
     init_spend_control();
     init_compression();
+    init_errors5();
     init_version4();
     init_session();
     init_updater();
@@ -229338,7 +229484,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!`);
@@ -229355,7 +229509,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)}`
               );

package/docs/configuration.md

@@ -209,7 +209,8 @@ Per-request alternative: send `x-clawrouter-debug: false` on the request.
 
 ### CLAWROUTER_SOLANA_RPC_URL
 
-Override the Solana RPC endpoint used for USDC balance checks (Solana chain only):
+Override the Solana RPC endpoint used for USDC balance checks **and for signing
+payments** (Solana chain only):
 
 ```bash
 export CLAWROUTER_SOLANA_RPC_URL=https://your-rpc-provider.com
@@ -218,6 +219,21 @@ openclaw gateway restart
 
 Public RPC may rate-limit on heavy usage. Use a dedicated RPC for production.
 
+Unlike Base, where the EIP-3009 signature is produced entirely offline, signing
+a Solana payment reads the payment asset's mint account over RPC. A host that
+cannot reach `api.mainnet-beta.solana.com` therefore fails **every** paid Solana
+call with `fetch failed` while `sol.blockrun.ai` itself answers normally. Check
+egress before blaming the gateway:
+
+```bash
+curl -s -m 10 -X POST https://api.mainnet-beta.solana.com \
+  -H 'content-type: application/json' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"getAccountInfo","params":["EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",{"encoding":"base64"}]}'
+```
+
+If that hangs or is refused, point this variable at an endpoint the host can
+reach.
+
 ---
 
 ## Wallet Configuration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/clawrouter",
-  "version": "0.12.269",
+  "version": "0.12.271",
   "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,19 +24,35 @@ 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):**
+**Pricing — flat per call, the same for every endpoint.**
 
-- **Tier 1 — $0.001** — prices, rankings, lists, news, simple reads
-- **Tier 2 — $0.005** — orderbooks, candles, search, wallet details, social
-- **Tier 3 — $0.020** — on-chain SQL queries, structured queries, schema introspection
+Surf used to be tiered at $0.001 / $0.005 / $0.020. It is not any more: upstream
+now prices all three tiers identically (`SURF_TIER_{1,2,3}_PRICE` are equal). The
+`Tier` column in the catalog below still describes endpoint weight, but it no
+longer affects what you pay. Anything quoting the old tier prices is stale.
+
+| Rail                        | Price per call                              |
+| --------------------------- | ------------------------------------------- |
+| API key (`api.blockrun.ai`) | **$0.0075** — base rate, no transaction fee |
+| Wallet, Solana              | **$0.0075**                                 |
+| Wallet, Base                | **$0.0085**                                 |
+
+Verified 2026-09-05 by measurement, not from a price page: the API-key figure by
+diffing the account ledger across one call, the wallet figures by reading the
+`amount` in the x402 402 challenge, which quotes the price before anything is
+signed. Base and Solana genuinely differ for the same endpoint.
+
+**The 402 quote is always authoritative.** On the wallet rail the price arrives
+in the challenge before you pay, so if this table ever disagrees with it, believe
+the challenge and treat the table as stale.
 
 > 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