@blockrun/llm 3.22.0 → 3.22.1

package/README.md

@@ -507,6 +507,9 @@ console.log(res.costUsd, res.settlement);        // what you paid, and the tx
 (Base / Arc). `costUsd` is what the call added to `getSpending()`: the signed
 price under `exact`, the metered `extra.chargedAmount` under batch settlement,
 `0` for a free model; it is undefined in API-key mode (billed to the account).
+When the gateway answers a paid request from a free fallback model it skips
+settlement: `costUsd` is `0`, `settlement.skipped` is `"free-fallback"`, and
+nothing is added to `getSpending()`.
 
 **Setup:**
 1. Export your Solana wallet key: `export SOLANA_WALLET_KEY="your-bs58-key"`

package/dist/index.cjs

@@ -553,7 +553,15 @@ function readSettlement(response, quotedUsd, scheme) {
   };
   return { costUsd, settlement };
 }
+function settlementSkipped(response) {
+  return response.headers.get("X-Settlement-Skipped") === "free-fallback";
+}
 function withCost(body, response, bookedUsd, scheme) {
+  if (settlementSkipped(response)) {
+    body.costUsd = 0;
+    body.settlement = { ...readSettlement(response, bookedUsd, scheme).settlement, skipped: "free-fallback" };
+    return body;
+  }
   body.costUsd = bookedUsd;
   body.settlement = readSettlement(response, bookedUsd, scheme).settlement;
   return body;
@@ -4824,7 +4832,7 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.22.0";
+var SDK_VERSION = "3.22.1";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
@@ -5390,11 +5398,7 @@ var LLMClient = class _LLMClient {
           }
           throw new APIError(`API error after payment: ${retryResp2.status}`, retryResp2.status, sanitizeErrorResponse(errorBody));
         }
-        const costUsd2 = parseFloat(details.amount) / 1e6;
-        this.sessionCalls += 1;
-        this.sessionTotalUsd += costUsd2;
-        this.recordCost(url, costUsd2, { body, network: details.network });
-        return withCost(await this.parseChatResponse(retryResp2), retryResp2, costUsd2, "exact");
+        return this.bookPaid(url, body, details, retryResp2);
       }
     }
     if (retryResponse.status === 402) {
@@ -5413,11 +5417,22 @@ var LLMClient = class _LLMClient {
         sanitizeErrorResponse(errorBody)
       );
     }
+    return this.bookPaid(url, body, details, retryResponse);
+  }
+  /**
+   * Book a served, paid chat call and attach its cost. A response the gateway
+   * served from a free fallback with settlement skipped
+   * (`X-Settlement-Skipped: free-fallback`) moved nothing on chain, so it is
+   * not added to `getSpending()` or the cost log, and reports `costUsd: 0`.
+   */
+  async bookPaid(url, body, details, response) {
     const costUsd = parseFloat(details.amount) / 1e6;
-    this.sessionCalls += 1;
-    this.sessionTotalUsd += costUsd;
-    this.recordCost(url, costUsd, { body, network: details.network });
-    return withCost(await this.parseChatResponse(retryResponse), retryResponse, costUsd, "exact");
+    if (!settlementSkipped(response)) {
+      this.sessionCalls += 1;
+      this.sessionTotalUsd += costUsd;
+      this.recordCost(url, costUsd, { body, network: details.network });
+    }
+    return withCost(await this.parseChatResponse(response), response, costUsd, "exact");
   }
   /**
    * Sign a payment header and return the PAYMENT-SIGNATURE value.
@@ -13404,7 +13419,7 @@ var SolanaLLMClient = class {
       throw withDisposition(error, "paid-or-in-doubt");
     }
     await this.assertPaid(retryResponse);
-    this.recordSettlement(costUsd);
+    if (!settlementSkipped(retryResponse)) this.recordSettlement(costUsd);
     const paid = await this.readPaidJson(retryResponse);
     return withCost(paid, retryResponse, costUsd, "exact");
   }

package/dist/index.d.cts

@@ -230,6 +230,13 @@ interface Settlement {
     network?: string;
     /** Present and false only when the gateway reported a failed settlement. */
     success?: false;
