Skip to content

Latest commit

 

History

878 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

ClawRouter Banner

The LLM router built for autonomous agents

Use one BlockRun account API key or let an agent settle each request over x402.

Local smart routing across 76 models.

7 models free, no crypto required.


7 free models  Agent native  Account API keys  Local routing  x402 USDC  Open source

npm version npm downloads GitHub stars CI TypeScript License: MIT

USDC Hackathon Winner x402 Protocol Solana Base Network OpenClaw Plugin Telegram

XClawRouter is an open-source smart LLM router that reduces AI API costs by 84%. 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. 76 models from OpenAI, Anthropic, Google, xAI, DeepSeek, and more. MIT licensed.


Why ClawRouter exists

XClawRouter supports both teams that want a familiar account API and agents that pay autonomously:

  • Starts at $0 — 7 NVIDIA models are free forever (incl. 1M-context DeepSeek V4 + a vision-capable Nemotron Omni)
  • One account API key — prepaid BlockRun credit across supported products
  • Optional x402 wallet — the wallet signature is authentication
  • No model selection — 15-dimension scoring picks the right model automatically
  • No credit cards — agents pay per-request with USDC via x402
  • No trust required — runs locally, <1ms routing, zero external dependencies

Both modes use the same local router and model IDs.


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 BlockRun API key or wallet signature
Payment Credit card BYO keys Credit card $49-499/mo Account credit or 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

We're the only one that checks all five boxes.


Quick Start

Recommended: create a BlockRun account, create an API key, and add credits. Export the key as BLOCKRUN_API_KEY; XClawRouter will use it instead of a wallet.

Option A — OpenClaw Agent

OpenClaw is an AI coding agent. If you're using it, XClawRouter installs as a plugin. Three install paths — pick whichever fits:

1. One-liner (recommended) — installs the plugin, bootstraps onchainos, and points you at the wallet login command:

curl -fsSL https://blockrun.ai/XClawRouter-update | bash
export BLOCKRUN_API_KEY=brk_...
openclaw gateway restart

2. Manual via OpenClaw plugin manager — if you want to see each step:

openclaw plugins install @blockrun/xclawrouter
openclaw plugins enable xclawrouter    # add to plugins.allow so the gateway loads it
export BLOCKRUN_API_KEY=brk_...
openclaw gateway restart

3. Global npm install — same effect as #2, useful for CI or pinned deployments:

npm install -g @blockrun/xclawrouter
openclaw plugins enable xclawrouter    # add to plugins.allow so the gateway loads it
export BLOCKRUN_API_KEY=brk_...
openclaw gateway restart

For x402 instead, omit BLOCKRUN_API_KEY and run npx @blockrun/xclawrouter setup to connect an OKX Agentic Wallet. Local wallet users can choose Solana before Base.

Done. Smart routing (blockrun/auto) is now your default model.

Option B — Standalone (continue.dev, Cursor, VS Code, any OpenAI-compatible client)

Using Claude Code? Check out BRCC — it's purpose-built for Claude Code with the same smart routing and x402 payments.

No OpenClaw required. XClawRouter runs as a local proxy on port 8402.

1. Start the proxy

export BLOCKRUN_API_KEY=brk_...
npx @blockrun/xclawrouter

2. Fund your account or wallet

Account users add prepaid credit at user.blockrun.ai/dashboard/credits. For x402, fund USDC on Solana or Base. To stay at $0, pin a free model such as free/nemotron-3.5-lightning.

3. Point your client at http://localhost:8402

continue.dev~/.continue/config.yaml

Important: apiBase must end with /v1/ (including the trailing slash). Without it, continue.dev constructs the URL as /chat/completions instead of /v1/chat/completions, and the proxy returns 404.

models:
  - name: ClawRouter Auto
    provider: openai
    model: blockrun/auto
    apiBase: http://localhost:8402/v1/
    apiKey: x402
    roles:
      - chat
      - edit
      - apply

To pin a specific model, replace blockrun/auto with any model from blockrun.ai/models, e.g. anthropic/claude-opus-5, xai/grok-4.5.

Both provider: openai and provider: clawrouter work — just make sure apiBase ends with /v1/.

Legacy JSON format (~/.continue/config.json)
{
  "models": [
    {
      "title": "ClawRouter Auto",
      "provider": "openai",
      "model": "blockrun/auto",
      "apiBase": "http://localhost:8402/v1/",
      "apiKey": "x402"
    }
  ]
}
Cursor — Settings → Models → OpenAI-compatible

