@blockrun/clawrouter 0.12.282 → 0.12.283

package/README.md

@@ -9,11 +9,11 @@ Agents can only sign transactions.<br><br>
 <strong>ClawRouter is the only LLM router that lets agents operate independently.</strong><br><br>
 <em>Pay however you like: <strong>credit card</strong> — sign up at <a href="https://user.blockrun.ai"><strong>user.blockrun.ai</strong></a>, top up, mint an API key<br>
 or <strong>USDC</strong> on Solana or Base (x402 wallet, no account at all).<br>
-Or neither — <!-- br:models.free -->6<!-- /br:models.free --> models are free, with no signup, no key and no wallet.</em></p>
+Or neither — <!-- br:models.free -->7<!-- /br:models.free --> models are free, with no signup, no key and no wallet.</em></p>
 
 <br>
 
-<img src="https://img.shields.io/badge/🆓_6_Free_Models-success?style=for-the-badge" alt="6 free models">&nbsp;
+<img src="https://img.shields.io/badge/🆓_7_Free_Models-success?style=for-the-badge" alt="7 free models">&nbsp;
 <img src="https://img.shields.io/badge/🤖_Agent--Native-black?style=for-the-badge" alt="Agent native">&nbsp;
 <img src="https://img.shields.io/badge/💳_Card_or_USDC-blue?style=for-the-badge" alt="Card or USDC">&nbsp;
 <img src="https://img.shields.io/badge/⚡_Local_Routing-yellow?style=for-the-badge" alt="Local routing">&nbsp;
@@ -36,7 +36,7 @@ Or neither — <!-- br:models.free -->6<!-- /br:models.free --> models are free,
 
 </div>
 
