BlockRunAI/ClawRouterPublic

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.

         

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. 82 models from OpenAI, Anthropic, Google, xAI, DeepSeek, and more. MIT licensed.

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.

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.

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:

• Starts at $0 — 6 open-weight models are free forever (incl. a 1M-context reasoner and two sub-second coders). Image turns route to paid models — see the free-tier note below.
• No accounts needed — a wallet is generated locally, no signup
• No API keys needed — your wallet signature IS authentication
• No model selection — 15-dimension scoring + constraint-first ranking (router-core) picks the right model automatically
• No credit card needed — agents pay per-request with USDC via x402
• No trust required — runs locally, <1ms routing, zero external dependencies

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

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 82 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.

Full walkthrough: Paying with a credit card.

✓ Open source · ✓ Smart routing · ✓ Runs locally · ✓ Crypto native · ✓ Agent ready

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

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:

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 82 chat models plus images, video, speech and the live-data APIs. No wallet, no crypto, no seed phrase.

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.

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.

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 82 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

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

{
  "models": [
    {
      "title": "ClawRouter Auto",
      "provider": "openai",
      "model": "blockrun/auto",
      "apiBase": "http://localhost:8402/v1/",
      "apiKey": "x402"
    }
  ]
}

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

Choose your routing strategy with /model <profile>:

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

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-dimension scorer → tier + task shape
        → hard filters (tools · vision · context · max-output · structured output)
        → rank survivors (quality · capability · cost · speed · reliability)
        → winner + ordered fallback chain → Response

1. Classify — a 15-dimension weighted scorer picks a tier (SIMPLE / MEDIUM / COMPLEX / REASONING); a task classifier labels the shape of the work (code_agent, tool_agent, reasoning_math, long_context, vision, …). Turns that actually need their tools switch to agent-tuned tiers automatically.
2. Filter — every model that cannot satisfy the request is dropped before anything is scored. A model that can't call tools, can't read the image, or can't hold the conversation never gets to win on price.
3. Rank — survivors are scored on task quality, capability, estimated cost, speed and reliability, with per-profile weights (eco leans on cost, premium on quality and reliability).
4. Recover — the whole ranked list rides along as the fallback chain, so a provider timeout or 5xx costs a retry, not the task.

† Withheld from /v1/models — since Router Core V3.5 no chain names such a model: every primary and every fallback rung above is a model you can find on the public pricing page. savings-mix.json prices the published savings claim on the same visible models. ‡ Auto-selected in any profile when the turn actually needs its attached tools; prefers models that keep going instead of stopping to ask.

These are the curated primaries; every tier carries a benchmark-ordered fallback chain — full chains and per-profile ranking weights in docs/routing-profiles.md. On router-core's frozen three-arm agent benchmark (τ-bench, BrowseComp, Terminal-Bench) the V3.4 policy (the last one benchmarked; V3.5 is a catalog refresh on the same scorer and weights) completed 57% of tasks vs 49% for the previous rules router, at 6.4% lower cost per successful task — and spent 8.9% of the tokens a pinned flagship would have.

84% cheaper than pinning Claude Opus 5 for the same traffic, on auto; 98% on eco.

Not an "up to" figure. The baseline, the workload mix and the token ratio are published in savings-mix.json, priced against the live catalog, so anyone can recompute it and get the same answer. Models withheld from /v1/models are excluded from the mix — pricing a public claim on a model you cannot look up is not defensible — which makes the number conservative.

Rollback lever: routing.strategy: "rules" restores the V2 primary-first selector; routing.shadow compares both locally without a second paid call.

Generate images directly from chat with /cr-imagegen:

/cr-imagegen a dog dancing on the beach
/cr-imagegen --model gpt-image-2 a futuristic city at sunset
/cr-imagegen --model banana-pro --size 2048x2048 mountain landscape

The slash command is /cr-imagegen to avoid colliding with Telegram channel commands. Typing /imagegen in chat still works for backward compatibility.

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}'

