Clawrouter

ClawRouter

Hosted-gateway LLM router that saves 84% on inference costs by forwarding each request to the blockrun.ai gateway, which picks the cheapest model capable of handling it across 78 models from 9 providers (6 free open-weight models). All billing flows through one BlockRun credential — either a USDC wallet paying x402 per call, or a BlockRun API key drawing on card-funded account credit. Either way you do not hold provider API keys.

This is not a local-inference tool. ClawRouter is a thin local proxy. Your prompts are sent over HTTPS to the blockrun.ai gateway for model execution. If your workload requires inference that never leaves your machine, use a local runtime like Ollama — ClawRouter is not the right tool for that use case.

Source: https://github.com/BlockRunAI/ClawRouter · npm: https://www.npmjs.com/package/@blockrun/clawrouter · License: MIT.

Data Flow

Copy code
Your app → localhost proxy (ClawRouter) → https://blockrun.ai/api  (or sol.blockrun.ai/api)
                                              ↓
                                        OpenAI / Anthropic / Google / etc.
                                              ↓
                                        Response → back through proxy → your app

Sent to blockrun.ai on every request: the model name, the full prompt/messages body, sampling params (temperature, max_tokens, tools, etc.), and a payment credential — an X-PAYMENT header containing a signed x402 USDC micropayment in wallet mode, or an Authorization: Bearer brk_live_… header in API-key mode.

Not sent: your wallet private key (only the detached payment signature is sent), any other local files, environment variables, or OpenClaw config beyond what's needed for this request.

Blockrun's privacy stance: https://blockrun.ai/privacy. Treat prompts the same way you'd treat prompts sent to any hosted LLM API (OpenAI, Anthropic, etc.) — do not send data you would not share with a third-party API provider.

Credentials & Local Key Storage

ClawRouter does not collect or forward third-party provider API keys. You do not supply OpenAI, Anthropic, Google, DeepSeek, xAI, or NVIDIA credentials — the blockrun.ai gateway owns those relationships.

What models.providers.blockrun stores (fully enumerated):

How and where keys are stored:

• Keys live in the OpenClaw user config file — typically ~/.config/openclaw/config.json on Linux, ~/Library/Application Support/openclaw/config.json on macOS, %APPDATA%\openclaw\config.json on Windows — under the models.providers.blockrun path.
• Written by OpenClaw's standard config writer with 0600 permissions on POSIX systems (owner read/write only).
• Stored in plaintext, the same way every OpenClaw provider's API key is stored. ClawRouter does not add an extra encryption layer; your filesystem permissions are the security boundary. If you require an encrypted keystore, run OpenClaw on an encrypted volume (FileVault, LUKS, BitLocker) or use a dedicated burner wallet funded only with what you intend to spend.
• Auto-generation uses @scure/bip39 to produce a 24-word mnemonic, then BIP-44 derivation for both chains. Source: src/wallet.ts.

Operational guidance: treat the wallet as a spending account with a small top-up, not a long-term store of value. Fund it with what you expect to spend on LLM calls. If the host machine is compromised, the wallet key is compromised — rotate and refund.

Supply-Chain Integrity

• Every release is tagged on GitHub: https://github.com/BlockRunAI/ClawRouter/releases
• Every release publishes to npm with a matching version: https://www.npmjs.com/package/@blockrun/clawrouter?activeTab=versions
• The skills/release/SKILL.md mandatory checklist enforces: same version in package.json, matching git tag, matching GitHub release, and matching npm publish.
• To verify locally: npm pack @blockrun/clawrouter@<version> and compare the tarball contents to the tagged commit.

Install

bashCopy code
openclaw plugins install @blockrun/clawrouter

The structured install block above tells OpenClaw to install the auditable npm package @blockrun/clawrouter. Source for every version is on GitHub; every release is tagged.

Setup

bashCopy code
# Enable smart routing (auto-picks cheapest model per request)
openclaw models set blockrun/auto

# Or pin a specific model
openclaw models set openai/gpt-4o

How Routing Works

Routing is done locally by @blockrun/router-core (Router Core V3.4, constraint-first), inlined into ClawRouter and pinned by commit. No network call, no second model — about a quarter of a millisecond per request.

1. A 15-dimension weighted scorer classifies each request into one of four tiers, and a task classifier labels the shape of the work (chat, extraction, code_edit, code_agent, tool_agent, reasoning_math, long_context, vision, …).
2. Models that cannot satisfy the request — no tool calling, no vision, too small a context window or max-output, incompatible structured output — are removed before anything is scored.
3. Survivors are ranked on task quality, capability, estimated cost, speed and reliability; the full ranked list is kept as the fallback chain for timeouts and 5xx.

Curated primaries on the default auto profile:

• SIMPLE — factual lookups, greetings, translations → gemini-2.5-flash ($0.30/$2.50)
• MEDIUM — summaries, explanations, data extraction → kimi-k2.7 ($0.95/$4.00)
• COMPLEX — code generation, multi-step analysis → gemini-3.1-pro ($2/$12)
• REASONING — proofs, formal logic, multi-step math → grok-4-1-fast-reasoning ($0.20/$0.50)

