Skip to content
/ ClawRouter Public

Smart LLM router — save 78% on inference costs. 30+ models, one wallet, x402 micropayments.

311 stars 32 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

BlockRunAI/ClawRouter

BranchesTags

Repository files navigation

ClawRouter

Save 78% on LLM costs. Automatically.

Route every request to the cheapest model that can handle it. One wallet, 30+ models, zero API keys.

npm License: MIT TypeScript Node

Docs · Models · Telegram · X

"What is 2+2?"            → DeepSeek        $0.27/M    saved 99%
"Summarize this article"  → GPT-4o-mini     $0.60/M    saved 99%
"Build a React component" → Claude Sonnet   $15.00/M   best balance
"Prove this theorem"      → o3              $10.00/M   reasoning

Why ClawRouter?

  • 100% local routing — 14-dimension weighted scoring runs on your machine in <1ms
  • Zero external calls — no API calls for routing decisions, ever
  • 30+ models — OpenAI, Anthropic, Google, DeepSeek, xAI through one wallet
  • x402 micropayments — pay per request with USDC on Base, no API keys
  • Open source — MIT licensed, fully inspectable routing logic

Quick Start (2 mins)

# 1. Install — auto-generates a wallet on Base
openclaw plugin install @blockrun/clawrouter

# 2. Fund your wallet with USDC on Base (address printed on install)
#    $5 is enough for thousands of requests

# 3. Enable smart routing
openclaw config set model blockrun/auto

Every request now routes to the cheapest capable model.

Already have a funded wallet? export BLOCKRUN_WALLET_KEY=0x...

Want a specific model? openclaw config set model openai/gpt-4o — still get x402 payments and usage logging.

How Routing Works

100% local, <1ms, zero API calls.

Request → Weighted Scorer (14 dimensions)
              │
              ├── High confidence → Pick model from tier → Done
              │
              └── Low confidence → Default to MEDIUM tier → Done

No external classifier calls. Ambiguous queries default to the MEDIUM tier (DeepSeek/GPT-4o-mini) — fast, cheap, and good enough for most tasks.

14-Dimension Weighted Scoring

Dimension Weight What It Detects
Reasoning markers 0.18 "prove", "theorem", "step by step"
Code presence 0.15 "function", "async", "import", "```"
Simple indicators 0.12 "what is", "define", "translate"
Multi-step patterns 0.12 "first...then", "step 1", numbered lists
Technical terms 0.10 "algorithm", "kubernetes", "distributed"
Token count 0.08 short (<50) vs long (>500) prompts
Creative markers 0.05 "story", "poem", "brainstorm"
Question complexity 0.05 Multiple question marks
Constraint count 0.04 "at most", "O(n)", "maximum"
Imperative verbs 0.03 "build", "create", "implement"
Output format 0.03 "json", "yaml", "schema"
Domain specificity 0.02 "quantum", "fpga", "genomics"
Reference complexity 0.02 "the docs", "the api", "above"
Negation complexity 0.01 "don't", "avoid", "without"

Weighted sum → sigmoid confidence calibration → tier selection.

Tier → Model Mapping

Tier Primary Model Cost/M Savings vs Opus
SIMPLE deepseek-chat $0.27 99.6%
MEDIUM gpt-4o-mini $0.60 99.2%
COMPLEX claude-sonnet-4 $15.00 80%
REASONING o3 $10.00 87%

Special rule: 2+ reasoning markers → REASONING at 0.97 confidence.

Cost Savings (Real Numbers)

Tier % of Traffic Cost/M
SIMPLE ~45% $0.27
MEDIUM ~35% $0.60
COMPLEX ~15% $15.00
REASONING ~5% $10.00
Blended average $3.17/M

Compared to $75/M for Claude Opus = 96% savings on a typical workload.

Models

30+ models across 5 providers, one wallet:

Model Input $/M Output $/M Context Reasoning
OpenAI
gpt-5.2 $1.75 $14.00 400K *
gpt-4o $2.50 $10.00 128K
gpt-4o-mini $0.15 $0.60 128K
o3 $2.00 $8.00 200K *
o3-mini $1.10 $4.40 128K *
Anthropic
claude-opus-4.5 $15.00 $75.00 200K *
claude-sonnet-4 $3.00 $15.00 200K *
claude-haiku-4.5 $1.00 $5.00 200K
Google
gemini-2.5-pro $1.25 $10.00 1M *
gemini-2.5-flash $0.15 $0.60 1M
DeepSeek
deepseek-chat $0.14 $0.28 128K
deepseek-reasoner $0.55 $2.19 128K *
xAI
grok-3 $3.00 $15.00 131K *
grok-3-mini $0.30 $0.50 131K

Full list: src/models.ts

Payment

No account. No API key. Payment IS authentication via x402.

Request → 402 (price: $0.003) → wallet signs USDC → retry → response

USDC stays in your wallet until spent — non-custodial. Price is visible in the 402 header before signing.

