@blockrun/clawrouter 0.12.269 → 0.12.271

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 (11) hide show
  1. package/README.md +74 -51
  2. package/dist/cli.js +195 -34
  3. package/dist/index.d.ts +37 -4
  4. package/dist/index.js +188 -34
  5. package/docs/configuration.md +17 -1
  6. package/package.json +1 -1
  7. package/skills/clawrouter/SKILL.md +8 -8
  8. package/skills/imagegen/SKILL.md +2 -2
  9. package/skills/phone/SKILL.md +3 -2
  10. package/skills/predexon/SKILL.md +1 -1
  11. package/skills/surf/SKILL.md +24 -8
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> (API key, via <a href="https://user.blockrun.ai">user.blockrun.ai</a>)<br>
11
- or <strong>USDC</strong> on Base or Solana (x402 wallet, no account at all).<br>
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>
@@ -78,11 +78,11 @@ This is the stack that lets agents operate autonomously: **x402 + USDC + local r
78
78
 
79
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.
80
80
 
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 | [user.blockrun.ai](https://user.blockrun.ai) → `clawrouter login brk_live_…` |
85
- | An autonomous agent | **USDC** on Base or Solana, per request | Nothing — a wallet is generated on first run |
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) |
86
86
 
87
87
  Full walkthrough: [Paying with a credit card](#paying-with-a-credit-card-api-key).
88
88
 
@@ -113,22 +113,28 @@ Full walkthrough: [Paying with a credit card](#paying-with-a-credit-card-api-key
113
113
 
114
114
  **Two ways to pay for the paid ones — pick one, the rest of ClawRouter is identical:**
115
115
 
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** | `blockrun.ai` (Base) / `sol.blockrun.ai` (Solana) | `api.blockrun.ai` |
122
- | **Billing** | USDC leaves your wallet per call, non-custodial | Card-funded account credit, drawn down at exact usage |
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** |
123
124
 
124
125
  ClawRouter prefers the API key whenever one is configured, so `clawrouter login`
125
126
  is all it takes to switch and `clawrouter logout` is all it takes to switch back.
126
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
+
127
133
  ### Desktop control plane (macOS)
128
134
 
129
135
  The Electron app in [`apps/desktop`](apps/desktop) provides one-click connections
130
136
  for OpenClaw, Codex, Hermes, DeepSeek Harness, and Pi, plus model pricing/context,
131
- wallet balances, Base/Solana switching, and Coinbase Onramp. It snapshots each
137
+ wallet balances, Solana/Base switching, and Coinbase Onramp. It snapshots each
132
138
  agent's existing config before changing it and restores the original bytes when
133
139
  you disconnect. Wallets are shared through `~/.blockrun`; older ClawRouter
134
140
  wallets are copied there automatically without overwriting existing Core files.
@@ -165,7 +171,7 @@ openclaw gateway restart
165
171
 
166
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.
167
173
  >
168
- > **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 Base & Solana.
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.
169
175
 
170
176
  No OpenClaw required. ClawRouter runs as a local proxy on port 8402.
171
177
 
@@ -176,7 +182,7 @@ npx @blockrun/clawrouter
176
182
  ```
177
183
 
178
184
  **2. Fund your wallet** — optional, skip for free tier
179
- 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.
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.
180
186
 
181
187
  **3. Point your client at `http://localhost:8402`**
182
188
 
@@ -438,11 +444,19 @@ Surf is BlockRun's unified crypto data API — **84 endpoints across 13 domains*
438
444
 
439
445
  ClawRouter ships Surf as a **skill, not as typed wrappers**. The proxy whitelists `/v1/surf/*` so any call through the local proxy is paid x402 from the same wallet; the agent reads `skills/surf/SKILL.md` for the endpoint catalog and crafts the HTTP call. No `blockrun_surf_*` tool definitions to maintain; a new Surf endpoint requires zero ClawRouter release.
440
446
 
441
- | Tier | Cost | Examples |
442
- | ---- | ---------: | ------------------------------------------------------------- |
443
- | 1 | **$0.001** | prices, rankings, lists, news |
444
- | 2 | **$0.005** | orderbooks, candles, search, wallet details, social mindshare |
445
- | 3 | **$0.020** | on-chain SQL / query / schema, chat completions |
447
+ **Flat per-call pricing** — every Surf endpoint costs the same. The old
448
+ $0.001/$0.005/$0.020 tiers no longer apply; upstream prices all three tiers
449
+ identically, and the tier now describes only endpoint weight.
450
+
451
+ | Rail | Price per call |
452
+ | --------------------------- | ---------------------------------- |
453
+ | API key (`api.blockrun.ai`) | **$0.0075** (base rate, no tx fee) |
454
+ | Wallet — Solana | **$0.0075** |
455
+ | Wallet — Base | **$0.0085** |
456
+
457
+ Measured 2026-09-05: the API-key rate from the account ledger, the wallet rates
458
+ from the x402 challenge, which quotes the price before anything is signed. On the
459
+ wallet rail that quote is always authoritative.
446
460
 
447
461
  **Usage (HTTP):**
448
462
 
@@ -522,11 +536,11 @@ No Surf account, no API key — settles directly to Surf's Base treasury in USDC
522
536
  | zai/glm-5.2 | $1.40 | $4.40 | $0.0029 | 1M | reasoning, coding, tools (flagship) |
523
537
  | zai/glm-5.1 | $1.40 | $4.40 | $0.0029 | 200K | reasoning, tools (promo ended 2026-06-05) |
524
538
  | qwen/qwen3.7-max | $1.475 | $4.425 | $0.0030 | 1M | reasoning, agentic, tools (Qwen flagship) |
525
- | xai/grok-4.3 | $1.50 | $4.00 | $0.0028 | 1M | reasoning, vision, agentic, tools |
526
- | google/gemini-3.6-flash | $1.50 | $7.50 | $0.0045 | 1M | reasoning, vision, tools (newest Flash) |
539
+ | xai/grok-4.3 | $1.25 | $2.50 | $0.0019 | 1M | reasoning, vision, agentic, tools |
540
+ | google/gemini-3.6-flash | $0.75 | $3.75 | $0.0023 | 1M | reasoning, vision, tools (newest Flash) |
527
541
  | google/gemini-3.5-flash | $1.50 | $9.00 | $0.0053 | 1M | reasoning, vision, tools (thinking) |
528
- | xai/grok-4.5 | $2.50 | $9.00 | $0.0058 | 500K | reasoning, vision, agentic, tools |
529
- | xai/grok-build-0.1 | $1.50 | $3.00 | $0.0023 | 256K | agentic coding, tools |
542
+ | xai/grok-4.5 | $2.00 | $6.00 | $0.0040 | 500K | reasoning, vision, agentic, tools |
543
+ | xai/grok-build-0.1 | $1.00 | $2.00 | $0.0015 | 256K | agentic coding, tools |
530
544
  | openai/gpt-5.2 | $1.75 | $14.00 | $0.0079 | 400K | reasoning, vision, agentic, tools |
531
545
  | openai/gpt-5.3 | $1.75 | $14.00 | $0.0079 | 128K | reasoning, vision, agentic, tools |
532
546
  | openai/gpt-5.3-codex | $1.75 | $14.00 | $0.0079 | 400K | agentic, tools |
@@ -547,8 +561,8 @@ No Surf account, no API key — settles directly to Surf's Base treasury in USDC
547
561
  | anthropic/claude-sonnet-4.6 | $3.00 | $15.00 | $0.0090 | 200K | reasoning, vision, agentic, tools |
548
562
  | anthropic/claude-opus-5 | $5.00 | $25.00 | $0.0150 | 1M | reasoning, vision, agentic, tools |
549
563
  | anthropic/claude-opus-4.8 | $5.00 | $25.00 | $0.0150 | 1M | reasoning, vision, agentic, tools |
550
- | openai/gpt-5.6-sol | $5.00 | $30.00 | $0.0175 | 1M | reasoning, vision, agentic, tools |
551
- | openai/gpt-5.6-sol-pro | $5.00 | $30.00 | $0.0175 | 1M | reasoning, vision, agentic, tools |
564
+ | openai/gpt-5.6-sol | $4.00 | $20.00 | $0.0120 | 1M | reasoning, vision, agentic, tools |
565
+ | openai/gpt-5.6-sol-pro | $4.00 | $20.00 | $0.0120 | 1M | reasoning, vision, agentic, tools |
552
566
  | openai/gpt-5.5 | $5.00 | $30.00 | $0.0175 | 1M | reasoning, vision, agentic, tools |
553
567
  | moonshot/kimi-k3 | $3.00 | $15.00 | $0.0110 | 1M | reasoning, vision, agentic, tools |
554
568
  | openai/chat-latest | $5.00 | $30.00 | $0.0175 | 128K | vision, tools |
@@ -577,7 +591,7 @@ Request → 402 (price: $0.003) → wallet signs USDC → retry → response
577
591
 
578
592
  USDC stays in your wallet until spent — non-custodial. Price is visible in the 402 header before signing.
579
593
 
580
- **Dual-chain support:** Pay with **USDC** on **Base (EVM)** or **USDC on Solana**. Both wallets are derived from a single BIP-39 mnemonic on first run. New installs default to **Solana**; existing installs stay on **Base** unless switched with `/wallet solana`.
594
+ **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`.
581
595
 
582
596
  ```bash
583
597
  /wallet # Check balance and address (both chains)
@@ -595,10 +609,10 @@ USDC stays in your wallet until spent — non-custodial. Price is visible in the
595
609
 
596
610
  **Fund your wallet:**
597
611
 
612
+ - **Solana (default):** Send USDC on Solana to your Solana address
598
613
  - **Base (EVM):** Send USDC on Base to your EVM address
599
- - **Solana:** Send USDC on Solana to your Solana address
600
614
  - **Coinbase/CEX:** Withdraw USDC to either network
601
- - **Credit card:** don't fund a wallet at all — use an API key instead (below)
615
+ - **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)
602
616
 
603
617
  ---
604
618
 
@@ -612,11 +626,11 @@ by card-funded credit — and ClawRouter speaks that too.
612
626
 
613
627
  Go to **[user.blockrun.ai](https://user.blockrun.ai)**:
614
628
 
615
- 1. Sign in.
616
- 2. **Credits** → top up with a credit card. The processing fee is charged at
617
- purchase, not on inference: you pay it once on the top-up and every model
618
- then bills at the published list price, with **no per-call minimum and no
619
- per-call fee**.
629
+ 1. **Sign in with Google.** That is the whole signup — no invite, no sales call.
630
+ 2. **Credits** → top up with a credit card. The processing fee is **5.5% + $0.30**,
631
+ charged at purchase, not on inference: you pay it once on the top-up and every
632
+ model then bills at **provider list price with no markup**, with **no per-call
633
+ minimum and no per-call fee**.
620
634
  3. **API Keys** → create a key. It is shown once and looks like
621
635
  `brk_live_…` — copy it before you leave the page.
622
636
 
@@ -674,12 +688,19 @@ chains, the response cache and the local spend controls.
674
688
  signs with a private key — `clawrouter doctor` will not mint one either.
675
689
  - **Balance lives server-side.** There is no local balance to check: a call that
676
690
  outruns your credit comes back as HTTP `402 insufficient_quota`, naming the
677
- top-up page. Free models stay free and need no credit at all.
678
- - **Chat today, media next.** `api.blockrun.ai` currently serves the chat and
679
- text-completion endpoints (`/v1/chat/completions`, `/v1/messages`, `/v1/models`).
680
- Image, video, audio and the partner APIs are still wallet-only; ClawRouter says
681
- so explicitly instead of returning a bare 404, and they light up on the API-key
682
- path as BlockRun publishes them — no ClawRouter release needed.
691
+ top-up page. Free models stay free and need no credit at all — all
692
+ <!-- br:models.free -->7<!-- /br:models.free --> are served on the API-key gateway too.
693
+ - **One key covers nearly everything.** Verified live against `api.blockrun.ai`
694
+ on 2026-09-05: chat completions (`/v1/chat/completions`), the Anthropic-shaped
695
+ `/v1/messages`, `/v1/models`, image generation, speech, video, and the partner
696
+ APIs — Surf crypto data, Exa search, prediction markets, and phone lookup and
697
+ fraud checks.
698
+ - **The wallet-only exceptions** are the routes that bind a lease or a position
699
+ to a payer address, because there is no address to bind to without a wallet:
700
+ buying, renewing, listing and releasing **phone numbers** (the gateway answers
701
+ those with a raw `402` on a key), and **Polymarket trading**, which ClawRouter
702
+ signs locally with the wallet key. Phone lookups, fraud checks and outbound
703
+ voice calls are fine on a key; only owning a number is not.
683
704
  - **`maxCostPerRun` and `/exclude` still apply**, along with the router's own
684
705
  budget filter — they live in the router, not the signer. **`clawrouter policy`
685
706
  limits do not**: they are enforced in the x402 pre-sign hook, and nothing is
@@ -716,7 +737,7 @@ For basic usage, no configuration needed. For advanced options:
716
737
  | `BLOCKRUN_PROXY_PORT` | `8402` | Local proxy port |
717
738
  | `CLAWROUTER_DISABLED` | `false` | Disable smart routing |
718
739
  | `CLAWROUTER_DEBUG_HEADERS` | `on` | Set to `off` to suppress `x-clawrouter-*` debug response headers |
719
- | `CLAWROUTER_SOLANA_RPC_URL` | `https://api.mainnet-beta.solana.com` | Solana RPC endpoint |
740
+ | `CLAWROUTER_SOLANA_RPC_URL` | `https://api.mainnet-beta.solana.com` | Solana RPC endpoint — balance checks and payment signing |
720
741
 
721
742
  **Full reference:** [docs/configuration.md](docs/configuration.md)
722
743
 
@@ -799,13 +820,15 @@ npm test
799
820
 
800
821
  ## Support
801
822
 
802
- | Channel | Link |
803
- | --------------------- | ------------------------------------------------------------------ |
804
- | 📅 Schedule Demo | [calendly.com/vickyfu9/30min](https://calendly.com/vickyfu9/30min) |
805
- | 💬 Community Telegram | [t.me/blockrunAI](https://t.me/blockrunAI) |
806
- | 🐦 X / Twitter | [x.com/blockrunai](https://x.com/blockrunai) |
807
- | 📱 Founder Telegram | [@bc1max](https://t.me/bc1max) |
808
- | ✉️ Email | vicky@blockrun.ai |
823
+ | Channel | Link |
824
+ | --------------------- | -------------------------------------------------------------------------------- |
825
+ | 🔑 Sign up / API keys | [user.blockrun.ai](https://user.blockrun.ai) |
826
+ | 💳 Add credit | [user.blockrun.ai/dashboard/credits](https://user.blockrun.ai/dashboard/credits) |
827
+ | 📅 Schedule Demo | [calendly.com/vickyfu9/30min](https://calendly.com/vickyfu9/30min) |
828
+ | 💬 Community Telegram | [t.me/blockrunAI](https://t.me/blockrunAI) |
829
+ | 🐦 X / Twitter | [x.com/blockrunai](https://x.com/blockrunai) |
830
+ | 📱 Founder Telegram | [@bc1max](https://t.me/bc1max) |
831
+ | ✉️ Email | vicky@blockrun.ai |
809
832
 
810
833
  ---
811
834
 
@@ -843,7 +866,7 @@ Run Claude Code with <!-- br:models.chatVisible -->76<!-- /br:models.chatVisible
843
866
 
844
867
  **ClawRouter for NousResearch Hermes**
845
868
 
846
- Python plugin that wraps the ClawRouter proxy for `hermes-agent`. Same <!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> models, same x402 USDC payments on Base & Solana, native Hermes ergonomics.
869
+ 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.
847
870
 
848
871
  `pip install hermes-plugin-clawrouter`
849
872