@blockrun/clawrouter 0.12.257 → 0.12.258

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (17) hide show
  1. package/README.md +28 -26
  2. package/dist/cli.js +378 -132
  3. package/dist/index.js +378 -132
  4. package/dist/router/index.js +43 -30
  5. package/docs/9-free-ai-models-zero-cost-blockrun.md +73 -86
  6. package/docs/anthropic-cost-savings.md +4 -4
  7. package/docs/anthropic-third-party-harness-changes.md +3 -3
  8. package/docs/clawrouter-cuts-llm-api-costs-500x.md +1 -1
  9. package/docs/clawrouter-vs-openrouter-llm-routing-comparison.md +3 -3
  10. package/docs/features.md +9 -8
  11. package/docs/routing-profiles.md +24 -22
  12. package/docs/subscription-failover.md +1 -1
  13. package/package.json +3 -3
  14. package/scripts/benchmark.py +2 -2
  15. package/scripts/reinstall.sh +7 -5
  16. package/skills/clawrouter/SKILL.md +4 -4
  17. package/src/top-models.json +8 -4
package/README.md CHANGED
@@ -7,11 +7,11 @@
7
7
  <p>Agents can't sign up for accounts. Agents can't enter credit cards.<br>
8
8
  Agents can only sign transactions.<br><br>
9
9
  <strong>ClawRouter is the only LLM router that lets agents operate independently.</strong><br><br>
10
- <em><!-- br:models.free -->5<!-- /br:models.free --> models free, no crypto required. No signup. No API key. No credit card.</em></p>
10
+ <em><!-- br:models.free -->7<!-- /br:models.free --> models free, no crypto required. No signup. No API key. No credit card.</em></p>
11
11
 
12
12
  <br>
13
13
 
14
- <img src="https://img.shields.io/badge/🆓_5_Free_Models-success?style=for-the-badge" alt="5 free models">&nbsp;
14
+ <img src="https://img.shields.io/badge/🆓_7_Free_Models-success?style=for-the-badge" alt="7 free models">&nbsp;
15
15
  <img src="https://img.shields.io/badge/🤖_Agent--Native-black?style=for-the-badge" alt="Agent native">&nbsp;
16
16
  <img src="https://img.shields.io/badge/🔑_Zero_API_Keys-blue?style=for-the-badge" alt="No API keys">&nbsp;
17
17
  <img src="https://img.shields.io/badge/⚡_Local_Routing-yellow?style=for-the-badge" alt="Local routing">&nbsp;
@@ -34,7 +34,7 @@ Agents can only sign transactions.<br><br>
34
34
 
35
35
  </div>
36
36
 
37
- > **ClawRouter** is an open-source smart LLM router that reduces AI API costs by up to <!-- br:savings.autoVsBaselinePct -->88<!-- /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. ClawRouter is the only LLM router built for autonomous AI agents — it uses wallet signatures for authentication (no API keys) and USDC micropayments via the x402 protocol (no credit cards). <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> models from OpenAI, Anthropic, Google, xAI, DeepSeek, and more. MIT licensed.
37
+ > **ClawRouter** is an open-source smart LLM router that reduces AI API costs by up to <!-- br:savings.autoVsBaselinePct -->88<!-- /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. ClawRouter is the only LLM router built for autonomous AI agents — it uses wallet signatures for authentication (no API keys) and USDC micropayments via the x402 protocol (no credit cards). <!-- br:models.chatVisible -->73<!-- /br:models.chatVisible --> models from OpenAI, Anthropic, Google, xAI, DeepSeek, and more. MIT licensed.
38
38
 
39
39
  ---
40
40
 
@@ -46,7 +46,7 @@ Every other LLM router was built for **human developers** — create an account,
46
46
 
47
47
  ClawRouter is built for the agent-first world:
48
48
 
49
- - **Starts at $0** — <!-- br:models.free -->5<!-- /br:models.free --> NVIDIA models are free forever (incl. reasoning-grade Step 3.7 Flash + a vision-capable Nemotron Omni)
49
+ - **Starts at $0** — <!-- br:models.free -->7<!-- /br:models.free --> open-weight models are free forever (incl. a 1M-context reasoner, the vision-capable Nemotron Omni, and two sub-second coders)
50
50
  - **No accounts** — a wallet is generated locally, no signup
51
51
  - **No API keys** — your wallet signature IS authentication
52
52
  - **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
@@ -61,8 +61,8 @@ This is the stack that lets agents operate autonomously: **x402 + USDC + local r
61
61
 