Fund your wallet:

  • Coinbase: Buy USDC, send to Base
  • Bridge: Move USDC from any chain to Base
  • CEX: Withdraw USDC to Base network

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Your Application                         │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   ClawRouter (localhost)                     │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐ │
│  │ Weighted Scorer │→ │ Model Selector  │→ │ x402 Signer │ │
│  │  (14 dimensions)│  │ (cheapest tier) │  │   (USDC)    │ │
│  └─────────────────┘  └─────────────────┘  └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      BlockRun API                            │
│         → OpenAI | Anthropic | Google | DeepSeek | xAI      │
└─────────────────────────────────────────────────────────────┘

Routing is client-side — open source and inspectable.

Source Structure

src/
├── index.ts          # Plugin entry point
├── provider.ts       # OpenClaw provider registration
├── proxy.ts          # Local HTTP proxy + x402 payment
├── models.ts         # 30+ model definitions with pricing
├── auth.ts           # Wallet key resolution
├── logger.ts         # JSON usage logging
├── dedup.ts          # Response deduplication (prevents double-charge)
├── payment-cache.ts  # Pre-auth optimization (skips 402 round trip)
├── x402.ts           # EIP-712 USDC payment signing
└── router/
    ├── index.ts      # route() entry point
    ├── rules.ts      # 14-dimension weighted scoring
    ├── selector.ts   # Tier → model selection
    ├── config.ts     # Default routing config
    └── types.ts      # TypeScript types

Configuration

Override Tier Models

# openclaw.yaml
plugins:
  - id: "@blockrun/clawrouter"
    config:
      routing:
        tiers:
          COMPLEX:
            primary: "openai/gpt-4o"
          SIMPLE:
            primary: "google/gemini-2.5-flash"

Override Scoring Weights

routing:
  scoring:
    reasoningKeywords: ["proof", "theorem", "formal verification"]
    codeKeywords: ["function", "class", "async", "await"]

Programmatic Usage

Use without OpenClaw:

import { startProxy } from "@blockrun/clawrouter";

const proxy = await startProxy({
  walletKey: process.env.BLOCKRUN_WALLET_KEY!,
  onReady: (port) => console.log(`Proxy on port ${port}`),
  onRouted: (d) => console.log(`${d.model} saved ${(d.savings * 100).toFixed(0)}%`),
});

// Any OpenAI-compatible client works
const res = await fetch(`${proxy.baseUrl}/v1/chat/completions`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "blockrun/auto",
    messages: [{ role: "user", content: "What is 2+2?" }],
  }),
});

await proxy.close();

Or use the router directly:

import { route, DEFAULT_ROUTING_CONFIG, BLOCKRUN_MODELS } from "@blockrun/clawrouter";

// Build pricing map
const modelPricing = new Map();
for (const m of BLOCKRUN_MODELS) {
  modelPricing.set(m.id, { inputPrice: m.inputPrice, outputPrice: m.outputPrice });
}

const decision = route("Prove sqrt(2) is irrational", undefined, 4096, {
  config: DEFAULT_ROUTING_CONFIG,
  modelPricing,
});

console.log(decision);
// {
//   model: "openai/o3",
//   tier: "REASONING",
//   confidence: 0.97,
//   method: "rules",
//   savings: 0.87,
//   costEstimate: 0.041,
// }

Performance Optimizations (v0.3)

  • SSE heartbeat: Sends headers + heartbeat immediately, preventing upstream timeouts
  • Response dedup: SHA-256 hash → 30s cache, prevents double-charge on retries
  • Payment pre-auth: Caches 402 params, pre-signs USDC, skips 402 round trip (~200ms saved)

Why Not OpenRouter / LiteLLM?

They're built for developers. ClawRouter is built for agents.

OpenRouter / LiteLLM ClawRouter
Setup Human creates account Agent generates wallet
Auth API key (shared secret) Wallet signature (cryptographic)
Payment Prepaid balance (custodial) Per-request (non-custodial)
Routing Proprietary / closed Open source, client-side

Agents shouldn't need a human to paste API keys. They should generate a wallet, receive funds, and pay per request — programmatically.

Development

git clone https://github.com/BlockRunAI/ClawRouter.git
cd ClawRouter
npm install
npm run build
npm run typecheck

# End-to-end tests (requires funded wallet)
BLOCKRUN_WALLET_KEY=0x... npx tsx test-e2e.ts

Roadmap

  • Smart routing — 14-dimension weighted scoring, 4-tier model selection
  • x402 payments — per-request USDC micropayments, non-custodial
  • Response dedup — prevents double-charge on retries
  • Payment pre-auth — skips 402 round trip
  • SSE heartbeat — prevents upstream timeouts
  • Cascade routing — try cheap model first, escalate on low quality
  • Spend controls — daily/monthly budgets
  • Analytics dashboard — cost tracking at blockrun.ai

License

MIT

BlockRun — Pay-per-request AI infrastructure

If ClawRouter saves you money, consider starring the repo.

About

Smart LLM router — save 78% on inference costs. 30+ models, one wallet, x402 micropayments.

Topics

crypto ai gemini openai micropayments ai-agents cost-optimization smart-routing usdc llm anthropic deepseek llm-router x402 openclaw

Resources

Readme
Activity
Custom properties

Stars

311 stars

Watchers

25 watching

Forks

32 forks
Report repository

Releases

2 tags

Packages

No packages published

Languages