ClawRouter README

The project's README from github.com/BlockRunAI/ClawRouter. As one markdown file: README.md.

ClawRouter Banner

The LLM router built for autonomous agents

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.

Pay however you like: credit card — sign up at user.blockrun.ai, top up, mint an API key
or USDC on Solana or Base (x402 wallet, no account at all).
Or neither — 6 models are free, with no signup, no key and no wallet.


6 free models  Agent native  Card or USDC  Local routing  x402 USDC  Open source

npm version npm downloads GitHub stars CI TypeScript License: MIT

USDC Hackathon Winner x402 Protocol Base Network Solana OpenClaw Plugin Telegram

ClawRouter is an open-source smart LLM router that reduces AI API costs by up to 84%. It analyzes each request across 15 dimensions and routes to the cheapest capable model in under 1ms, entirely locally. It is the only LLM router that an autonomous agent can pay for by itself — a wallet signature is the account, and USDC micropayments over the x402 protocol are the billing — and it takes an ordinary credit card too: sign up at user.blockrun.ai, top up, and run the same router on an API key. 78 models from OpenAI, Anthropic, Google, xAI, DeepSeek, and more. MIT licensed.

What BlockRun is

BlockRun lets agents pay for the outcome — every LLM, tool and data source, best value per dollar.

Not a seat, not a subscription, not a monthly minimum you keep paying while the agent idles. An agent asks for one thing — an answer, an image, a transcript, a price, a call placed — and pays for that one thing at the moment it happens. Nothing to sign up for, nothing to cancel.
Every LLM 78 chat models across 9 providers, behind one endpoint and one balance
Every tool 10 image models, 8 video models, music, 5 voices, img2img editing, and outbound phone calls that come back as transcripts
Every data source web, news and neural search; prediction markets; live crypto and equity quotes; on-chain SQL over 100M+ labeled wallets; DEX routing; RPC across 40 chains
Best value per dollar 15-dimension local routing sends each request to the cheapest model that can actually do it — 84% below pinning Claude Opus 5 on the same traffic, computed from a published workload mix rather than estimated

ClawRouter is how an agent reaches it. BlockRun is the gateway and the billing; ClawRouter is the MIT-licensed router that runs on your machine, decides which model each request deserves, and settles the bill — a wallet signature in USDC, or a credit-card-funded API key. The rest of this README is about ClawRouter.

Why ClawRouter exists

Every other LLM router was built for human developers — create an account, get an API key, pick a model from a dashboard, pay with a credit card.

Agents can't do any of that.

ClawRouter is built for the agent-first world:

This is the stack that lets agents operate autonomously: x402 + USDC + local routing.

…and if you are a human, not an agent

Every "no X needed" above is a capability, not a restriction. ClawRouter takes a credit card too. Sign up at user.blockrun.ai, top up, mint an API key, and run clawrouter login brk_live_…. Same router, same 78 models, same local routing — calls go to api.blockrun.ai on a bearer token and bill your account credit. No crypto, no gas, no seed phrase.

You are Pay with Setup
Just trying it Nothing Install and pin a free model
A person Credit card → account credit Sign up at user.blockrun.ai → clawrouter login brk_live_…
An autonomous agent USDC on Solana or Base, per request Nothing — a wallet is generated on first run (Solana by default)

Full walkthrough: Paying with a credit card.

How it compares

OpenRouter LiteLLM Martian Portkey ClawRouter
Models 200+ 100+ Smart routing Gateway 78
Free tier Rate-limited BYO keys No No 6 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 or API key
Payment Credit card BYO keys Credit card $49-499/mo USDC per-request or card credit
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

No wallet? 6 models work free out of the box. Install, run, and pin free/nemotron-3.5-lightning (or any of the 6) — no crypto, no signup, no balance required. Add a credit card or USDC later when you want paid models.

Two ways to pay for the paid ones — pick one, the rest of ClawRouter is identical:

Wallet (default) API key
Who it is for Autonomous agents, and anyone happy holding USDC People who would rather pay with a card
Setup Nothing — a wallet is generated on first run Sign up at user.blockrun.ai, top up, mint a key, clawrouter login brk_live_…
Auth An x402 signature per request Authorization: Bearer brk_live_…
Gateway sol.blockrun.ai (Solana, default) / blockrun.ai (Base) api.blockrun.ai
Billing USDC leaves your wallet per call, non-custodial Card-funded account credit, drawn down at exact usage
Fees $0.001/tx settlement fee (covers on-chain gas) 5.5% + $0.30 on the top-up, then list price with nothing per call

ClawRouter prefers the API key whenever one is configured, so clawrouter login is all it takes to switch and clawrouter logout is all it takes to switch back.

Where do I sign up? user.blockrun.ai — sign in with Google, add credit with a card under Credits, mint a key under API Keys. That one key covers all 78 chat models plus images, video, speech and the live-data APIs. No wallet, no crypto, no seed phrase.

Desktop control plane (macOS)

The Electron app in apps/desktop provides one-click connections for OpenClaw, Codex, Hermes, DeepSeek Harness, and Pi, plus model pricing/context, wallet balances, Solana/Base switching, and Coinbase Onramp. It snapshots each agent's existing config before changing it and restores the original bytes when you disconnect. Wallets are shared through ~/.blockrun; older ClawRouter wallets are copied there automatically without overwriting existing Core files.

