Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# XClawRouter

Smart LLM router for autonomous agents. <!-- br:models.chatVisible -->66<!-- /br:models.chatVisible --> models. Wallet-based auth. USDC micropayments via x402.
Smart LLM router for autonomous agents. <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> models. Wallet-based auth. USDC micropayments via x402.

## Commands

Expand Down
16 changes: 8 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
<p>Agents can't sign up for accounts. Agents can't enter credit cards.<br>
Agents can only sign transactions.<br><br>
<strong>ClawRouter is the only LLM router that lets agents operate independently.</strong><br><br>
<em><!-- br:models.free -->8<!-- /br:models.free --> models free, no crypto required. No signup. No API key. No credit card.</em></p>
<em><!-- br:models.free -->6<!-- /br:models.free --> models free, no crypto required. No signup. No API key. No credit card.</em></p>

<br>

Expand All @@ -34,7 +34,7 @@ Agents can only sign transactions.<br><br>

</div>

> **ClawRouter** is an open-source smart LLM router that reduces AI API costs by <!-- br:savings.autoVsBaselinePct -->87<!-- /br:savings.autoVsBaselinePct -->%. 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). <!-- br:models.chatVisible -->66<!-- /br:models.chatVisible --> 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 <!-- br:savings.autoVsBaselinePct -->87<!-- /br:savings.autoVsBaselinePct -->%. 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). <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> models from OpenAI, Anthropic, Google, xAI, DeepSeek, and more. MIT licensed.

---

Expand Down Expand Up @@ -62,7 +62,7 @@ This is the stack that lets agents operate autonomously: **x402 + USDC + local r
| | OpenRouter | LiteLLM | Martian | Portkey | **ClawRouter** |
| ---------------- | ----------------- | ---------------- | ----------------- | ----------------- | ---------------------------------------------------------------------- |
| **Models** | 200+ | 100+ | Smart routing | Gateway | **60+** |
| **Free tier** | Rate-limited | BYO keys | No | No | **<!-- br:models.free -->8<!-- /br:models.free --> models, no signup** |
| **Free tier** | Rate-limited | BYO keys | No | No | **<!-- br:models.free -->6<!-- /br:models.free --> 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** |
Expand All @@ -78,7 +78,7 @@ This is the stack that lets agents operate autonomously: **x402 + USDC + local r

## Quick Start

> **No wallet? <!-- br:models.free -->8<!-- /br:models.free --> 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? <!-- br:models.free -->6<!-- /br:models.free --> 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

Expand Down Expand Up @@ -297,7 +297,7 @@ Edit existing images with `/img2img`:

## Models & Pricing

<!-- br:models.chatVisible -->66<!-- /br:models.chatVisible --> models across 9 providers, one wallet. **Starting at $0.0002/request.**
<!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> 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).

Expand Down Expand Up @@ -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:** <!-- br:models.free -->8<!-- /br:models.free --> 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:** <!-- br:models.free -->6<!-- /br:models.free --> 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.

---
Expand Down Expand Up @@ -552,7 +552,7 @@ npm test

**The LLM router built for autonomous agents**

You're here. <!-- br:models.chatVisible -->66<!-- /br:models.chatVisible --> models, local smart routing, x402 USDC payments — the only stack that lets agents operate independently.
You're here. <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> models, local smart routing, x402 USDC payments — the only stack that lets agents operate independently.

`curl -fsSL https://blockrun.ai/XClawRouter-update | bash`

Expand All @@ -563,7 +563,7 @@ You're here. <!-- br:models.chatVisible -->66<!-- /br:models.chatVisible --> mod

**BlockRun for Claude Code**

Run Claude Code with <!-- br:models.chatVisible -->66<!-- /br:models.chatVisible --> models, no rate limits, no Anthropic account, no phone verification. Pay per request with USDC — your wallet is your identity.
Run Claude Code with <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> 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`

Expand Down
16 changes: 8 additions & 8 deletions brand-numbers.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,17 @@
"$schema": "https://blockrun.ai/brand/numbers.schema.json",
"version": 1,
"models": {
"chatVisible": 66,
"totalVisible": 86,
"free": 8,
"freeWithheld": 17,
"image": 8,
"chatVisible": 71,
"totalVisible": 92,
"free": 6,
"freeWithheld": 19,
"image": 9,
"video": 5,
"music": 1,
"speech": 5,
"soundfx": 1,
"withFallback": 44,
"withFallbackAllEntries": 75
"withFallback": 46,
"withFallbackAllEntries": 79
},
"clawrouter": {
"dimensions": 15,
Expand All @@ -21,7 +21,7 @@
"aliases": 202
},
"mcp": {
"tools": 19
"tools": 20
},
"chains": {
"rpc": 40
Expand Down
2 changes: 1 addition & 1 deletion docs/anthropic-cost-savings.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <!-- br:models.chatVisible -->66<!-- /br:models.chatVisible --> 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 <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> AI models. It saves you money in three ways: **smart routing**, **token optimization**, and **response caching**.

```
┌─────────────┐ ┌──────────────────────────────┐ ┌──────────────────┐
Expand Down
4 changes: 2 additions & 2 deletions docs/anthropic-third-party-harness-changes.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <!-- br:models.chatVisible -->66<!-- /br:models.chatVisible --> 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 <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> 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
Expand Down Expand Up @@ -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** — <!-- br:models.chatVisible -->66<!-- /br:models.chatVisible --> models, switch anytime
- **No vendor lock-in** — <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> 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
Expand Down
2 changes: 1 addition & 1 deletion docs/clawrouter-cuts-llm-api-costs-500x.md
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ Less context repeated = fewer tokens = lower cost. Agents that need to recall ea