Turns that actually need their attached tools switch to agent-tuned tiers (gpt-4o-mini → kimi-k2.7 → claude-sonnet-4.6). eco opens on the free tier (nemotron-3.5-lightning); premium climbs to gpt-5.3-codex / claude-fable-5 / claude-sonnet-4.6. Full chains: docs/routing-profiles.md.

Prices are per 1M input/output tokens. Per-tier savings percentages are deliberately not quoted here: the published figure is blended across a stated workload mix, and a per-tier number invites comparing it against a baseline nobody wrote down. See savings-mix.json.

Available Models

Built-in Agent Tools

In addition to LLM routing, ClawRouter exposes BlockRun's x402-gated data APIs as ready-to-use OpenClaw tools. Every tool is paid from the same USDC wallet — no extra setup, no extra API keys.

Market Data

Realtime prices and historical OHLC across every asset class. The agent should call these directly instead of scraping finance sites.

Image & Video Generation

Phone & Voice (Twilio + Bland.ai)

Verify phone numbers and place AI-powered outbound voice calls. Real-world side effects — only call blockrun_voice_call when the user has explicitly asked to place a call. Server enforces an emergency-number blocklist; ClawRouter does not.

Voice calls are fire-and-forget: the POST returns a call_id + poll_url immediately, the call itself runs in the cloud for up to 30 minutes. Poll blockrun_voice_status every 10–30s while in_progress to retrieve the transcript. Slash command: /cr-call +1<E.164> "<task>" [--voice nat] [--max-duration 5]. CLI: clawrouter phone numbers list/buy/renew/release and clawrouter phone lookup/fraud <+E.164>. See the phone skill for the full call-flow reference.

Prediction Markets (Predexon)

Full prediction-market toolbox spanning Polymarket, Kalshi, Limitless, Opinion, Predict.Fun, dFlow + Binance for crypto candles. 57 endpoints (Predexon v2) exposed as 9 agent tools (8 named ergonomic wrappers + 1 catch-all):

• Markets & trading — events, markets list per venue, cross-venue search (markets/search), orderbooks, candlesticks (per-market and per-token), trades, positions, volume charts.
• Leaderboard & smart money — global + per-market leaderboards, smart-money positioning, top holders, smart-activity feed.
• Wallet analytics — full wallet profile, P&L time series, per-market breakdown, similar-wallet discovery, batch profiles, AND/OR filters.
• UMA oracle + wallet identity — UMA optimistic-oracle resolution status (uma/markets, uma/market/{conditionId}); wallet identity labels (ENS / Lens / exchange / risk tags), bulk identity, on-chain cluster discovery.

Pricing: $0.001 per market-data call, $0.005 per analytics / search / wallet call. See the predexon skill for the full endpoint reference.

Prediction-Market Trading (Polymarket) — REAL MONEY

Beyond reading odds, ClawRouter can place, manage, and redeem real bets on Polymarket (CLOB V2, Polygon) via the blockrun_polymarket tool. Unlike every other tool here it is not an HTTP-proxy wrapper — it runs a local trading engine that signs CLOB orders (EIP-712) with the SAME ClawRouter wallet that pays for LLM calls, and posts them to Polymarket (through BlockRun's Tokyo egress by default, so it works out of the box in geoblocked regions).

• Funds: bets spend pUSD in a gasless Polygon deposit-wallet vault derived from your key; action:"fund" moves your Base USDC → pUSD gaslessly (x402, $0.01 fee, non-custodial). Winnings withdraw back to native USDC on Base.
• Safety: confirm:true is hard-required to place/sign anything (omit → dry-run preview); per-order cap POLYMARKET_MAX_BET_USD (default $25) + optional POLYMARKET_MAX_SESSION_USD. Bets do NOT draw from the x402 API budget.
• Zero config: no Polymarket account, API keys, or gas token — first setup bootstraps everything from your wallet. Discover token IDs with the blockrun_predexon_* data tools first. See the polymarket-trading skill for the golden rules and end-to-end flow.

Crypto Data (Surf) — skill-only integration

Surf is a unified crypto data API with 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 POST /surf/onchain/sql — ad-hoc SELECT against the warehouse, no indexer required.

ClawRouter ships Surf as a skill, not as typed wrappers. The base proxy whitelists /v1/surf/* so any call through http://127.0.0.1:8402/v1/surf/... flows through the same x402 wallet that pays for LLM calls. The endpoint catalog, parameter shapes, and example flows live in the dedicated surf skill — Claude Code (or any agent) reads that skill on demand and crafts the HTTP call itself. No blockrun_surf_* tool definitions to maintain, no release of ClawRouter when Surf adds endpoint #85.

Pricing tiers (per call, settled in USDC directly to Surf's Base treasury): $0.001 prices/rankings/lists/news · $0.005 orderbooks/candles/search/wallet details/social · $0.02 on-chain SQL/query/schema, chat completions. No monthly minimums, no Surf account, no API key. See the surf skill for the full endpoint reference.

This is the pattern for new BlockRun-marketplace APIs going forward: base proxy whitelists the namespace, a dedicated skill documents the surface — no hand-coded tool wrappers per endpoint.

Example Output

Copy code
[ClawRouter] google/gemini-2.5-flash (SIMPLE, rules, confidence=0.92)
             Cost: $0.0025 | Baseline: $0.308 | Saved: 99.2%