@blockrun/clawrouter 0.12.268 → 0.12.270
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 +81 -45
- package/dist/cli.js +191 -71
- package/dist/index.d.ts +48 -5
- package/dist/index.js +190 -70
- package/package.json +1 -1
- package/skills/clawrouter/SKILL.md +8 -8
- package/skills/imagegen/SKILL.md +2 -2
- package/skills/phone/SKILL.md +3 -2
- package/skills/predexon/SKILL.md +1 -1
- package/skills/surf/SKILL.md +4 -4
package/README.md
CHANGED
|
@@ -7,8 +7,8 @@
|
|
|
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>Pay however you like: <strong>credit card</strong>
|
|
11
|
-
or <strong>USDC</strong> on
|
|
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
|
+
or <strong>USDC</strong> on Solana or Base (x402 wallet, no account at all).<br>
|
|
12
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>
|
|
@@ -40,6 +40,23 @@ Or neither — <!-- br:models.free -->7<!-- /br:models.free --> models are free,
|
|
|
40
40
|
|
|
41
41
|
---
|
|
42
42
|
|
|
43
|
+
## What BlockRun is
|
|
44
|
+
|
|
45
|
+
> **BlockRun lets agents pay for the outcome — every LLM, tool and data source, best value per dollar.**
|
|
46
|
+
|
|
47
|
+
Not a seat, not a subscription, not a monthly minimum you keep paying while the agent idles. An agent asks for one thing — an answer, an image, a transcript, a price, a call placed — and pays for that one thing at the moment it happens. Nothing to sign up for, nothing to cancel.
|
|
48
|
+
|
|
49
|
+
| | |
|
|
50
|
+
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
51
|
+
| **Every LLM** | <!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> chat models across 9 providers, behind one endpoint and one balance |
|
|
52
|
+
| **Every tool** | <!-- br:models.image -->9<!-- /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
|
+
| **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
|
+
| **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 |
|
|
55
|
+
|
|
56
|
+
**ClawRouter is how an agent reaches it.** BlockRun is the gateway and the billing; ClawRouter is the MIT-licensed router that runs on your machine, decides which model each request deserves, and settles the bill — a wallet signature in USDC, or a credit-card-funded API key. The rest of this README is about ClawRouter.
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
43
60
|
## Why ClawRouter exists
|
|
44
61
|
|
|
45
62
|
Every other LLM router was built for **human developers** — create an account, get an API key, pick a model from a dashboard, pay with a credit card.
|
|
@@ -61,11 +78,11 @@ This is the stack that lets agents operate autonomously: **x402 + USDC + local r
|
|
|
61
78
|
|
|
62
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 -->76<!-- /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.
|
|
63
80
|
|
|
64
|
-
| You are | Pay with | Setup
|
|
65
|
-
| ------------------- | --------------------------------------- |
|
|
66
|
-
| Just trying it | Nothing | Install and pin a free model
|
|
67
|
-
| A person | **Credit card** → account credit | [user.blockrun.ai](https://user.blockrun.ai) → `clawrouter login brk_live_…` |
|
|
68
|
-
| An autonomous agent | **USDC** on
|
|
81
|
+
| You are | Pay with | Setup |
|
|
82
|
+
| ------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------- |
|
|
83
|
+
| Just trying it | Nothing | Install and pin a free model |
|
|
84
|
+
| A person | **Credit card** → account credit | **Sign up at [user.blockrun.ai](https://user.blockrun.ai)** → `clawrouter login brk_live_…` |
|
|
85
|
+
| An autonomous agent | **USDC** on Solana or Base, per request | Nothing — a wallet is generated on first run (Solana by default) |
|
|
69
86
|
|
|
70
87
|
Full walkthrough: [Paying with a credit card](#paying-with-a-credit-card-api-key).
|
|
71
88
|
|
|
@@ -96,22 +113,28 @@ Full walkthrough: [Paying with a credit card](#paying-with-a-credit-card-api-key
|
|
|
96
113
|
|
|
97
114
|
**Two ways to pay for the paid ones — pick one, the rest of ClawRouter is identical:**
|
|
98
115
|
|
|
99
|
-
| | Wallet (default)
|
|
100
|
-
| ----------------- |
|
|
101
|
-
| **Who it is for** | Autonomous agents, and anyone happy holding USDC
|
|
102
|
-
| **Setup** | Nothing — a wallet is generated on first run
|
|
103
|
-
| **Auth** | An x402 signature per request
|
|
104
|
-
| **Gateway** | `blockrun.ai` (
|
|
105
|
-
| **Billing** | USDC leaves your wallet per call, non-custodial
|
|
116
|
+
| | Wallet (default) | API key |
|
|
117
|
+
| ----------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
|
118
|
+
| **Who it is for** | Autonomous agents, and anyone happy holding USDC | People who would rather pay with a card |
|
|
119
|
+
| **Setup** | Nothing — a wallet is generated on first run | Sign up at [user.blockrun.ai](https://user.blockrun.ai), top up, mint a key, `clawrouter login brk_live_…` |
|
|
120
|
+
| **Auth** | An x402 signature per request | `Authorization: Bearer brk_live_…` |
|
|
121
|
+
| **Gateway** | `sol.blockrun.ai` (Solana, default) / `blockrun.ai` (Base) | `api.blockrun.ai` |
|
|
122
|
+
| **Billing** | USDC leaves your wallet per call, non-custodial | Card-funded account credit, drawn down at exact usage |
|
|
123
|
+
| **Fees** | $0.001/tx settlement fee (covers on-chain gas) | 5.5% + $0.30 on the top-up, then list price with **nothing per call** |
|
|
106
124
|
|
|
107
125
|
ClawRouter prefers the API key whenever one is configured, so `clawrouter login`
|
|
108
126
|
is all it takes to switch and `clawrouter logout` is all it takes to switch back.
|
|
109
127
|
|
|
128
|
+
> **Where do I sign up?** [**user.blockrun.ai**](https://user.blockrun.ai) — sign in with
|
|
129
|
+
> Google, add credit with a card under **Credits**, mint a key under **API Keys**. That
|
|
130
|
+
> one key covers all <!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> chat models
|
|
131
|
+
> plus images, video, speech and the live-data APIs. No wallet, no crypto, no seed phrase.
|
|
132
|
+
|
|
110
133
|
### Desktop control plane (macOS)
|
|
111
134
|
|
|
112
135
|
The Electron app in [`apps/desktop`](apps/desktop) provides one-click connections
|
|
113
136
|
for OpenClaw, Codex, Hermes, DeepSeek Harness, and Pi, plus model pricing/context,
|
|
114
|
-
wallet balances, Base
|
|
137
|
+
wallet balances, Solana/Base switching, and Coinbase Onramp. It snapshots each
|
|
115
138
|
agent's existing config before changing it and restores the original bytes when
|
|
116
139
|
you disconnect. Wallets are shared through `~/.blockrun`; older ClawRouter
|
|
117
140
|
wallets are copied there automatically without overwriting existing Core files.
|
|
@@ -148,7 +171,7 @@ openclaw gateway restart
|
|
|
148
171
|
|
|
149
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.
|
|
150
173
|
>
|
|
151
|
-
> **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 -->76<!-- /br:models.chatVisible --> models, same x402 USDC settlement on
|
|
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 -->76<!-- /br:models.chatVisible --> models, same x402 USDC settlement on Solana & Base.
|
|
152
175
|
|
|
153
176
|
No OpenClaw required. ClawRouter runs as a local proxy on port 8402.
|
|
154
177
|
|
|
@@ -159,7 +182,7 @@ npx @blockrun/clawrouter
|
|
|
159
182
|
```
|
|
160
183
|
|
|
161
184
|
**2. Fund your wallet** — optional, skip for free tier
|
|
162
|
-
Your wallet address is printed on first run. For paid models, send a few USDC on
|
|
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.
|
|
163
186
|
|
|
164
187
|
**3. Point your client at `http://localhost:8402`**
|
|
165
188
|
|
|
@@ -505,11 +528,11 @@ No Surf account, no API key — settles directly to Surf's Base treasury in USDC
|
|
|
505
528
|
| zai/glm-5.2 | $1.40 | $4.40 | $0.0029 | 1M | reasoning, coding, tools (flagship) |
|
|
506
529
|
| zai/glm-5.1 | $1.40 | $4.40 | $0.0029 | 200K | reasoning, tools (promo ended 2026-06-05) |
|
|
507
530
|
| qwen/qwen3.7-max | $1.475 | $4.425 | $0.0030 | 1M | reasoning, agentic, tools (Qwen flagship) |
|
|
508
|
-
| xai/grok-4.3 | $1.
|
|
509
|
-
| google/gemini-3.6-flash | $
|
|
531
|
+
| xai/grok-4.3 | $1.25 | $2.50 | $0.0019 | 1M | reasoning, vision, agentic, tools |
|
|
532
|
+
| google/gemini-3.6-flash | $0.75 | $3.75 | $0.0023 | 1M | reasoning, vision, tools (newest Flash) |
|
|
510
533
|
| google/gemini-3.5-flash | $1.50 | $9.00 | $0.0053 | 1M | reasoning, vision, tools (thinking) |
|
|
511
|
-
| xai/grok-4.5 | $2.
|
|
512
|
-
| xai/grok-build-0.1 | $1.
|
|
534
|
+
| xai/grok-4.5 | $2.00 | $6.00 | $0.0040 | 500K | reasoning, vision, agentic, tools |
|
|
535
|
+
| xai/grok-build-0.1 | $1.00 | $2.00 | $0.0015 | 256K | agentic coding, tools |
|
|
513
536
|
| openai/gpt-5.2 | $1.75 | $14.00 | $0.0079 | 400K | reasoning, vision, agentic, tools |
|
|
514
537
|
| openai/gpt-5.3 | $1.75 | $14.00 | $0.0079 | 128K | reasoning, vision, agentic, tools |
|
|
515
538
|
| openai/gpt-5.3-codex | $1.75 | $14.00 | $0.0079 | 400K | agentic, tools |
|
|
@@ -530,8 +553,8 @@ No Surf account, no API key — settles directly to Surf's Base treasury in USDC
|
|
|
530
553
|
| anthropic/claude-sonnet-4.6 | $3.00 | $15.00 | $0.0090 | 200K | reasoning, vision, agentic, tools |
|
|
531
554
|
| anthropic/claude-opus-5 | $5.00 | $25.00 | $0.0150 | 1M | reasoning, vision, agentic, tools |
|
|
532
555
|
| anthropic/claude-opus-4.8 | $5.00 | $25.00 | $0.0150 | 1M | reasoning, vision, agentic, tools |
|
|
533
|
-
| openai/gpt-5.6-sol | $
|
|
534
|
-
| openai/gpt-5.6-sol-pro | $
|
|
556
|
+
| openai/gpt-5.6-sol | $4.00 | $20.00 | $0.0120 | 1M | reasoning, vision, agentic, tools |
|
|
557
|
+
| openai/gpt-5.6-sol-pro | $4.00 | $20.00 | $0.0120 | 1M | reasoning, vision, agentic, tools |
|
|
535
558
|
| openai/gpt-5.5 | $5.00 | $30.00 | $0.0175 | 1M | reasoning, vision, agentic, tools |
|
|
536
559
|
| moonshot/kimi-k3 | $3.00 | $15.00 | $0.0110 | 1M | reasoning, vision, agentic, tools |
|
|
537
560
|
| openai/chat-latest | $5.00 | $30.00 | $0.0175 | 128K | vision, tools |
|
|
@@ -560,7 +583,7 @@ Request → 402 (price: $0.003) → wallet signs USDC → retry → response
|
|
|
560
583
|
|
|
561
584
|
USDC stays in your wallet until spent — non-custodial. Price is visible in the 402 header before signing.
|
|
562
585
|
|
|
563
|
-
**Dual-chain support:** Pay with **USDC
|
|
586
|
+
**Dual-chain support:** Pay with **USDC on Solana** (the default) or **USDC on Base (EVM)**. Both wallets are derived from a single BIP-39 mnemonic on first run. New installs get **Solana**; an install that predates the Solana default keeps its **Base** wallet — its USDC is there — until you switch with `/wallet solana`.
|
|
564
587
|
|
|
565
588
|
```bash
|
|
566
589
|
/wallet # Check balance and address (both chains)
|
|
@@ -578,10 +601,10 @@ USDC stays in your wallet until spent — non-custodial. Price is visible in the
|
|
|
578
601
|
|
|
579
602
|
**Fund your wallet:**
|
|
580
603
|
|
|
604
|
+
- **Solana (default):** Send USDC on Solana to your Solana address
|
|
581
605
|
- **Base (EVM):** Send USDC on Base to your EVM address
|
|
582
|
-
- **Solana:** Send USDC on Solana to your Solana address
|
|
583
606
|
- **Coinbase/CEX:** Withdraw USDC to either network
|
|
584
|
-
- **Credit card:** don't fund a wallet at all — use an API key instead (below)
|
|
607
|
+
- **Credit card:** don't fund a wallet at all — [sign up at user.blockrun.ai](https://user.blockrun.ai) and use an API key instead (below)
|
|
585
608
|
|
|
586
609
|
---
|
|
587
610
|
|
|
@@ -595,11 +618,11 @@ by card-funded credit — and ClawRouter speaks that too.
|
|
|
595
618
|
|
|
596
619
|
Go to **[user.blockrun.ai](https://user.blockrun.ai)**:
|
|
597
620
|
|
|
598
|
-
1. Sign in.
|
|
599
|
-
2. **Credits** → top up with a credit card. The processing fee is
|
|
600
|
-
purchase, not on inference: you pay it once on the top-up and every
|
|
601
|
-
then bills at
|
|
602
|
-
per-call fee**.
|
|
621
|
+
1. **Sign in with Google.** That is the whole signup — no invite, no sales call.
|
|
622
|
+
2. **Credits** → top up with a credit card. The processing fee is **5.5% + $0.30**,
|
|
623
|
+
charged at purchase, not on inference: you pay it once on the top-up and every
|
|
624
|
+
model then bills at **provider list price with no markup**, with **no per-call
|
|
625
|
+
minimum and no per-call fee**.
|
|
603
626
|
3. **API Keys** → create a key. It is shown once and looks like
|
|
604
627
|
`brk_live_…` — copy it before you leave the page.
|
|
605
628
|
|
|
@@ -657,12 +680,19 @@ chains, the response cache and the local spend controls.
|
|
|
657
680
|
signs with a private key — `clawrouter doctor` will not mint one either.
|
|
658
681
|
- **Balance lives server-side.** There is no local balance to check: a call that
|
|
659
682
|
outruns your credit comes back as HTTP `402 insufficient_quota`, naming the
|
|
660
|
-
top-up page. Free models stay free and need no credit at all
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
683
|
+
top-up page. Free models stay free and need no credit at all — all
|
|
684
|
+
<!-- br:models.free -->7<!-- /br:models.free --> are served on the API-key gateway too.
|
|
685
|
+
- **One key covers nearly everything.** Verified live against `api.blockrun.ai`
|
|
686
|
+
on 2026-09-05: chat completions (`/v1/chat/completions`), the Anthropic-shaped
|
|
687
|
+
`/v1/messages`, `/v1/models`, image generation, speech, video, and the partner
|
|
688
|
+
APIs — Surf crypto data, Exa search, prediction markets, and phone lookup and
|
|
689
|
+
fraud checks.
|
|
690
|
+
- **The wallet-only exceptions** are the routes that bind a lease or a position
|
|
691
|
+
to a payer address, because there is no address to bind to without a wallet:
|
|
692
|
+
buying, renewing, listing and releasing **phone numbers** (the gateway answers
|
|
693
|
+
those with a raw `402` on a key), and **Polymarket trading**, which ClawRouter
|
|
694
|
+
signs locally with the wallet key. Phone lookups, fraud checks and outbound
|
|
695
|
+
voice calls are fine on a key; only owning a number is not.
|
|
666
696
|
- **`maxCostPerRun` and `/exclude` still apply**, along with the router's own
|
|
667
697
|
budget filter — they live in the router, not the signer. **`clawrouter policy`
|
|
668
698
|
limits do not**: they are enforced in the x402 pre-sign hook, and nothing is
|
|
@@ -782,13 +812,15 @@ npm test
|
|
|
782
812
|
|
|
783
813
|
## Support
|
|
784
814
|
|
|
785
|
-
| Channel | Link
|
|
786
|
-
| --------------------- |
|
|
787
|
-
|
|
|
788
|
-
|
|
|
789
|
-
|
|
|
790
|
-
|
|
|
791
|
-
|
|
|
815
|
+
| Channel | Link |
|
|
816
|
+
| --------------------- | -------------------------------------------------------------------------------- |
|
|
817
|
+
| 🔑 Sign up / API keys | [user.blockrun.ai](https://user.blockrun.ai) |
|
|
818
|
+
| 💳 Add credit | [user.blockrun.ai/dashboard/credits](https://user.blockrun.ai/dashboard/credits) |
|
|
819
|
+
| 📅 Schedule Demo | [calendly.com/vickyfu9/30min](https://calendly.com/vickyfu9/30min) |
|
|
820
|
+
| 💬 Community Telegram | [t.me/blockrunAI](https://t.me/blockrunAI) |
|
|
821
|
+
| 🐦 X / Twitter | [x.com/blockrunai](https://x.com/blockrunai) |
|
|
822
|
+
| 📱 Founder Telegram | [@bc1max](https://t.me/bc1max) |
|
|
823
|
+
| ✉️ Email | vicky@blockrun.ai |
|
|
792
824
|
|
|
793
825
|
---
|
|
794
826
|
|
|
@@ -826,7 +858,7 @@ Run Claude Code with <!-- br:models.chatVisible -->76<!-- /br:models.chatVisible
|
|
|
826
858
|
|
|
827
859
|
**ClawRouter for NousResearch Hermes**
|
|
828
860
|
|
|
829
|
-
Python plugin that wraps the ClawRouter proxy for `hermes-agent`. Same <!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> models, same x402 USDC payments on
|
|
861
|
+
Python plugin that wraps the ClawRouter proxy for `hermes-agent`. Same <!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> models, same x402 USDC payments on Solana & Base, native Hermes ergonomics.
|
|
830
862
|
|
|
831
863
|
`pip install hermes-plugin-clawrouter`
|
|
832
864
|
|
|
@@ -868,6 +900,10 @@ Python plugin that wraps the ClawRouter proxy for `hermes-agent`. Same <!-- br:m
|
|
|
868
900
|
|
|
869
901
|
## Frequently Asked Questions
|
|
870
902
|
|
|
903
|
+
### What is BlockRun?
|
|
904
|
+
|
|
905
|
+
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 -->76<!-- /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.
|
|
906
|
+
|
|
871
907
|
### What is ClawRouter?
|
|
872
908
|
|
|
873
909
|
ClawRouter is an open-source (MIT licensed) smart LLM router built for autonomous AI agents. 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 — no external API calls needed for routing decisions.
|