Set base URL to http://localhost:8402, API key to x402, model to blockrun/auto.

Any OpenAI SDK
from openai import OpenAI
client = OpenAI(base_url="http://localhost:8402", api_key="x402")
response = client.chat.completions.create(model="blockrun/auto", messages=[...])

Routing Profiles

Choose your routing strategy with /model <profile>:

Profile Strategy Savings Best For
/model free Free NVIDIA models 100% $0 balance, learning
/model auto Balanced (default) 74-100% General use
/model eco Cheapest possible 95-100% Maximum savings
/model premium Best quality 0% Mission-critical

Shortcuts: /model grok, /model br-sonnet, /model gpt5, /model o3


How It Works

100% local routing. <1ms latency. Zero external API calls.

Request → Weighted Scorer (15 dimensions) → Tier → Best Model → Response
Tier ECO Model AUTO Model PREMIUM Model
SIMPLE free/nemotron-3.5-lightning (FREE) gemini-2.5-flash ($0.3/$2.5) kimi-k3 ($3/$15)
MEDIUM gemini-3.1-flash-lite ($0.25/$1.5) kimi-k3 ($3/$15) gpt-5.3-codex ($1.75/$14)
COMPLEX gemini-3.1-flash-lite ($0.25/$1.5) gemini-3.1-pro ($2/$12) claude-opus-4.8 ($5/$25)
REASONING deepseek-reasoner ($0.14/$0.28) deepseek-reasoner ($0.14/$0.28) claude-sonnet-4.6 ($3/$15)

Blended average: $2.05/M vs $25/M for Claude Opus = 84% savings


Image Generation

Generate images directly from chat with /imagegen:

/imagegen a dog dancing on the beach
/imagegen --model dall-e-3 a futuristic city at sunset
/imagegen --model banana-pro --size 2048x2048 mountain landscape
Model Provider Price Max Size
nano-banana Google Gemini Flash $0.05/image 1024x1024
banana-pro Google Gemini Pro $0.10/image 4096x4096
dall-e-3 OpenAI DALL-E 3 $0.04/image 1792x1024
gpt-image OpenAI GPT Image 1 $0.02/image 1536x1024
flux Black Forest Flux 1.1 $0.04/image 1024x1024
xai/grok-imagine-image xAI Grok Imagine $0.02/image 1024x1024
xai/grok-imagine-image-pro xAI Grok Imagine Pro $0.07/image 1024x1024
zai/cogview-4 Zhipu CogView-4 $0.015/image 1440x1440

Video Generation

Generate short AI videos directly from chat with /videogen:

/videogen a red apple slowly spinning
/videogen --model seedance-2-fast --duration=5 a cat waving
/videogen --model grok-video a neon city at night

Or drive it over HTTP — ClawRouter proxies the BlockRun gateway, handles x402 payment, and downloads the returned MP4 to local disk, rewriting url to http://localhost:8402/videos/<file>.mp4 so the asset survives past the upstream's temporary bucket.

curl -X POST http://localhost:8402/v1/videos/generations \
  -H "Content-Type: application/json" \
  -d '{"model":"bytedance/seedance-2.0-fast","prompt":"a red apple slowly spinning","duration_seconds":5}'
Model Provider Price Duration
bytedance/seedance-1.5-pro ByteDance Seedance $0.03/sec 5s default, up to 10s
bytedance/seedance-2.0-fast ByteDance Seedance $0.15/sec 5s default, up to 10s
bytedance/seedance-2.0 ByteDance Seedance $0.30/sec 5s default, up to 10s
xai/grok-imagine-video xAI Grok Imagine $0.05/sec 8s default

Calls block for 30–120s while the upstream polls the job. Text-to-video and image-to-video (image_url parameter) are both supported. Seedance 2.0 Fast typically returns in 60–80s; 2.0 Pro trades latency for quality.

Image Editing (img2img)

Edit existing images with /img2img:

/img2img --image ~/photo.png change the background to a starry sky
/img2img --image ./cat.jpg --mask ./mask.png remove the background
Option Required Description
--image <path> Yes Local image file path (supports ~/)
--mask <path> No Mask image (white = area to edit)
--model <model> No Model to use (default: gpt-image-1)
--size <WxH> No Output size (default: 1024x1024)

API endpoint: POST http://localhost:8402/v1/images/image2image — see full docs.


Models & Pricing

76 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).

Budget Models (under $0.001/request)