62
62
  | | OpenRouter | LiteLLM | Martian | Portkey | **ClawRouter** |
63
63
  | ---------------- | ----------------- | ---------------- | ----------------- | ----------------- | ---------------------------------------------------------------------- |
64
- | **Models** | 200+ | 100+ | Smart routing | Gateway | **<!-- br:models.chatVisible -->71<!-- /br:models.chatVisible -->** |
65
- | **Free tier** | Rate-limited | BYO keys | No | No | **<!-- br:models.free -->5<!-- /br:models.free --> models, no signup** |
64
+ | **Models** | 200+ | 100+ | Smart routing | Gateway | **<!-- br:models.chatVisible -->73<!-- /br:models.chatVisible -->** |
65
+ | **Free tier** | Rate-limited | BYO keys | No | No | **<!-- br:models.free -->7<!-- /br:models.free --> models, no signup** |
66
66
  | **Routing** | Manual selection | Manual selection | Smart (closed) | Observability | **Smart (open source)** |
67
67
  | **Auth** | Account + API key | Your API keys | Account + API key | Account + API key | **Wallet signature** |
68
68
  | **Payment** | Credit card | BYO keys | Credit card | $49-499/mo | **USDC per-request** |
@@ -78,7 +78,7 @@ This is the stack that lets agents operate autonomously: **x402 + USDC + local r
78
78
 
79
79
  ## Quick Start
80
80
 
81
- > **No wallet? <!-- br:models.free -->5<!-- /br:models.free --> models work free out of the box.** Install, run, and pin `free/mistral-nemotron` (or any of the <!-- br:models.free -->5<!-- /br:models.free -->) — no crypto, no signup, no balance required. Add USDC later when you want paid models.
81
+ > **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 USDC later when you want paid models.
82
82
 
83
83
  ### Option A — OpenClaw Agent
84
84
 
@@ -107,7 +107,7 @@ openclaw gateway restart
107
107
 
108
108
  > **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.
109
109
  >
110
- > **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 -->71<!-- /br:models.chatVisible --> models, same x402 USDC settlement on Base & Solana.
110
+ > **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 -->73<!-- /br:models.chatVisible --> models, same x402 USDC settlement on Base & Solana.
111
111
 
112
112
  No OpenClaw required. ClawRouter runs as a local proxy on port 8402.
113
113
 
@@ -118,7 +118,7 @@ npx @blockrun/clawrouter
118
118
  ```
119
119
 
120
120
  **2. Fund your wallet** — optional, skip for free tier
121
- Your wallet address is printed on first run. For paid models, send a few USDC on Base or Solana — $5 covers thousands of requests. To stay at $0, pin any of the <!-- br:models.free -->5<!-- /br:models.free --> free models (e.g. `free/mistral-nemotron`) or use `/model free` inside OpenClaw.
121
+ Your wallet address is printed on first run. For paid models, send a few USDC on Base or Solana — $5 covers thousands of requests. 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.
122
122
 
123
123
  **3. Point your client at `http://localhost:8402`**
124
124
 
@@ -217,12 +217,12 @@ Request → 15-dimension scorer → tier + task shape
217
217
  3. **Rank** — survivors are scored on task quality, capability, estimated cost, speed and reliability, with per-profile weights (`eco` leans on cost, `premium` on quality and reliability).
218
218
  4. **Recover** — the whole ranked list rides along as the fallback chain, so a provider timeout or 5xx costs a retry, not the task.
219
219
 
220
- | Tier | ECO Model | AUTO Model | PREMIUM Model | AGENTIC Model ‡ |
221
- | --------- | ------------------------------- | ------------------------------- | ---------------------------- | ------------------------- |
222
- | SIMPLE | step-3.7-flash (**FREE**) | gemini-2.5-flash ($0.30/$2.50) | gemini-3.5-flash ($1.50/$9) | gpt-4o-mini ($0.15/$0.60) |
223
- | MEDIUM | glm-5.3-flash ($0.15/$0.50) | gemini-3.5-flash ($1.50/$9) | gpt-5.3-codex ($1.75/$14.00) | gpt-5-mini ($0.25/$2) |
224
- | COMPLEX | glm-5.3-flash ($0.15/$0.50) | gemini-3.1-pro ($2/$12) | claude-fable-5 ($10/$50) | claude-sonnet-5 ($3/$15) |
225
- | REASONING | deepseek-reasoner ($0.14/$0.28) | deepseek-reasoner ($0.14/$0.28) | claude-sonnet-5 ($3/$15) | claude-sonnet-5 ($3/$15) |
220
+ | Tier | ECO Model | AUTO Model | PREMIUM Model | AGENTIC Model ‡ |
221
+ | --------- | --------------------------------- | ------------------------------- | ---------------------------- | ------------------------- |
222
+ | SIMPLE | nemotron-3.5-lightning (**FREE**) | gemini-2.5-flash ($0.30/$2.50) | gemini-3.5-flash ($1.50/$9) | gpt-4o-mini ($0.15/$0.60) |
223
+ | MEDIUM | glm-5.3-flash ($0.15/$0.50) | gemini-3.5-flash ($1.50/$9) | gpt-5.3-codex ($1.75/$14.00) | gpt-5-mini ($0.25/$2) |
224
+ | COMPLEX | glm-5.3-flash ($0.15/$0.50) | gemini-3.1-pro ($2/$12) | claude-fable-5 ($10/$50) | claude-sonnet-5 ($3/$15) |
225
+ | REASONING | deepseek-reasoner ($0.14/$0.28) | deepseek-reasoner ($0.14/$0.28) | claude-sonnet-5 ($3/$15) | claude-sonnet-5 ($3/$15) |
226
226
 
