diff --git a/.github/workflows/brand-numbers.yml b/.github/workflows/brand-numbers.yml new file mode 100644 index 0000000..c1f63f9 --- /dev/null +++ b/.github/workflows/brand-numbers.yml @@ -0,0 +1,24 @@ +name: Brand numbers + +on: + push: + branches: [main] + pull_request: + workflow_dispatch: + +# Fails when a marketing number in this repo disagrees with brand-numbers.json. +# +# --check is deliberately OFFLINE. It compares against the committed snapshot +# and never fetches, so a blockrun.ai deploy in progress cannot fail this repo's +# CI. Pulling a newer artifact is a separate, deliberate act: +# +# node scripts/sync-brand-numbers.mjs --refresh +jobs: + check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 22 + - run: node scripts/sync-brand-numbers.mjs --check diff --git a/.prettierignore b/.prettierignore index 1a99321..4bd4d4d 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,3 +1,8 @@ dist/ node_modules/ package-lock.json + +# Vendored byte-for-byte from BlockRunAI/blockrun:brand/sync-brand-numbers.mjs. +# Formatting it here would fork the copy from the source and from the other +# repos that carry it, and blockrun CI compares them. +scripts/sync-brand-numbers.mjs diff --git a/CLAUDE.md b/CLAUDE.md index 7c96b06..f4047ec 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,6 +1,6 @@ # XClawRouter -Smart LLM router for autonomous agents. 60+ models. Wallet-based auth. USDC micropayments via x402. +Smart LLM router for autonomous agents. 66 models. Wallet-based auth. USDC micropayments via x402. ## Commands diff --git a/README.md b/README.md index 9c824c1..b75b04a 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@

Agents can't sign up for accounts. Agents can't enter credit cards.
Agents can only sign transactions.

ClawRouter is the only LLM router that lets agents operate independently.

-7 models free, no crypto required. No signup. No API key. No credit card.

+8 models free, no crypto required. No signup. No API key. No credit card.


@@ -34,7 +34,7 @@ Agents can only sign transactions.