-> **ClawRouter** is an open-source smart LLM router that reduces AI API costs by up to <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->%. It analyzes each request across <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions --> dimensions and routes to the cheapest capable model in under 1ms, entirely locally. It is the only LLM router that an autonomous agent can pay for by itself — a wallet signature is the account, and USDC micropayments over the x402 protocol are the billing — and it takes an ordinary credit card too: sign up at [user.blockrun.ai](https://user.blockrun.ai), top up, and run the same router on an API key. <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> models from OpenAI, Anthropic, Google, xAI, DeepSeek, and more. MIT licensed.
+> **ClawRouter** is an open-source smart LLM router that reduces AI API costs by up to <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->%. It analyzes each request across <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions --> dimensions and routes to the cheapest capable model in under 1ms, entirely locally. It is the only LLM router that an autonomous agent can pay for by itself — a wallet signature is the account, and USDC micropayments over the x402 protocol are the billing — and it takes an ordinary credit card too: sign up at [user.blockrun.ai](https://user.blockrun.ai), top up, and run the same router on an API key. <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models from OpenAI, Anthropic, Google, xAI, DeepSeek, and more. MIT licensed.
 
 ---
 
@@ -48,7 +48,7 @@ Not a seat, not a subscription, not a monthly minimum you keep paying while the
 
 |                           |                                                                                                                                                                                                                                                                                                                                                               |
 | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Every LLM**             | <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> chat models across 9 providers, behind one endpoint and one balance                                                                                                                                                                                                                           |
+| **Every LLM**             | <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> chat models across 9 providers, behind one endpoint and one balance                                                                                                                                                                                                                           |
 | **Every tool**            | <!-- br:models.image -->12<!-- /br:models.image --> image models, <!-- br:models.video -->8<!-- /br:models.video --> video models, music, <!-- br:models.speech -->5<!-- /br:models.speech --> voices, img2img editing, and outbound phone calls that come back as transcripts                                                                                |
 | **Every data source**     | web, news and neural search; prediction markets; live crypto and equity quotes; on-chain SQL over 100M+ labeled wallets; DEX routing; RPC across <!-- br:chains.rpc -->40<!-- /br:chains.rpc --> chains                                                                                                                                                       |
 | **Best value per dollar** | <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions -->-dimension local routing sends each request to the cheapest model that can actually do it — <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->% below pinning Claude Opus 5 on the same traffic, computed from a published workload mix rather than estimated |
@@ -65,7 +65,7 @@ Every other LLM router was built for **human developers** — create an account,
 
 ClawRouter is built for the agent-first world:
 
-- **Starts at $0** — <!-- br:models.free -->6<!-- /br:models.free --> open-weight models are free forever (incl. a 1M-context reasoner and two sub-second coders). Image turns route to paid models — see the free-tier note below.
+- **Starts at $0** — <!-- br:models.free -->7<!-- /br:models.free --> open-weight models are free forever (incl. a 1M-context reasoner and two sub-second coders). Image turns route to paid models — see the free-tier note below.
 - **No accounts needed** — a wallet is generated locally, no signup
 - **No API keys needed** — your wallet signature IS authentication
 - **No model selection** — <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions -->-dimension scoring + constraint-first ranking ([router-core](https://github.com/BlockRunAI/router-core)) picks the right model automatically
@@ -76,7 +76,7 @@ This is the stack that lets agents operate autonomously: **x402 + USDC + local r
 
 ### …and if you are a human, not an agent
 
-Every "no X needed" above is a capability, not a restriction. **ClawRouter takes a credit card too.** Sign up at **[user.blockrun.ai](https://user.blockrun.ai)**, top up, mint an API key, and run `clawrouter login brk_live_…`. Same router, same <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> models, same local routing — calls go to `api.blockrun.ai` on a bearer token and bill your account credit. No crypto, no gas, no seed phrase.
+Every "no X needed" above is a capability, not a restriction. **ClawRouter takes a credit card too.** Sign up at **[user.blockrun.ai](https://user.blockrun.ai)**, top up, mint an API key, and run `clawrouter login brk_live_…`. Same router, same <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models, same local routing — calls go to `api.blockrun.ai` on a bearer token and bill your account credit. No crypto, no gas, no seed phrase.
 
 | You are             | Pay with                                | Setup                                                                                       |
 | ------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------- |
@@ -92,8 +92,8 @@ Full walkthrough: [Paying with a credit card](#paying-with-a-credit-card-api-key
 
 |                  | OpenRouter        | LiteLLM          | Martian           | Portkey           | **ClawRouter**                                                         |
 | ---------------- | ----------------- | ---------------- | ----------------- | ----------------- | ---------------------------------------------------------------------- |
-| **Models**       | 200+              | 100+             | Smart routing     | Gateway           | **<!-- br:models.chatVisible -->82<!-- /br:models.chatVisible -->**    |
-| **Free tier**    | Rate-limited      | BYO keys         | No                | No                | **<!-- br:models.free -->6<!-- /br:models.free --> models, no signup** |
+| **Models**       | 200+              | 100+             | Smart routing     | Gateway           | **<!-- br:models.chatVisible -->88<!-- /br:models.chatVisible -->**    |
+| **Free tier**    | Rate-limited      | BYO keys         | No                | No                | **<!-- br:models.free -->7<!-- /br:models.free --> models, no signup** |
 | **Routing**      | Manual selection  | Manual selection | Smart (closed)    | Observability     | **Smart (open source)**                                                |
 | **Auth**         | Account + API key | Your API keys    | Account + API key | Account + API key | **Wallet signature _or_ API key**                                      |
 | **Payment**      | Credit card       | BYO keys         | Credit card       | $49-499/mo        | **USDC per-request _or_ card credit**                                  |
@@ -109,7 +109,7 @@ Full walkthrough: [Paying with a credit card](#paying-with-a-credit-card-api-key
 
 ## Quick Start
 
-> **No wallet? <!-- br:models.free -->6<!-- /br:models.free --> models work free out of the box.** Install, run, and pin `free/nemotron-3.5-lightning` (or any of the <!-- br:models.free -->6<!-- /br:models.free -->) — no crypto, no signup, no balance required. Add a credit card or USDC later when you want paid models.
+> **No wallet? <!-- br:models.free -->7<!-- /br:models.free --> models work free out of the box.** Install, run, and pin `free/nemotron-3.5-lightning` (or any of the <!-- br:models.free -->7<!-- /br:models.free -->) — no crypto, no signup, no balance required. Add a credit card or USDC later when you want paid models.
 
 **Two ways to pay for the paid ones — pick one, the rest of ClawRouter is identical:**
 
@@ -127,7 +127,7 @@ is all it takes to switch and `clawrouter logout` is all it takes to switch back
 
 > **Where do I sign up?** [**user.blockrun.ai**](https://user.blockrun.ai) — sign in with
 > Google, add credit with a card under **Credits**, mint a key under **API Keys**. That
-> one key covers all <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> chat models
+> one key covers all <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> chat models
 > plus images, video, speech and the live-data APIs. No wallet, no crypto, no seed phrase.
 
 ### Desktop control plane (macOS)
@@ -171,7 +171,7 @@ openclaw gateway restart
 
 > **Using Claude Code?** Check out [BRCC](https://github.com/BlockRunAI/brcc) — it's purpose-built for Claude Code with the same smart routing and x402 payments.
 >
-> **Using NousResearch Hermes?** See [ClawRouter-Hermes](https://github.com/BlockRunAI/ClawRouter-Hermes) — a Python plugin that wires Hermes into the ClawRouter proxy. Same wallet, same <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> models, same x402 USDC settlement on Solana & Base.
+> **Using NousResearch Hermes?** See [ClawRouter-Hermes](https://github.com/BlockRunAI/ClawRouter-Hermes) — a Python plugin that wires Hermes into the ClawRouter proxy. Same wallet, same <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models, same x402 USDC settlement on Solana & Base.
 
 No OpenClaw required. ClawRouter runs as a local proxy on port 8402.
 
@@ -182,7 +182,7 @@ npx @blockrun/clawrouter
 ```
 
 **2. Fund your wallet** — optional, skip for free tier
-Your wallet address is printed on first run. For paid models, send a few USDC on Solana (the default chain) or Base — $5 covers thousands of requests. Prefer a card? [Sign up at user.blockrun.ai](https://user.blockrun.ai) and run `clawrouter login brk_live_…` instead. To stay at $0, pin any of the <!-- br:models.free -->6<!-- /br:models.free --> free models (e.g. `free/nemotron-3.5-lightning`) or use `/model free` inside OpenClaw.
+Your wallet address is printed on first run. For paid models, send a few USDC on Solana (the default chain) or Base — $5 covers thousands of requests. Prefer a card? [Sign up at user.blockrun.ai](https://user.blockrun.ai) and run `clawrouter login brk_live_…` instead. To stay at $0, pin any of the <!-- br:models.free -->7<!-- /br:models.free --> free models (e.g. `free/nemotron-3.5-lightning`) or use `/model free` inside OpenClaw.
 
 **3. Point your client at `http://localhost:8402`**
 
@@ -485,7 +485,7 @@ No Surf account, no API key — settles directly to Surf's Base treasury in USDC
 
 ## Models & Pricing
 
-<!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> models across 9 providers, one wallet. **<!-- br:models.free -->6<!-- /br:models.free --> models are $0 — paid models start at fractions of a cent.**
+<!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models across 9 providers, one wallet. **<!-- br:models.free -->7<!-- /br:models.free --> models are $0 — paid models start at fractions of a cent.**
 
 > **💡 "Cost per request"** = estimated cost for a typical chat message (~500 input + 500 output tokens). Paid requests also carry a flat **$0.001/tx settlement fee** (covers on-chain gas; already included in the price the gateway quotes). Free models never pay it.
 
@@ -585,7 +585,7 @@ No Surf account, no API key — settles directly to Surf's Base treasury in USDC
 | openai/gpt-5.4-pro          |    $30.00 |    $180.00 |    $0.1050 | 1M      | reasoning, tools                                       |
 | openai/gpt-5.5-pro          |    $30.00 |    $180.00 |    $0.1050 | 1M      | reasoning, vision, tools                               |
 
-> **Free tier:** <!-- br:models.free -->6<!-- /br:models.free --> open-weight models cost nothing — `/model free` pins the free default (`nemotron-3.5-lightning`, with the other five as fallbacks), `/model eco` opens on it, or pick one directly (e.g., `/model lightning` for 1M-context reasoning, `/model north-mini` or `/model laguna` for fast coding).
+> **Free tier:** <!-- br:models.free -->7<!-- /br:models.free --> open-weight models cost nothing — `/model free` pins the free default (`nemotron-3.5-lightning`, with the other five as fallbacks), `/model eco` opens on it, or pick one directly (e.g., `/model lightning` for 1M-context reasoning, `/model north-mini` or `/model laguna` for fast coding).
 >
 > **No free vision.** Two free models are catalogued as vision-capable and neither reliably is: on a 64×64 solid-colour probe `nemotron-3-nano-omni` was right 1 of 4 times on Base and answered "white" for red on Solana, and `llama-3.2-11b-vision` replied "I'm unable to see the image" 3 of 3 while answering text fine. Both return HTTP 200, so a wrong answer arrives with no error to branch on. ClawRouter therefore does not flag them for vision, and requests carrying an `image_url` route to a paid vision model instead.
 > **Best value:** `gpt-5-nano` and `gemini-2.5-flash-lite` deliver strong results at ~$0.0003/request.
@@ -728,7 +728,7 @@ chains, the response cache and the local spend controls.
 - **Balance lives server-side.** There is no local balance to check: a call that
   outruns your credit comes back as HTTP `402 insufficient_quota`, naming the
   top-up page. Free models stay free and need no credit at all — all
-  <!-- br:models.free -->6<!-- /br:models.free --> are served on the API-key gateway too.
+  <!-- br:models.free -->7<!-- /br:models.free --> are served on the API-key gateway too.
 - **One key covers nearly everything.** Verified live against `api.blockrun.ai`
   on 2026-09-05: chat completions (`/v1/chat/completions`), the Anthropic-shaped
   `/v1/messages`, `/v1/models`, image generation, speech, video, and the partner
@@ -881,7 +881,7 @@ npm test
 
 **The LLM router built for autonomous agents**
 
-You're here. <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> models, local smart routing, and two ways to pay — a credit-card-funded API key, or x402 USDC from a wallet, which is what lets an agent operate independently.
+You're here. <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models, local smart routing, and two ways to pay — a credit-card-funded API key, or x402 USDC from a wallet, which is what lets an agent operate independently.
 
 `curl -fsSL https://blockrun.ai/ClawRouter-update | bash`
 
@@ -892,7 +892,7 @@ You're here. <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> mod
 
 **BlockRun for Claude Code**
 
-Run Claude Code with <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> models, no rate limits, no Anthropic account, no phone verification. Pay per request with USDC — your wallet is your identity.
+Run Claude Code with <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models, no rate limits, no Anthropic account, no phone verification. Pay per request with USDC — your wallet is your identity.
 
 `curl -fsSL https://blockrun.ai/brcc-install | bash`
 
@@ -905,7 +905,7 @@ Run Claude Code with <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible
 
 **ClawRouter for NousResearch Hermes**
 
-Python plugin that wraps the ClawRouter proxy for `hermes-agent`. Same <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> models, same x402 USDC payments on Solana & Base, native Hermes ergonomics.
+Python plugin that wraps the ClawRouter proxy for `hermes-agent`. Same <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models, same x402 USDC payments on Solana & Base, native Hermes ergonomics.
 
 `pip install hermes-plugin-clawrouter`
 
@@ -949,7 +949,7 @@ Python plugin that wraps the ClawRouter proxy for `hermes-agent`. Same <!-- br:m
 
 ### What is BlockRun?
 
-BlockRun lets agents pay for the outcome — every LLM, tool and data source, best value per dollar. One endpoint and one balance covering <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> chat models plus image, video, music and speech generation, search, market data and multi-chain RPC, billed per call with USDC over [x402](https://x402.org) or a credit-card-funded API key — no seat, no subscription, no minimum. ClawRouter is the open-source local router agents use to reach it.
+BlockRun lets agents pay for the outcome — every LLM, tool and data source, best value per dollar. One endpoint and one balance covering <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> chat models plus image, video, music and speech generation, search, market data and multi-chain RPC, billed per call with USDC over [x402](https://x402.org) or a credit-card-funded API key — no seat, no subscription, no minimum. ClawRouter is the open-source local router agents use to reach it.
 
 ### What is ClawRouter?
 
@@ -977,7 +977,7 @@ No. A wallet is the default because it is what lets an _agent_ pay for itself,
 but you can sign up at **[user.blockrun.ai](https://user.blockrun.ai)**, top up
 with a credit card, mint an API key and run `clawrouter login brk_live_…`. Calls
 then go to `api.blockrun.ai` on a bearer token and bill your account credit — no
-crypto, no gas, no seed phrase. And the <!-- br:models.free -->6<!-- /br:models.free --> free models need neither: no
+crypto, no gas, no seed phrase. And the <!-- br:models.free -->7<!-- /br:models.free --> free models need neither: no
 wallet, no key, no signup. See [Paying with a credit card](#paying-with-a-credit-card-api-key).
 
 ### Is ClawRouter free?

package/dist/cli.js

@@ -32315,6 +32315,11 @@ function getSharedSpendControl() {
   host.__clawrouterSharedSpendControl ??= new SpendControl();
   return host.__clawrouterSharedSpendControl;
 }
+function parseQuotedAmountMicros(selected) {
+  const raw = selected.amount ?? selected.maxAmountRequired;
+  if (typeof raw !== "string" || !CANONICAL_AMOUNT.test(raw)) return void 0;
+  return BigInt(raw);
+}
 function parseQuotedAmountUsd(selected) {
   const raw = selected.amount ?? selected.maxAmountRequired;
   if (typeof raw !== "string" || !CANONICAL_AMOUNT.test(raw)) {
@@ -33080,6 +33085,16 @@ function createPayFetchWithPreAuth(baseFetch, client, ttlMs = DEFAULT_TTL_MS, op
       return est === void 0 ? void 0 : Number(est);
     };
     const needMicros = estimateMicros();
+    const notifyDeclinedPayment = () => {
+      if (!options?.onPaymentDeclined) return;
+      try {
+        options.onPaymentDeclined();
+      } catch (error) {
+        console.error(
+          `[ClawRouter] onPaymentDeclined callback failed: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    };
     const cached = !options?.skipPreAuth ? cache2.get(cacheKey2) : void 0;
     const preAuthCovers = cached !== void 0 && Date.now() - cached.cachedAt < ttlMs && cached.coverMicros !== void 0 && needMicros !== void 0 && needMicros <= cached.coverMicros;
     if (preAuthCovers) {
@@ -33098,6 +33113,7 @@ function createPayFetchWithPreAuth(baseFetch, client, ttlMs = DEFAULT_TTL_MS, op
           return response2;
         }
         paymentInFlight = false;
+        notifyDeclinedPayment();
         cache2.delete(cacheKey2);
       } catch (err) {
         cache2.delete(cacheKey2);
@@ -33142,6 +33158,7 @@ function createPayFetchWithPreAuth(baseFetch, client, ttlMs = DEFAULT_TTL_MS, op
       clonedRequest.headers.set(key3, value);
     }
     const paidResponse = await baseFetch(clonedRequest);
+    if (paidResponse.status === 402) notifyDeclinedPayment();
     notifyAcceptedPayment(paidResponse, payload);
     return paidResponse;
   };
@@ -64789,6 +64806,132 @@ var init_api_key = __esm({
   }
 });
 
+// src/session-spend.ts
+function parseMicros(raw) {
+  if (raw === void 0 || !/^\d+$/.test(raw)) return void 0;
+  return BigInt(raw);
+}
+function usdToMicros(usd2) {
+  return BigInt(Math.round(usd2 * 1e6));
+}
+function microsToUsd(micros) {
+  return Number(micros) / 1e6;
+}
+var SessionSpend, CostCapError;
+var init_session_spend = __esm({
+  "src/session-spend.ts"() {
+    "use strict";
+    init_spend_control();
+    SessionSpend = class _SessionSpend {
+      constructor(store, sessionId, capMicros, holdMicros) {
+        this.store = store;
+        this.sessionId = sessionId;
+        this.capMicros = capMicros;
+        this.heldMicros = holdMicros;
+        if (holdMicros > 0n) store.adjustSessionHold(sessionId, holdMicros);
+      }
+      store;
+      sessionId;
+      capMicros;
+      /** Budget this request still holds against the session (strict mode only). */
+      heldMicros;
+      /** Sum of payments signed by this request that still count. */
+      signedMicros = 0n;
+      /** The most recent signature not yet settled or voided — the one a decline undoes. */
+      lastSignedMicros = 0n;
+      released = false;
+      /**
+       * Strict mode: admit the request only if the session's spend, plus what its
+       * other in-flight requests hold, plus this request's estimate fits the cap —
+       * and hold the estimate in the same step.
+       */
+      static admit(store, sessionId, capMicros, estimateMicros) {
+        const spentMicros = store.getSessionCostMicros(sessionId);
+        const heldMicros = store.getSessionHoldMicros(sessionId);
+        if (spentMicros + heldMicros + estimateMicros > capMicros) {
+          return { admitted: false, spentMicros, heldMicros, estimateMicros };
+        }
+        return {
+          admitted: true,
+          spend: new _SessionSpend(store, sessionId, capMicros, estimateMicros)
+        };
+      }
+      /** Graceful mode: track signed spend, enforce nothing. */
+      static track(store, sessionId) {
+        return new _SessionSpend(store, sessionId, void 0, 0n);
+      }
+      get isStrict() {
+        return this.capMicros !== void 0;
+      }
+      /**
+       * Before a payment is created: may this request sign `quoteMicros`?
+       * Spend already recorded (including this request's own earlier signatures)
+       * plus what OTHER in-flight requests hold, plus the quote, must fit the cap.
+       * Always true in graceful mode.
+       */
+      coverPayment(quoteMicros) {
+        if (this.capMicros === void 0) return true;
+        const spent = this.store.getSessionCostMicros(this.sessionId);
+        const heldByOthers = this.store.getSessionHoldMicros(this.sessionId) - this.heldMicros;
+        if (spent + heldByOthers + quoteMicros > this.capMicros) return false;
+        if (quoteMicros > this.heldMicros) {
+          this.store.adjustSessionHold(this.sessionId, quoteMicros - this.heldMicros);
+          this.heldMicros = quoteMicros;
+        }
+        return true;
+      }
+      /** A payment was signed: it is spend now, and replaces part of the hold. */
+      recordSigned(amountMicros) {
+        if (amountMicros <= 0n) return;
+        this.signedMicros += amountMicros;
+        this.lastSignedMicros = amountMicros;
+        this.store.addSessionCost(this.sessionId, amountMicros);
+        this.shrinkHold(amountMicros);
+      }
+      /**
+       * The gateway answered the payment just signed with a 402: nothing settled.
+       * Payments within one request are signed and sent one at a time, so the
+       * decline always belongs to the latest signature. Undone at most once.
+       */
+      voidLastSigned() {
+        const undo = this.lastSignedMicros;
+        this.lastSignedMicros = 0n;
+        if (undo <= 0n) return;
+        this.signedMicros -= undo;
+        this.store.addSessionCost(this.sessionId, -undo);
+      }
+      /**
+       * An attempt succeeded. When nothing was signed for this request (the API
+       * key rail), the local estimate is the only record of the spend. When a
+       * payment was signed, it is already recorded at its real amount.
+       */
+      recordSuccess(estimateMicros) {
+        if (this.signedMicros > 0n || estimateMicros <= 0n) return;
+        this.store.addSessionCost(this.sessionId, estimateMicros);
+        this.shrinkHold(estimateMicros);
+      }
+      /** The request is over: return whatever it still holds. Idempotent. */
+      release() {
+        if (this.released) return;
+        this.released = true;
+        this.shrinkHold(this.heldMicros);
+      }
+      shrinkHold(byMicros) {
+        const drop = byMicros < this.heldMicros ? byMicros : this.heldMicros;
+        if (drop <= 0n) return;
+        this.heldMicros -= drop;
+        this.store.adjustSessionHold(this.sessionId, -drop);
+      }
+    };
+    CostCapError = class extends SpendPolicyError {
+      constructor(reason) {
+        super(reason);
+        this.name = "CostCapError";
+      }
+    };
+  }
+});
+
 // src/compression/types.ts
 var DEFAULT_COMPRESSION_CONFIG;
 var init_types2 = __esm({
@@ -65636,6 +65779,9 @@ var init_session = __esm({
     };
     SessionStore = class {
       sessions = /* @__PURE__ */ new Map();
+      // Kept apart from `sessions`: a hold belongs to requests still running, so it
+      // must not vanish when the idle-session sweep drops an entry mid-request.
+      sessionHolds = /* @__PURE__ */ new Map();
       config;
       cleanupInterval = null;
       constructor(config = {}) {
@@ -65811,14 +65957,34 @@ var init_session = __esm({
           this.sessions.set(sessionId, entry);
         }
         entry.sessionCostMicros += additionalMicros;
+        if (entry.sessionCostMicros < 0n) entry.sessionCostMicros = 0n;
       }
       /**
        * Get the total accumulated cost for a session in USD.
        */
       getSessionCostUsd(sessionId) {
-        const entry = this.sessions.get(sessionId);
-        if (!entry) return 0;
-        return Number(entry.sessionCostMicros) / 1e6;
+        return Number(this.getSessionCostMicros(sessionId)) / 1e6;
+      }
+      /**
+       * Get the total accumulated cost for a session in USDC micros.
+       */
+      getSessionCostMicros(sessionId) {
+        return this.sessions.get(sessionId)?.sessionCostMicros ?? 0n;
+      }
+      /**
+       * Budget held by a session's in-flight requests (USDC micros) — admitted
+       * against the strict cap but not yet spent. See session-spend.ts.
+       */
+      getSessionHoldMicros(sessionId) {
+        return this.sessionHolds.get(sessionId) ?? 0n;
+      }
+      /**
+       * Grow (positive) or release (negative) a session's in-flight hold.
+       */
+      adjustSessionHold(sessionId, deltaMicros) {
+        const next = (this.sessionHolds.get(sessionId) ?? 0n) + deltaMicros;
+        if (next > 0n) this.sessionHolds.set(sessionId, next);
+        else this.sessionHolds.delete(sessionId);
       }
       /**
        * Stop the cleanup interval.
@@ -96521,6 +96687,19 @@ async function startProxy(options) {
   }
   const account = walletKey ? privateKeyToAccount(walletKey) : void 0;
   const x402 = authMode === "wallet" ? new x402Client() : void 0;
+  x402?.onBeforePaymentCreation(async (context) => {
+    const spend = paymentStore.getStore()?.sessionSpend;
+    if (!spend?.isStrict) return;
+    const quote = parseQuotedAmountMicros(context.selectedRequirements);
+    if (quote === void 0) {
+      throw new CostCapError("ClawRouter cost cap: unreadable payment amount in the 402 quote");
+    }
+    if (!spend.coverPayment(quote)) {
+      throw new CostCapError(
+        `ClawRouter cost cap exceeded: signing $${microsToUsd(quote).toFixed(6)} would push this session past its maxCostPerRun limit`
+      );
+    }
+  });
   if (x402 && account) {
     const evmPublicClient = createPublicClient({ chain: base, transport: http() });
     const evmSigner = toClientEvmSigner(account, evmPublicClient);
@@ -96563,6 +96742,11 @@ async function startProxy(options) {
     if (store) store.amountUsd = amountUsd;
     console.log(`[ClawRouter] Payment signed on ${chain3} (${network}) \u2014 $${amountUsd.toFixed(6)}`);
   });
+  x402?.onAfterPaymentCreation(async (context) => {
+    const spend = paymentStore.getStore()?.sessionSpend;
+    const amount = parseQuotedAmountMicros(context.selectedRequirements);
+    if (spend && amount !== void 0) spend.recordSigned(amount);
+  });
   const payFetch = authMode === "api-key" ? withSpendPolicy(
     createApiKeyFetch(apiKey, fetch, apiBase),
     options.spendControl ?? getSharedSpendControl(),
@@ -96581,7 +96765,10 @@ async function startProxy(options) {
     // Only the wallet rail settles per call. The API-key rail is billed
     // server-side against account credit, so there is no per-request
     // settlement for an observer to report.
-    onPayment: options.onPayment
+    onPayment: options.onPayment,
+    // A 402 answer to a signed payment means the gateway declined it and
+    // nothing settled — take it back off the session's budget.
+    onPaymentDeclined: () => paymentStore.getStore()?.sessionSpend?.voidLastSigned()
   });
   let balanceMonitor;
   if (options._balanceMonitorOverride) {
@@ -97865,6 +98052,17 @@ async function tryModelRequest(upstreamUrl, method, headers, body, modelId, maxT
     return { success: true, response };
   } catch (err) {
     const errorMsg = err instanceof Error ? err.message : String(err);
+    if (err instanceof CostCapError) {
+      return {
+        success: false,
+        errorBody: JSON.stringify({
+          error: { message: errorMsg, type: "cost_cap_exceeded", code: "cost_cap_exceeded" }
+        }),
+        errorStatus: 429,
+        isProviderError: false,
+        errorCategory: "payment_error"
+      };
+    }
     if (err instanceof SpendPolicyError) {
       return {
         success: false,
@@ -98944,14 +99142,23 @@ async function proxyRequest(req, res, apiBase, payFetch, options, routerOpts, de
       }
     }
   }
+  let sessionSpend;
   if (options.maxCostPerRunUsd && effectiveSessionId && !isFreeModel && (options.maxCostPerRunMode ?? "graceful") === "strict") {
-    const runCostUsd = sessionStore.getSessionCostUsd(effectiveSessionId);
     const thisReqEstStr = estimatedCostMicros !== void 0 ? estimatedCostMicros.toString() : modelId ? estimateAmount(modelId, body.length, maxTokens) : void 0;
-    const thisReqEstUsd = thisReqEstStr ? Number(thisReqEstStr) / 1e6 : 0;
-    const projectedCostUsd = runCostUsd + thisReqEstUsd;
-    if (projectedCostUsd > options.maxCostPerRunUsd) {
+    const admission = SessionSpend.admit(
+      sessionStore,
+      effectiveSessionId,
+      usdToMicros(options.maxCostPerRunUsd),
+      parseMicros(thisReqEstStr) ?? 0n
+    );
+    if (!admission.admitted) {
+      const spentUsd = microsToUsd(admission.spentMicros);
+      const heldUsd = microsToUsd(admission.heldMicros);
+      const estUsd = microsToUsd(admission.estimateMicros);
+      const projectedCostUsd = spentUsd + heldUsd + estUsd;
+      const breakdown = `spent $${spentUsd.toFixed(4)}${heldUsd > 0 ? ` + in flight $${heldUsd.toFixed(4)}` : ""} + est $${estUsd.toFixed(4)}`;
       console.log(
-        `[ClawRouter] Cost cap exceeded for session ${effectiveSessionId.slice(0, 8)}...: projected $${projectedCostUsd.toFixed(4)} (spent $${runCostUsd.toFixed(4)} + est $${thisReqEstUsd.toFixed(4)}) > $${options.maxCostPerRunUsd} limit`
+        `[ClawRouter] Cost cap exceeded for session ${effectiveSessionId.slice(0, 8)}...: projected $${projectedCostUsd.toFixed(4)} (${breakdown}) > $${options.maxCostPerRunUsd} limit`
       );
       res.writeHead(429, {
         "Content-Type": "application/json",
@@ -98960,7 +99167,7 @@ async function proxyRequest(req, res, apiBase, payFetch, options, routerOpts, de
       res.end(
         JSON.stringify({
           error: {
-            message: `ClawRouter cost cap exceeded: projected spend $${projectedCostUsd.toFixed(4)} (spent $${runCostUsd.toFixed(4)} + est $${thisReqEstUsd.toFixed(4)}) would exceed limit $${options.maxCostPerRunUsd}`,
+            message: `ClawRouter cost cap exceeded: projected spend $${projectedCostUsd.toFixed(4)} (${breakdown}) would exceed limit $${options.maxCostPerRunUsd}`,
             type: "cost_cap_exceeded",
             code: "cost_cap_exceeded"
           }
@@ -98969,7 +99176,12 @@ async function proxyRequest(req, res, apiBase, payFetch, options, routerOpts, de
       deduplicator.removeInflight(dedupKey);
       return;
     }
+    sessionSpend = admission.spend;
+  } else if (options.maxCostPerRunUsd && effectiveSessionId) {
+    sessionSpend = SessionSpend.track(sessionStore, effectiveSessionId);
   }
+  const requestStore = paymentStore.getStore();
+  if (requestStore) requestStore.sessionSpend = sessionSpend;
   if (options.maxCostPerRunUsd && effectiveSessionId && !isFreeModel && (options.maxCostPerRunMode ?? "graceful") === "graceful") {
     const runCostUsd = sessionStore.getSessionCostUsd(effectiveSessionId);
     const remainingUsd = options.maxCostPerRunUsd - runCostUsd;
@@ -99365,11 +99577,9 @@ data: [DONE]
         actualModelUsed = tryModel;
         recordOutcome(tryModel, requestKind, true);
         console.log(`[ClawRouter] Success with model: ${tryModel}`);
-        if (options.maxCostPerRunUsd && effectiveSessionId && !FREE_MODELS.has(tryModel)) {
-          const costEst = estimateAmount(tryModel, body.length, maxTokens);
-          if (costEst) {
-            sessionStore.addSessionCost(effectiveSessionId, BigInt(costEst));
-          }
+        if (sessionSpend && !FREE_MODELS.has(tryModel)) {
+          const costEst = parseMicros(estimateAmount(tryModel, body.length, maxTokens));
+          if (costEst !== void 0) sessionSpend.recordSuccess(costEst);
         }
         break;
       }
@@ -99443,11 +99653,9 @@ data: [DONE]
             upstream = retryResult.response;
             actualModelUsed = tryModel;
             console.log(`[ClawRouter] Explicit-pin retry succeeded for: ${tryModel}`);
-            if (options.maxCostPerRunUsd && effectiveSessionId && !FREE_MODELS.has(tryModel)) {
-              const costEst = estimateAmount(tryModel, body.length, maxTokens);
-              if (costEst) {
-                sessionStore.addSessionCost(effectiveSessionId, BigInt(costEst));
-              }
+            if (sessionSpend && !FREE_MODELS.has(tryModel)) {
+              const costEst = parseMicros(estimateAmount(tryModel, body.length, maxTokens));
+              if (costEst !== void 0) sessionSpend.recordSuccess(costEst);
             }
             break;
           }
@@ -99514,11 +99722,9 @@ data: [DONE]
                 upstream = retryResult.response;
                 actualModelUsed = tryModel;
                 console.log(`[ClawRouter] Rate-limit retry succeeded for: ${tryModel}`);
-                if (options.maxCostPerRunUsd && effectiveSessionId && !FREE_MODELS.has(tryModel)) {
-                  const costEst = estimateAmount(tryModel, body.length, maxTokens);
-                  if (costEst) {
-                    sessionStore.addSessionCost(effectiveSessionId, BigInt(costEst));
-                  }
+                if (sessionSpend && !FREE_MODELS.has(tryModel)) {
+                  const costEst = parseMicros(estimateAmount(tryModel, body.length, maxTokens));
+                  if (costEst !== void 0) sessionSpend.recordSuccess(costEst);
                 }
                 break;
               }
@@ -99612,6 +99818,7 @@ data: [DONE]
       );
       const rawErrBody = lastError?.body || structuredMessage;
       const errStatus = lastError?.status || 502;
+      const costCapRefusal = errStatus === 429 && rawErrBody.includes('"cost_cap_exceeded"');
       const transformedErr = transformPaymentError(rawErrBody);
       requestHadError = true;
       if (headersSentEarly) {
@@ -99648,7 +99855,8 @@ data: [DONE]
           "Content-Type": "application/json",
           "x-context-used-kb": String(originalContextSizeKB),
           "x-context-limit-kb": String(CONTEXT_LIMIT_KB),
-          ...lastError?.requestId ? { "x-blockrun-request-id": lastError.requestId } : {}
+          ...lastError?.requestId ? { "x-blockrun-request-id": lastError.requestId } : {},
+          ...costCapRefusal ? { "X-ClawRouter-Cost-Cap-Exceeded": "1" } : {}
         });
         res.end(transformedErr);
         deduplicator.complete(dedupKey, {
@@ -100082,6 +100290,8 @@ data: [DONE]
       throw new Error(`Request timed out after ${timeoutMs}ms`, { cause: err });
     }
     throw err;
+  } finally {
+    sessionSpend?.release();
   }
   const logModel = routingDecision?.model ?? modelId;
   if (logModel) {
@@ -100168,6 +100378,7 @@ var init_proxy = __esm({
     init_auth();
     init_api_key();
     init_spend_control();
+    init_session_spend();
     init_compression();
     init_errors5();
     init_version4();
@@ -123261,7 +123472,7 @@ var init_client5 = __esm({
 function resolveSpendControl(deps) {
   return deps?.spendControl ?? getSharedSpendControl();
 }
-function usdToMicros(usd2) {
+function usdToMicros2(usd2) {
   return String(Math.ceil(usd2 * 1e6));
 }
 async function signUnderSpendPolicy(deps, quote, action, sign4) {
@@ -123527,7 +123738,7 @@ Re-call with confirm:true to sign and submit.`,
         payTo: negRisk ? NEG_RISK_CTF_EXCHANGE_V2 : CTF_EXCHANGE_V2,
         network: `eip155:${POLYGON_CHAIN_ID}`,
         asset: PUSD_COLLATERAL,
-        amount: usdToMicros(notional)
+        amount: usdToMicros2(notional)
       };
       let r2;
       try {

package/dist/index.d.ts

@@ -966,6 +966,7 @@ declare const DEFAULT_SESSION_CONFIG: SessionConfig;
  */
 declare class SessionStore {
     private sessions;
+    private sessionHolds;
     private config;
     private cleanupInterval;
     constructor(config?: Partial<SessionConfig>);
@@ -1036,6 +1037,19 @@ declare class SessionStore {
      * Get the total accumulated cost for a session in USD.
      */
     getSessionCostUsd(sessionId: string): number;
+    /**
+     * Get the total accumulated cost for a session in USDC micros.
+     */
+    getSessionCostMicros(sessionId: string): bigint;
+    /**
+     * Budget held by a session's in-flight requests (USDC micros) — admitted
+     * against the strict cap but not yet spent. See session-spend.ts.
+     */
+    getSessionHoldMicros(sessionId: string): bigint;
+    /**
+     * Grow (positive) or release (negative) a session's in-flight hold.
+     */
+    adjustSessionHold(sessionId: string, deltaMicros: bigint): void;
     /**
      * Stop the cleanup interval.
      */

package/dist/index.js

@@ -34678,6 +34678,11 @@ function getSharedSpendControl() {
   host.__clawrouterSharedSpendControl ??= new SpendControl();
   return host.__clawrouterSharedSpendControl;
 }
+function parseQuotedAmountMicros(selected) {
+  const raw = selected.amount ?? selected.maxAmountRequired;
+  if (typeof raw !== "string" || !CANONICAL_AMOUNT.test(raw)) return void 0;
+  return BigInt(raw);
+}
 function parseQuotedAmountUsd(selected) {
   const raw = selected.amount ?? selected.maxAmountRequired;
   if (typeof raw !== "string" || !CANONICAL_AMOUNT.test(raw)) {
@@ -35443,6 +35448,16 @@ function createPayFetchWithPreAuth(baseFetch, client, ttlMs = DEFAULT_TTL_MS, op
       return est === void 0 ? void 0 : Number(est);
     };
     const needMicros = estimateMicros();
+    const notifyDeclinedPayment = () => {
+      if (!options?.onPaymentDeclined) return;
+      try {
+        options.onPaymentDeclined();
+      } catch (error) {
+        console.error(
+          `[ClawRouter] onPaymentDeclined callback failed: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    };
     const cached = !options?.skipPreAuth ? cache2.get(cacheKey2) : void 0;
     const preAuthCovers = cached !== void 0 && Date.now() - cached.cachedAt < ttlMs && cached.coverMicros !== void 0 && needMicros !== void 0 && needMicros <= cached.coverMicros;
     if (preAuthCovers) {
@@ -35461,6 +35476,7 @@ function createPayFetchWithPreAuth(baseFetch, client, ttlMs = DEFAULT_TTL_MS, op
           return response2;
         }
         paymentInFlight = false;
+        notifyDeclinedPayment();
         cache2.delete(cacheKey2);
       } catch (err) {
         cache2.delete(cacheKey2);
@@ -35505,6 +35521,7 @@ function createPayFetchWithPreAuth(baseFetch, client, ttlMs = DEFAULT_TTL_MS, op
       clonedRequest.headers.set(key3, value);
     }
     const paidResponse = await baseFetch(clonedRequest);
+    if (paidResponse.status === 402) notifyDeclinedPayment();
     notifyAcceptedPayment(paidResponse, payload);
     return paidResponse;
   };
@@ -64542,6 +64559,132 @@ var init_api_key = __esm({
   }
 });
 
+// src/session-spend.ts
+function parseMicros(raw) {
+  if (raw === void 0 || !/^\d+$/.test(raw)) return void 0;
+  return BigInt(raw);
+}
+function usdToMicros(usd) {
+  return BigInt(Math.round(usd * 1e6));
+}
+function microsToUsd(micros) {
+  return Number(micros) / 1e6;
+}
+var SessionSpend, CostCapError;
+var init_session_spend = __esm({
+  "src/session-spend.ts"() {
+    "use strict";
+    init_spend_control();
+    SessionSpend = class _SessionSpend {
+      constructor(store, sessionId, capMicros, holdMicros) {
+        this.store = store;
+        this.sessionId = sessionId;
+        this.capMicros = capMicros;
+        this.heldMicros = holdMicros;
+        if (holdMicros > 0n) store.adjustSessionHold(sessionId, holdMicros);
+      }
+      store;
+      sessionId;
+      capMicros;
+      /** Budget this request still holds against the session (strict mode only). */
+      heldMicros;
+      /** Sum of payments signed by this request that still count. */
+      signedMicros = 0n;
+      /** The most recent signature not yet settled or voided — the one a decline undoes. */
+      lastSignedMicros = 0n;
+      released = false;
+      /**
+       * Strict mode: admit the request only if the session's spend, plus what its
+       * other in-flight requests hold, plus this request's estimate fits the cap —
+       * and hold the estimate in the same step.
+       */
+      static admit(store, sessionId, capMicros, estimateMicros) {
+        const spentMicros = store.getSessionCostMicros(sessionId);
+        const heldMicros = store.getSessionHoldMicros(sessionId);
+        if (spentMicros + heldMicros + estimateMicros > capMicros) {
+          return { admitted: false, spentMicros, heldMicros, estimateMicros };
+        }
+        return {
+          admitted: true,
+          spend: new _SessionSpend(store, sessionId, capMicros, estimateMicros)
+        };
+      }
+      /** Graceful mode: track signed spend, enforce nothing. */
+      static track(store, sessionId) {
+        return new _SessionSpend(store, sessionId, void 0, 0n);
+      }
+      get isStrict() {
+        return this.capMicros !== void 0;
+      }
+      /**
+       * Before a payment is created: may this request sign `quoteMicros`?
+       * Spend already recorded (including this request's own earlier signatures)
+       * plus what OTHER in-flight requests hold, plus the quote, must fit the cap.
+       * Always true in graceful mode.
+       */
+      coverPayment(quoteMicros) {
+        if (this.capMicros === void 0) return true;
+        const spent = this.store.getSessionCostMicros(this.sessionId);
+        const heldByOthers = this.store.getSessionHoldMicros(this.sessionId) - this.heldMicros;
+        if (spent + heldByOthers + quoteMicros > this.capMicros) return false;
+        if (quoteMicros > this.heldMicros) {
+          this.store.adjustSessionHold(this.sessionId, quoteMicros - this.heldMicros);
+          this.heldMicros = quoteMicros;
+        }
+        return true;
+      }
+      /** A payment was signed: it is spend now, and replaces part of the hold. */
+      recordSigned(amountMicros) {
+        if (amountMicros <= 0n) return;
+        this.signedMicros += amountMicros;
+        this.lastSignedMicros = amountMicros;
+        this.store.addSessionCost(this.sessionId, amountMicros);
+        this.shrinkHold(amountMicros);
+      }
+      /**
+       * The gateway answered the payment just signed with a 402: nothing settled.
+       * Payments within one request are signed and sent one at a time, so the
+       * decline always belongs to the latest signature. Undone at most once.
+       */
+      voidLastSigned() {
+        const undo = this.lastSignedMicros;
+        this.lastSignedMicros = 0n;
+        if (undo <= 0n) return;
+        this.signedMicros -= undo;
+        this.store.addSessionCost(this.sessionId, -undo);
+      }
+      /**
+       * An attempt succeeded. When nothing was signed for this request (the API
+       * key rail), the local estimate is the only record of the spend. When a
+       * payment was signed, it is already recorded at its real amount.
+       */
+      recordSuccess(estimateMicros) {
+        if (this.signedMicros > 0n || estimateMicros <= 0n) return;
+        this.store.addSessionCost(this.sessionId, estimateMicros);
+        this.shrinkHold(estimateMicros);
+      }
+      /** The request is over: return whatever it still holds. Idempotent. */
+      release() {
+        if (this.released) return;
+        this.released = true;
+        this.shrinkHold(this.heldMicros);
+      }
+      shrinkHold(byMicros) {
+        const drop = byMicros < this.heldMicros ? byMicros : this.heldMicros;
+        if (drop <= 0n) return;
+        this.heldMicros -= drop;
+        this.store.adjustSessionHold(this.sessionId, -drop);
+      }
+    };
+    CostCapError = class extends SpendPolicyError {
+      constructor(reason) {
+        super(reason);
+        this.name = "CostCapError";
+      }
+    };
+  }
+});
+
 // src/compression/types.ts
 var DEFAULT_COMPRESSION_CONFIG;
 var init_types2 = __esm({
@@ -65389,6 +65532,9 @@ var init_session = __esm({
     };
     SessionStore = class {
       sessions = /* @__PURE__ */ new Map();
+      // Kept apart from `sessions`: a hold belongs to requests still running, so it
+      // must not vanish when the idle-session sweep drops an entry mid-request.
+      sessionHolds = /* @__PURE__ */ new Map();
       config;
       cleanupInterval = null;
       constructor(config = {}) {
@@ -65564,14 +65710,34 @@ var init_session = __esm({
           this.sessions.set(sessionId, entry);
         }
         entry.sessionCostMicros += additionalMicros;
+        if (entry.sessionCostMicros < 0n) entry.sessionCostMicros = 0n;
       }
       /**
        * Get the total accumulated cost for a session in USD.
        */
       getSessionCostUsd(sessionId) {
-        const entry = this.sessions.get(sessionId);
-        if (!entry) return 0;
-        return Number(entry.sessionCostMicros) / 1e6;
+        return Number(this.getSessionCostMicros(sessionId)) / 1e6;
+      }
+      /**
+       * Get the total accumulated cost for a session in USDC micros.
+       */
+      getSessionCostMicros(sessionId) {
+        return this.sessions.get(sessionId)?.sessionCostMicros ?? 0n;
+      }
+      /**
+       * Budget held by a session's in-flight requests (USDC micros) — admitted
+       * against the strict cap but not yet spent. See session-spend.ts.
+       */
+      getSessionHoldMicros(sessionId) {
+        return this.sessionHolds.get(sessionId) ?? 0n;
+      }
+      /**
+       * Grow (positive) or release (negative) a session's in-flight hold.
+       */
+      adjustSessionHold(sessionId, deltaMicros) {
+        const next = (this.sessionHolds.get(sessionId) ?? 0n) + deltaMicros;
+        if (next > 0n) this.sessionHolds.set(sessionId, next);
+        else this.sessionHolds.delete(sessionId);
       }
       /**
        * Stop the cleanup interval.
@@ -96274,6 +96440,19 @@ async function startProxy(options) {
   }
   const account = walletKey ? privateKeyToAccount(walletKey) : void 0;
   const x402 = authMode === "wallet" ? new x402Client() : void 0;
+  x402?.onBeforePaymentCreation(async (context) => {
+    const spend = paymentStore.getStore()?.sessionSpend;
+    if (!spend?.isStrict) return;
+    const quote = parseQuotedAmountMicros(context.selectedRequirements);
+    if (quote === void 0) {
+      throw new CostCapError("ClawRouter cost cap: unreadable payment amount in the 402 quote");
+    }
+    if (!spend.coverPayment(quote)) {
+      throw new CostCapError(
+        `ClawRouter cost cap exceeded: signing $${microsToUsd(quote).toFixed(6)} would push this session past its maxCostPerRun limit`
+      );
+    }
+  });
   if (x402 && account) {
     const evmPublicClient = createPublicClient({ chain: base, transport: http() });
     const evmSigner = toClientEvmSigner(account, evmPublicClient);
@@ -96316,6 +96495,11 @@ async function startProxy(options) {
     if (store) store.amountUsd = amountUsd;
     console.log(`[ClawRouter] Payment signed on ${chain3} (${network}) \u2014 $${amountUsd.toFixed(6)}`);
   });
+  x402?.onAfterPaymentCreation(async (context) => {
+    const spend = paymentStore.getStore()?.sessionSpend;
+    const amount = parseQuotedAmountMicros(context.selectedRequirements);
+    if (spend && amount !== void 0) spend.recordSigned(amount);
+  });
   const payFetch = authMode === "api-key" ? withSpendPolicy(
     createApiKeyFetch(apiKey, fetch, apiBase),
     options.spendControl ?? getSharedSpendControl(),
@@ -96334,7 +96518,10 @@ async function startProxy(options) {
     // Only the wallet rail settles per call. The API-key rail is billed
     // server-side against account credit, so there is no per-request
     // settlement for an observer to report.
-    onPayment: options.onPayment
+    onPayment: options.onPayment,
+    // A 402 answer to a signed payment means the gateway declined it and
+    // nothing settled — take it back off the session's budget.
+    onPaymentDeclined: () => paymentStore.getStore()?.sessionSpend?.voidLastSigned()
   });
   let balanceMonitor;
   if (options._balanceMonitorOverride) {
@@ -97618,6 +97805,17 @@ async function tryModelRequest(upstreamUrl, method, headers, body, modelId, maxT
     return { success: true, response };
   } catch (err) {
     const errorMsg = err instanceof Error ? err.message : String(err);
+    if (err instanceof CostCapError) {
+      return {
+        success: false,
+        errorBody: JSON.stringify({
+          error: { message: errorMsg, type: "cost_cap_exceeded", code: "cost_cap_exceeded" }
+        }),
+        errorStatus: 429,
+        isProviderError: false,
+        errorCategory: "payment_error"
+      };
+    }
     if (err instanceof SpendPolicyError) {
       return {
         success: false,
@@ -98697,14 +98895,23 @@ async function proxyRequest(req, res, apiBase, payFetch, options, routerOpts, de
       }
     }
   }
+  let sessionSpend;
   if (options.maxCostPerRunUsd && effectiveSessionId && !isFreeModel && (options.maxCostPerRunMode ?? "graceful") === "strict") {
-    const runCostUsd = sessionStore.getSessionCostUsd(effectiveSessionId);
     const thisReqEstStr = estimatedCostMicros !== void 0 ? estimatedCostMicros.toString() : modelId ? estimateAmount(modelId, body.length, maxTokens) : void 0;
-    const thisReqEstUsd = thisReqEstStr ? Number(thisReqEstStr) / 1e6 : 0;
-    const projectedCostUsd = runCostUsd + thisReqEstUsd;
-    if (projectedCostUsd > options.maxCostPerRunUsd) {
+    const admission = SessionSpend.admit(
+      sessionStore,
+      effectiveSessionId,
+      usdToMicros(options.maxCostPerRunUsd),
+      parseMicros(thisReqEstStr) ?? 0n
+    );
+    if (!admission.admitted) {
+      const spentUsd = microsToUsd(admission.spentMicros);
+      const heldUsd = microsToUsd(admission.heldMicros);
+      const estUsd = microsToUsd(admission.estimateMicros);
+      const projectedCostUsd = spentUsd + heldUsd + estUsd;
+      const breakdown = `spent $${spentUsd.toFixed(4)}${heldUsd > 0 ? ` + in flight $${heldUsd.toFixed(4)}` : ""} + est $${estUsd.toFixed(4)}`;
       console.log(
-        `[ClawRouter] Cost cap exceeded for session ${effectiveSessionId.slice(0, 8)}...: projected $${projectedCostUsd.toFixed(4)} (spent $${runCostUsd.toFixed(4)} + est $${thisReqEstUsd.toFixed(4)}) > $${options.maxCostPerRunUsd} limit`
+        `[ClawRouter] Cost cap exceeded for session ${effectiveSessionId.slice(0, 8)}...: projected $${projectedCostUsd.toFixed(4)} (${breakdown}) > $${options.maxCostPerRunUsd} limit`
       );
       res.writeHead(429, {
         "Content-Type": "application/json",
@@ -98713,7 +98920,7 @@ async function proxyRequest(req, res, apiBase, payFetch, options, routerOpts, de
       res.end(
         JSON.stringify({
           error: {
-            message: `ClawRouter cost cap exceeded: projected spend $${projectedCostUsd.toFixed(4)} (spent $${runCostUsd.toFixed(4)} + est $${thisReqEstUsd.toFixed(4)}) would exceed limit $${options.maxCostPerRunUsd}`,
+            message: `ClawRouter cost cap exceeded: projected spend $${projectedCostUsd.toFixed(4)} (${breakdown}) would exceed limit $${options.maxCostPerRunUsd}`,
             type: "cost_cap_exceeded",
             code: "cost_cap_exceeded"
           }
@@ -98722,7 +98929,12 @@ async function proxyRequest(req, res, apiBase, payFetch, options, routerOpts, de
       deduplicator.removeInflight(dedupKey);
       return;
     }
+    sessionSpend = admission.spend;
+  } else if (options.maxCostPerRunUsd && effectiveSessionId) {
+    sessionSpend = SessionSpend.track(sessionStore, effectiveSessionId);
   }
+  const requestStore = paymentStore.getStore();
+  if (requestStore) requestStore.sessionSpend = sessionSpend;
   if (options.maxCostPerRunUsd && effectiveSessionId && !isFreeModel && (options.maxCostPerRunMode ?? "graceful") === "graceful") {
     const runCostUsd = sessionStore.getSessionCostUsd(effectiveSessionId);
     const remainingUsd = options.maxCostPerRunUsd - runCostUsd;
@@ -99118,11 +99330,9 @@ data: [DONE]
         actualModelUsed = tryModel;
         recordOutcome(tryModel, requestKind, true);
         console.log(`[ClawRouter] Success with model: ${tryModel}`);
-        if (options.maxCostPerRunUsd && effectiveSessionId && !FREE_MODELS.has(tryModel)) {
-          const costEst = estimateAmount(tryModel, body.length, maxTokens);
-          if (costEst) {
-            sessionStore.addSessionCost(effectiveSessionId, BigInt(costEst));
-          }
+        if (sessionSpend && !FREE_MODELS.has(tryModel)) {
+          const costEst = parseMicros(estimateAmount(tryModel, body.length, maxTokens));
+          if (costEst !== void 0) sessionSpend.recordSuccess(costEst);
         }
         break;
       }
@@ -99196,11 +99406,9 @@ data: [DONE]
             upstream = retryResult.response;
             actualModelUsed = tryModel;
             console.log(`[ClawRouter] Explicit-pin retry succeeded for: ${tryModel}`);
-            if (options.maxCostPerRunUsd && effectiveSessionId && !FREE_MODELS.has(tryModel)) {
-              const costEst = estimateAmount(tryModel, body.length, maxTokens);
-              if (costEst) {
-                sessionStore.addSessionCost(effectiveSessionId, BigInt(costEst));
-              }
+            if (sessionSpend && !FREE_MODELS.has(tryModel)) {
+              const costEst = parseMicros(estimateAmount(tryModel, body.length, maxTokens));
+              if (costEst !== void 0) sessionSpend.recordSuccess(costEst);
             }
             break;
           }
@@ -99267,11 +99475,9 @@ data: [DONE]
                 upstream = retryResult.response;
                 actualModelUsed = tryModel;
                 console.log(`[ClawRouter] Rate-limit retry succeeded for: ${tryModel}`);
-                if (options.maxCostPerRunUsd && effectiveSessionId && !FREE_MODELS.has(tryModel)) {
-                  const costEst = estimateAmount(tryModel, body.length, maxTokens);
-                  if (costEst) {
-                    sessionStore.addSessionCost(effectiveSessionId, BigInt(costEst));
-                  }
+                if (sessionSpend && !FREE_MODELS.has(tryModel)) {
+                  const costEst = parseMicros(estimateAmount(tryModel, body.length, maxTokens));
+                  if (costEst !== void 0) sessionSpend.recordSuccess(costEst);
                 }
                 break;
               }
@@ -99365,6 +99571,7 @@ data: [DONE]
       );
       const rawErrBody = lastError?.body || structuredMessage;
       const errStatus = lastError?.status || 502;
+      const costCapRefusal = errStatus === 429 && rawErrBody.includes('"cost_cap_exceeded"');
       const transformedErr = transformPaymentError(rawErrBody);
       requestHadError = true;
       if (headersSentEarly) {
@@ -99401,7 +99608,8 @@ data: [DONE]
           "Content-Type": "application/json",
           "x-context-used-kb": String(originalContextSizeKB),
           "x-context-limit-kb": String(CONTEXT_LIMIT_KB),
-          ...lastError?.requestId ? { "x-blockrun-request-id": lastError.requestId } : {}
+          ...lastError?.requestId ? { "x-blockrun-request-id": lastError.requestId } : {},
+          ...costCapRefusal ? { "X-ClawRouter-Cost-Cap-Exceeded": "1" } : {}
         });
         res.end(transformedErr);
         deduplicator.complete(dedupKey, {
@@ -99835,6 +100043,8 @@ data: [DONE]
       throw new Error(`Request timed out after ${timeoutMs}ms`, { cause: err });
     }
     throw err;
+  } finally {
+    sessionSpend?.release();
   }
   const logModel = routingDecision?.model ?? modelId;
   if (logModel) {
@@ -99921,6 +100131,7 @@ var init_proxy = __esm({
     init_auth();
     init_api_key();
     init_spend_control();
+    init_session_spend();
     init_compression();
     init_errors5();
     init_version4();
@@ -122622,7 +122833,7 @@ var init_client5 = __esm({
 function resolveSpendControl(deps) {
   return deps?.spendControl ?? getSharedSpendControl();
 }
-function usdToMicros(usd) {
+function usdToMicros2(usd) {
   return String(Math.ceil(usd * 1e6));
 }
 async function signUnderSpendPolicy(deps, quote, action, sign4) {
@@ -122888,7 +123099,7 @@ Re-call with confirm:true to sign and submit.`,
         payTo: negRisk ? NEG_RISK_CTF_EXCHANGE_V2 : CTF_EXCHANGE_V2,
         network: `eip155:${POLYGON_CHAIN_ID}`,
         asset: PUSD_COLLATERAL,
-        amount: usdToMicros(notional)
+        amount: usdToMicros2(notional)
       };
       let r2;
       try {

package/docs/9-free-ai-models-zero-cost-blockrun.md

@@ -1,7 +1,7 @@
 # 9 Free AI Models, Zero Cost: How BlockRun Gives Developers Top-Tier LLMs for Nothing
 
 > **The count in this title is a snapshot, and so is every model name below.**
-> It was 9 when this was written; the published free tier is <!-- br:models.free -->6<!-- /br:models.free --> today, and _none_ of the
+> It was 9 when this was written; the published free tier is <!-- br:models.free -->7<!-- /br:models.free --> today, and _none_ of the
 > nine originals is still in it. Free hosting is volatile — NVIDIA retired four
 > of the five visible free models in a single sweep on 2026-08-30 — so the tier
 > gets rebuilt rather than topped up. The URL keeps its original slug so existing
@@ -23,7 +23,7 @@ BlockRun's answer: just take them.
 
 ---
 
-## The Lineup: <!-- br:models.free -->6<!-- /br:models.free --> Models, $0.00
+## The Lineup: <!-- br:models.free -->7<!-- /br:models.free --> Models, $0.00
 
 Through [ClawRouter](https://github.com/BlockRunAI/ClawRouter) — BlockRun's local AI routing proxy — you get zero-cost access to the following (checked against the live catalog 2026-09-29):
 
@@ -236,13 +236,13 @@ Look at the cost trajectory over the past three years:
 - **2023:** GPT-4 dominates alone at $30/$60 per M tokens
 - **2024:** Open-source models surge, prices halve repeatedly
 - **2025:** DeepSeek, Qwen push top-tier inference below $1/M
-- **2026:** BlockRun offers <!-- br:models.free -->6<!-- /br:models.free --> free models through a single API
+- **2026:** BlockRun offers <!-- br:models.free -->7<!-- /br:models.free --> free models through a single API
 
 **A free tier that gets rebuilt rather than retired isn't just a product feature — it's a signal.** Baseline AI capability is becoming infrastructure. Like internet bandwidth before it, the cost of "good enough" AI inference is converging toward zero.
 
 BlockRun and ClawRouter exist to be the **routing layer** in this transition: not locked to any single provider, not bound to any single model, always giving developers the lowest-cost path to the right capability.
 
-Today it's <!-- br:models.free -->6<!-- /br:models.free --> free models, and they are not the same seven as last month. Tomorrow it could be 50. Prices will only drop. Capabilities will only improve. The names will keep churning.
+Today it's <!-- br:models.free -->7<!-- /br:models.free --> free models, and they are not the same seven as last month. Tomorrow it could be 50. Prices will only drop. Capabilities will only improve. The names will keep churning.
 
 **The one constant: your code doesn't need to change.**
 
@@ -257,7 +257,7 @@ clawrouter start
 
 Point your `base_url` to `http://localhost:8402/v1`. That's the whole setup.
 
-<!-- br:models.free -->6<!-- /br:models.free --> free models. Up to 1M context. Unlimited calls. Zero cost.
+<!-- br:models.free -->7<!-- /br:models.free --> free models. Up to 1M context. Unlimited calls. Zero cost.
 
 Go build something.
 

package/docs/anthropic-cost-savings.md

@@ -50,7 +50,7 @@ This is where you're paying for real value:
 
 ## The Solution: ClawRouter
 
-[ClawRouter](https://github.com/BlockRunAI/ClawRouter) is an open-source local proxy that sits between your app and <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> AI models. It saves you money in three ways: **smart routing**, **token optimization**, and **response caching**.
+[ClawRouter](https://github.com/BlockRunAI/ClawRouter) is an open-source local proxy that sits between your app and <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> AI models. It saves you money in three ways: **smart routing**, **token optimization**, and **response caching**.
 
 ```
 ┌─────────────┐     ┌──────────────────────────────┐     ┌──────────────────┐

package/docs/anthropic-third-party-harness-changes.md

@@ -31,7 +31,7 @@ This is exactly the problem [ClawRouter](https://github.com/BlockRunAI/ClawRoute
 
 ## ClawRouter: Smart Routing for Agents
 
-ClawRouter is an open-source local proxy that sits between your agent and <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> LLM models across 9 providers. It analyzes every request across 15 dimensions and routes it to the cheapest model that can handle it — in under 1ms, entirely locally.
+ClawRouter is an open-source local proxy that sits between your agent and <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> LLM models across 9 providers. It analyzes every request across 15 dimensions and routes it to the cheapest model that can handle it — in under 1ms, entirely locally.
 
 ```
 Your Agent → ClawRouter (localhost:8402) → Best model for the job
@@ -74,12 +74,12 @@ Then point your agent at `http://localhost:8402/v1/` with any OpenAI-compatible
 
 - **No API keys to manage** — wallet-based cryptographic auth
 - **No subscriptions** — pay per request in USDC (Base or Solana)
-- **No vendor lock-in** — <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> models, switch anytime
+- **No vendor lock-in** — <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models, switch anytime
 - **You control your wallet** — non-custodial, funds never held by a third party
 - **Budget caps** — set a max spend per session, ClawRouter gracefully downgrades when budget runs low
 - **Token compression** — 7-layer pipeline reduces token costs by 7–40% before they hit any provider
 - **Response caching** — identical requests within 10 minutes cost $0
-- **<!-- br:models.free -->6<!-- /br:models.free --> free models** — for tasks that don't need a paid model at all
+- **<!-- br:models.free -->7<!-- /br:models.free --> free models** — for tasks that don't need a paid model at all
 
 ### Routing Profiles
 

package/docs/clawrouter-vs-openrouter-llm-routing-comparison.md

@@ -222,7 +222,7 @@ OpenRouter doesn't always pass through provider-specific features correctly. Ima
 
 **Direct provider routing.** ClawRouter routes through BlockRun's API directly to providers — not through a second aggregator. One hop, not two. Provider-specific features work because there's no middleman translating them.
 
-![Guaranteed Feature Parity & Direct Connectivity — Three-panel diagram: Vision (image_url auto-detected → vision-capable models only), Tool Calling (toolCalling flag → agentic models only), Catalog (curated <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> models with automatic legacy-to-modern redirects). Direct provider routing means no dropped payloads.](./assets/clawrouter-feature-parity-direct-connectivity.png)
+![Guaranteed Feature Parity & Direct Connectivity — Three-panel diagram: Vision (image_url auto-detected → vision-capable models only), Tool Calling (toolCalling flag → agentic models only), Catalog (curated <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models with automatic legacy-to-modern redirects). Direct provider routing means no dropped payloads.](./assets/clawrouter-feature-parity-direct-connectivity.png)
 
 ---
 
@@ -240,7 +240,7 @@ When new models launch, OpenRouter's catalog lags. Users configure a model that
 
 ### How ClawRouter Solves This
 
-ClawRouter maintains a curated catalog of <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> models across 9 providers (including <!-- br:models.free -->6<!-- /br:models.free --> free models), updated with each release. Delisted models have automatic redirect aliases:
+ClawRouter maintains a curated catalog of <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models across 9 providers (including <!-- br:models.free -->7<!-- /br:models.free --> free models), updated with each release. Delisted models have automatic redirect aliases:
 
 ```typescript
 // Delisted models redirect automatically
@@ -268,7 +268,7 @@ No silent drops. No stale catalog. Models are benchmarked for speed, quality, an
 | **Rate limits**     | Per-key, shared                  | Per-wallet, independent                                                                                  |
 | **Vision support**  | Images sometimes dropped         | Auto-detected, vision-only fallback                                                                      |
 | **Tool calling**    | Silent failures with some models | Flag-based filtering, guaranteed support                                                                 |
-| **Model catalog**   | Laggy, silent drops              | Curated <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> models, redirect aliases         |
+| **Model catalog**   | Laggy, silent drops              | Curated <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models, redirect aliases         |
 | **Budget control**  | Monthly invoice                  | Per-session cap (`maxCostPerRun`)                                                                        |
 | **Setup**           | Create account, paste key        | Agent generates wallet, auto-configured                                                                  |
 | **Average cost**    | $25/M tokens (Opus direct)       | auto-routed = **<!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->% savings** |

package/docs/configuration.md

@@ -489,9 +489,15 @@ plugins:
       # graceful (default): when budget runs low, ClawRouter automatically downgrades
       #   to cheaper models (premium → auto → eco → free). Tasks keep running.
       #   Only returns an error if no model can serve the request at all.
+      #   Spend is the amount each signed payment authorized, counted when it is
+      #   signed — a payment whose response is lost still counts.
       #
       # strict: immediately returns 429 (X-ClawRouter-Cost-Cap-Exceeded: 1) once
       #   the session spend reaches the cap. Use when you need a hard budget ceiling.
+      #   Requests in flight hold their estimated cost, so concurrent calls cannot
+      #   all pass on the same spent total; every signed payment counts at once,
+      #   even one whose response is lost; and each payment (including retries and
+      #   fallbacks) is checked against the cap before it is signed.
       maxCostPerRunMode: graceful # or: strict
 
       # Note: image generation endpoints (/v1/images/generations) bypass maxCostPerRun.

package/package.json

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

package/skills/clawrouter/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clawrouter
-description: Hosted-gateway LLM router — save 84% on inference costs. A local proxy that forwards each request to the blockrun.ai gateway, which routes to the cheapest capable model across 82 models from OpenAI, Anthropic, Google, DeepSeek, xAI, Z.AI, and more. 6 free open-weight models included. Also exposes realtime market data (global stocks, crypto, FX, commodities), Twitter/X intelligence, prediction-market data across Polymarket, Kalshi, Limitless, Opinion, Predict.Fun, dFlow + UMA oracle resolution + wallet identity & clustering, phone-number intelligence (carrier + SIM-swap fraud detection) plus AI-powered outbound voice calls (Twilio + Bland.ai), AND the Surf unified crypto data API (84 endpoints — CEX/DEX, on-chain SQL over 80+ ClickHouse tables, 100M+ labeled wallets, prediction markets, social/CT mindshare, news, VC fund intel) as built-in agent tools. Not a local-inference tool — prompts are sent to the blockrun.ai gateway.
+description: Hosted-gateway LLM router — save 84% on inference costs. A local proxy that forwards each request to the blockrun.ai gateway, which routes to the cheapest capable model across 88 models from OpenAI, Anthropic, Google, DeepSeek, xAI, Z.AI, and more. 7 free open-weight models included. Also exposes realtime market data (global stocks, crypto, FX, commodities), Twitter/X intelligence, prediction-market data across Polymarket, Kalshi, Limitless, Opinion, Predict.Fun, dFlow + UMA oracle resolution + wallet identity & clustering, phone-number intelligence (carrier + SIM-swap fraud detection) plus AI-powered outbound voice calls (Twilio + Bland.ai), AND the Surf unified crypto data API (84 endpoints — CEX/DEX, on-chain SQL over 80+ ClickHouse tables, 100M+ labeled wallets, prediction markets, social/CT mindshare, news, VC fund intel) as built-in agent tools. Not a local-inference tool — prompts are sent to the blockrun.ai gateway.
 triggers:
   - "clawrouter"
   - "claw router"
@@ -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 -->82<!-- /br:models.chatVisible --> models from 9 providers (<!-- br:models.free -->6<!-- /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.
+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 -->88<!-- /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.
 
@@ -147,7 +147,7 @@ it against a baseline nobody wrote down. See
 
 ## Available Models
 
-<!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> models including: gpt-6-astra [GPT-6 flagship, 1M ctx], gpt-6-sol, gpt-6-luna [fast, $0.10/$0.50], gpt-5.6-terra [balanced, stable default], gpt-5.6-sol [flagship], gpt-5.6-luna [cost-efficient], gpt-5.6-sol/terra/luna-pro [pro reasoning tiers], gpt-5.5, gpt-5.5-pro [max compute], chat-latest [ChatGPT Instant], gpt-5.4, gpt-5.1, gpt-4o, o3, claude-fable-5.1, claude-fable-5, claude-opus-5.5 [newest Opus, $4/$20], claude-opus-5 [1M ctx], claude-opus-4.8, claude-opus-4.7, claude-opus-4.5, claude-sonnet-5.5, claude-sonnet-5, claude-sonnet-4.6, gemini-3.1-pro, gemini-3.6-flash, gemini-3.5-flash-lite, gemini-2.5-flash, deepseek-v4-pro, deepseek-chat, grok-4.7, grok-4.6, grok-4.5, grok-4.3, grok-build-0.1, glm-5.3 [Z.AI flagship, 1M ctx], glm-5.3-flash [natively multimodal, 1M ctx — $0.15/$0.50], glm-5.2, minimax-m3, kimi-k3 [1M ctx flagship], kimi-k2.7, qwen3.7-max [Qwen flagship, 1M ctx], qwen3.7-plus, qwen3.7-flash, mimo [Xiaomi MiMo-V2.5 Pro, 1M ctx], and <!-- br:models.free -->6<!-- /br:models.free --> free open-weight models (nemotron-3.5-lightning [1M ctx, thinking mode — the free default], nemotron-3-ultra-550b [550B/55B MoE, 1M ctx — the largest free model], nemotron-3-nano-omni-30b-a3b-reasoning [256K ctx], llama-3.2-11b-vision [Meta Llama], north-mini-code [Cohere, coding, sub-second], laguna-xs-2.1 [Poolside, coding, ~161 tok/s]). The free tier is text-only — image turns route to a paid vision model, because the two free models the catalogs advertise as vision-capable fail a solid-colour probe on both chains and do so with an HTTP 200.
+<!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> models including: gpt-6-astra [GPT-6 flagship, 1M ctx], gpt-6-sol, gpt-6-luna [fast, $0.10/$0.50], gpt-5.6-terra [balanced, stable default], gpt-5.6-sol [flagship], gpt-5.6-luna [cost-efficient], gpt-5.6-sol/terra/luna-pro [pro reasoning tiers], gpt-5.5, gpt-5.5-pro [max compute], chat-latest [ChatGPT Instant], gpt-5.4, gpt-5.1, gpt-4o, o3, claude-fable-5.1, claude-fable-5, claude-opus-5.5 [newest Opus, $4/$20], claude-opus-5 [1M ctx], claude-opus-4.8, claude-opus-4.7, claude-opus-4.5, claude-sonnet-5.5, claude-sonnet-5, claude-sonnet-4.6, gemini-3.1-pro, gemini-3.6-flash, gemini-3.5-flash-lite, gemini-2.5-flash, deepseek-v4-pro, deepseek-chat, grok-4.7, grok-4.6, grok-4.5, grok-4.3, grok-build-0.1, glm-5.3 [Z.AI flagship, 1M ctx], glm-5.3-flash [natively multimodal, 1M ctx — $0.15/$0.50], glm-5.2, minimax-m3, kimi-k3 [1M ctx flagship], kimi-k2.7, qwen3.7-max [Qwen flagship, 1M ctx], qwen3.7-plus, qwen3.7-flash, mimo [Xiaomi MiMo-V2.5 Pro, 1M ctx], and <!-- br:models.free -->7<!-- /br:models.free --> free open-weight models (nemotron-3.5-lightning [1M ctx, thinking mode — the free default], nemotron-3-ultra-550b [550B/55B MoE, 1M ctx — the largest free model], nemotron-3-nano-omni-30b-a3b-reasoning [256K ctx], llama-3.2-11b-vision [Meta Llama], north-mini-code [Cohere, coding, sub-second], laguna-xs-2.1 [Poolside, coding, ~161 tok/s]). The free tier is text-only — image turns route to a paid vision model, because the two free models the catalogs advertise as vision-capable fail a solid-colour probe on both chains and do so with an HTTP 200.
 
 ## Built-in Agent Tools