227
227
  † Withheld from `/v1/models` — since Router Core V3.5 no chain names such a model: every primary and every fallback rung above is a model you can find on the public pricing page. [savings-mix.json](https://github.com/BlockRunAI/blockrun/blob/main/src/brand/savings-mix.json) prices the published savings claim on the same visible models.
228
228
  ‡ Auto-selected in any profile when the turn actually needs its attached tools; prefers models that keep going instead of stopping to ask.
@@ -407,7 +407,7 @@ No Surf account, no API key — settles directly to Surf's Base treasury in USDC
407
407
 
408
408
  ## Models & Pricing
409
409
 
410
- <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> models across 9 providers, one wallet. **<!-- br:models.free -->5<!-- /br:models.free --> models are $0 — paid models start at fractions of a cent.**
410
+ <!-- br:models.chatVisible -->73<!-- /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.**
411
411
 
412
412
  > **💡 "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.
413
413
 
@@ -415,11 +415,13 @@ No Surf account, no API key — settles directly to Surf's Base treasury in USDC
415
415
 
416
416
  | Model | Input $/M | Output $/M | ~$/request | Context | Features |
417
417
  | ------------------------------------------- | --------: | ---------: | ---------: | ------- | -------------------------------------------- |
418
+ | free/nemotron-3.5-lightning | **FREE** | **FREE** | **$0** | 1M | reasoning (thinking mode) — the free default |
419
+ | free/nemotron-3-nano-30b | **FREE** | **FREE** | **$0** | 131K | fastest free model (~121 tok/s) |
420
+ | free/laguna-xs-2.1 | **FREE** | **FREE** | **$0** | 131K | coding (Poolside, ~161 tok/s) |
421
+ | free/north-mini-code | **FREE** | **FREE** | **$0** | 256K | coding (Cohere, sub-second) |
418
422
  | free/nemotron-3-nano-omni-30b-a3b-reasoning | **FREE** | **FREE** | **$0** | 256K | reasoning, **vision** (text+img+video+audio) |
419
- | free/mistral-nemotron | **FREE** | **FREE** | **$0** | 131K | instruction following |
420
- | free/step-3.7-flash | **FREE** | **FREE** | **$0** | 131K | reasoning |
421
- | free/nemotron-nano-9b-v2 | **FREE** | **FREE** | **$0** | 131K | fast lightweight generalist |
422
- | free/nemotron-nano-12b-v2-vl | **FREE** | **FREE** | **$0** | 131K | vision (text + image) |
423
+ | free/nemotron-3-ultra-550b | **FREE** | **FREE** | **$0** | 1M | largest free model (550B/55B MoE) |
424
+ | free/llama-3.2-11b-vision | **FREE** | **FREE** | **$0** | 128K | Meta Llama, image input |
423
425
  | qwen/qwen3.7-flash | $0.03 | $0.13 | $0.0001 | 1M | reasoning, tools (fastest Qwen tier) |
424
426
  | openai/gpt-5-nano | $0.05 | $0.40 | $0.0002 | 128K | tools |
425
427
  | openai/gpt-5.6-luna-pro | $0.10 | $0.60 | $0.0004 | 1M | reasoning, vision, agentic, tools |
@@ -497,7 +499,7 @@ No Surf account, no API key — settles directly to Surf's Base treasury in USDC
497
499
  | openai/gpt-5.4-pro | $30.00 | $180.00 | $0.1050 | 400K | reasoning, tools |
498
500
  | openai/gpt-5.5-pro | $30.00 | $180.00 | $0.1050 | 1M | reasoning, vision, tools |
499
501
 
500
- > **Free tier:** <!-- br:models.free -->5<!-- /br:models.free --> NVIDIA-hosted models cost nothing — `/model free` pins the free default (`step-3.7-flash`, with the other four as fallbacks), `/model eco` opens on it, or pick one directly (e.g., `/model nemotron-omni` for vision, `/model step-flash` for reasoning, `/model mistral-nemotron` for instruction following).
502
+ > **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 six as fallbacks), `/model eco` opens on it, or pick one directly (e.g., `/model nemotron-omni` for vision, `/model lightning` for 1M-context reasoning, `/model north-mini` or `/model laguna` for fast coding, `/model llama-vision` for Meta Llama).
501
503
  > **Best value:** `gpt-5-nano` and `gemini-2.5-flash-lite` deliver strong results at ~$0.0003/request.