-> **ClawRouter** is an open-source smart LLM router that reduces AI API costs by up to 92%. It analyzes each request across 15 dimensions and routes to the cheapest capable model in under 1ms, entirely locally. ClawRouter is the only LLM router built for autonomous AI agents — it uses wallet signatures for authentication (no API keys) and USDC micropayments via the x402 protocol (no credit cards). 60+ models from OpenAI, Anthropic, Google, xAI, DeepSeek, and more. MIT licensed. +> **ClawRouter** is an open-source smart LLM router that reduces AI API costs by 87%. It analyzes each request across 15 dimensions and routes to the cheapest capable model in under 1ms, entirely locally. ClawRouter is the only LLM router built for autonomous AI agents — it uses wallet signatures for authentication (no API keys) and USDC micropayments via the x402 protocol (no credit cards). 66 models from OpenAI, Anthropic, Google, xAI, DeepSeek, and more. MIT licensed. --- @@ -59,16 +59,16 @@ This is the stack that lets agents operate autonomously: **x402 + USDC + local r ## How it compares -| | OpenRouter | LiteLLM | Martian | Portkey | **ClawRouter** | -| ---------------- | ----------------- | ---------------- | ----------------- | ----------------- | ----------------------- | -| **Models** | 200+ | 100+ | Smart routing | Gateway | **60+** | -| **Free tier** | Rate-limited | BYO keys | No | No | **7 models, no signup** | -| **Routing** | Manual selection | Manual selection | Smart (closed) | Observability | **Smart (open source)** | -| **Auth** | Account + API key | Your API keys | Account + API key | Account + API key | **Wallet signature** | -| **Payment** | Credit card | BYO keys | Credit card | $49-499/mo | **USDC per-request** | -| **Runs locally** | No | Yes | No | No | **Yes** | -| **Open source** | No | Yes | No | Partial | **Yes** | -| **Agent-ready** | No | No | No | No | **Yes** | +| | OpenRouter | LiteLLM | Martian | Portkey | **ClawRouter** | +| ---------------- | ----------------- | ---------------- | ----------------- | ----------------- | ---------------------------------------------------------------------- | +| **Models** | 200+ | 100+ | Smart routing | Gateway | **60+** | +| **Free tier** | Rate-limited | BYO keys | No | No | **8 models, no signup** | +| **Routing** | Manual selection | Manual selection | Smart (closed) | Observability | **Smart (open source)** | +| **Auth** | Account + API key | Your API keys | Account + API key | Account + API key | **Wallet signature** | +| **Payment** | Credit card | BYO keys | Credit card | $49-499/mo | **USDC per-request** | +| **Runs locally** | No | Yes | No | No | **Yes** | +| **Open source** | No | Yes | No | Partial | **Yes** | +| **Agent-ready** | No | No | No | No | **Yes** | ✓ Open source · ✓ Smart routing · ✓ Runs locally · ✓ Crypto native · ✓ Agent ready @@ -78,7 +78,7 @@ This is the stack that lets agents operate autonomously: **x402 + USDC + local r ## Quick Start -> **No wallet? 7 models work free out of the box.** Install, run, and pin `free/gpt-oss-120b` (or any of the 7) — no crypto, no signup, no balance required. Add USDC later when you want paid models. +> **No wallet? 8 models work free out of the box.** Install, run, and pin `free/gpt-oss-120b` (or any of the 7) — no crypto, no signup, no balance required. Add USDC later when you want paid models. ### Option A — OpenClaw Agent @@ -223,7 +223,7 @@ Request → Weighted Scorer (15 dimensions) → Tier → Best Model → Response | COMPLEX | gemini-3.1-flash-lite ($0.25/$1.50) | gemini-3.1-pro ($2/$12) | claude-opus-4.6 ($5/$25) | | REASONING | grok-4-1-fast ($0.20/$0.50) | grok-4-1-fast-reasoning ($0.20/$0.50) | claude-sonnet-4.6 ($3/$15) | -**Blended average: $2.05/M** vs $25/M for Claude Opus = **92% savings** +**Blended average: $2.05/M** vs $25/M for Claude Opus = **87% savings** --- @@ -297,7 +297,7 @@ Edit existing images with `/img2img`: ## Models & Pricing -60+ models across 9 providers, one wallet. **Starting at $0.0002/request.** +66 models across 9 providers, one wallet. **Starting at $0.0002/request.** > **💡 "Cost per request"** = estimated cost for a typical chat message (~500 input + 500 output tokens). @@ -382,7 +382,7 @@ Edit existing images with `/img2img`: | openai/gpt-5.2-pro | $21.00 | $168.00 | $0.0945 | 400K | reasoning, tools | | openai/gpt-5.4-pro | $30.00 | $180.00 | $0.1050 | 400K | reasoning, tools | -> **Free tier:** 7 models cost nothing — `/model free` points to gpt-oss-120b, or pick any free model directly (e.g., `/model nemotron-omni` for vision, `/model qwen-coder` for coding, `/model deepseek-v4-flash` for reasoning + 1M context, `/model maverick` for general chat). +> **Free tier:** 8 models cost nothing — `/model free` points to gpt-oss-120b, or pick any free model directly (e.g., `/model nemotron-omni` for vision, `/model qwen-coder` for coding, `/model deepseek-v4-flash` for reasoning + 1M context, `/model maverick` for general chat). > **Best value:** `gpt-5-nano` and `gemini-2.5-flash-lite` deliver strong results at ~$0.0003/request. --- @@ -552,7 +552,7 @@ npm test **The LLM router built for autonomous agents** -You're here. 60+ models, local smart routing, x402 USDC payments — the only stack that lets agents operate independently. +You're here. 66 models, local smart routing, x402 USDC payments — the only stack that lets agents operate independently. `curl -fsSL https://blockrun.ai/XClawRouter-update | bash` @@ -563,7 +563,7 @@ You're here. 60+ models, local smart routing, x402 USDC payments — the only st **BlockRun for Claude Code** -Run Claude Code with 50+ models, no rate limits, no Anthropic account, no phone verification. Pay per request with USDC — your wallet is your identity. +Run Claude Code with 66 models, no rate limits, no Anthropic account, no phone verification. Pay per request with USDC — your wallet is your identity. `curl -fsSL https://blockrun.ai/brcc-install | bash` @@ -606,7 +606,7 @@ ClawRouter is an open-source (MIT licensed) smart LLM router built for autonomou ### How much can ClawRouter save on LLM costs? -ClawRouter's blended average cost is $2.05 per million tokens compared to $25/M for Claude Opus, representing 92% savings. Actual savings depend on your workload — simple queries are routed to free models ($0/request), while complex tasks get premium models. +ClawRouter's blended average cost is $2.05 per million tokens compared to $25/M for Claude Opus, representing 87% savings. Actual savings depend on your workload — simple queries are routed to free models ($0/request), while complex tasks get premium models. ### How does ClawRouter compare to OpenRouter? diff --git a/brand-numbers.json b/brand-numbers.json new file mode 100644 index 0000000..312505d --- /dev/null +++ b/brand-numbers.json @@ -0,0 +1,34 @@ +{ + "$schema": "https://blockrun.ai/brand/numbers.schema.json", + "version": 1, + "models": { + "chatVisible": 66, + "totalVisible": 86, + "free": 8, + "freeWithheld": 17, + "image": 8, + "video": 5, + "music": 1, + "speech": 5, + "soundfx": 1, + "withFallback": 44, + "withFallbackAllEntries": 75 + }, + "clawrouter": { + "dimensions": 15, + "tiers": 4, + "profiles": 4, + "aliases": 202 + }, + "mcp": { + "tools": 19 + }, + "chains": { + "rpc": 40 + }, + "savings": { + "baselineModel": "anthropic/claude-opus-5", + "ecoVsBaselinePct": 98, + "autoVsBaselinePct": 87 + } +} diff --git a/docs/11-free-ai-models-zero-cost-blockrun.md b/docs/11-free-ai-models-zero-cost-blockrun.md index 6c59b8b..441dfcf 100644 --- a/docs/11-free-ai-models-zero-cost-blockrun.md +++ b/docs/11-free-ai-models-zero-cost-blockrun.md @@ -1,5 +1,11 @@ # 11 Free AI Models, Zero Cost: How BlockRun Gives Developers Top-Tier LLMs for Nothing +> **The count in this title is a snapshot.** It was 11 when this was written; the +> published free tier is now 8 — models are withheld from `/v1/models` when a +> provider's terms change, most recently over NVIDIA's prompt-retention policy. +> The URL keeps its original slug so existing links do not break. Current figures: +> [blockrun.ai/brand/numbers.json](https://blockrun.ai/brand/numbers.json). + ## The Cost Problem Nobody Talks About It's 2026. Large language models are table stakes for developers. But here's the uncomfortable truth — **the models you can afford aren't good enough, and the good ones aren't affordable.** @@ -82,7 +88,7 @@ Assume 100 requests per day, distributed roughly as: | ClawRouter ECO mode | ~$1–3 | | Manual free model selection | **$0** | -**ECO mode saves 92%+ compared to Claude Opus alone.** +**ECO mode is 98% cheaper than pinning Claude Opus 5 for every request.** --- diff --git a/docs/anthropic-cost-savings.md b/docs/anthropic-cost-savings.md index d5a9487..dad2f0b 100644 --- a/docs/anthropic-cost-savings.md +++ b/docs/anthropic-cost-savings.md @@ -50,7 +50,7 @@ This is where you're paying for real value: ## The Solution: ClawRouter -[ClawRouter](https://github.com/BlockRunAI/XClawRouter) is an open-source local proxy that sits between your app and 41+ AI models. It saves you money in three ways: **smart routing**, **token optimization**, and **response caching**. +[ClawRouter](https://github.com/BlockRunAI/XClawRouter) is an open-source local proxy that sits between your app and 66 AI models. It saves you money in three ways: **smart routing**, **token optimization**, and **response caching**. ``` ┌─────────────┐ ┌──────────────────────────────┐ ┌──────────────────┐ diff --git a/docs/anthropic-third-party-harness-changes.md b/docs/anthropic-third-party-harness-changes.md index 0bc42c5..b22c421 100644 --- a/docs/anthropic-third-party-harness-changes.md +++ b/docs/anthropic-third-party-harness-changes.md @@ -31,7 +31,7 @@ This is exactly the problem [XClawRouter](https://github.com/BlockRunAI/XClawRou ## XClawRouter: Smart Routing for Agents -XClawRouter is an open-source local proxy that sits between your agent and 55+ LLM models across 9 providers. It analyzes every request across 15 dimensions and routes it to the cheapest model that can handle it — in under 1ms, entirely locally. +XClawRouter is an open-source local proxy that sits between your agent and 66 LLM models across 9 providers. It analyzes every request across 15 dimensions and routes it to the cheapest model that can handle it — in under 1ms, entirely locally. ``` Your Agent → XClawRouter (localhost:8402) → Best model for the job @@ -56,7 +56,7 @@ From 20,000+ production requests: | Free models (trivial tasks) | 12.8% | $0.00 | | Others | 13.8% | varies | -**Result: 81% savings vs. Sonnet-for-everything, 89% vs. Opus-for-everything.** +**Result: 87% cheaper than pinning Claude Opus 5 for every request** — the published figure, priced on a stated workload mix rather than estimated. A typical user running 10K mixed requests/month: @@ -74,7 +74,7 @@ Then point your agent at `http://localhost:8402/v1/` with any OpenAI-compatible - **No API keys to manage** — wallet-based cryptographic auth - **No subscriptions** — pay per request in USDC (Base or Solana) -- **No vendor lock-in** — 55+ models, switch anytime +- **No vendor lock-in** — 66 models, switch anytime - **You control your wallet** — non-custodial, funds never held by a third party - **Budget caps** — set a max spend per session, XClawRouter gracefully downgrades when budget runs low - **Token compression** — 7-layer pipeline reduces token costs by 7–40% before they hit any provider diff --git a/docs/clawrouter-cuts-llm-api-costs-500x.md b/docs/clawrouter-cuts-llm-api-costs-500x.md index fe1bf5d..990c975 100644 --- a/docs/clawrouter-cuts-llm-api-costs-500x.md +++ b/docs/clawrouter-cuts-llm-api-costs-500x.md @@ -135,7 +135,7 @@ Less context repeated = fewer tokens = lower cost. Agents that need to recall ea ### 7. x402 Micropayments — Wallet-Based Budget Control -