Option A — OpenClaw Agent

OpenClaw is an AI coding agent. If you're using it, ClawRouter installs as a plugin. Two paths:

A1. Recommended — one-shot install script:

curl -fsSL https://blockrun.ai/ClawRouter-update | bash
openclaw gateway restart

This handles everything: registration, models config, auth profile, wallet setup. Smart routing (blockrun/auto) is now your default model.

OpenClaw now also bundles an unrelated plugin named clawrouter (@openclaw/clawrouter). BlockRun uses the distinct plugin id blockrun-clawrouter; the installer preserves the official plugin and allows both products to coexist.

A2. If you prefer pure npm:

npm install -g @blockrun/clawrouter
clawrouter setup            # finishes OpenClaw integration — REQUIRED
openclaw gateway restart

⚠️ Skipping clawrouter setup will leave you broken. Bare npm install -g only puts the package on disk; it does NOT register the plugin with OpenClaw, sync the models allowlist, or write the auth profile. Symptom: /models in your bot shows only OpenClaw's defaults instead of the 55 BlockRun models. Run clawrouter setup to repair, or use path A1 to begin with.

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.

Using NousResearch Hermes? See ClawRouter-Hermes — a Python plugin that wires Hermes into the ClawRouter proxy. Same wallet, same 78 models, same x402 USDC settlement on Solana & Base.

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

1. Start the proxy

npx @blockrun/clawrouter

2. Fund your wallet — optional, skip for free tier Your wallet address is printed on first run. For paid models, send a few USDC on Solana (the default chain) or Base — $5 covers thousands of requests. Prefer a card? Sign up at user.blockrun.ai and run clawrouter login brk_live_… instead. To stay at $0, pin any of the 6 free models (e.g. free/nemotron-3.5-lightning) or use /model free inside OpenClaw.

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) 84% General use
/model eco Cheapest possible 98% 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.

Routing decisions come from @blockrun/router-core — Router Core V3.5, the constraint-first portfolio router shared by every BlockRun product (ClawRouter, Franklin, the @blockrun/llm SDKs, ClawRouter-Hermes). ClawRouter inlines it at build time, pinned to an exact commit, and injects its live model catalog at startup.

Request → 15-dimens

ClawRouter (BlockRunAI/ClawRouter)

Searching Database…

6.6K ·GitHub
ClawRouter
What is this?ClawRouter is an open-source LLM router built for autonomous agents: it picks the cheapest capable model from 78 models across 9 providers in under 1ms, entirely locally, and lets an agent pay per request with USDC (via the x402 protocol) instead of signing up for a human account.
Is this a hosted service or something that runs on my machine?It is a local proxy/CLI that runs on your machine on port 8402 and exposes an OpenAI-compatible endpoint; the actual billing and model catalog live behind BlockRun's gateway, but routing decisions happen locally with no external calls.
How do I get it running with my coding agent?For OpenClaw, use the one-shot install script which handles registration, model config, auth and wallet setup; for any other OpenAI-compatible client (continue.dev, Cursor, VS Code), npm-install the CLI, start the local proxy, and point the client's base URL at it with /v1/ at the end.
Do I need a crypto wallet or API key before trying it?No — 6 open-weight models (including a 1M-context reasoner) run completely free with no wallet, signup, or key; a wallet (auto-generated) or a BlockRun API key is only needed to unlock the other 78 paid models.
What happens if I just npm install it without the setup step?A bare 'npm install -g' only drops the package on disk — it does not register the plugin with OpenClaw, sync the model allowlist, or write the auth profile, so your bot's /models list will only show OpenClaw's defaults until you run 'clawrouter setup'.
Does routing send my requests to a third-party server first?No — the model-selection step is entirely local with zero external API calls; only the actual chat request is sent out to whichever provider gets chosen.
What routing profiles can I switch between?/model free uses only free NVIDIA models (100% savings), /model auto is the balanced default (84% savings), /model eco maximizes savings (98%), and /model premium always picks the best-quality model (0% savings).
Which coding agents and clients does it support?It plugs into OpenClaw as a native plugin, and ships a macOS desktop app with one-click connections for OpenClaw, Codex, Hermes, DeepSeek Harness, and Pi. As a standalone proxy it also works with continue.dev, Cursor, VS Code, or any OpenAI-compatible client.
How does it decide which model to use?Router Core V3.5 scores each request across 15 dimensions and does constraint-first ranking to pick the cheapest model that can actually handle it, inlined at build time and pinned to an exact commit.
Can I pay with a regular credit card instead of crypto?Yes — sign up at user.blockrun.ai, add credit with a card, and mint an API key, then run 'clawrouter login' to switch ClawRouter from wallet-based x402 payments to card-funded account credit.
What are similar projects?openclaw-zero-token, jev-router, OmniRoute, ThinkWatch-Lite, brigade, casbin-gateway, pxpipe, Raven
Which topics is it in?x402, llm-router, cost-optimization, api-gateway, cryptocurrency, blockchain, openclaw, deepseek, gemini, proxy, anthropic, openai
Creator
BlockRunAI
Size
154.1 MB
Stars
6.6K
Updated
CommitOct 13Releasev0.12.288Oct 13
Age
8mo
Commits · 90 Days