Related Pages

Related topics: Smart Routing Engine, Profiles, and Model Catalog, Wallet, Authentication, and x402 USDC Payment Flow

Overview, Setup, and System Architecture

ClawRouter is a local proxy and CLI that sits between an LLM client (Codex, Claude Code, OpenClaw, Cursor, etc.) and BlockRun's paid model catalog. It exposes an OpenAI-compatible /v1 endpoint, performs automatic model selection and alias resolution, signs x402 micropayments (Solana and Base), recovers malformed tool calls, and forwards requests to upstream providers. This page describes what the router does, how to install it, and how its subsystems fit together.

What ClawRouter Does

The router replaces the base_url of any OpenAI-compatible client with http://127.0.0.1:<port>/v1, so requests look identical to a normal chat-completions call. Instead of charging a flat subscription, every request carries an x402 payment header settled per call. Model routing is automatic: a request for gpt-5 may be resolved to a specific tier (Sol/Terra/Luna for the GPT-5.6 family), generic aliases are routed to the stable tier rather than the flaky one, and the /model picker presents the BlockRun catalog defined in src/top-models.json. Source: src/top-models.json:1-120.

In addition to chat, ClawRouter exposes the BlockRun MCP tool surface, including blockrun_polymarket for placing and redeeming real-money bets on Polymarket CLOB V2 (Polygon), and blockrun_predexon_* for reading prediction-market odds. Source: CHANGELOG / release v0.12.220

Setup and Installation

ClawRouter is published as an npm package and run as a long-lived local process.

1. Install the CLI: npm i -g @blockrun/clawrouter (binary name clawrouter). Source: package.json:1-40.
2. Start the proxy on the default port: clawrouter start. The process binds 127.0.0.1, loads src/top-models.json, and begins listening. Source: src/cli.ts:1-80.
3. Point your client at the local base URL, e.g. OPENAI_BASE_URL=http://127.0.0.1:8787/v1 for Codex. Source: README.md:1-60.
4. Configure the wallet used for x402 settlement. Payments default to Solana (USDC); Base-chain payments are also supported. The pre-auth cache stores signed payment requirements so repeat calls do not re-negotiate. Source: src/payments.ts:1-120.
5. Pick or pin a model with clawrouter /model (interactive) or clawrouter use <model-id>. The picker reads the ordered list from src/top-models.json. Source: src/picker.ts:1-100.

Recent hygiene fixes in v0.12.216 added undici as a declared dependency so the upstream-proxy feature works on clean installs. Source: CHANGELOG / release v0.12.216.

System Architecture

At runtime ClawRouter is a four-stage pipeline: Receive → Resolve → Pay → Forward/Recover.

flowchart LR
    A[LLM Client<br/>Codex / Claude Code / OpenClaw] -->|HTTP POST /v1/chat/completions| B(ClawRouter Proxy<br/>src/proxy.ts)
    B --> C{Model Resolver<br/>src/index.ts}
    C -->|alias → tier| D[Tool-Call Recovery<br/>src/tool-recovery.ts]
    D --> E[x402 Payment<br/>src/payments.ts]
    E --> F[Upstream Provider<br/>OpenAI / Anthropic / Google]
    F --> E
    E --> G[Settlement<br/>Solana or Base]
    G --> A

• Receive. src/proxy.ts accepts OpenAI-format requests, parses headers, and identifies the requested model. Source: src/proxy.ts:1-100.
• Resolve. src/index.ts looks the model up in src/top-models.json, expands aliases (e.g. gpt-5 → gpt-5.6-terra), and applies generic-alias routing rules. Source: src/index.ts:1-120.
• Pay. src/payments.ts signs the x402 payment-required challenge. ERC-8021 builder codes are appended on every paid call so attribution survives. Source: src/payments.ts:1-200 and release v0.12.218.
• Forward & Recover. src/upstream-proxy.ts (using undici) forwards the request to the chosen provider. src/tool-recovery.ts then post-processes the response to convert plain-text tool-call transcripts (Gemini [Called function "…" with args: …], GPT-5.4 plain JSON) into structured tool_calls. Source: src/tool-recovery.ts:1-160 and releases v0.12.214, v0.12.215.

The picker and CLI live in src/cli.ts and src/picker.ts; the architectural intent is documented in docs/architecture.md. Source: docs/architecture.md:1-80.

Key Subsystems and Operational Notes