Model Input $/M Output $/M ~$/request Context Features
free/nemotron-3.5-lightning FREE FREE $0 1M reasoning — default free model
free/nemotron-3-nano-30b FREE FREE $0 131K reasoning, fastest free model (~121 tok/s)
free/laguna-xs-2.1 FREE FREE $0 131K coding
free/north-mini-code FREE FREE $0 256K coding
free/nemotron-3-nano-omni-30b-a3b-reasoning FREE FREE $0 256K reasoning, vision (text+img+video+audio)
free/nemotron-3-ultra-550b FREE FREE $0 1M reasoning
free/llama-3.2-11b-vision FREE FREE $0 128K vision
openai/gpt-4.1-nano $0.10 $0.40 $0.0003 128K tools
google/gemini-2.5-flash-lite $0.10 $0.40 $0.0003 1M tools
openai/gpt-4o-mini $0.15 $0.60 $0.0004 128K tools
openai/gpt-5.4-nano $0.20 $1.25 $0.0007 1M tools
openai/gpt-5-mini $0.25 $2.00 $0.0011 200K tools
google/gemini-3.1-flash-lite $0.25 $1.50 $0.0009 1M tools
deepseek/deepseek-chat $0.20 $0.40 $0.0003 1M tools (V4 Flash chat)
deepseek/deepseek-reasoner $0.20 $0.40 $0.0003 1M reasoning, tools (V4 Flash thinking)
deepseek/deepseek-v4-pro $0.435 $0.87 $0.0007 1M reasoning, agentic, tools (V4 flagship)
zai/glm-5 $0.60 $1.92 $0.0013 200K tools
zai/glm-5-turbo $1.20 $4.00 $0.0026 200K tools
minimax/minimax-m3 $0.30 $1.20 $0.0008 1M reasoning, agentic, tools
minimax/minimax-m2.7 $0.30 $1.20 $0.0008 205K reasoning, agentic, tools
google/gemini-2.5-flash $0.30 $2.50 $0.0014 1M vision, tools
openai/gpt-4.1-mini $0.40 $1.60 $0.0010 128K tools
google/gemini-3.5-flash $0.50 $3.00 $0.0018 1M reasoning, vision, tools (thinking built-in)
google/gemini-3-flash-preview $0.50 $3.00 $0.0018 1M vision
xiaomi/mimo-v2.5 $0.14 $0.28 $0.0003 1M reasoning, vision, tools
qwen/qwen3.8-flash $0.15 $0.47 $0.0003 1M reasoning, vision, tools
tencent/hy3 $0.13 $0.53 $0.0003 262K reasoning, tools
zai/glm-5.3-flash $0.15 $0.50 $0.0003 1M reasoning, vision, tools
openai/gpt-5.6-luna $0.20 $1.20 $0.0007 1M vision, agentic, tools
xiaomi/mimo-v2.5-pro $0.43 $0.87 $0.0008 1M reasoning, tools
deepseek/deepseek-v4-flash-vision-exp $0.44 $1.32 $0.0010 1M reasoning, vision, tools

Mid-Range Models ($0.001–$0.01/request)

Model Input $/M Output $/M ~$/request Context Features
openai/gpt-5.4-mini $0.75 $4.50 $0.0026 400K vision, agentic, tools
anthropic/claude-haiku-4.5 $1.00 $5.00 $0.0030 200K vision, agentic, tools
openai/o3-mini $1.10 $4.40 $0.0028 128K reasoning, tools
openai/o4-mini $1.10 $4.40 $0.0028 128K reasoning, tools
google/gemini-2.5-pro $1.25 $10.00 $0.0056 1M reasoning, vision, tools
zai/glm-5.1 $1.40 $4.40 $0.0029 200K reasoning, tools (promo ended 2026-06-05)
xai/grok-4.3 $1.25 $2.50 $0.0019 1M reasoning, vision, agentic, tools
xai/grok-build-0.1 $1.00 $2.00 $0.0015 256K agentic coding, tools
openai/gpt-5.2 $1.75 $14.00 $0.0079 400K reasoning, vision, agentic, tools
openai/gpt-5.3-codex $1.75 $14.00 $0.0079 400K agentic, tools
openai/gpt-4.1 $2.00 $8.00 $0.0050 128K vision, tools
openai/o3 $2.00 $8.00 $0.0050 200K reasoning, tools
google/gemini-3.1-pro $2.00 $12.00 $0.0070 1M reasoning, vision, tools
openai/gpt-4o $2.50 $10.00 $0.0063 128K vision, agentic, tools
openai/gpt-5.4 $2.50 $15.00 $0.0088 400K reasoning, vision, agentic, tools
google/gemini-3.5-flash-lite $0.30 $2.50 $0.0013 1M reasoning, tools
zai/glm-5.2 $1.40 $4.40 $0.0032 1M reasoning, tools
zai/glm-5.3 $1.40 $4.40 $0.0032 1M reasoning, tools
qwen/qwen3.7-max $1.48 $4.42 $0.0032 1M reasoning, agentic, tools
google/gemini-3.6-flash $1.50 $7.50 $0.0045 1M reasoning, vision, tools
xai/grok-4.5 $2.00 $6.00 $0.0040 500K reasoning, vision, agentic, tools
openai/gpt-5.6-terra $2.00 $12.00 $0.0068 1M reasoning, vision, agentic, tools
anthropic/claude-sonnet-5 $3.00 $15.00 $0.0090 1M reasoning, vision, agentic, tools
moonshot/kimi-k3 $3.00 $15.00 $0.0090 1M reasoning, vision, agentic, tools

