@blockrun/clawrouter 0.12.282 → 0.12.284
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.
- package/README.md +23 -22
- package/dist/cli.js +281 -35
- package/dist/index.d.ts +14 -0
- package/dist/index.js +239 -28
- package/docs/9-free-ai-models-zero-cost-blockrun.md +5 -5
- package/docs/anthropic-cost-savings.md +1 -1
- package/docs/anthropic-third-party-harness-changes.md +3 -3
- package/docs/clawrouter-vs-openrouter-llm-routing-comparison.md +3 -3
- package/docs/configuration.md +6 -0
- package/package.json +2 -2
- package/skills/clawrouter/SKILL.md +3 -3
package/README.md
CHANGED
|
@@ -9,11 +9,11 @@ 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
10
|
<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>
|
|
11
11
|
or <strong>USDC</strong> on Solana or Base (x402 wallet, no account at all).<br>
|
|
12
|
-
Or neither — <!-- br:models.free -->
|
|
12
|
+
Or neither — <!-- br:models.free -->7<!-- /br:models.free --> models are free, with no signup, no key and no wallet.</em></p>
|
|
13
13
|
|
|
14
14
|
<br>
|
|
15
15
|
|
|
16
|
-
<img src="https://img.shields.io/badge/🆓
|
|
16
|
+
<img src="https://img.shields.io/badge/🆓_7_Free_Models-success?style=for-the-badge" alt="7 free models">
|
|
17
17
|
<img src="https://img.shields.io/badge/🤖_Agent--Native-black?style=for-the-badge" alt="Agent native">
|
|
18
18
|
<img src="https://img.shields.io/badge/💳_Card_or_USDC-blue?style=for-the-badge" alt="Card or USDC">
|
|
19
19
|
<img src="https://img.shields.io/badge/⚡_Local_Routing-yellow?style=for-the-badge" alt="Local routing">
|
|
@@ -36,7 +36,7 @@ Or neither — <!-- br:models.free -->6<!-- /br:models.free --> models are free,
|
|
|
36
36
|
|
|
37
37
|
</div>
|
|
38
38
|
|
|
39
|
-
> **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 -->
|
|
39
|
+
> **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.
|
|
40
40
|
|
|
41
41
|
---
|
|
42
42
|
|
|
@@ -48,7 +48,7 @@ Not a seat, not a subscription, not a monthly minimum you keep paying while the
|
|
|
48
48
|
|
|
49
49
|
| | |
|
|
50
50
|
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
51
|
-
| **Every LLM** | <!-- br:models.chatVisible -->
|
|
51
|
+
| **Every LLM** | <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> chat models across 9 providers, behind one endpoint and one balance |
|
|
52
52
|
| **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 |
|
|
53
53
|
| **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 |
|
|
54
54
|
| **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,
|
|
|
65
65
|
|
|
66
66
|
ClawRouter is built for the agent-first world:
|
|
67
67
|
|
|
68
|
-
- **Starts at $0** — <!-- br:models.free -->
|
|
68
|
+
- **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.
|
|
69
69
|
- **No accounts needed** — a wallet is generated locally, no signup
|
|
70
70
|
- **No API keys needed** — your wallet signature IS authentication
|
|
71
71
|
- **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
|
|
|
76
76
|
|
|
77
77
|
### …and if you are a human, not an agent
|
|
78
78
|
|
|
79
|
-
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 -->
|
|
79
|
+
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.
|
|
80
80
|
|
|
81
81
|
| You are | Pay with | Setup |
|
|
82
82
|
| ------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------- |
|
|
@@ -92,8 +92,8 @@ Full walkthrough: [Paying with a credit card](#paying-with-a-credit-card-api-key
|
|
|
92
92
|
|
|
93
93
|
| | OpenRouter | LiteLLM | Martian | Portkey | **ClawRouter** |
|
|
94
94
|
| ---------------- | ----------------- | ---------------- | ----------------- | ----------------- | ---------------------------------------------------------------------- |
|
|
95
|
-
| **Models** | 200+ | 100+ | Smart routing | Gateway | **<!-- br:models.chatVisible -->
|
|
96
|
-
| **Free tier** | Rate-limited | BYO keys | No | No | **<!-- br:models.free -->
|
|
95
|
+
| **Models** | 200+ | 100+ | Smart routing | Gateway | **<!-- br:models.chatVisible -->88<!-- /br:models.chatVisible -->** |
|
|
96
|
+
| **Free tier** | Rate-limited | BYO keys | No | No | **<!-- br:models.free -->7<!-- /br:models.free --> models, no signup** |
|
|
97
97
|
| **Routing** | Manual selection | Manual selection | Smart (closed) | Observability | **Smart (open source)** |
|
|
98
98
|
| **Auth** | Account + API key | Your API keys | Account + API key | Account + API key | **Wallet signature _or_ API key** |
|
|
99
99
|
| **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
|
|
|
109
109
|
|
|
110
110
|
## Quick Start
|
|
111
111
|
|
|
112
|
-
> **No wallet? <!-- br:models.free -->
|
|
112
|
+
> **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.
|
|
113
113
|
|
|
114
114
|
**Two ways to pay for the paid ones — pick one, the rest of ClawRouter is identical:**
|
|
115
115
|
|
|
@@ -127,7 +127,7 @@ is all it takes to switch and `clawrouter logout` is all it takes to switch back
|
|
|
127
127
|
|
|
128
128
|
> **Where do I sign up?** [**user.blockrun.ai**](https://user.blockrun.ai) — sign in with
|
|
129
129
|
> Google, add credit with a card under **Credits**, mint a key under **API Keys**. That
|
|
130
|
-
> one key covers all <!-- br:models.chatVisible -->
|
|
130
|
+
> one key covers all <!-- br:models.chatVisible -->88<!-- /br:models.chatVisible --> chat models
|
|
131
131
|
> plus images, video, speech and the live-data APIs. No wallet, no crypto, no seed phrase.
|
|
132
132
|
|
|
133
133
|
### Desktop control plane (macOS)
|
|
@@ -171,7 +171,7 @@ openclaw gateway restart
|
|
|
171
171
|
|
|
172
172
|
> **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.
|
|
173
173
|
>
|
|
174
|
-
> **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 -->
|
|
174
|
+
> **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.
|
|
175
175
|
|
|
176
176
|
No OpenClaw required. ClawRouter runs as a local proxy on port 8402.
|
|
177
177
|
|
|
@@ -182,7 +182,7 @@ npx @blockrun/clawrouter
|
|
|
182
182
|
```
|
|
183
183
|
|
|
184
184
|
**2. Fund your wallet** — optional, skip for free tier
|
|
185
|
-
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 -->
|
|
185
|
+
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.
|
|
186
186
|
|
|
187
187
|
**3. Point your client at `http://localhost:8402`**
|
|
188
188
|
|
|
@@ -485,7 +485,7 @@ No Surf account, no API key — settles directly to Surf's Base treasury in USDC
|
|
|
485
485
|
|
|
486
486
|
## Models & Pricing
|
|
487
487
|
|
|
488
|
-
<!-- br:models.chatVisible -->
|
|
488
|
+
<!-- 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.**
|
|
489
489
|
|
|
490
490
|
> **💡 "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.
|
|
491
491
|
|
|
@@ -585,7 +585,7 @@ No Surf account, no API key — settles directly to Surf's Base treasury in USDC
|
|
|
585
585
|
| openai/gpt-5.4-pro | $30.00 | $180.00 | $0.1050 | 1M | reasoning, tools |
|
|
586
586
|
| openai/gpt-5.5-pro | $30.00 | $180.00 | $0.1050 | 1M | reasoning, vision, tools |
|
|
587
587
|
|
|
588
|
-
> **Free tier:** <!-- br:models.free -->
|
|
588
|
+
> **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).
|
|
589
589
|
>
|
|
590
590
|
> **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.
|
|
591
591
|
> **Best value:** `gpt-5-nano` and `gemini-2.5-flash-lite` deliver strong results at ~$0.0003/request.
|
|
@@ -697,8 +697,9 @@ table has drifted from the gateway's. **Charged but not in this machine's
|
|
|
697
697
|
journal** is the one to look at hardest: money left the account for a call this
|
|
698
698
|
machine did not make — expected if the same key is used on another machine or by
|
|
699
699
|
another BlockRun product, and worth investigating if not. Exit code `2` in that
|
|
700
|
-
case, so a scheduled check can alert on it
|
|
701
|
-
|
|
700
|
+
case, so a scheduled check can alert on it, and `1` when the ledger could not be
|
|
701
|
+
read in full, since the unread pages could hold exactly those charges. Rows still
|
|
702
|
+
**pending pricing** are excluded from the totals rather than counted as $0.
|
|
702
703
|
|
|
703
704
|
Your per-call sum will always be less than your card statement by exactly the
|
|
704
705
|
top-up fees, which are charged at purchase and never appear as ledger rows. That
|
|
@@ -728,7 +729,7 @@ chains, the response cache and the local spend controls.
|
|
|
728
729
|
- **Balance lives server-side.** There is no local balance to check: a call that
|
|
729
730
|
outruns your credit comes back as HTTP `402 insufficient_quota`, naming the
|
|
730
731
|
top-up page. Free models stay free and need no credit at all — all
|
|
731
|
-
<!-- br:models.free -->
|
|
732
|
+
<!-- br:models.free -->7<!-- /br:models.free --> are served on the API-key gateway too.
|
|
732
733
|
- **One key covers nearly everything.** Verified live against `api.blockrun.ai`
|
|
733
734
|
on 2026-09-05: chat completions (`/v1/chat/completions`), the Anthropic-shaped
|
|
734
735
|
`/v1/messages`, `/v1/models`, image generation, speech, video, and the partner
|
|
@@ -881,7 +882,7 @@ npm test
|
|
|
881
882
|
|
|
882
883
|
**The LLM router built for autonomous agents**
|
|
883
884
|
|
|
884
|
-
You're here. <!-- br:models.chatVisible -->
|
|
885
|
+
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.
|
|
885
886
|
|
|
886
887
|
`curl -fsSL https://blockrun.ai/ClawRouter-update | bash`
|
|
887
888
|
|
|
@@ -892,7 +893,7 @@ You're here. <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible --> mod
|
|
|
892
893
|
|
|
893
894
|
**BlockRun for Claude Code**
|
|
894
895
|
|
|
895
|
-
Run Claude Code with <!-- br:models.chatVisible -->
|
|
896
|
+
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.
|
|
896
897
|
|
|
897
898
|
`curl -fsSL https://blockrun.ai/brcc-install | bash`
|
|
898
899
|
|
|
@@ -905,7 +906,7 @@ Run Claude Code with <!-- br:models.chatVisible -->82<!-- /br:models.chatVisible
|
|
|
905
906
|
|
|
906
907
|
**ClawRouter for NousResearch Hermes**
|
|
907
908
|
|
|
908
|
-
Python plugin that wraps the ClawRouter proxy for `hermes-agent`. Same <!-- br:models.chatVisible -->
|
|
909
|
+
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.
|
|
909
910
|
|
|
910
911
|
`pip install hermes-plugin-clawrouter`
|
|
911
912
|
|
|
@@ -949,7 +950,7 @@ Python plugin that wraps the ClawRouter proxy for `hermes-agent`. Same <!-- br:m
|
|
|
949
950
|
|
|
950
951
|
### What is BlockRun?
|
|
951
952
|
|
|
952
|
-
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 -->
|
|
953
|
+
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.
|
|
953
954
|
|
|
954
955
|
### What is ClawRouter?
|
|
955
956
|
|
|
@@ -977,7 +978,7 @@ No. A wallet is the default because it is what lets an _agent_ pay for itself,
|
|
|
977
978
|
but you can sign up at **[user.blockrun.ai](https://user.blockrun.ai)**, top up
|
|
978
979
|
with a credit card, mint an API key and run `clawrouter login brk_live_…`. Calls
|
|
979
980
|
then go to `api.blockrun.ai` on a bearer token and bill your account credit — no
|
|
980
|
-
crypto, no gas, no seed phrase. And the <!-- br:models.free -->
|
|
981
|
+
crypto, no gas, no seed phrase. And the <!-- br:models.free -->7<!-- /br:models.free --> free models need neither: no
|
|
981
982
|
wallet, no key, no signup. See [Paying with a credit card](#paying-with-a-credit-card-api-key).
|
|
982
983
|
|
|
983
984
|
### Is ClawRouter free?
|