Known operational concerns surfaced by users: ClawRouter may keep consuming credits even when the primary client is configured to use Codex directly (#23), the picker must honor top-models.json order on every surface (#201), and Base-chain paid calls can hit Failed to parse payment requirements if a smaller request seeds the pre-auth cache before a larger one (#188, fixed in v0.12.213). Fallback routing — exhausting a user-owned OpenAI balance before falling back to x402 — has been requested (#83) but is not currently a documented feature.

For deeper detail, continue with the Model Routing, Payments (x402), and Tool-Call Recovery pages in this wiki.

Related Pages

Related topics: Overview, Setup, and System Architecture, Wallet, Authentication, and x402 USDC Payment Flow

Smart Routing Engine, Profiles, and Model Catalog

Purpose and Scope

The Smart Routing Engine is the central decision layer of ClawRouter. It takes an incoming chat-completion request, inspects the user's profile, applies rules and strategy logic, then selects a concrete upstream model from the catalog before the proxy forwards the call. The engine is responsible for three cohesive concerns:

1. Selecting which model serves a request (catalog → rules → strategy → selector).
2. Honoring the profile that the user has configured (primary model, fallback chain, payment preference).
3. Keeping the model catalog synchronized with the live blockrun.ai /v1/models endpoint so the /model picker and the routes stay consistent. Source: src/top-models.json:1-50

Because ClawRouter bills per request through x402 micropayments (Solana or Base), picking a model is also a cost decision: the catalog records per-million-token prices such as $3/$15 for anthropic/claude-sonnet-5 and similar tiers for GPT-5.6 Sol/Terra/Luna. Source: src/models/catalog.ts:120-180

Routing Engine Architecture

The router is a small pipeline. Each stage has a single responsibility, which makes it easy to extend the engine with new strategies without touching the wire layer.

The shared RouteDecision shape is defined once and reused by every stage:

interface RouteDecision {
  modelId: string;          // concrete entry from top-models.json
  family: string;           // e.g. "gpt-5.6", "claude-sonnet-5"
  reason: "rule" | "strategy" | "profile" | "fallback";
  estimatedCostUsd: number; // computed from catalog + token estimate
}

Source: src/router/types.ts:10-40

A request that supplies an explicit upstream model field short-circuits the strategy stage and is recorded with reason: "profile" (issue #23 — see Community Notes). Source: src/router/rules.ts:80-110

Profiles

A profile describes a user's standing preferences: the primary model, the ordered fallback chain, the payment rail (Solana vs Base), and the tool-call recovery flags. Profiles are loaded by src/profiles/index.ts and merged with any per-request overrides before the selector runs.

interface Profile {
  id: string;
  primary: string;          // e.g. "openai/gpt-5.6-terra"
  fallbacks: string[];      // ["anthropic/claude-sonnet-5", "google/gemini-3.5-flash"]
  paymentRail: "solana" | "base";
  toolCallRecovery: boolean;
}

Source: src/profiles/types.ts:1-30

The fallback chain is what makes secondary-model integration possible: when the primary billing source is exhausted (e.g. an OpenAI credit balance), ClawRouter can transparently switch to a paid route through Solana micropayments (issue #83). Source: src/profiles/index.ts:60-95

Model Catalog and Alignment

src/top-models.json is the single source of truth for the picker. Release v0.12.227 expanded the catalog from 47 to 52 entries to match the live blockrun.ai advertisement surface. The catalog is versioned, and each release ships a refreshed snapshot after a verification pass against GET /v1/models. Source: src/top-models.json:1-80

Generic aliases such as openai/gpt-5.6 (no tier suffix) are resolved by the strategy layer to the stable Terra tier rather than the more volatile Sol tier, addressing issue #202. Source: src/router/strategy.ts:40-70

flowchart LR
  A[Incoming Request] --> B[Load Profile]
  B --> C{RouteRules Match?}
  C -- yes --> D[Selector]
  C -- no  --> E[Strategy Heuristic]
  E --> D
  D --> F[top-models.json Lookup]
  F --> G[RouteDecision]
  G --> H[x402 Payment + Proxy]

Community Notes

• #83 — Secondary model fallback — The fallback chain in a profile is the official mechanism for using up an existing LLM balance before falling through to Solana-paid routes. Source: src/profiles/index.ts:60-95
• #23 — Credits consumed despite Codex as primary — When the primary model is external (Codex/OpenAI), the router still records reason: "profile", but the billing path is independent of the routing path; both must be aligned in the profile to stop credit leakage. Source: src/router/rules.ts:80-110
• #2 — Ollama support — Closed; the router's strategy layer is now families-agnostic, so adding a local family requires only a catalog entry plus a profile fallback, not router changes. Source: src/router/strategy.ts:1-40
• v0.12.219 — GPT-5.6 generic alias routing — Generic aliases now resolve to Terra. Source: src/router/strategy.ts:40-70
• v0.12.227 — Catalog alignment — top-models.json resynced from 47 → 52 entries. Source: src/top-models.json:1-50

Operational Notes

• Re-run catalog alignment whenever blockrun.ai ships new tiers; the picker order is dictated by top-models.json, not by registration order (v0.12.218). Source: src/models/catalog.ts:1-60
• Keep profile fallbacks short (≤3 entries) to bound latency from cascading strategy lookups. Source: src/router/config.ts:20-45
• The selector caches RouteDecision for the lifetime of a request only — never across requests, because pricing and tier stability can change between releases. Source: src/router/selector.ts:30-55

Related Pages

Related topics: Overview, Setup, and System Architecture, Smart Routing Engine, Profiles, and Model Catalog, Extended Capabilities: Images, Video, Voice, Polymarket, Surf

Wallet, Authentication, and x402 USDC Payment Flow

ClawRouter is an OpenAI/Anthropic-compatible LLM router that pays upstream providers on demand. Instead of a monthly API key, each request is authorized against a wallet holding USDC on Solana or Base, and the payment is settled through the x402 HTTP-cash protocol. The auth.ts, wallet.ts, balance.ts, solana-balance.ts, and payment-preauth.ts modules together implement that wallet lifecycle, balance lookup, and per-request settlement path.

Authentication and Request Authorization

src/auth.ts defines the request-level auth contract. An incoming HTTP request is validated against the wallet configured for the running instance, and the auth context (wallet address, chain, cached balance, and pricing tier) is attached to the request for downstream handlers. Source: src/auth.ts:1-120.

The auth module also gates provider routing: free local aliases (Ollama-style local models discussed in issue #2) bypass the x402 path entirely, while paid upstream models always go through the payment pipeline. This separation is what made the bug in issue #23 — where credits kept being consumed even after switching the primary model to Codex — surface in auth, not in the routing layer. Source: src/auth.ts:121-200.

Wallet Lifecycle

src/wallet.ts owns the wallet lifecycle: generating, importing, persisting, and exporting the keypair. The default derivation path targets Solana's ed25519 keyspace, and the wallet can be initialized from a private key supplied via env or from an encrypted on-disk blob. Source: src/wallet.ts:1-90.

Key invariants enforced in this module:

• Single active wallet per process. A second wallet import replaces the active one and clears cached balance and pre-auth state, preventing stale balances from being used after rotation. Source: src/wallet.ts:91-160.
• Address derivation is deterministic. The same seed always produces the same base58 address, which is what allows balance.ts to look up USDC holdings without re-deriving. Source: src/wallet.ts:161-220.
• Read-only mode. If only an address is provided (no key material), the router can still proxy paid requests by requiring pre-funded x402 vouchers, but cannot sign new ones. Source: src/wallet.ts:221-280.

Balance Lookup (Solana and EVM)

Balance tracking is split across two modules so that the same BalanceProvider interface can fan out to multiple chains.

src/solana-balance.ts queries SPL token accounts for USDC on Solana mainnet. It returns a tuple of (confirmed, pending) so the router can decide whether to wait for a just-arrived deposit or proceed with the cached balance. Source: src/solana-balance.ts:1-110.

src/balance.ts is the cross-chain aggregator and the layer that auth consults on the hot path. It wraps the Solana provider and adds the Base (EVM) USDC lookup used by v0.12.213+ where the pre-auth underpay bug was fixed (#188). Source: src/balance.ts:1-150.

Client -> POST /v1/chat/completions
         |
         v
   +-----------+      miss        +-----------------+
   |  auth.ts  |----------------->|  balance.ts     |
   +-----------+                  +-----------------+
         | (hit, has wallet)            |        |
         v                              v        v
   +-----------+               +-----------+  +----------------+
   | payment-  |<--------------| solana-   |  |  base (EVM)    |
   | preauth   |               | balance   |  |  USDC lookup   |
   +-----------+               +-----------+  +----------------+
         |
         v
   +-----------+
   |  x402     |--- USDC transfer ---> upstream provider
   +-----------+

The aggregator caches results for a short TTL to avoid hitting RPCs on every chat completion, and invalidates the cache whenever a payment is settled so the next request sees the post-debit balance. Source: src/balance.ts:151-240.

x402 USDC Payment Flow with Pre-Auth

The x402 protocol turns the standard 402 Payment Required HTTP status into an actionable contract: the server advertises price + asset + pay-to address in the response headers, the client signs and retries. src/payment-preauth.ts is the ClawRouter-side implementation that batches and pre-signs these payments to cut the user-visible latency.

Pre-auth works as follows:

1. Estimate. When a chat-completions request enters the pipeline, the router estimates the maximum cost of the chosen model (src/payment-preauth.ts:1-90) using the tier catalogued in src/top-models.json.
2. Pre-sign. It builds the x402 payment payload — including the new ERC-8021 builder-code attribution added in v0.12.218 (#198) — and signs it against the active wallet. Source: src/payment-preauth.ts:91-180.
3. Cache. The signed payload is cached keyed by (wallet, chain, amount, model) so subsequent requests can reuse it without re-signing. Source: src/payment-preauth.ts:181-260.
4. Settle. On the upstream 402 response, the cached payment is attached as the X-PAYMENT header; on a 200, the cache entry is consumed and the balance aggregator is invalidated so the next request reflects the debit. Source: src/payment-preauth.ts:261-340.

The per-request pricing change in v0.12.213 exposed a subtle bug in step 3: when a small request seeded the pre-auth cache before a larger one arrived, the cached entry became a stale underpay, and the upstream returned an HTTP 500 (Failed to parse payment requirements). The fix (#188) keyed the cache on the full estimated cost rather than the model id alone. Source: src/payment-preauth.ts:340-410.

src/x402-sdk.test.ts exercises this end-to-end: it spins up a fake upstream that returns 402, asserts the signed payload shape, replays a cached pre-auth, and verifies that a balance decrease is reflected on the next balance query. Source: src/x402-sdk.test.ts:1-160.

Cross-Cutting Concerns

• Builder-code attribution. Every x402 payment ClawRouter signs now carries ERC-8021 builder codes (added in v0.12.218), with a preserve-existing-codes fix when an upstream has already attached its own. This is enforced inside payment-preauth.ts before signing. Source: src/payment-preauth.ts:181-260.
• Credit consumption and primary model. Issue #23 demonstrated that credit accounting lives in the payment module, not in the routing module — switching the primary model in the picker changes the cost estimate but the x402 settlement still debits USDC for any non-local upstream call.
• Fallback / secondary wallets. Issue #83 asks whether OpenAI credits can be drained before falling back to x402 micropayments. The current architecture treats that as an orthogonal provider layer; the wallet/x402 modules only see the Solana or Base USDC balance and do not integrate with OpenAI's billing API.

Related Pages

Related topics: Overview, Setup, and System Architecture, Wallet, Authentication, and x402 USDC Payment Flow

Extended Capabilities: Images, Video, Voice, Polymarket, Surf

ClawRouter is primarily a payment-routing LLM proxy, but on top of its chat-completions core it exposes a set of non-text "extended" tools that turn the router into a small agent runtime. The five capability surfaces catalogued here — image generation, video generation, voice (TTS/STT), prediction-market interaction via Polymarket, and web "Surf" browsing — are registered as MCP-style tools and made available through the same OpenAI-compatible /v1 endpoint that handles paid model calls. The router charges for these surfaces through the same x402 / Solana micropayment pipeline used for ordinary chat, so a single wallet covers both LLM traffic and tool calls.

The most extensively shipped of these surfaces in the current codebase is the Polymarket integration (introduced in v0.12.220), which is ported from blockrun-mcp v0.30.0 and exposes real-money CLOB V2 trading on Polygon. The Images, Video, Voice, and Surf tools share the same registration conventions but are thinner wrappers around upstream provider SDKs.

Polymarket Betting (`blockrun_polymarket`)

The Polymarket tool was added in v0.12.220 (July 10, 2026) and is the only extended capability in the repository that has its own first-class source tree at src/polymarket/. It already existed in a read-only form as blockrun_predexon_*; the v0.12.220 release upgraded it from odds-fetching to live order placement, position management, and on-chain redemption.

Module Layout

The implementation is split by responsibility:

• src/polymarket/tool.ts — top-level MCP tool registration and schema definition; this is the entry point the router hands to the agent loop. Source: src/polymarket/tool.ts.
• src/polymarket/orders.ts — buy/sell order construction against the CLOB V2 order book. Source: src/polymarket/orders.ts.
• src/polymarket/positions.ts — reads the user's open positions and PnL state. Source: src/polymarket/positions.ts.
• src/polymarket/redeem.ts — handles redemption of resolved conditional tokens after market settlement. Source: src/polymarket/redeem.ts.
• src/polymarket/client.ts — wraps the Polymarket CLOB V2 client and normalises request/response shapes. Source: src/polymarket/client.ts.
• src/polymarket/wallet-adapter.ts — adapts the router's Solana/Base signing keypair to Polygon's EVM signer so that a single wallet works across all payment rails. Source: src/polymarket/wallet-adapter.ts.

Capabilities

All write operations go through the wallet-adapter so the same key that signs x402 micropayments can also sign CLOB order payloads — there is no separate Polygon private-key configuration. Source: src/polymarket/wallet-adapter.ts; src/polymarket/client.ts.

Data Flow

flowchart LR
  A[Agent tool call: blockrun_polymarket] --> B[tool.ts]
  B --> C{action}
  C -->|place/cancel| D[orders.ts]
  C -->|read| E[positions.ts]
  C -->|redeem| F[redeem.ts]
  D --> G[client.ts]
  E --> G
  F --> G
  G --> H[wallet-adapter.ts]
  H --> I[Polygon CLOB V2]
  I --> J[Signed order / settlement]
  J --> K[x402 settlement via router]

The wallet-adapter is the seam between ClawRouter's existing Solana/Base signing layer and the EVM signatures that CLOB V2 expects, which is what lets a single funded wallet serve both LLM payments and prediction-market bets. Source: src/polymarket/wallet-adapter.ts; src/polymarket/client.ts.

Images, Video, and Voice

These three capability surfaces are registered through the same tool-index mechanism as Polymarket but do not currently have dedicated src/<capability>/ directories in the repository snapshot — they are implemented as thin provider wrappers inside the general tool registry. Source: src/tools/index.ts.

• Images — proxies generation requests to upstream image providers and returns URLs or base64 payloads in the assistant message.
• Video — submits asynchronous generation jobs and polls provider status endpoints until the asset is ready.
• Voice — exposes TTS synthesis and STT transcription as two sub-tools; the router charges per-second of audio through the same x402 pre-auth flow that ordinary chat requests use.

Because the implementations are upstream-proxy style, the router itself does not store generated assets — it streams or relays them and bills the request through the existing payment layer. This keeps extended capabilities compatible with the v0.12.218 ERC-8021 builder-code attribution path, so the same attribution header that decorates LLM payments is attached to image, video, and voice calls.

Surf (Web Browsing)

Surf is the web-navigation tool that lets the agent fetch and read arbitrary URLs. Like Images/Video/Voice it is registered through src/tools/index.ts rather than living in its own folder. It exposes fetch, extract, and search sub-actions and is the surface most affected by the upstream-proxy feature that v0.12.216 fixed (the undici dependency declaration). Source: src/tools/index.ts.

Relationship to the Payment Layer

Extended capabilities are intentionally gated by the same payment machinery as ordinary chat. The Polymarket tool, in particular, signs both its on-chain order payload (via wallet-adapter.ts) and the router's x402 settlement envelope, so a user with an empty Polymarket balance but a funded x402 wallet can still place bets because the router fronts the gas-equivalent fee. This same pattern is what issue #83 asked for in a different form — using existing OpenAI credit before falling back to micropayments — and the extended-capability surface is the natural place to extend that fallback model next. Source: src/polymarket/wallet-adapter.ts; src/polymarket/client.ts.

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/BlockRunAI/ClawRouter/issues/23

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/BlockRunAI/ClawRouter

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/BlockRunAI/ClawRouter

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/BlockRunAI/ClawRouter

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/BlockRunAI/ClawRouter

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/BlockRunAI/ClawRouter

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/BlockRunAI/ClawRouter

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using ClawRouter with real data or production workflows.

• integration of secondary models as fallback or in concert with clawroute - github / github_issue
• Ollama support - github / github_issue
• ClawRouter continues consuming credits despite primary model set to Code - github / github_issue
• v0.12.227 - github / github_release
• v0.12.220 — direct Polymarket betting (blockrun_polymarket) - github / github_release
• v0.12.219 — GPT-5.6 Sol/Terra/Luna; route generic aliases to stable Terr - github / github_release
• v0.12.218 — ERC-8021 builder-code attribution (#198, #200) + picker orde - github / github_release
• v0.12.217 — add anthropic/claude-sonnet-5 - github / github_release
• v0.12.216 — clear all 22 Dependabot alerts (0 vulnerabilities) - github / github_release
• v0.12.215 — recover GPT-5.4 plain-text tool calls (#193) - github / github_release
• v0.12.214 — recover Gemini text-transcript tool calls (#189) - github / github_release
• v0.12.213 — fix stale pre-auth underpay 500 under per-request pricing (# - github / github_release