Premium Models ($0.01+/request)

Model Input $/M Output $/M ~$/request Context Features
anthropic/claude-sonnet-4.6 $3.00 $15.00 $0.0090 200K reasoning, vision, agentic, tools
anthropic/claude-opus-4.8 $5.00 $25.00 $0.0150 1M reasoning, vision, agentic, tools
anthropic/claude-opus-4.7 $5.00 $25.00 $0.0150 1M reasoning, vision, agentic, tools
openai/gpt-5.5 $5.00 $30.00 $0.0175 1M reasoning, vision, agentic, tools
openai/o1 $15.00 $60.00 $0.0375 200K reasoning, tools
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
anthropic/claude-opus-4.5 $5.00 $25.00 $0.0150 200K reasoning, vision, agentic, tools
anthropic/claude-opus-5 $5.00 $25.00 $0.0150 1M reasoning, vision, agentic, tools
openai/gpt-5.6-sol $5.00 $30.00 $0.0170 1M reasoning, vision, agentic, tools
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: 7 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.


Authentication and payment

Account API (recommended): send BLOCKRUN_API_KEY as a bearer token to https://api.blockrun.ai/v1. XClawRouter handles this when the variable or apiKey plugin setting is present. Manage keys at user.blockrun.ai/dashboard/keys and credit at user.blockrun.ai/dashboard/credits.

x402 wallet: 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.

Dual-chain support: Pay with USDC on Solana or USDC on Base (EVM). Both wallets are derived from a single BIP-39 mnemonic on first run.

/wallet              # Check balance and address (both chains)
/wallet export       # Export mnemonic + keys for backup
/wallet recover      # Restore wallet from mnemonic on a new machine
/wallet solana       # Switch to Solana USDC payments
/wallet base         # Switch back to Base (EVM) USDC payments
/chain solana        # Alias for /wallet solana
/stats               # View usage and savings
/stats clear         # Reset usage statistics
/exclude             # Show excluded models
/exclude add <model> # Block a model from routing (aliases work: "grok-4", "free")
/exclude remove <model> # Unblock a model
/exclude clear       # Remove all exclusions

Fund your wallet:

  • Solana: Send USDC on Solana to your Solana address
  • Base (EVM): Send USDC on Base to your EVM address
  • Coinbase/CEX: Withdraw USDC to either network
  • Credit card: Reach out to @bc1max on Telegram

Screenshots

Smart Routing in Action

ClawRouter savings
Telegram Integration

Telegram demo

Configuration

For basic usage, no configuration needed. For advanced options:

Variable Default Description
BLOCKRUN_API_KEY unset Account API key; takes priority over wallet mode
BLOCKRUN_API_BASE_URL https://api.blockrun.ai Account API root for staging/private deployments
BLOCKRUN_WALLET_KEY auto-generated x402 wallet private key
BLOCKRUN_PROXY_PORT 8402 Local proxy port
CLAWROUTER_DISABLED false Disable smart routing
CLAWROUTER_SOLANA_RPC_URL https://api.mainnet-beta.solana.com Solana RPC endpoint

Full reference: docs/configuration.md

Model Exclusion

Block specific models from being routed to. Useful if a model doesn't follow your agent instructions or you want to control costs.