Seedance is token-priced upstream at ~20,256 tokens/sec — the blockrun videos route now defaults Seedance to resolution=720p with generate_audio=true for text-to-video (2× the per-second token count of the older 480p baseline; audio is included in that rate). The quote is duration × tokens/sec × $/1M tokens × 1.05 margin. Image-to-video is priced the same as text-to-video (the earlier ~40% i2v discount was removed upstream on 2026-06-01; only video-to-video remains cheaper). Sora 2 is flat-priced at $0.10/sec for both t2v and i2v — note it rejects human faces in reference images (use Seedance + RealFace for real people). Calls block for 30–120s while the upstream polls the job. Seedance 2.0 Fast typically returns in 60–80s; 2.0 Pro trades latency for quality.

For real-person character consistency across frames, pass real_face_asset_id (format ta_xxxxxxxx) on 2.0 Fast or 2.0 Pro. Asset IDs come from token360's Asset UI after H5 face verification — see blockrun's /docs/video/real-person-ip for the enrollment walkthrough. Cannot be combined with image_url (both seed the first frame — pick one). Pricing is unchanged.

curl -X POST http://localhost:8402/v1/videos/generations \
  -H "Content-Type: application/json" \
  -d '{"model":"bytedance/seedance-2.0","prompt":"the person walks through a forest","real_face_asset_id":"ta_abc123def","duration_seconds":5}'

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

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

Verify phone numbers and place AI-powered outbound voice calls directly from chat. Phone intelligence runs on Twilio; voice calls use Bland.ai. Payment is automatic via x402 from the wallet.

/cr-call +14155552671 "Hi, this is calling to confirm tomorrow's 3pm meeting"
/cr-call +14155552671 "Order a large pepperoni for delivery" --voice josh --max-duration 10

Calls are fire-and-forget: the request returns a call_id and poll_url immediately. The call itself runs in the cloud for up to 30 minutes. Poll GET /v1/voice/call/{call_id} (or clawrouter share/transcripts dashboard) to retrieve the transcript and recording when status is completed.

CLI for wallet-owned numbers:

clawrouter phone numbers list                              # See active numbers + expiry
clawrouter phone numbers buy US --area-code 415            # Provision a SF number
clawrouter phone numbers renew +14155551234                # Extend 30 days
clawrouter phone numbers release +14155551234              # Release
clawrouter phone lookup +14155552671                       # Carrier + line type
clawrouter phone fraud +14155552671                        # SIM-swap + fwd signals

HTTP API:

# Place a call
curl -X POST http://localhost:8402/v1/voice/call \
  -H "Content-Type: application/json" \
  -d '{"to":"+14155552671","task":"Confirm the 3pm Thursday meeting.","max_duration":5}'
# → { "call_id": "call_abc123", "poll_url": "/v1/voice/call/call_abc123", "status": "queued" }

# Poll for transcript
curl http://localhost:8402/v1/voice/call/call_abc123

LLM agents discover all eight operations as blockrun_phone_* / blockrun_voice_* tools (see /partners).

⚠️ blockrun_voice_call and /cr-call place a real outbound phone call. Server enforces an emergency-number blocklist; choose --from from wallet-owned numbers via phone numbers list.

Surf is BlockRun's unified crypto data API — 84 endpoints across 13 domains: CEX/DEX markets, on-chain SQL over 80+ ClickHouse tables (Ethereum, Base, Arbitrum, BSC, TRON, HyperEVM, Tempo), 100M+ labeled wallets, prediction markets (Polymarket + Kalshi), social/CT mindshare, news, project/DeFi metrics, token analytics, unified search, VC fund intelligence. The killer feature is ad-hoc POST /surf/onchain/sql — agents query the warehouse directly without running an indexer.

