@blockrun/clawrouter 0.12.269 → 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.
Files changed (10) hide show
  1. package/README.md +60 -45
  2. package/dist/cli.js +50 -23
  3. package/dist/index.d.ts +20 -4
  4. package/dist/index.js +50 -23
  5. package/package.json +1 -1
  6. package/skills/clawrouter/SKILL.md +8 -8
  7. package/skills/imagegen/SKILL.md +2 -2
  8. package/skills/phone/SKILL.md +3 -2
  9. package/skills/predexon/SKILL.md +1 -1
  10. 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> (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
 
@@ -522,11 +528,11 @@ No Surf account, no API key — settles directly to Surf's Base treasury in USDC
522
528
  | zai/glm-5.2 | $1.40 | $4.40 | $0.0029 | 1M | reasoning, coding, tools (flagship) |
523
529
  | zai/glm-5.1 | $1.40 | $4.40 | $0.0029 | 200K | reasoning, tools (promo ended 2026-06-05) |
524
530
  | 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) |
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) |
527
533
  | 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 |
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 |
530
536
  | openai/gpt-5.2 | $1.75 | $14.00 | $0.0079 | 400K | reasoning, vision, agentic, tools |
531
537
  | openai/gpt-5.3 | $1.75 | $14.00 | $0.0079 | 128K | reasoning, vision, agentic, tools |
532
538
  | openai/gpt-5.3-codex | $1.75 | $14.00 | $0.0079 | 400K | agentic, tools |
@@ -547,8 +553,8 @@ No Surf account, no API key — settles directly to Surf's Base treasury in USDC
547
553
  | anthropic/claude-sonnet-4.6 | $3.00 | $15.00 | $0.0090 | 200K | reasoning, vision, agentic, tools |
548
554
  | anthropic/claude-opus-5 | $5.00 | $25.00 | $0.0150 | 1M | reasoning, vision, agentic, tools |
549
555
  | 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 |
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 |
552
558
  | openai/gpt-5.5 | $5.00 | $30.00 | $0.0175 | 1M | reasoning, vision, agentic, tools |
553
559
  | moonshot/kimi-k3 | $3.00 | $15.00 | $0.0110 | 1M | reasoning, vision, agentic, tools |
554
560
  | openai/chat-latest | $5.00 | $30.00 | $0.0175 | 128K | vision, tools |
@@ -577,7 +583,7 @@ Request → 402 (price: $0.003) → wallet signs USDC → retry → response
577
583
 
578
584
  USDC stays in your wallet until spent — non-custodial. Price is visible in the 402 header before signing.
579
585
 
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`.
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`.
581
587
 