/exclude add free/nemotron-3.5-lightning   # Block the default free model
/exclude add grok-4                # Aliases work — blocks all grok-4 variants
/exclude add gpt-5.4               # Skip expensive models
/exclude                           # Show current exclusions
/exclude remove grok-4             # Unblock a model
/exclude clear                     # Remove all exclusions

Exclusions persist across restarts (~/.openclaw/blockrun/exclude-models.json). If all models in a tier are excluded, the safety net ignores the filter so routing never breaks.


Troubleshooting

When things go wrong, run the doctor:

npx @blockrun/xclawrouter doctor

This collects diagnostics and sends them to Claude Sonnet for AI-powered analysis:

🩺 BlockRun Doctor v0.12.24

System
  ✓ OS: darwin arm64
  ✓ Node: v20.11.0

Wallet
  ✓ Address: 0x1234...abcd
  ✓ Balance: $12.50

Network
  ✓ BlockRun API: reachable (142ms)
  ✗ Local proxy: not running on :8402

📤 Sending to Claude Sonnet 4.6 (~$0.003)...

🤖 AI Analysis:
The local proxy isn't running. Run `openclaw gateway restart` to fix.

Use Opus for complex issues:

npx @blockrun/xclawrouter doctor opus

Ask a specific question:

npx @blockrun/xclawrouter doctor "why is my request failing?"
npx @blockrun/xclawrouter doctor opus "深度分析我的配置"

Cost: Sonnet ~$0.003 (default) | Opus ~$0.01


Development

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

Support

Channel Link
📅 Schedule Demo calendly.com/vickyfu9/30min
💬 Community Telegram t.me/blockrunAI
🐦 X / Twitter x.com/blockrunai
📱 Founder Telegram @bc1max
✉️ Email vicky@blockrun.ai

From the BlockRun Ecosystem

⚡ ClawRouter

The LLM router built for autonomous agents

You're here. 76 models, local smart routing, x402 USDC payments — the only stack that lets agents operate independently.

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

🤖 BRCC

BlockRun for Claude Code

Run Claude Code with 76 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


More Resources

Resource Description
Documentation Full docs
Model Pricing All models & prices
Image Generation & Editing API examples, 5 models
Routing Profiles ECO/AUTO/PREMIUM details
Architecture Technical deep dive
Configuration Environment variables
Troubleshooting Common issues

Blog

Article Topic
11 Free AI Models, Zero Cost How BlockRun gives developers top-tier LLMs for nothing
ClawRouter Cuts LLM API Costs 500× Deep dive into cost savings
ClawRouter vs OpenRouter Head-to-head comparison
Smart LLM Router: 14-Dimension Classifier How the routing engine works
LLM Router Benchmark: 46 Models, Sub-1ms Performance benchmarks
Anthropic Cost Savings Reducing Claude API spend

Frequently Asked Questions

What is ClawRouter?

ClawRouter is an open-source (MIT licensed) smart LLM router built for autonomous AI agents. It analyzes each request across 15 dimensions and routes to the cheapest capable model in under 1ms, entirely locally — no external API calls needed for routing decisions.

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 84% 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?

XClawRouter is open source and runs locally. It supports either one BlockRun account API key or autonomous USDC x402 settlement, and automatically picks the best model for each request.

How does ClawRouter compare to LiteLLM?

Both are open source and run locally. XClawRouter adds automatic model selection and accepts one BlockRun API key or an x402 wallet; LiteLLM typically requires separate provider keys and manual model selection.

What agents does ClawRouter work with?

ClawRouter works with any tool that makes OpenAI-compatible API calls — point it at http://localhost:8402. This includes continue.dev, Cursor, VS Code extensions, ElizaOS, and custom agents. It also integrates as a plugin with OpenClaw (an AI coding agent), which enables additional features like slash commands and usage reports.

Is ClawRouter free?

ClawRouter itself is free and MIT licensed. You pay only for the LLM API calls routed through it — and several models (nemotron-3.5-lightning, nemotron-3-nano-30b, laguna-xs-2.1, north-mini-code, nemotron-3-nano-omni-30b-a3b-reasoning, nemotron-3-ultra-550b, llama-3.2-11b-vision) are completely free. Use /model free to smart-route across them, or pick any by name.


MIT License · BlockRun — Agent-native AI infrastructure

⭐ If ClawRouter powers your agents, consider starring the repo!

About

Smart LLM router powered by OKX OnchainOS wallet. BlockRun's full model catalog, wallet-based auth, USDC micropayments via x402 on Base & Solana.

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages