@blockrun/clawrouter 0.12.270 → 0.12.271

package/README.md

@@ -444,11 +444,19 @@ Surf is BlockRun's unified crypto data API — **84 endpoints across 13 domains*
 
 ClawRouter ships Surf as a **skill, not as typed wrappers**. The proxy whitelists `/v1/surf/*` so any call through the local proxy is paid x402 from the same wallet; the agent reads `skills/surf/SKILL.md` for the endpoint catalog and crafts the HTTP call. No `blockrun_surf_*` tool definitions to maintain; a new Surf endpoint requires zero ClawRouter release.
 
-| Tier |       Cost | Examples                                                      |
-| ---- | ---------: | ------------------------------------------------------------- |
-| 1    | **$0.001** | prices, rankings, lists, news                                 |
-| 2    | **$0.005** | orderbooks, candles, search, wallet details, social mindshare |
-| 3    | **$0.020** | on-chain SQL / query / schema, chat completions               |
+**Flat per-call pricing** — every Surf endpoint costs the same. The old
+$0.001/$0.005/$0.020 tiers no longer apply; upstream prices all three tiers
+identically, and the tier now describes only endpoint weight.
+
+| Rail                        | Price per call                     |
+| --------------------------- | ---------------------------------- |
+| API key (`api.blockrun.ai`) | **$0.0075** (base rate, no tx fee) |
+| Wallet — Solana             | **$0.0075**                        |
+| Wallet — Base               | **$0.0085**                        |
+
+Measured 2026-09-05: the API-key rate from the account ledger, the wallet rates
+from the x402 challenge, which quotes the price before anything is signed. On the
+wallet rail that quote is always authoritative.
 
 **Usage (HTTP):**
 
@@ -729,7 +737,7 @@ For basic usage, no configuration needed. For advanced options:
 | `BLOCKRUN_PROXY_PORT`       | `8402`                                | Local proxy port                                                                                                            |
 | `CLAWROUTER_DISABLED`       | `false`                               | Disable smart routing                                                                                                       |
 | `CLAWROUTER_DEBUG_HEADERS`  | `on`                                  | Set to `off` to suppress `x-clawrouter-*` debug response headers                                                            |
-| `CLAWROUTER_SOLANA_RPC_URL` | `https://api.mainnet-beta.solana.com` | Solana RPC endpoint                                                                                                         |
+| `CLAWROUTER_SOLANA_RPC_URL` | `https://api.mainnet-beta.solana.com` | Solana RPC endpoint — balance checks and payment signing                                                                    |
 
 **Full reference:** [docs/configuration.md](docs/configuration.md)
 

package/dist/cli.js

@@ -40713,6 +40713,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"() {
@@ -60152,6 +60164,40 @@ async function clearApiKey() {
   }
   return { removed, envStillSet: Boolean(process["env"].BLOCKRUN_API_KEY?.trim()) };
 }
+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);
@@ -90673,6 +90719,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";
@@ -91427,6 +91491,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}`;
@@ -91476,8 +91557,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,
@@ -91486,6 +91568,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,
@@ -91677,8 +91760,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;
@@ -91778,7 +91873,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 {
@@ -92883,7 +92986,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") || "";
@@ -92920,9 +93024,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
@@ -92955,6 +93062,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");
@@ -94361,7 +94469,8 @@ data: [DONE]
       }
       lastError = {
         body: result.errorBody || "Unknown error",
-        status: result.errorStatus || 500
+        status: result.errorStatus || 500,
+        requestId: result.upstreamRequestId
       };
       failedAttempts.push({
         model: tryModel,
@@ -94433,7 +94542,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,
@@ -94575,10 +94685,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);
@@ -94616,7 +94729,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, {
@@ -95080,12 +95194,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,
@@ -95125,6 +95251,7 @@ var init_proxy = __esm({
     init_api_key();
     init_spend_control();
     init_compression();
+    init_errors5();
     init_version4();
     init_session();
     init_updater();
@@ -230609,6 +230736,12 @@ ClawRouter Status (port ${port})
       console.log(`  Auth:          BlockRun API key ${data.apiKey}`);
       console.log(`  Gateway:       ${data.gateway}`);
       console.log(`  Billing:       account credit \u2014 top up at ${PORTAL_CREDITS_URL}`);
+      if (data.creditSummary) console.log(`  Credit:        ${data.creditSummary}`);
+      if (data.blocked) {
+        console.log(`  \u26A0 Account is blocked${data.blockedReason ? `: ${data.blockedReason}` : ""}`);
+      } else if (data.isEmpty) {
+        console.log(`  \u26A0 Credit exhausted \u2014 top up at ${PORTAL_CREDITS_URL}`);
+      }
     } else {
       console.log(`  Auth:          wallet (x402)`);
       console.log(`  Payment Chain: ${data.paymentChain}`);
@@ -230636,6 +230769,7 @@ ClawRouter Account
       console.log(`  Auth:    BlockRun API key ${data.apiKey}`);
       console.log(`  Gateway: ${data.gateway}`);
       console.log(`  Billing: account credit (no wallet, no chain)`);
+      if (data.creditSummary) console.log(`  Credit:  ${data.creditSummary}`);
       console.log(`  Top up:  ${PORTAL_CREDITS_URL}`);
       console.log(`  Usage:   ${PORTAL_URL}/dashboard`);
       console.log();

package/dist/index.d.ts

@@ -1416,6 +1416,23 @@ type UsageEntry = {
     partnerId?: string;
     /** Partner service name (e.g., "BlockRun") — only set for partner API calls */
     service?: string;
+    /**
+     * The gateway's own id for this request, from the `x-blockrun-request-id`
+     * response header. Absent for requests that never reached the gateway (a
+     * cache hit, a local refusal, an aborted call).
+     *
+     * This is the JOIN KEY for billing reconciliation. Every `cost` in this file
+     * is a LOCAL estimate computed from our copy of the price table, so it drifts
+     * whenever that copy goes stale — six prices were wrong until v0.12.270, and
+     * `/stats` had been reporting the wrong money the whole time. Recording the
+     * gateway's id is what will let us diff this journal line-by-line against a
+     * server-side ledger and show what was actually charged instead of what we
+     * guessed. It cannot be backfilled: a call whose id we did not record is
+     * unreconcilable forever, which is why this is captured before the ledger API
+     * that will consume it exists. It is also the id support needs to trace one
+     * failed call.
+     */
+    requestId?: string;
 };
 /**
  * Log a usage entry as a JSON line.

package/dist/index.js

@@ -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"() {
@@ -59939,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);
@@ -90460,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";
@@ -91214,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}`;
@@ -91263,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,
@@ -91273,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,
@@ -91464,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;
@@ -91565,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 {
@@ -92670,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") || "";
@@ -92707,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
@@ -92742,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");
@@ -94148,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,
@@ -94220,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,
@@ -94362,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);
@@ -94403,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, {
@@ -94867,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,
@@ -94912,6 +95038,7 @@ var init_proxy = __esm({
     init_api_key();
     init_spend_control();
     init_compression();
+    init_errors5();
     init_version4();
     init_session();
     init_updater();

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.270",
+  "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/surf/SKILL.md

@@ -26,11 +26,27 @@ license: MIT
 
 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):**
-
-- **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
+**Pricing — flat per call, the same for every endpoint.**
+
+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.