+    /**
+     * `"free-fallback"` when the gateway served a paid request from a free
+     * fallback model and skipped settlement (`X-Settlement-Skipped`): nothing
+     * moved on chain, so `costUsd` is 0 and nothing was added to `getSpending()`.
+     * `quotedUsd` still states what was signed.
+     */
+    skipped?: "free-fallback";
 }
 interface FunctionCall {
     name: string;
@@ -1479,6 +1486,13 @@ declare class LLMClient {
     private signFrom402;
     /** Send the signed payment and read the answer. The payment may settle from here on. */
     private sendPaid;
+    /**
+     * Book a served, paid chat call and attach its cost. A response the gateway
+     * served from a free fallback with settlement skipped
+     * (`X-Settlement-Skipped: free-fallback`) moved nothing on chain, so it is
+     * not added to `getSpending()` or the cost log, and reports `costUsd: 0`.
+     */
+    private bookPaid;
     /**
      * Sign a payment header and return the PAYMENT-SIGNATURE value.
      * Extracted to share logic between streaming and non-streaming flows.

package/dist/index.d.ts

@@ -230,6 +230,13 @@ interface Settlement {
     network?: string;
     /** Present and false only when the gateway reported a failed settlement. */
     success?: false;
+    /**
+     * `"free-fallback"` when the gateway served a paid request from a free
+     * fallback model and skipped settlement (`X-Settlement-Skipped`): nothing
+     * moved on chain, so `costUsd` is 0 and nothing was added to `getSpending()`.
+     * `quotedUsd` still states what was signed.
+     */
+    skipped?: "free-fallback";
 }
 interface FunctionCall {
     name: string;
@@ -1479,6 +1486,13 @@ declare class LLMClient {
     private signFrom402;
     /** Send the signed payment and read the answer. The payment may settle from here on. */
     private sendPaid;
+    /**
+     * Book a served, paid chat call and attach its cost. A response the gateway
+     * served from a free fallback with settlement skipped
+     * (`X-Settlement-Skipped: free-fallback`) moved nothing on chain, so it is
+     * not added to `getSpending()` or the cost log, and reports `costUsd: 0`.
+     */
+    private bookPaid;
     /**
      * Sign a payment header and return the PAYMENT-SIGNATURE value.
      * Extracted to share logic between streaming and non-streaming flows.

package/dist/index.js

@@ -423,7 +423,15 @@ function readSettlement(response, quotedUsd, scheme) {
   };
   return { costUsd, settlement };
 }
+function settlementSkipped(response) {
+  return response.headers.get("X-Settlement-Skipped") === "free-fallback";
+}
 function withCost(body, response, bookedUsd, scheme) {
+  if (settlementSkipped(response)) {
+    body.costUsd = 0;
+    body.settlement = { ...readSettlement(response, bookedUsd, scheme).settlement, skipped: "free-fallback" };
+    return body;
+  }
   body.costUsd = bookedUsd;
   body.settlement = readSettlement(response, bookedUsd, scheme).settlement;
   return body;
@@ -4694,7 +4702,7 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.22.0";
+var SDK_VERSION = "3.22.1";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
@@ -5260,11 +5268,7 @@ var LLMClient = class _LLMClient {
           }
           throw new APIError(`API error after payment: ${retryResp2.status}`, retryResp2.status, sanitizeErrorResponse(errorBody));
         }
-        const costUsd2 = parseFloat(details.amount) / 1e6;
-        this.sessionCalls += 1;
-        this.sessionTotalUsd += costUsd2;
-        this.recordCost(url, costUsd2, { body, network: details.network });
-        return withCost(await this.parseChatResponse(retryResp2), retryResp2, costUsd2, "exact");
+        return this.bookPaid(url, body, details, retryResp2);
       }
     }
     if (retryResponse.status === 402) {
@@ -5283,11 +5287,22 @@ var LLMClient = class _LLMClient {
         sanitizeErrorResponse(errorBody)
       );
     }
+    return this.bookPaid(url, body, details, retryResponse);
+  }
+  /**
+   * Book a served, paid chat call and attach its cost. A response the gateway
+   * served from a free fallback with settlement skipped
+   * (`X-Settlement-Skipped: free-fallback`) moved nothing on chain, so it is
+   * not added to `getSpending()` or the cost log, and reports `costUsd: 0`.
+   */
+  async bookPaid(url, body, details, response) {
     const costUsd = parseFloat(details.amount) / 1e6;
-    this.sessionCalls += 1;
-    this.sessionTotalUsd += costUsd;
-    this.recordCost(url, costUsd, { body, network: details.network });
-    return withCost(await this.parseChatResponse(retryResponse), retryResponse, costUsd, "exact");
+    if (!settlementSkipped(response)) {
+      this.sessionCalls += 1;
+      this.sessionTotalUsd += costUsd;
+      this.recordCost(url, costUsd, { body, network: details.network });
+    }
+    return withCost(await this.parseChatResponse(response), response, costUsd, "exact");
   }
   /**
    * Sign a payment header and return the PAYMENT-SIGNATURE value.
@@ -13274,7 +13289,7 @@ var SolanaLLMClient = class {
       throw withDisposition(error, "paid-or-in-doubt");
     }
     await this.assertPaid(retryResponse);
-    this.recordSettlement(costUsd);
+    if (!settlementSkipped(retryResponse)) this.recordSettlement(costUsd);
     const paid = await this.readPaidJson(retryResponse);
     return withCost(paid, retryResponse, costUsd, "exact");
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/llm",
-  "version": "3.22.0",
+  "version": "3.22.1",
   "type": "module",
   "description": "TypeScript SDK for BlockRun - every frontier model behind one OpenAI-compatible client. Pay with a BlockRun API key or per-call in USDC. Smart routing picks the cheapest capable model. No rate limits.",
   "main": "dist/index.cjs",