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 -->76<!-- /br:models.chatVisible --> models. Wallet-based auth. USDC micropayments via x402.
Smart LLM router for autonomous agents. <!-- br:models.chatVisible -->78<!-- /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 @@ -5,8 +5,8 @@
<h1>The LLM router built for autonomous agents</h1>

<p>Use one BlockRun account API key or let an agent settle each request over x402.<br><br>
<strong>Local smart routing across <!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> models.</strong><br><br>
<em><!-- br:models.free -->7<!-- /br:models.free --> models free, no crypto required.</em></p>
<strong>Local smart routing across <!-- br:models.chatVisible -->78<!-- /br:models.chatVisible --> models.</strong><br><br>
<em><!-- br:models.free -->6<!-- /br:models.free --> models free, no crypto required.</em></p>

<br>

Expand All @@ -33,7 +33,7 @@

</div>

> **XClawRouter** is an open-source smart LLM router that reduces AI API costs by <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->%. It analyzes each request across 15 dimensions and routes locally to the cheapest capable model in under 1ms. Use a BlockRun account API key with prepaid credit, or settle requests with USDC over x402 on Solana or Base. <!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> models from OpenAI, Anthropic, Google, xAI, DeepSeek, and more. MIT licensed.
> **XClawRouter** is an open-source smart LLM router that reduces AI API costs by <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->%. It analyzes each request across 15 dimensions and routes locally to the cheapest capable model in under 1ms. Use a BlockRun account API key with prepaid credit, or settle requests with USDC over x402 on Solana or Base. <!-- br:models.chatVisible -->78<!-- /br:models.chatVisible --> models from OpenAI, Anthropic, Google, xAI, DeepSeek, and more. MIT licensed.

---

Expand All @@ -57,7 +57,7 @@ Both modes use the same local router and model IDs.
| | OpenRouter | LiteLLM | Martian | Portkey | **ClawRouter** |
| ---------------- | ----------------- | ---------------- | ----------------- | ----------------- | ---------------------------------------------------------------------- |
| **Models** | 200+ | 100+ | Smart routing | Gateway | **60+** |
| **Free tier** | Rate-limited | BYO keys | No | No | **<!-- br:models.free -->7<!-- /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 | **BlockRun API key or wallet signature** |
| **Payment** | Credit card | BYO keys | Credit card | $49-499/mo | **Account credit or USDC per-request** |
Expand Down Expand Up @@ -294,7 +294,7 @@ Edit existing images with `/img2img`:

## Models & Pricing

<!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> models across 9 providers, one BlockRun API key or x402 wallet. **Starting at $0.0002/request.**
<!-- br:models.chatVisible -->78<!-- /br:models.chatVisible --> models across 9 providers, one BlockRun API key or x402 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 @@ -380,7 +380,7 @@ Edit existing images with `/img2img`:
| anthropic/claude-fable-5 | $10.00 | $50.00 | $0.0300 | 1M | reasoning, vision, agentic, tools |
| openai/gpt-5.5-pro | $30.00 | $180.00 | $0.1020 | 1M | reasoning, vision, tools |

> **Free tier:** <!-- br:models.free -->7<!-- /br:models.free --> models cost nothing — `/model free` points to nemotron-3.5-lightning, or pick any free model directly (e.g., `/model nemotron-omni` for vision, `/model north-mini-code` for coding, `/model nemotron-3-ultra-550b` for reasoning + 1M context).
> **Free tier:** <!-- br:models.free -->6<!-- /br:models.free --> models cost nothing — `/model free` points to nemotron-3.5-lightning, or pick any free model directly (e.g., `/model nemotron-omni` for vision, `/model north-mini-code` for coding, `/model nemotron-3-ultra-550b` for reasoning + 1M context).
> **Best value:** `xiaomi/mimo-v2.5`, `qwen/qwen3.8-flash` and `zai/glm-5.3-flash` deliver strong results at ~$0.0003/request.

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

**The LLM router built for autonomous agents**

You're here. <!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> models, local smart routing, x402 USDC payments — the only stack that lets agents operate independently.
You're here. <!-- br:models.chatVisible -->78<!-- /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 @@ -565,7 +565,7 @@ You're here. <!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> mod

**BlockRun for Claude Code**

Run Claude Code with <!-- br:models.chatVisible -->76<!-- /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 -->78<!-- /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
12 changes: 6 additions & 6 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": 76,
"totalVisible": 100,
"free": 7,
"freeWithheld": 26,
"chatVisible": 78,
"totalVisible": 102,
"free": 6,
"freeWithheld": 27,
"image": 9,
"video": 8,
"music": 1,
"speech": 5,
"soundfx": 1,
"withFallback": 34,
"withFallbackAllEntries": 73
"withFallback": 33,
"withFallbackAllEntries": 74
},
"clawrouter": {
"dimensions": 15,
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 -->76<!-- /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 -->78<!-- /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 -->76<!-- /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 -->78<!-- /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 -->76<!-- /br:models.chatVisible --> models, switch anytime
- **No vendor lock-in** — <!-- br:models.chatVisible -->78<!-- /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 -->76<!-- /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 -->78<!-- /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 -->76<!-- /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 -->78<!-- /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 -->76<!-- /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 -->78<!-- /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 -->76<!-- /br:models.chatVisible --> models, redirect aliases |
| **Model catalog** | Laggy, silent drops | Curated <!-- br:models.chatVisible -->78<!-- /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 -->84<!-- /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 -->76<!-- /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 -->78<!-- /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 -->76<!-- /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 -->78<!-- /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 -->76<!-- /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 -->78<!-- /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 -->76<!-- /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 -->78<!-- /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 -->76<!-- /br:models.chatVisible --> models through our production payment pipeline.
Before building the router, we needed ground truth. We benchmarked all <!-- br:models.chatVisible -->78<!-- /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 -->76<!-- /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 -->78<!-- /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 -->76<!-- /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 -->78<!-- /br:models.chatVisible --> models, pay-per-request with USDC. [blockrun.ai](https://blockrun.ai)_
Loading
Loading