582
588
  ```bash
583
589
  /wallet # Check balance and address (both chains)
@@ -595,10 +601,10 @@ USDC stays in your wallet until spent — non-custodial. Price is visible in the
595
601
 
596
602
  **Fund your wallet:**
597
603
 
604
+ - **Solana (default):** Send USDC on Solana to your Solana address
598
605
  - **Base (EVM):** Send USDC on Base to your EVM address
599
- - **Solana:** Send USDC on Solana to your Solana address
600
606
  - **Coinbase/CEX:** Withdraw USDC to either network
601
- - **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)
602
608
 
603
609
  ---
604
610
 
@@ -612,11 +618,11 @@ by card-funded credit — and ClawRouter speaks that too.
612
618
 
613
619
  Go to **[user.blockrun.ai](https://user.blockrun.ai)**:
614
620
 
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**.
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**.
620
626
  3. **API Keys** → create a key. It is shown once and looks like
621
627
  `brk_live_…` — copy it before you leave the page.
622
628
 
@@ -674,12 +680,19 @@ chains, the response cache and the local spend controls.
674
680
  signs with a private key — `clawrouter doctor` will not mint one either.
675
681
  - **Balance lives server-side.** There is no local balance to check: a call that
676
682
  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.
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.
683
696
  - **`maxCostPerRun` and `/exclude` still apply**, along with the router's own
684
697
  budget filter — they live in the router, not the signer. **`clawrouter policy`
685
698
  limits do not**: they are enforced in the x402 pre-sign hook, and nothing is
@@ -799,13 +812,15 @@ npm test
799
812
 
800
813
  ## Support
801
814
 
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 |
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 |
809
824
 
810
825
  ---
811
826
 
@@ -843,7 +858,7 @@ Run Claude Code with <!-- br:models.chatVisible -->76<!-- /br:models.chatVisible
843
858
 
844
859
  **ClawRouter for NousResearch Hermes**
845
860
 
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.
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.
847
862
 
848
863
  `pip install hermes-plugin-clawrouter`
849
864
 
package/dist/cli.js CHANGED
@@ -38541,8 +38541,8 @@ var init_models = __esm({
38541
38541
  id: "openai/gpt-5.6-sol",
38542
38542
  name: "GPT-5.6 Sol",
38543
38543
  version: "5.6",
38544
- inputPrice: 5,
38545
- outputPrice: 30,
38544
+ inputPrice: 4,
38545
+ outputPrice: 20,
38546
38546
  contextWindow: 105e4,
38547
38547
  maxOutput: 128e3,
38548
38548
  reasoning: true,
@@ -38583,8 +38583,8 @@ var init_models = __esm({
38583
38583
  id: "openai/gpt-5.6-sol-pro",
38584
38584
  name: "GPT-5.6 Sol Pro",
38585
38585
  version: "5.6",
38586
- inputPrice: 5,
38587
- outputPrice: 30,
38586
+ inputPrice: 4,
38587
+ outputPrice: 20,
38588
38588
  contextWindow: 105e4,
38589
38589
  maxOutput: 128e3,
38590
38590
  reasoning: true,
@@ -39022,8 +39022,8 @@ var init_models = __esm({
39022
39022
  id: "google/gemini-3.6-flash",
39023
39023
  name: "Gemini 3.6 Flash",
39024
39024
  version: "3.6",
39025
- inputPrice: 1.5,
39026
- outputPrice: 7.5,
39025
+ inputPrice: 0.75,
39026
+ outputPrice: 3.75,
39027
39027
  contextWindow: 1048576,
39028
39028
  maxOutput: 65536,
39029
39029
  reasoning: true,
@@ -39419,8 +39419,8 @@ var init_models = __esm({
39419
39419
  id: "xai/grok-4.5",
39420
39420
  name: "Grok 4.5",
39421
39421
  version: "4.5",
39422
- inputPrice: 2.5,
39423
- outputPrice: 9,
39422
+ inputPrice: 2,
39423
+ outputPrice: 6,
39424
39424
  contextWindow: 5e5,
39425
39425
  maxOutput: 16384,
39426
39426
  reasoning: true,
@@ -39434,8 +39434,8 @@ var init_models = __esm({
39434
39434
  id: "xai/grok-4.3",
39435
39435
  name: "Grok 4.3",
39436
39436
  version: "4.3",
39437
- inputPrice: 1.5,
39438
- outputPrice: 4,
39437
+ inputPrice: 1.25,
39438
+ outputPrice: 2.5,
39439
39439
  contextWindow: 1e6,
39440
39440
  maxOutput: 16384,
39441
39441
  reasoning: true,
@@ -39447,8 +39447,8 @@ var init_models = __esm({
39447
39447
  id: "xai/grok-build-0.1",
39448
39448
  name: "Grok Build 0.1",
39449
39449
  version: "0.1",
39450
- inputPrice: 1.5,
39451
- outputPrice: 3,
39450
+ inputPrice: 1,
39451
+ outputPrice: 2,
39452
39452
  contextWindow: 256e3,
39453
39453
  maxOutput: 16384,
39454
39454
  agentic: true,
@@ -60054,13 +60054,18 @@ async function loadPaymentChain() {
60054
60054
  const core = await readOptional(CORE_CHAIN_FILE);
60055
60055
  if (core === "solana") return "solana";
60056
60056
  if (core === "base") return "base";
60057
- try {
60058
- const content = (await readTextFile(CHAIN_FILE)).trim();
60059
- if (content === "solana") return "solana";
60060
- return "base";
60061
- } catch {
60062
- return "base";
60063
- }
60057
+ const legacy = await readOptional(CHAIN_FILE);
60058
+ if (legacy === "solana") return "solana";
60059
+ if (legacy === "base") return "base";
60060
+ return await hasExistingWallet() ? "base" : "solana";
60061
+ }
60062
+ async function hasExistingWallet() {
60063
+ if (process["env"].BLOCKRUN_WALLET_KEY?.trim()) return true;
60064
+ const [core, legacy] = await Promise.all([
60065
+ readOptional(CORE_WALLET_FILE),
60066
+ readOptional(WALLET_FILE)
60067
+ ]);
60068
+ return Boolean(core || legacy);
60064
60069
  }
60065
60070
  async function resolvePaymentChain() {
60066
60071
  if (process["env"].CLAWROUTER_PAYMENT_CHAIN === "solana") return "solana";
@@ -60194,7 +60199,7 @@ var init_api_key = __esm({
60194
60199
  HINTS = {
60195
60200
  401: `Check BLOCKRUN_API_KEY, or mint a new key at ${PORTAL_KEYS_URL}.`,
60196
60201
  402: `Top up your BlockRun credit at ${PORTAL_CREDITS_URL}.`,
60197
- 404: `api.blockrun.ai does not serve this endpoint yet \u2014 it currently carries chat and text completions. For media and partner APIs, run ClawRouter in wallet mode (unset BLOCKRUN_API_KEY and run "clawrouter logout").`
60202
+ 404: `api.blockrun.ai does not serve this endpoint. Chat, Anthropic-shaped messages, images, speech, video and the partner APIs (Surf, Exa, prediction markets, phone lookup) all work on an API key. The wallet-only exceptions are the routes that bind a lease or a position to a payer address \u2014 buying/renewing/releasing phone numbers, and Polymarket trading \u2014 which need a wallet to own the thing being bought. For those, unset BLOCKRUN_API_KEY and run "clawrouter logout".`
60198
60203
  };
60199
60204
  }
60200
60205
  });
@@ -92578,7 +92583,8 @@ async function startProxy(options) {
92578
92583
  }
92579
92584
  return;
92580
92585
  }
92581
- if (req.url?.match(
92586
+ const isVerbatimGatewayPath = req.url === "/v1/messages" || (req.url?.startsWith("/v1/messages?") ?? false) || req.url === "/v1/audio/speech" || (req.url?.startsWith("/v1/audio/speech?") ?? false);
92587
+ if (isVerbatimGatewayPath || req.url?.match(
92582
92588
  /^\/v1\/(?:partner|pm|exa|modal|stocks|usstock|crypto|fx|commodity|phone|voice|surf)\//
92583
92589
  )) {
92584
92590
  try {
@@ -92610,6 +92616,19 @@ async function startProxy(options) {
92610
92616
  res.end(JSON.stringify({ error: "Not found" }));
92611
92617
  return;
92612
92618
  }
92619
+ if (!req.url.includes("/chat/completions")) {
92620
+ res.writeHead(404, { "Content-Type": "application/json" });
92621
+ res.end(
92622
+ JSON.stringify({
92623
+ error: {
92624
+ message: `ClawRouter does not proxy ${req.url}. It serves /v1/chat/completions, /v1/messages, /v1/models, /v1/images/generations, /v1/images/image2image, /v1/videos/generations, /v1/audio/generations, /v1/audio/speech, and the partner prefixes /v1/{partner,pm,exa,modal,stocks,usstock,crypto,fx,commodity,phone,voice,surf}/. If BlockRun serves this endpoint, call it directly against the gateway.`,
92625
+ type: "invalid_request_error",
92626
+ code: "unsupported_endpoint"
92627
+ }
92628
+ })
92629
+ );
92630
+ return;
92631
+ }
92613
92632
  try {
92614
92633
  await proxyRequest(
92615
92634
  req,
@@ -229633,7 +229652,15 @@ ${errText}`
229633
229652
  });