### 7. x402 Micropayments — Wallet-Based Budget Control

<p align="center"><img src="assets/blockrun-clawrouter-x402-usdc-micropayment-wallet-budget-control.png" alt="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" width="720"></p>
<p align="center"><img src="assets/blockrun-clawrouter-x402-usdc-micropayment-wallet-budget-control.png" alt="Budget limits enforced by physical construction — wallet loaded via Base/Solana, pay per call across <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> models, balance hits zero and the valve shuts cleanly" width="720"></p>

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.

Expand Down
6 changes: 3 additions & 3 deletions docs/clawrouter-vs-openrouter-llm-routing-comparison.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <!-- br:models.chatVisible -->66<!-- /br:models.chatVisible --> 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 <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> models with automatic legacy-to-modern redirects). Direct provider routing means no dropped payloads.](./assets/clawrouter-feature-parity-direct-connectivity.png)

---

Expand All @@ -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 <!-- br:models.chatVisible -->66<!-- /br:models.chatVisible --> models across 9 providers (including 11 free models), updated with each release. Delisted models have automatic redirect aliases:
XClawRouter maintains a curated catalog of <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> models across 9 providers (including 11 free models), updated with each release. Delisted models have automatic redirect aliases:

```typescript
// Delisted models redirect automatically
Expand Down Expand Up @@ -268,7 +268,7 @@ No silent drops. No stale catalog. Models are benchmarked for speed, quality, an
| **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 <!-- br:models.chatVisible -->66<!-- /br:models.chatVisible --> models, redirect aliases |
| **Model catalog** | Laggy, silent drops | Curated <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> 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 = **<!-- br:savings.autoVsBaselinePct -->87<!-- /br:savings.autoVsBaselinePct -->% savings** |
Expand Down
4 changes: 2 additions & 2 deletions docs/llm-router-benchmark-46-models-sub-1ms-routing.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ The results changed how we route requests.

## Why We Did This

BlockRun is an x402 micropayment gateway that sits between your AI agent and <!-- br:models.chatVisible -->66<!-- /br:models.chatVisible --> 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 <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> 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.

Expand Down Expand Up @@ -136,7 +136,7 @@ Raw benchmark data: [benchmark-results.json](https://github.com/BlockRunAI/XClaw

---

_BlockRun is the x402 micropayment gateway for AI. One wallet, <!-- br:models.chatVisible -->66<!-- /br:models.chatVisible --> models, pay-per-request with USDC. [Get started](https://blockrun.ai)_
_BlockRun is the x402 micropayment gateway for AI. One wallet, <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> models, pay-per-request with USDC. [Get started](https://blockrun.ai)_

---

Expand Down
2 changes: 1 addition & 1 deletion docs/plans/2026-02-03-smart-routing-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <!-- br:models.chatVisible -->66<!-- /br:models.chatVisible --> models). Phase 2 solves cost optimization by routing queries to the cheapest capable model.
Phase 1 solved API key management (one wallet for <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> models). Phase 2 solves cost optimization by routing queries to the cheapest capable model.

## Why Client-Side

Expand Down
8 changes: 4 additions & 4 deletions docs/smart-llm-router-14-dimension-classifier.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ _March 20, 2026 | BlockRun Engineering_
> the benchmark. For current figures see
> [blockrun.ai/brand/numbers.json](https://blockrun.ai/brand/numbers.json).

When you route AI requests across <!-- br:models.chatVisible -->66<!-- /br:models.chatVisible --> 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.
When you route AI requests across <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> 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.

Expand All @@ -26,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 <!-- br:models.chatVisible -->66<!-- /br:models.chatVisible --> models through our production payment pipeline.
Before building the router, we needed ground truth. We benchmarked all <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> models through our production payment pipeline.

### Methodology

Expand Down Expand Up @@ -317,12 +317,12 @@ We originally designed a two-stage system where low-confidence rules-based class

## Appendix: Full Benchmark Data

Raw data (<!-- br:models.chatVisible -->66<!-- /br:models.chatVisible --> models, latency, throughput, IQ scores, pricing): [`benchmark-merged.json`](https://github.com/BlockRunAI/XClawRouter/blob/main/benchmark-merged.json)
Raw data (<!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> 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)

Scoring implementation: [`src/router/rules.ts`](https://github.com/BlockRunAI/XClawRouter/blob/main/src/router/rules.ts)

---

_BlockRun is the x402 micropayment gateway for AI. One wallet, <!-- br:models.chatVisible -->66<!-- /br:models.chatVisible --> models, pay-per-request with USDC. [blockrun.ai](https://blockrun.ai)_
_BlockRun is the x402 micropayment gateway for AI. One wallet, <!-- br:models.chatVisible -->71<!-- /br:models.chatVisible --> models, pay-per-request with USDC. [blockrun.ai](https://blockrun.ai)_
Loading
Loading