Budget limits enforced by physical construction — wallet loaded via Base/Solana, pay per call across 41+ models, balance hits zero and the valve shuts cleanly

+

Budget limits enforced by physical construction — wallet loaded via Base/Solana, pay per call across <!-- br:models.chatVisible -->66<!-- /br:models.chatVisible --> models, balance hits zero and the valve shuts cleanly

XClawRouter pays for inference via [x402](https://x402.org/) USDC micropayments (Base or Solana). You load a wallet. Each inference call costs exactly what it costs. When the wallet runs low, requests stop cleanly. @@ -144,7 +144,7 @@ There is no monthly invoice. There is no 3am email. There is a wallet balance, a **`maxCostPerRun`** — a per-session cost ceiling that stops or downgrades requests once a session exceeds a configured threshold (e.g., `$0.50`). This closes the remaining gap ([#3181](https://github.com/openclaw/openclaw/issues/3181)) where a wallet with sufficient funds can still accumulate within a single run. Two modes: `graceful` (downgrade to cheaper models) and `strict` (hard 429 once the cap is hit). ``` -41+ models. One wallet. Pay per call. +66 models. One wallet. Pay per call. ``` --- diff --git a/docs/clawrouter-vs-openrouter-llm-routing-comparison.md b/docs/clawrouter-vs-openrouter-llm-routing-comparison.md index a7cbe3a..bc09c9d 100644 --- a/docs/clawrouter-vs-openrouter-llm-routing-comparison.md +++ b/docs/clawrouter-vs-openrouter-llm-routing-comparison.md @@ -222,7 +222,7 @@ OpenRouter doesn't always pass through provider-specific features correctly. Ima **Direct provider routing.** XClawRouter routes through BlockRun's API directly to providers — not through a second aggregator. One hop, not two. Provider-specific features work because there's no middleman translating them. -![Guaranteed Feature Parity & Direct Connectivity — Three-panel diagram: Vision (image_url auto-detected → vision-capable models only), Tool Calling (toolCalling flag → agentic models only), Catalog (curated 55+ models with automatic legacy-to-modern redirects). Direct provider routing means no dropped payloads.](./assets/clawrouter-feature-parity-direct-connectivity.png) +![Guaranteed Feature Parity & Direct Connectivity — Three-panel diagram: Vision (image_url auto-detected → vision-capable models only), Tool Calling (toolCalling flag → agentic models only), Catalog (curated 66 models with automatic legacy-to-modern redirects). Direct provider routing means no dropped payloads.](./assets/clawrouter-feature-parity-direct-connectivity.png) --- @@ -240,7 +240,7 @@ When new models launch, OpenRouter's catalog lags. Users configure a model that ### How XClawRouter Solves This -XClawRouter maintains a curated catalog of 55+ models across 9 providers (including 11 free models), updated with each release. Delisted models have automatic redirect aliases: +XClawRouter maintains a curated catalog of 66 models across 9 providers (including 11 free models), updated with each release. Delisted models have automatic redirect aliases: ```typescript // Delisted models redirect automatically @@ -256,22 +256,22 @@ No silent drops. No stale catalog. Models are benchmarked for speed, quality, an ## The Full Comparison -| | OpenRouter | XClawRouter | -| ------------------- | -------------------------------- | ---------------------------------------------- | -| **Authentication** | API key (leak risk) | Wallet signature (no keys) | -| **Payment** | Prepaid balance (custodial) | Per-request USDC (non-custodial) | -| **Routing** | Server-side black box | Local 14-dim classifier, <1ms | -| **Fallback** | Often broken (20+ issues) | 8-deep chains, per-model isolation | -| **Model IDs** | Nested prefixes, mangling bugs | Clean aliases, single format | -| **Cost visibility** | None per-request | Headers + JSONL logs + `/stats` | -| **Empty wallet** | Request fails | Auto-fallback to free tier | -| **Rate limits** | Per-key, shared | Per-wallet, independent | -| **Vision support** | Images sometimes dropped | Auto-detected, vision-only fallback | -| **Tool calling** | Silent failures with some models | Flag-based filtering, guaranteed support | -| **Model catalog** | Laggy, silent drops | Curated 55+ models, redirect aliases | -| **Budget control** | Monthly invoice | Per-session cap (`maxCostPerRun`) | -| **Setup** | Create account, paste key | Agent generates wallet, auto-configured | -| **Average cost** | $25/M tokens (Opus direct) | $2.05/M tokens (auto-routed) = **92% savings** | +| | OpenRouter | XClawRouter | +| ------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------- | +| **Authentication** | API key (leak risk) | Wallet signature (no keys) | +| **Payment** | Prepaid balance (custodial) | Per-request USDC (non-custodial) | +| **Routing** | Server-side black box | Local 14-dim classifier, <1ms | +| **Fallback** | Often broken (20+ issues) | 8-deep chains, per-model isolation | +| **Model IDs** | Nested prefixes, mangling bugs | Clean aliases, single format | +| **Cost visibility** | None per-request | Headers + JSONL logs + `/stats` | +| **Empty wallet** | Request fails | Auto-fallback to free tier | +| **Rate limits** | Per-key, shared | Per-wallet, independent | +| **Vision support** | Images sometimes dropped | Auto-detected, vision-only fallback | +| **Tool calling** | Silent failures with some models | Flag-based filtering, guaranteed support | +| **Model catalog** | Laggy, silent drops | Curated 66 models, redirect aliases | +| **Budget control** | Monthly invoice | Per-session cap (`maxCostPerRun`) | +| **Setup** | Create account, paste key | Agent generates wallet, auto-configured | +| **Average cost** | $25/M tokens (Opus direct) | auto-routed = **87% savings** | ![The Engineering Matrix — Side-by-side feature comparison: OpenRouter vs XClawRouter across Routing, Authentication, Payment, Fallback, Model IDs, Empty Wallet, Vision/Tools, and Average Cost. XClawRouter wins on every dimension.](./assets/clawrouter-engineering-matrix-comparison.png) diff --git a/docs/llm-router-benchmark-46-models-sub-1ms-routing.md b/docs/llm-router-benchmark-46-models-sub-1ms-routing.md index d983778..1062ac4 100644 --- a/docs/llm-router-benchmark-46-models-sub-1ms-routing.md +++ b/docs/llm-router-benchmark-46-models-sub-1ms-routing.md @@ -2,13 +2,18 @@ _March 16, 2026 | BlockRun Engineering_ +> **Numbers in this post are a snapshot from the date above.** They record what was +> measured then and are deliberately not updated — rewriting them would misrepresent +> the benchmark. For current figures see +> [blockrun.ai/brand/numbers.json](https://blockrun.ai/brand/numbers.json). + Last week we ran every model on BlockRun through a real-world latency benchmark — 39 models, same prompts, same payment pipeline, same hardware. No cherry-picked results. No synthetic lab conditions. Just cold, hard numbers from production infrastructure. The results changed how we route requests. ## Why We Did This -BlockRun is an x402 micropayment gateway that sits between your AI agent and 39+ LLM providers. Every request flows through our payment verification layer before hitting the model API. That means our latency numbers include everything a real user experiences: payment auth, provider API call, and response delivery. +BlockRun is an x402 micropayment gateway that sits between your AI agent and 66 LLM providers. Every request flows through our payment verification layer before hitting the model API. That means our latency numbers include everything a real user experiences: payment auth, provider API call, and response delivery. Most benchmarks measure model speed in isolation. We wanted to measure what users actually feel. @@ -131,7 +136,7 @@ Raw benchmark data: [benchmark-results.json](https://github.com/BlockRunAI/XClaw --- -_BlockRun is the x402 micropayment gateway for AI. One wallet, 39+ models, pay-per-request with USDC. [Get started](https://blockrun.ai)_ +_BlockRun is the x402 micropayment gateway for AI. One wallet, 66 models, pay-per-request with USDC. [Get started](https://blockrun.ai)_ --- diff --git a/docs/plans/2026-02-03-smart-routing-design.md b/docs/plans/2026-02-03-smart-routing-design.md index 157f707..f0d9bcf 100644 --- a/docs/plans/2026-02-03-smart-routing-design.md +++ b/docs/plans/2026-02-03-smart-routing-design.md @@ -6,7 +6,7 @@ Simple queries go to Claude Opus at $75/M output tokens when Gemini Flash could handle them at $0.60/M. No cost-aware model selection. -Phase 1 solved API key management (one wallet for 30+ models). Phase 2 solves cost optimization by routing queries to the cheapest capable model. +Phase 1 solved API key management (one wallet for 66 models). Phase 2 solves cost optimization by routing queries to the cheapest capable model. ## Why Client-Side diff --git a/docs/smart-llm-router-14-dimension-classifier.md b/docs/smart-llm-router-14-dimension-classifier.md index f3c34ef..7719268 100644 --- a/docs/smart-llm-router-14-dimension-classifier.md +++ b/docs/smart-llm-router-14-dimension-classifier.md @@ -2,7 +2,12 @@ _March 20, 2026 | BlockRun Engineering_ -When you route AI requests across 55+ models from 8 providers, you can't just pick the cheapest one. You can't just pick the fastest one either. We learned this the hard way. +> **Numbers in this post are a snapshot from the date above.** They record what was +> measured then and are deliberately not updated — rewriting them would misrepresent +> the benchmark. For current figures see +> [blockrun.ai/brand/numbers.json](https://blockrun.ai/brand/numbers.json). + +When you route AI requests across 66 models from 8 providers, you can't just pick the cheapest one. You can't just pick the fastest one either. We learned this the hard way. This is the technical story of how we benchmarked every model on our platform, discovered that speed and intelligence are poorly correlated, and built a production routing system that classifies requests in under 1ms using 14 weighted dimensions with sigmoid confidence calibration. @@ -21,7 +26,7 @@ We needed a system that could classify any request and route it to the optimal m ## Step 1: Benchmarking the Fleet -Before building the router, we needed ground truth. We benchmarked all 55+ models through our production payment pipeline. +Before building the router, we needed ground truth. We benchmarked all 66 models through our production payment pipeline. ### Methodology @@ -312,7 +317,7 @@ We originally designed a two-stage system where low-confidence rules-based class ## Appendix: Full Benchmark Data -Raw data (55+ models, latency, throughput, IQ scores, pricing): [`benchmark-merged.json`](https://github.com/BlockRunAI/XClawRouter/blob/main/benchmark-merged.json) +Raw data (66 models, latency, throughput, IQ scores, pricing): [`benchmark-merged.json`](https://github.com/BlockRunAI/XClawRouter/blob/main/benchmark-merged.json) Routing configuration: [`src/router/config.ts`](https://github.com/BlockRunAI/XClawRouter/blob/main/src/router/config.ts) @@ -320,4 +325,4 @@ Scoring implementation: [`src/router/rules.ts`](https://github.com/BlockRunAI/XC --- -_BlockRun is the x402 micropayment gateway for AI. One wallet, 55+ models, pay-per-request with USDC. [blockrun.ai](https://blockrun.ai)_ +_BlockRun is the x402 micropayment gateway for AI. One wallet, 66 models, pay-per-request with USDC. [blockrun.ai](https://blockrun.ai)_ diff --git a/scripts/sync-brand-numbers.mjs b/scripts/sync-brand-numbers.mjs new file mode 100644 index 0000000..c3717f4 --- /dev/null +++ b/scripts/sync-brand-numbers.mjs @@ -0,0 +1,270 @@ +#!/usr/bin/env node +/** + * Sync marketing numbers from BlockRun's canonical brand artifact. + * + * This file is copied byte-for-byte into every public repo as + * scripts/sync-brand-numbers.mjs. It is a copy rather than an npm package on + * purpose: a package would mean 37 dependency bumps, and several consuming + * repos have no package.json at all. Zero dependencies, plain Node. + * + * node scripts/sync-brand-numbers.mjs rewrite markers in place + * node scripts/sync-brand-numbers.mjs --check exit 1 on drift, write nothing + * node scripts/sync-brand-numbers.mjs --refresh re-fetch the artifact first + * + * --check NEVER touches the network. PR CI must be deterministic and offline: + * if it fetched, a deploy in progress would fail every repo in the org at once. + * Freshness is the fan-out job's problem, not the pull request's. + * + * Markers look like: 66 + * and wrap the WHOLE token, so a badge URL, its alt text and the prose number + * can all regenerate from one key. + */ +import { existsSync, lstatSync, readFileSync, writeFileSync, readdirSync } from "node:fs"; +import { join, relative, extname } from "node:path"; + +const ROOT = process.cwd(); +const SNAPSHOT = join(ROOT, "brand-numbers.json"); +// ORIGIN is tried first because it IS the truth — the mirror can only ever be +// as fresh as the last time someone refreshed it. The mirror exists so a repo +// can still sync while blockrun.ai is down, not to front the origin. +// +// The mirror is awesome-blockrun's own brand-numbers.json: that repo consumes +// the artifact like every other, and its snapshot doubles as the org's copy. +// One file, one role per repo, nothing to keep in step by hand. +const ORIGIN = "https://blockrun.ai/brand/numbers.json"; +const MIRROR = + "https://raw.githubusercontent.com/BlockRunAI/awesome-blockrun/main/brand-numbers.json"; + +const argv = new Set(process.argv.slice(2)); +const check = argv.has("--check"); +const refresh = argv.has("--refresh"); + +const SKIP_DIRS = new Set([ + "node_modules", ".git", "dist", "build", "out", ".next", "coverage", + "vendor", "target", "__pycache__", ".venv", "venv", +]); +// .txt is here for llms.txt, which is a first-class marketing surface: it is +// what agents read to find out what BlockRun serves. Scanning other .txt files +// costs a read and changes nothing — only files with markers are ever written. +const TEXT_EXT = new Set([".md", ".mdx", ".txt"]); + +/* ── 1. numbers ──────────────────────────────────────────────────────────── */ + +async function loadNumbers() { + if (!refresh) { + try { + return JSON.parse(readFileSync(SNAPSHOT, "utf8")); + } catch { + fail( + `no brand-numbers.json in ${ROOT}\n` + + ` run with --refresh once to seed it from ${ORIGIN}`, + ); + } + } + for (const url of [ORIGIN, MIRROR]) { + try { + const res = await fetch(url, { signal: AbortSignal.timeout(10_000) }); + if (!res.ok) continue; + const json = await res.json(); + writeFileSync(SNAPSHOT, `${JSON.stringify(json, null, 2)}\n`); + return json; + } catch { + /* try the next source */ + } + } + fail(`could not refresh from ${MIRROR} or ${ORIGIN}`); +} + +/** Flatten nested numbers into dotted keys, ignoring $comment / rationale prose. */ +function flatten(obj, prefix = "") { + return Object.entries(obj).flatMap(([k, v]) => { + if (k.startsWith("$")) return []; + const key = `${prefix}${k}`; + if (v && typeof v === "object" && !Array.isArray(v)) return flatten(v, `${key}.`); + if (v === null) return []; + return [[key, v]]; + }); +} + +/* ── 2. renderers ────────────────────────────────────────────────────────── */ + +/** + * How a key becomes text. Default is the bare value. + * + * A marker may carry an `@modifier` — `` — which + * selects a renderer without changing which number is looked up. The modifier + * is what makes a key reusable: the same mcp.tools appears as a shields badge + * at the top of a README and as a bare "19 tools" in a table two screens down, + * and one marker still keeps the badge URL, its alt text and the label in step. + * + * Renderers are registered under the FULL marker name so a badge's label is + * written out rather than guessed from the key. + */ +const badge = (label) => (n) => + `${n} ${label}`; + +const RENDER = { + "mcp.tools@badge": badge("tools"), + "models.totalVisible@badge": badge("models"), + "models.chatVisible@badge": badge("models"), +}; +const render = (marker, value) => (RENDER[marker] ?? String)(value); + +/** `mcp.tools@badge` looks up `mcp.tools`. Unmodified markers are unaffected. */ +const keyOf = (marker) => marker.split("@")[0]; + +/* ── 3. marker rewriting ─────────────────────────────────────────────────── */ + +const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); +const OPEN_ANY = //g; +const CLOSE_ANY = //g; + +/** Byte ranges of fenced code blocks — markers inside them are documentation. */ +function fencedRanges(text) { + const ranges = []; + const fence = /^(\s*)(`{3,}|~{3,})[^\n]*$/gm; + let open = null; + for (let m; (m = fence.exec(text)); ) { + if (open === null) open = m.index; + else { + ranges.push([open, m.index + m[0].length]); + open = null; + } + } + return ranges; +} + +function syncFile(file, numbers, problems) { + const before = readFileSync(file, "utf8"); + const rel = relative(ROOT, file); + const fenced = fencedRanges(before); + const inFence = (i) => fenced.some(([a, b]) => i >= a && i < b); + const known = new Map(numbers); + const used = new Set(); + + // Markers actually present, so a file is only ever rewritten for what it uses + // and an @modifier is carried through to the renderer verbatim. + const markers = new Set(); + // A marker naming a key that does not exist is an error, never a silent + // no-op: a typo'd marker would otherwise sit there looking synced forever. + for (const [re, shown] of [ + [OPEN_ANY, (n) => ``], + [CLOSE_ANY, (n) => ``], + ]) { + for (const m of before.matchAll(re)) { + if (inFence(m.index)) continue; + markers.add(m[1]); + if (!known.has(keyOf(m[1]))) problems.push(`${rel}: unknown key ${shown(m[1])}`); + } + } + + let after = before; + for (const marker of markers) { + const key = keyOf(marker); + if (!known.has(key)) continue; + const value = known.get(key); + const pair = new RegExp( + `()([\\s\\S]*?)()`, + "g", + ); + after = after.replace(pair, (whole, open, inner, close, offset) => { + if (inFence(offset)) return whole; + // Nesting means the closing tag of an inner marker would be consumed by + // the outer one. Refuse rather than produce mangled output. + if (/`, "g"))] + .filter((m) => !inFence(m.index)).length; + const closes = [...before.matchAll(new RegExp(``, "g"))] + .filter((m) => !inFence(m.index)).length; + if (opens !== closes) problems.push(`${rel}: unbalanced marker br:${marker} (${opens} open, ${closes} close)`); + } + + return { before, after, changed: before !== after, used }; +} + +/* ── 4. walk ─────────────────────────────────────────────────────────────── */ + +function* walk(dir) { + for (const name of readdirSync(dir)) { + if (SKIP_DIRS.has(name)) continue; + const p = join(dir, name); + // lstat, not stat: a symlinked directory is reached by its real path or not + // at all. blockrun's docs/ -> awesome-blockrun/docs is exactly the case that + // matters — following it would edit a submodule's files behind the skip + // below, and a link pointing at an ancestor would recurse forever. + const s = lstatSync(p); + if (s.isSymbolicLink()) continue; + if (s.isDirectory()) { + // A nested repo is a submodule or vendored checkout: it carries its own + // brand-numbers.json and syncs itself. Rewriting its markers from THIS + // repo's snapshot would dirty a submodule nobody asked us to touch, and + // would report drift that belongs to another repo's CI. + if (existsSync(join(p, ".git"))) continue; + yield* walk(p); + } else if (TEXT_EXT.has(extname(name))) yield p; + } +} + +function fail(msg) { + console.error(`brand-numbers: ${msg}`); + process.exit(1); +} + +/* ── 5. run ──────────────────────────────────────────────────────────────── */ + +const raw = await loadNumbers(); +const numbers = flatten(raw); +const problems = []; +const drifted = []; +const everUsed = new Set(); + +for (const file of walk(ROOT)) { + const { before, after, changed, used } = syncFile(file, numbers, problems); + used.forEach((k) => everUsed.add(k)); + if (!changed) continue; + drifted.push({ file: relative(ROOT, file), before, after }); + if (!check) writeFileSync(file, after); +} + +if (problems.length) { + for (const p of problems) console.error(` ${p}`); + fail(`${problems.length} marker problem(s)`); +} + +if (check) { + if (drifted.length === 0) { + console.log(`brand-numbers: up to date (${everUsed.size} keys in use)`); + process.exit(0); + } + console.error("brand-numbers: these files disagree with brand-numbers.json\n"); + for (const { file, before, after } of drifted) { + const b = before.split("\n"); + const a = after.split("\n"); + for (let i = 0; i < Math.max(b.length, a.length); i++) { + if (b[i] !== a[i]) { + console.error(` ${file}:${i + 1}`); + console.error(` - ${(b[i] ?? "").trim()}`); + console.error(` + ${(a[i] ?? "").trim()}`); + } + } + } + console.error( + "\n fix with: node scripts/sync-brand-numbers.mjs && git commit -am 'chore: sync brand numbers'", + ); + process.exit(1); +} + +console.log( + drifted.length + ? `brand-numbers: updated ${drifted.length} file(s)` + : `brand-numbers: already up to date (${everUsed.size} keys in use)`, +); diff --git a/skills/xclawrouter/SKILL.md b/skills/xclawrouter/SKILL.md index 1cca5b0..eae1584 100644 --- a/skills/xclawrouter/SKILL.md +++ b/skills/xclawrouter/SKILL.md @@ -1,6 +1,6 @@ --- name: xclawrouter -description: Smart LLM router for OKX — agentic wallet, 55+ models, x402 micropayments on Base + Solana. Routes every request to the cheapest capable model. 11 free NVIDIA models included. +description: Smart LLM router for OKX — agentic wallet, 66 models, x402 micropayments on Base + Solana. Routes every request to the cheapest capable model. 11 free NVIDIA models included. triggers: - "xclawrouter" - "x claw router" @@ -19,7 +19,7 @@ metadata: { "openclaw": { "emoji": "🦀", "requires": { "config": ["models.prov # XClawRouter -Smart LLM router that saves 67% on inference costs by routing each request to the cheapest model that can handle it. 55+ models across 9 providers (11 free NVIDIA models), all through one wallet. +Smart LLM router that saves 87% on inference costs by routing each request to the cheapest model that can handle it. 66 models across 9 providers (11 free NVIDIA models), all through one wallet. ## Install @@ -41,16 +41,21 @@ openclaw models set openai/gpt-4o XClawRouter classifies each request into one of four tiers: -- **SIMPLE** (40% of traffic) — factual lookups, greetings, translations → Gemini Flash ($0.60/M, 99% savings) -- **MEDIUM** (30%) — summaries, explanations, data extraction → DeepSeek Chat ($0.42/M, 99% savings) -- **COMPLEX** (20%) — code generation, multi-step analysis → Claude Opus ($75/M, best quality) -- **REASONING** (10%) — proofs, formal logic, multi-step math → o3 ($8/M, 89% savings) +- **SIMPLE** — factual lookups, greetings, translations → gemini-2.5-flash ($0.30/$2.50) +- **MEDIUM** — summaries, explanations, data extraction → kimi-k2.7 ($0.95/$4.00) +- **COMPLEX** — code generation, multi-step analysis → gemini-3.1-pro ($2/$12) +- **REASONING** — proofs, formal logic, multi-step math → grok-4-1-fast-reasoning ($0.20/$0.50) + +Prices are per 1M input/output tokens on the default `auto` profile. Per-tier +savings percentages are deliberately not quoted: the published figure is blended +across a stated workload mix, and a per-tier number invites comparison against a +baseline nobody wrote down. Rules handle ~~80% of requests in <1ms. Only ambiguous queries hit the LLM classifier (~~$0.00003 per classification). ## Available Models -55+ models including: gpt-5.5, gpt-5.4, gpt-4o, o3, claude-opus-4.8, claude-opus-4.7, claude-sonnet-4.6, gemini-3.1-pro, gemini-3.5-flash, deepseek-v4-pro, deepseek-chat, grok-4.3, grok-build-0.1, kimi-k2.6, kimi-k2.5, and free NVIDIA-hosted models (gpt-oss-120b [default], gpt-oss-20b, deepseek-v4-flash, qwen3-coder-480b, llama-4-maverick, nemotron-3-nano-omni-30b-a3b-reasoning [vision]). +66 models including: gpt-5.5, gpt-5.4, gpt-4o, o3, claude-opus-4.8, claude-opus-4.7, claude-sonnet-4.6, gemini-3.1-pro, gemini-3.5-flash, deepseek-v4-pro, deepseek-chat, grok-4.3, grok-build-0.1, kimi-k2.6, kimi-k2.5, and free NVIDIA-hosted models (gpt-oss-120b [default], gpt-oss-20b, deepseek-v4-flash, qwen3-coder-480b, llama-4-maverick, nemotron-3-nano-omni-30b-a3b-reasoning [vision]). ## Example Output