229634
229653
  if (!isGatewayMode()) {
229635
229654
  if (shouldLogRegistration) {
229636
- resolveOrGenerateWalletKey().then(({ address: address2, source }) => {
229655
+ void (async () => {
229656
+ const keyResolution = await resolveApiKey().catch(() => void 0);
229657
+ if (keyResolution) {
229658
+ api.logger.info(
229659
+ `Using BlockRun API key ${maskApiKey(keyResolution.key)} (from ${keyResolution.source}) \u2014 billing account credit, no wallet`
229660
+ );
229661
+ return;
229662
+ }
229663
+ const { address: address2, source } = await resolveOrGenerateWalletKey();
229637
229664
  if (source === "generated") {
229638
229665
  api.logger.warn(`\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550`);
229639
229666
  api.logger.warn(` NEW WALLET GENERATED \u2014 BACK UP YOUR KEY NOW!`);
@@ -229650,7 +229677,7 @@ ${errText}`
229650
229677
  } else {
229651
229678
  api.logger.info(`Using wallet from BLOCKRUN_WALLET_KEY: ${address2}`);
229652
229679
  }
229653
- }).catch((err) => {
229680
+ })().catch((err) => {
229654
229681
  api.logger.warn(
229655
229682
  `Failed to initialize wallet: ${err instanceof Error ? err.message : String(err)}`
229656
229683
  );
package/dist/index.d.ts CHANGED
@@ -1248,13 +1248,29 @@ declare function setupSolana(): Promise<{
1248
1248
  declare function savePaymentChain(chain: "base" | "solana"): Promise<void>;
1249
1249
  /**
1250
1250
  * Load the persisted payment chain selection from disk.
1251
- * Returns "base" if no file exists or the file is invalid.
1252
- * New installs persist "solana" at wallet generation, so an absent file
1253
- * means a pre-existing install whose funds live on Base.
1251
+ *
1252
+ * Solana is the preferred rail, and since v0.12.246 wallet generation persists
1253
+ * `solana` outright — so a fresh install answers "solana" from its own chain
1254
+ * file, not from a default. This function only decides the case where no chain
1255
+ * file exists at all, and there the answer turns on whether a wallet already
1256
+ * does:
1257
+ *
1258
+ * no chain file, no wallet → "solana" (nothing to strand; prefer Solana)
1259
+ * no chain file, wallet on disk → "base" (a pre-v0.12.246 install)
1260
+ *
1261
+ * That second line is the one that must not move. An install predating the
1262
+ * Solana default has USDC sitting in its Base wallet and no Solana balance;
1263
+ * flipping it would point every request at a gateway its money is not on and
1264
+ * fail them all with an empty balance. The same reasoning covers a wallet
1265
+ * supplied through BLOCKRUN_WALLET_KEY, and a generated wallet whose Solana
1266
+ * derivation failed (no chain file is written in that case, on purpose — see
1267
+ * resolveOrGenerateWalletKey — and the wallet it did write keeps us on Base,
1268
+ * which is the only chain that proxy can actually sign for).
1254
1269
  */
1255
1270
  declare function loadPaymentChain(): Promise<"base" | "solana">;
1256
1271
  /**
1257
- * Resolve payment chain: env var first → persisted file second → default "base".
1272
+ * Resolve payment chain: env var first → persisted file second → the
1273
+ * fresh-install preference (Solana) last. See loadPaymentChain.
1258
1274
  */
1259
1275
  declare function resolvePaymentChain(): Promise<"base" | "solana">;
1260
1276
 
package/dist/index.js CHANGED
@@ -783,8 +783,8 @@ var init_models = __esm({
783
783
  id: "openai/gpt-5.6-sol",
784
784
  name: "GPT-5.6 Sol",
785
785
  version: "5.6",
786
- inputPrice: 5,
787
- outputPrice: 30,
786
+ inputPrice: 4,
787
+ outputPrice: 20,
788
788
  contextWindow: 105e4,
789
789
  maxOutput: 128e3,
790
790
  reasoning: true,
@@ -825,8 +825,8 @@ var init_models = __esm({
825
825
  id: "openai/gpt-5.6-sol-pro",
826
826
  name: "GPT-5.6 Sol Pro",
827
827
  version: "5.6",
828
- inputPrice: 5,
829
- outputPrice: 30,
828
+ inputPrice: 4,
829
+ outputPrice: 20,
830
830
  contextWindow: 105e4,
831
831
  maxOutput: 128e3,
832
832
  reasoning: true,
@@ -1264,8 +1264,8 @@ var init_models = __esm({
1264
1264
  id: "google/gemini-3.6-flash",
1265
1265
  name: "Gemini 3.6 Flash",
1266
1266
  version: "3.6",
1267
- inputPrice: 1.5,
1268
- outputPrice: 7.5,
1267
+ inputPrice: 0.75,
1268
+ outputPrice: 3.75,
1269
1269
  contextWindow: 1048576,
1270
1270
  maxOutput: 65536,
1271
1271
  reasoning: true,
@@ -1661,8 +1661,8 @@ var init_models = __esm({
1661
1661
  id: "xai/grok-4.5",
1662
1662
  name: "Grok 4.5",
1663
1663
  version: "4.5",
1664
- inputPrice: 2.5,
1665
- outputPrice: 9,
1664
+ inputPrice: 2,
1665
+ outputPrice: 6,
1666
1666
  contextWindow: 5e5,
1667
1667
  maxOutput: 16384,
1668
1668
  reasoning: true,
@@ -1676,8 +1676,8 @@ var init_models = __esm({
1676
1676
  id: "xai/grok-4.3",
1677
1677
  name: "Grok 4.3",
1678
1678
  version: "4.3",
1679
- inputPrice: 1.5,
1680
- outputPrice: 4,
1679
+ inputPrice: 1.25,
1680
+ outputPrice: 2.5,
1681
1681
  contextWindow: 1e6,
1682
1682
  maxOutput: 16384,
1683
1683
  reasoning: true,
@@ -1689,8 +1689,8 @@ var init_models = __esm({
1689
1689
  id: "xai/grok-build-0.1",
1690
1690
  name: "Grok Build 0.1",
1691
1691
  version: "0.1",
1692
- inputPrice: 1.5,
1693
- outputPrice: 3,
1692
+ inputPrice: 1,
1693
+ outputPrice: 2,
1694
1694
  contextWindow: 256e3,
1695
1695
  maxOutput: 16384,
1696
1696
  agentic: true,
@@ -59861,13 +59861,18 @@ async function loadPaymentChain() {
59861
59861
  const core = await readOptional(CORE_CHAIN_FILE);
59862
59862
  if (core === "solana") return "solana";
59863
59863
  if (core === "base") return "base";
59864
- try {
59865
- const content = (await readTextFile(CHAIN_FILE)).trim();
59866
- if (content === "solana") return "solana";
59867
- return "base";
59868
- } catch {
59869
- return "base";
59870
- }
59864
+ const legacy = await readOptional(CHAIN_FILE);
59865
+ if (legacy === "solana") return "solana";
59866
+ if (legacy === "base") return "base";
59867
+ return await hasExistingWallet() ? "base" : "solana";
59868
+ }
59869
+ async function hasExistingWallet() {
59870
+ if (process["env"].BLOCKRUN_WALLET_KEY?.trim()) return true;
59871
+ const [core, legacy] = await Promise.all([
59872
+ readOptional(CORE_WALLET_FILE),
59873
+ readOptional(WALLET_FILE)
59874
+ ]);
59875
+ return Boolean(core || legacy);
59871
59876
  }
59872
59877
  async function resolvePaymentChain() {
59873
59878
  if (process["env"].CLAWROUTER_PAYMENT_CHAIN === "solana") return "solana";
@@ -59981,7 +59986,7 @@ var init_api_key = __esm({
59981
59986
  HINTS = {
59982
59987
  401: `Check BLOCKRUN_API_KEY, or mint a new key at ${PORTAL_KEYS_URL}.`,
59983
59988
  402: `Top up your BlockRun credit at ${PORTAL_CREDITS_URL}.`,
59984
- 404: `api.blockrun.ai does not serve this endpoint yet \u2014 it currently carries chat and text completions. For media and partner APIs, run ClawRouter in wallet mode (unset BLOCKRUN_API_KEY and run "clawrouter logout").`
59989
+ 404: `api.blockrun.ai does not serve this endpoint. Chat, Anthropic-shaped messages, images, speech, video and the partner APIs (Surf, Exa, prediction markets, phone lookup) all work on an API key. The wallet-only exceptions are the routes that bind a lease or a position to a payer address \u2014 buying/renewing/releasing phone numbers, and Polymarket trading \u2014 which need a wallet to own the thing being bought. For those, unset BLOCKRUN_API_KEY and run "clawrouter logout".`
59985
59990
  };
59986
59991
  }
59987
59992
  });
@@ -92365,7 +92370,8 @@ async function startProxy(options) {
92365
92370
  }
92366
92371
  return;
92367
92372
  }
92368
- if (req.url?.match(
92373
+ const isVerbatimGatewayPath = req.url === "/v1/messages" || (req.url?.startsWith("/v1/messages?") ?? false) || req.url === "/v1/audio/speech" || (req.url?.startsWith("/v1/audio/speech?") ?? false);
92374
+ if (isVerbatimGatewayPath || req.url?.match(
92369
92375
  /^\/v1\/(?:partner|pm|exa|modal|stocks|usstock|crypto|fx|commodity|phone|voice|surf)\//
92370
92376
  )) {
92371
92377
  try {
@@ -92397,6 +92403,19 @@ async function startProxy(options) {
92397
92403
  res.end(JSON.stringify({ error: "Not found" }));
92398
92404
  return;
92399
92405
  }
92406
+ if (!req.url.includes("/chat/completions")) {
92407
+ res.writeHead(404, { "Content-Type": "application/json" });
92408
+ res.end(
92409
+ JSON.stringify({
92410
+ error: {
92411
+ message: `ClawRouter does not proxy ${req.url}. It serves /v1/chat/completions, /v1/messages, /v1/models, /v1/images/generations, /v1/images/image2image, /v1/videos/generations, /v1/audio/generations, /v1/audio/speech, and the partner prefixes /v1/{partner,pm,exa,modal,stocks,usstock,crypto,fx,commodity,phone,voice,surf}/. If BlockRun serves this endpoint, call it directly against the gateway.`,
92412
+ type: "invalid_request_error",
92413
+ code: "unsupported_endpoint"
92414
+ }
92415
+ })
92416
+ );
92417
+ return;
92418
+ }
92400
92419
  try {
92401
92420
  await proxyRequest(
92402
92421
  req,
@@ -229338,7 +229357,15 @@ ${errText}`
229338
229357
  });
229339
229358
  if (!isGatewayMode()) {
229340
229359
  if (shouldLogRegistration) {
229341
- resolveOrGenerateWalletKey().then(({ address: address2, source }) => {
229360
+ void (async () => {
229361
+ const keyResolution = await resolveApiKey().catch(() => void 0);
229362
+ if (keyResolution) {
229363
+ api.logger.info(
229364
+ `Using BlockRun API key ${maskApiKey(keyResolution.key)} (from ${keyResolution.source}) \u2014 billing account credit, no wallet`
229365
+ );
229366
+ return;
229367
+ }
229368
+ const { address: address2, source } = await resolveOrGenerateWalletKey();
229342
229369
  if (source === "generated") {
229343
229370
  api.logger.warn(`\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550`);
229344
229371
  api.logger.warn(` NEW WALLET GENERATED \u2014 BACK UP YOUR KEY NOW!`);
@@ -229355,7 +229382,7 @@ ${errText}`
229355
229382
  } else {
229356
229383
  api.logger.info(`Using wallet from BLOCKRUN_WALLET_KEY: ${address2}`);
229357
229384
  }
229358
- }).catch((err) => {
229385
+ })().catch((err) => {
229359
229386
  api.logger.warn(
229360
229387
  `Failed to initialize wallet: ${err instanceof Error ? err.message : String(err)}`
229361
229388
  );
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@blockrun/clawrouter",
3
- "version": "0.12.269",
3
+ "version": "0.12.270",
4
4
  "description": "Smart LLM router — save 84% on inference costs. 76 models (7 free). Pay by credit card (API key) or USDC (x402 wallet).",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
package/skills/clawrouter/SKILL.md CHANGED
@@ -53,7 +53,7 @@ metadata:
53
53
 
54
54
  # ClawRouter
55
55
 
56
- 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 -->76<!-- /br:models.chatVisible --> models from 9 providers (<!-- br:models.free -->7<!-- /br:models.free --> free open-weight models). All billing flows through one USDC wallet; you do not hold provider API keys.
56
+ 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 -->76<!-- /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.
57
57
 
58
58
  **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.
59
59
 
@@ -69,7 +69,7 @@ Your app → localhost proxy (ClawRouter) → https://blockrun.ai/api (or sol.b
69
69
  Response → back through proxy → your app
70
70
  ```
71
71
 
72
- **Sent to blockrun.ai on every request:** the model name, the full prompt/messages body, sampling params (temperature, max_tokens, tools, etc.), and an `X-PAYMENT` header containing a signed x402 USDC micropayment.
72
+ **Sent to blockrun.ai on every request:** the model name, the full prompt/messages body, sampling params (temperature, max_tokens, tools, etc.), and a payment credential — an `X-PAYMENT` header containing a signed x402 USDC micropayment in wallet mode, or an `Authorization: Bearer brk_live_…` header in API-key mode.
73
73
 
74
74
  **Not sent:** your wallet private key (only the detached payment signature is sent), any other local files, environment variables, or OpenClaw config beyond what's needed for this request.
75
75
 
@@ -81,12 +81,12 @@ ClawRouter does **not** collect or forward third-party provider API keys. You do
81
81
 
82
82
  **What `models.providers.blockrun` stores (fully enumerated):**
83
83
 
84
- | Field | Sensitive | Purpose |
85
- | ----------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
86
- | `walletKey` | Yes | EVM private key used to sign USDC micropayments via x402. **Auto-generated locally on first run** — no user input required. Never transmitted over the network; only detached payment signatures are sent. |
87
- | `solanaKey` | Yes | Solana keypair (BIP-44 `m/44'/501'/0'/0'`). Auto-derived from the same local mnemonic via `@scure/bip32` + `@scure/bip39`. |
88
- | `gateway` | No | Gateway URL. Defaults: `https://sol.blockrun.ai/api` (Solana, default chain for new installs) · `https://blockrun.ai/api` (Base, default for pre-existing installs). |
89
- | `routing` | No | Optional override of the router-core config (tier chains, `strategy: "rules"` rollback, `shadow` comparison, scorer keywords). |
84
+ | Field | Sensitive | Purpose |
85
+ | ----------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
86
+ | `walletKey` | Only in wallet mode | EVM private key used to sign USDC micropayments via x402. **Auto-generated locally on first run** — no user input required. Never transmitted over the network; only detached payment signatures are sent. Not used, read, or generated at all when a BlockRun API key is configured. |
87
+ | `solanaKey` | Yes | Solana keypair (BIP-44 `m/44'/501'/0'/0'`). Auto-derived from the same local mnemonic via `@scure/bip32` + `@scure/bip39`. |
88
+ | `gateway` | No | Gateway URL. Defaults: `https://sol.blockrun.ai/api` (Solana, default chain for new installs) · `https://blockrun.ai/api` (Base, default for pre-existing installs). |
89
+ | `routing` | No | Optional override of the router-core config (tier chains, `strategy: "rules"` rollback, `shadow` comparison, scorer keywords). |
90
90
 
91
91
  **How and where keys are stored:**
92
92
 
package/skills/imagegen/SKILL.md CHANGED
@@ -137,8 +137,8 @@ Response is identical to generation:
137
137
 
138
138
  ## Notes
139
139
 
140
- - Payment is automatic via x402 — deducted from the user's BlockRun wallet
141
- - If the call fails with a payment error, tell the user to fund their wallet at [blockrun.ai](https://blockrun.ai)
140
+ - Payment is automatic, and which rail it uses depends on how ClawRouter was started: an x402 USDC micropayment from the user's wallet, or a draw on account credit if a BlockRun API key is configured. Either way the agent does nothing.
141
+ - If the call fails with a payment error, check `GET http://localhost:8402/health` and read `authMode` before telling the user how to fix it: `wallet` → fund the wallet at [blockrun.ai](https://blockrun.ai); `api-key` → top up account credit at [user.blockrun.ai/dashboard/credits](https://user.blockrun.ai/dashboard/credits). Naming the wrong one sends the user to a page that cannot fix their error.
142
142
  - Google models may return base64 internally — ClawRouter uploads automatically and returns a hosted URL
143
143
  - OpenAI image models enforce OpenAI content policy; use `nano-banana` or `grok-imagine` for more flexibility
144
144
  - Image editing is only available with `gpt-image-1`; generation supports all listed models
package/skills/phone/SKILL.md CHANGED
@@ -200,8 +200,9 @@ GET `http://localhost:8402/v1/voice/call/{call_id}`. Returns:
200
200
 
201
201
  ## Notes
202
202
 
203
- - Payment is automatic via x402 — deducted from the user's BlockRun wallet on every call
204
- - If a call fails with a 402, tell the user to fund their wallet at [blockrun.ai](https://blockrun.ai)
203
+ - Payment is automatic on every call — an x402 USDC micropayment from the user's wallet, or a draw on account credit if a BlockRun API key is configured.
204
+ - If a call fails with a 402, check `GET http://localhost:8402/health` and read `authMode` first: `wallet` → fund the wallet at [blockrun.ai](https://blockrun.ai); `api-key` → top up at [user.blockrun.ai/dashboard/credits](https://user.blockrun.ai/dashboard/credits).
205
+ - Number leases are bound to the **wallet's** payer address, so `phone numbers list/buy/renew/release` and the `from` parameter are wallet-mode features. In API-key mode the gateway answers those routes with a raw `402` x402 challenge (verified 2026-09-05) because there is no payer address to bind a lease to. Lookups, fraud checks and outbound calls all work on an API key; just let the server auto-pick `from`.
205
206
  - Phone numbers are real, regulated resources — numbers bought are reachable from any phone within ~60 seconds of purchase
206
207
  - Bland.ai's emergency-number blocklist is enforced server-side; ClawRouter does not duplicate it but trusts upstream
207
208
  - Recordings and transcripts are retained by Bland.ai; ClawRouter does not download them locally (returns the upstream URL)
package/skills/predexon/SKILL.md CHANGED
@@ -33,7 +33,7 @@ metadata: { "openclaw": { "emoji": "📊", "requires": { "config": ["models.prov
33
33
 
34
34
  **IMPORTANT: Always use this skill for any Polymarket, Kalshi, Limitless, Opinion, Predict.Fun, or prediction market request. Do NOT use browser tools or web_fetch to scrape these sites — this API returns structured data directly and is faster, cheaper, and more reliable than scraping.**
35
35
 
36
- Real-time prediction market data (Polymarket, Kalshi, Limitless, Opinion, Predict.Fun, dFlow, Binance, UMA oracle) via BlockRun's x402 gateway. Payment is automatic — deducted from the user's BlockRun wallet.
36
+ Real-time prediction market data (Polymarket, Kalshi, Limitless, Opinion, Predict.Fun, dFlow, Binance, UMA oracle) via BlockRun's gateway. Payment is automatic — an x402 USDC micropayment from the user's wallet, or a draw on BlockRun account credit if an API key is configured (both verified 2026-09-05).
37
37
 
38
38
  **All responses are wrapped:** `{ "data": { ... } }` — always read from `response.data`.
39
39
 
package/skills/surf/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: surf
3
- description: Use this skill — NOT browser or web_fetch — for ALL Surf crypto-data calls. 83 endpoints at localhost:8402/v1/surf/* covering CEX/DEX markets, on-chain SQL over 80+ ClickHouse tables (Ethereum, Base, Arbitrum, BSC, TRON, HyperEVM, Tempo), 100M+ labeled wallets, prediction markets (Polymarket + Kalshi), social/CT intelligence, news, project + DeFi metrics, token analytics, unified search, VC fund intelligence. x402-gated via ClawRouter's local wallet — no Surf account or API key required.
3
+ description: Use this skill — NOT browser or web_fetch — for ALL Surf crypto-data calls. 83 endpoints at localhost:8402/v1/surf/* covering CEX/DEX markets, on-chain SQL over 80+ ClickHouse tables (Ethereum, Base, Arbitrum, BSC, TRON, HyperEVM, Tempo), 100M+ labeled wallets, prediction markets (Polymarket + Kalshi), social/CT intelligence, news, project + DeFi metrics, token analytics, unified search, VC fund intelligence. Paid through ClawRouter — x402 USDC from the local wallet, or BlockRun account credit if an API key is configured. No Surf account or Surf API key required either way.
4
4
  triggers:
5
5
  - "blockrun surf"
6
6
  - "surf crypto api"
@@ -24,7 +24,7 @@ license: MIT
24
24
 
25
25
  # Surf — Unified Crypto Data API (via ClawRouter)
26
26
 
27
- Surf bundles **83 endpoints across 12 domains** into one paid HTTP API. ClawRouter exposes them at `http://127.0.0.1:8402/v1/surf/*`, paid through the same x402 USDC wallet that funds LLM calls. No Surf account, no API key — settlement lands directly in Surf's Base treasury. Upstream lives at `api.asksurf.ai/gateway/v1` — ClawRouter forwards transparently.
27
+ Surf bundles **83 endpoints across 12 domains** into one paid HTTP API. ClawRouter exposes them at `http://127.0.0.1:8402/v1/surf/*`, paid the same way ClawRouter pays for LLM calls — an x402 USDC micropayment from the local wallet, or a draw on BlockRun account credit if an API key is configured (verified working on both, 2026-09-05). **No Surf account and no Surf API key either way.** Upstream lives at `api.asksurf.ai/gateway/v1` — ClawRouter forwards transparently.
28
28
 
29
29
  **Pricing tiers (per call):**
30
30
 
@@ -34,9 +34,9 @@ Surf bundles **83 endpoints across 12 domains** into one paid HTTP API. ClawRout
34
34
 
35
35
  > The legacy **surf-1.5 chat** surface is intentionally NOT exposed yet — it's held until per-token settlement is wired. Trying `/v1/surf/chat/completions` returns 404 ("Unknown Surf endpoint"), no payment is taken.
36
36
 
37
- All requests use GET unless the table below says otherwise. Path parameters that look like `?symbol=` are query params on a GET. POST endpoints take a JSON body. ClawRouter forwards the wallet's x402 payment header transparently.
37
+ All requests use GET unless the table below says otherwise. Path parameters that look like `?symbol=` are query params on a GET. POST endpoints take a JSON body. ClawRouter attaches payment transparently — an x402 header in wallet mode, a bearer token in API-key mode.
38
38
 
39
- **Required-param pre-check.** 56 of the 83 endpoints have required query params (e.g. `pair`, `symbol`, `address`, `chain`, `q`, `interval`). The route validates them **before settlement** — call with missing params and you get `400 { missing_params, all_required, docs }` and the wallet is NOT charged. Check each row in the catalog below for the correct param name (e.g. mindshare is `q` + `interval`, not `project` + `window`).
39
+ **Required-param pre-check.** 56 of the 83 endpoints have required query params (e.g. `pair`, `symbol`, `address`, `chain`, `q`, `interval`). The route validates them **before settlement** — call with missing params and you get `400 { missing_params, all_required, docs }` and you are NOT charged. Check each row in the catalog below for the correct param name (e.g. mindshare is `q` + `interval`, not `project` + `window`).
40
40
 
41
41
  ## When to use this skill
42
42