@blockrun/clawrouter 0.12.269 → 0.12.271

package/dist/cli.js

@@ -38541,8 +38541,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,
@@ -38583,8 +38583,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,
@@ -39022,8 +39022,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,
@@ -39419,8 +39419,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,
@@ -39434,8 +39434,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,
@@ -39447,8 +39447,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,
@@ -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"() {
@@ -60054,13 +60066,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";
@@ -60147,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);
@@ -60194,7 +60245,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".`
     };
   }
 });
@@ -90668,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";
@@ -91422,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}`;
@@ -91471,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,
@@ -91481,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,
@@ -91672,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;
@@ -91773,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 {
@@ -92578,7 +92686,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 {
@@ -92610,6 +92719,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,
@@ -92864,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") || "";
@@ -92901,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
@@ -92936,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");
@@ -94342,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,
@@ -94414,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,
@@ -94556,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);
@@ -94597,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, {
@@ -95061,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,
@@ -95106,6 +95251,7 @@ var init_proxy = __esm({
     init_api_key();
     init_spend_control();
     init_compression();
+    init_errors5();
     init_version4();
     init_session();
     init_updater();
@@ -229633,7 +229779,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!`);
@@ -229650,7 +229804,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)}`
               );
@@ -230582,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}`);
@@ -230609,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

@@ -1248,13 +1248,29 @@ declare function setupSolana(): Promise<{
 declare function savePaymentChain(chain: "base" | "solana"): Promise<void>;
 /**
  * Load the persisted payment chain selection from disk.
- * Returns "base" if no file exists or the file is invalid.
- * New installs persist "solana" at wallet generation, so an absent file
- * means a pre-existing install whose funds live on Base.
+ *
+ * Solana is the preferred rail, and since v0.12.246 wallet generation persists
+ * `solana` outright — so a fresh install answers "solana" from its own chain
+ * file, not from a default. This function only decides the case where no chain
+ * file exists at all, and there the answer turns on whether a wallet already
+ * does:
+ *
+ *   no chain file, no wallet   → "solana"  (nothing to strand; prefer Solana)
+ *   no chain file, wallet on disk → "base" (a pre-v0.12.246 install)
+ *
+ * That second line is the one that must not move. An install predating the
+ * Solana default has USDC sitting in its Base wallet and no Solana balance;
+ * flipping it would point every request at a gateway its money is not on and
+ * fail them all with an empty balance. The same reasoning covers a wallet
+ * supplied through BLOCKRUN_WALLET_KEY, and a generated wallet whose Solana
+ * derivation failed (no chain file is written in that case, on purpose — see
+ * resolveOrGenerateWalletKey — and the wallet it did write keeps us on Base,
+ * which is the only chain that proxy can actually sign for).
  */
 declare function loadPaymentChain(): Promise<"base" | "solana">;
 /**
- * Resolve payment chain: env var first → persisted file second → default "base".
+ * Resolve payment chain: env var first → persisted file second → the
+ * fresh-install preference (Solana) last. See loadPaymentChain.
  */
 declare function resolvePaymentChain(): Promise<"base" | "solana">;
 
@@ -1400,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.