ClawRouter ships Surf as a skill, not as typed wrappers. The proxy whitelists /v1/surf/* so any call through the local proxy is paid x402 from the same wallet; the agent reads skills/surf/SKILL.md for the endpoint catalog and crafts the HTTP call. No blockrun_surf_* tool definitions to maintain; a new Surf endpoint requires zero ClawRouter release.

Flat per-call pricing — every Surf endpoint costs the same. The old $0.001/$0.005/$0.020 tiers no longer apply; upstream prices all three tiers identically, and the tier now describes only endpoint weight.

Measured 2026-09-05: the API-key rate from the account ledger, the wallet rates from the x402 challenge, which quotes the price before anything is signed. That quote is authoritative for the rail that issued it — the key rail issues no 402, and the wallet quote includes a transaction fee account credit does not pay, so the two are not interchangeable. Solana being cheaper than Base is deliberate (the $0.001 is Base's transaction fee), not drift.

Usage (HTTP):

# Aggregated BTC spot price (Tier 1, $0.001)
curl 'http://localhost:8402/v1/surf/market/price?symbol=BTC'

# Bulk wallet labels over 100M+ labeled wallets (Tier 2, $0.005)
curl 'http://localhost:8402/v1/surf/wallet/labels/batch?addresses=0xabc,0xdef,0x123'

# Ad-hoc on-chain SQL (Tier 3, $0.020)
curl -X POST 'http://localhost:8402/v1/surf/onchain/sql' \
  -H 'content-type: application/json' \
  -d '{"sql":"SELECT count() FROM ethereum.transactions WHERE block_timestamp >= now() - INTERVAL 1 HOUR"}'

No Surf account, no API key — settles directly to Surf's Base treasury in USDC via the same wallet as LLM calls. Full endpoint reference: skills/surf/SKILL.md. Upstream marketplace: https://blockrun.ai/marketplace/surf.

💡 "Cost per request" = estimated cost for a typical chat message (~500 input + 500 output tokens). Paid requests also carry a flat $0.001/tx settlement fee (covers on-chain gas; already included in the price the gateway quotes). Free models never pay it.

Free tier: 6 open-weight models cost nothing — /model free pins the free default (nemotron-3.5-lightning, with the other five as fallbacks), /model eco opens on it, or pick one directly (e.g., /model lightning for 1M-context reasoning, /model north-mini or /model laguna for fast coding).

No free vision. Two free models are catalogued as vision-capable and neither reliably is: on a 64×64 solid-colour probe nemotron-3-nano-omni was right 1 of 4 times on Base and answered "white" for red on Solana, and llama-3.2-11b-vision replied "I'm unable to see the image" 3 of 3 while answering text fine. Both return HTTP 200, so a wrong answer arrives with no error to branch on. ClawRouter therefore does not flag them for vision, and requests carrying an image_url route to a paid vision model instead. Best value: gpt-5-nano and gemini-2.5-flash-lite deliver strong results at ~$0.0003/request.

Two rails. This section covers the wallet one; the card/API-key one is below.

Here, no account and no API key are needed at all — 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 (the default) or USDC on Base (EVM). Both wallets are derived from a single BIP-39 mnemonic on first run. New installs get Solana; an install that predates the Solana default keeps its Base wallet — its USDC is there — until you switch with /wallet solana.

/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 to Base (EVM) USDC payments
/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 (default): 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: don't fund a wallet at all — sign up at user.blockrun.ai and use an API key instead (below)

Wallets are what let an agent pay for itself. If you are a person and would rather pay the way you pay for everything else, BlockRun issues API keys backed by card-funded credit — and ClawRouter speaks that too.

1. Sign up and get a key

Go to user.blockrun.ai:

1. Sign in with Google. That is the whole signup — no invite, no sales call.
2. Credits → top up with a credit card. The processing fee is 5.5% + $0.30, charged at purchase, not on inference: you pay it once on the top-up and every model then bills at provider list price with no markup, with no per-call minimum and no per-call fee.
3. API Keys → create a key. It is shown once and looks like brk_live_… — copy it before you leave the page.

2. Tell ClawRouter about it

clawrouter login brk_live_...     # stores it in ~/.blockrun/.api-key (chmod 600)
clawrouter login                  # or run bare and paste at the prompt

Or, for CI and containers where you would rather not write a file:

export BLOCKRUN_API_KEY=brk_live_...

Either way, restart the proxy. That is the whole change — routing, model names, the free tier, /model auto, exclusions and the OpenAI-compatible surface all behave exactly as before:

npx @blockrun/clawrouter
# [ClawRouter] Using BlockRun API key brk_live_Ab3xQ9…f8c1 (from ~/.blockrun/.api-key)
# [ClawRouter] Billing: account credit — top up at https://user.blockrun.ai/dashboard/credits

3. Check it, and switch back whenever

clawrouter status     # names the mode, the gateway, the masked key and your credit
clawrouter doctor     # verifies the key against the gateway (401 = revoked or mistyped)
clawrouter reconcile  # diff your local usage journal against BlockRun's billing ledger
clawrouter logout     # delete the key and go back to paying from the wallet

Checking your bill without opening a dashboard. clawrouter reconcile compares what ClawRouter recorded locally against GET /v1/usage — BlockRun's authoritative ledger — joined on the gateway's own request id:

BlockRun reconciliation — last 7 days

  Gateway charged:  $12.41   (438 settled calls)
  Journal recorded: $12.41
  Matched:          438, of which 0 disagree on amount

Three outcomes are worth acting on. Amount mismatches mean the local price table has drifted from the gateway's. Charged but not in this machine's journal is the one to look at hardest: money left the account for a call this machine did not make — expected if the same key is used on another machine or by another BlockRun product, and worth investigating if not. Exit code 2 in that case, so a scheduled check can alert on it. Rows still pending pricing are excluded from the totals rather than counted as $0.

Your per-call sum will always be less than your card statement by exactly the top-up fees, which are charged at purchase and never appear as ledger rows. That gap is arithmetic, not a discrepancy.

Using it directly, without ClawRouter. The same key works against api.blockrun.ai from any OpenAI or Anthropic SDK — Authorization: Bearer for OpenAI clients, x-api-key for Anthropic ones:

curl https://api.blockrun.ai/v1/chat/completions \
  -H "Authorization: Bearer brk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"model": "anthropic/claude-sonnet-5", "messages": [{"role": "user", "content": "hello"}]}'

Running it through ClawRouter is what adds the smart routing, the fallback chains, the response cache and the local spend controls.

What to know

• The key wins. If a wallet and a key are both present, ClawRouter uses the key. A machine with both means "bill my account", not "keep spending my USDC". clawrouter logout (and unsetting BLOCKRUN_API_KEY) reverses it.
• No wallet is created. In API-key mode ClawRouter never generates, reads or signs with a private key — clawrouter doctor will not mint one either.
• Balance lives server-side. There is no local balance to check: a call that outruns your credit comes back as HTTP 402 insufficient_quota, naming the top-up page. Free models stay free and need no credit at all — all 6 are served on the API-key gateway too.
• One key covers nearly everything. Verified live against api.blockrun.ai on 2026-09-05: chat completions (/v1/chat/completions), the Anthropic-shaped /v1/messages, /v1/models, image generation, speech, video, and the partner APIs — Surf crypto data, Exa search, prediction markets, and phone lookup and fraud checks.
• The wallet-only exceptions are the routes that bind a lease or a position to a payer address, because there is no address to bind to without a wallet: buying, renewing, listing and releasing phone numbers (the gateway answers those with a raw 402 on a key), and Polymarket trading, which ClawRouter signs locally with the wallet key. Phone lookups, fraud checks and outbound voice calls are fine on a key; only owning a number is not.
• maxCostPerRun and /exclude still apply, along with the router's own budget filter — they live in the router, not the signer. clawrouter policy limits do not: they are enforced in the x402 pre-sign hook, and nothing is signed here. Your account balance is the cap instead, and ClawRouter warns at startup if you have one of those limits configured.

Smart Routing in Action

Telegram Integration

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

Full reference: docs/configuration.md

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 a free model (e.g. not for your workload)
/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.

When things go wrong, run the doctor:

npx @blockrun/clawrouter doctor

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