502
504
 
503
505
  ---
@@ -573,7 +575,7 @@ For basic usage, no configuration needed. For advanced options:
573
575
  Block specific models from being routed to. Useful if a model doesn't follow your agent instructions or you want to control costs.
574
576
 
575
577
  ```bash
576
- /exclude add free/step-3.7-flash # Block a free model (e.g. not for your workload)
578
+ /exclude add free/nemotron-3.5-lightning # Block a free model (e.g. not for your workload)
577
579
  /exclude add grok-4 # Aliases work — blocks all grok-4 variants
578
580
  /exclude add gpt-5.4 # Skip expensive models
579
581
  /exclude # Show current exclusions
@@ -667,7 +669,7 @@ npm test
667
669
 
668
670
  **The LLM router built for autonomous agents**
669
671
 
670
- You're here. <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> models, local smart routing, x402 USDC payments — the only stack that lets agents operate independently.
672
+ You're here. <!-- br:models.chatVisible -->73<!-- /br:models.chatVisible --> models, local smart routing, x402 USDC payments — the only stack that lets agents operate independently.
671
673
 
672
674
  `curl -fsSL https://blockrun.ai/ClawRouter-update | bash`
673
675
 
@@ -678,7 +680,7 @@ You're here. <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> mod
678
680
 
679
681
  **BlockRun for Claude Code**
680
682
 
681
- Run Claude Code with <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> models, no rate limits, no Anthropic account, no phone verification. Pay per request with USDC — your wallet is your identity.
683
+ Run Claude Code with <!-- br:models.chatVisible -->73<!-- /br:models.chatVisible --> models, no rate limits, no Anthropic account, no phone verification. Pay per request with USDC — your wallet is your identity.
682
684
 
683
685
  `curl -fsSL https://blockrun.ai/brcc-install | bash`
684
686
 
@@ -691,7 +693,7 @@ Run Claude Code with <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible
691
693
 
692
694
  **ClawRouter for NousResearch Hermes**
693
695
 
694
- Python plugin that wraps the ClawRouter proxy for `hermes-agent`. Same <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> models, same x402 USDC payments on Base & Solana, native Hermes ergonomics.
696
+ Python plugin that wraps the ClawRouter proxy for `hermes-agent`. Same <!-- br:models.chatVisible -->73<!-- /br:models.chatVisible --> models, same x402 USDC payments on Base & Solana, native Hermes ergonomics.
695
697
 
696
698
  `pip install hermes-plugin-clawrouter`
697
699
 
@@ -755,7 +757,7 @@ ClawRouter works with any tool that makes OpenAI-compatible API calls — point
755
757
 
756
758
  ### Is ClawRouter free?
757
759
 
758
- ClawRouter itself is free and MIT licensed. You pay only for the LLM API calls routed through it — and several NVIDIA-hosted models (`nemotron-3-nano-omni-30b-a3b-reasoning`, `mistral-nemotron`, `step-3.7-flash`, `nemotron-nano-9b-v2`, `nemotron-nano-12b-v2-vl`) are completely free. Use `/model free` to smart-route across them, or pick any by name.
760
+ ClawRouter itself is free and MIT licensed. You pay only for the LLM API calls routed through it — and several open-weight models (`nemotron-3.5-lightning`, `nemotron-3-nano-30b`, `laguna-xs-2.1`, `north-mini-code`, `nemotron-3-nano-omni-30b-a3b-reasoning`, `nemotron-3-ultra-550b`, `llama-3.2-11b-vision`) are completely free. Use `/model free` to smart-route across them, or pick any by name.
759
761
 
760
762
  ---
761
763