TWZRD Preflight for ClawRouter - the independent pre-spend gate

TWZRD is the independent scorer on the real Solana x402 payer graph. Use this as the preflight gate in front of ClawRouter (BlockRunAI/ClawRouter) and BlockRun spends in the OpenClaw/Moltbook ecosystem. If the ReadinessCard says block, abort before the local proxy or gateway triggers a 402.

Positioning: L7 trust annotation over L4 routing (ClawRouter local smart router + Surf marketplace + 55+ models). Does not replace ClawRouter; gates before it.

ClawRouter: local \x3C1ms routing, wallet sig auth, x402 USDC (Base primary + Solana SVM paths via sol.blockrun.ai), bundled Surf skill (83+ endpoints (see skills/surf/SKILL.md for current catalog) for CEX/DEX/on-chain SQL/pred markets/wallet intel), image/video/voice. One install for OpenClaw (plugin), Claude Code (MCP), standalone. No accounts/keys for the router itself.

No API key for TWZRD preflight. Free tier is curl.

The one rule

Before using ClawRouter (for models, Surf crypto data, Predexon, voice, etc.) or paying BlockRun:

curl -s -X POST https://intel.twzrd.xyz/v1/intel/preflight \
  -H 'content-type: application/json' \
  -d '{
    "resource_name": "ClawRouter Surf crypto data",
    "seller_wallet": "\x3CpayTo from ClawRouter 402 response or BlockRun/Surf treasury for the chain>",
    "price_usdc": 0.001,
    "agent_intent": "query surf onchain/sql or premium model via clawrouter proxy",
    "queried_pubkey": "\x3Cyour clawrouter wallet address, optional>"
  }'

Read readiness_card.decision (or top-level in some responses):

• block -> abort. Do not invoke the ClawRouter proxy (localhost:8402) or direct BlockRun call that would spend.

• warn -> proceed with caution (low corpus signal).

• allow -> proceed normally to ClawRouter/BlockRun.

Also returned: trust_score (0-100), caveats[], proof, can_spend. Gate strictly on decision=block. Free tier is conservative (many wallets default warn/can_spend=false). Fail open on preflight unavailability (timeout / non-2xx / error): log the skip, do not penalize the ClawRouter path.

Exact preflight usage (HTTP + MCP)

HTTP (no auth, as shown in the one rule; base https://intel.twzrd.xyz):

• POST /v1/intel/preflight (resource_name and/or seller_wallet required for good signal; price_usdc and agent_intent recommended).

• GET /v1/intel/score_wallet_for_intel , get_top_intel_agents, get_counterparties, get_facilitator_footprint, compare_wallets, score_wallets_batch.

• GET /v1/intel/trust/{pubkey}?seller_wallet=... (paid 0.05 USDC on Solana; returns full model + V5 receipt).

MCP (streamable-http, recommended for agents):

• https://intel.twzrd.xyz/mcp

• Primary tool: get_readiness_card_tool (resource_name, seller_wallet, agent_intent, price_usdc, queried_pubkey)

• Also: verify_receipt, get_provider_reputation, dexter_preflight, etc. (17 tools total).

OpenClaw: openclaw mcp add twzrd --url https://intel.twzrd.xyz/mcp --transport streamable-http

AgentCash already registers api.twzrd.xyz (use its MCP/CLI for mixed stables + TWZRD + preflight patterns; see AGENT_USAGE.md).

Composition

• Call TWZRD preflight first (free) for the intended ClawRouter resource (e.g. "ClawRouter Surf", "BlockRun premium model", "blockrun voice").

• If not block, proceed to ClawRouter local proxy call (OpenAI compat or direct /v1/surf/* or /v1/images etc.). ClawRouter handles its internal x402 to BlockRun treasury from the local wallet (EVM or Solana-derived via setup).

• Works with AgentCash (unified payer) or direct (@x402/fetch in custom, or ClawRouter's bundled).

• After a paid path (especially if you paid TWZRD for intel or have a settle receipt): verify with offline tool or MCP verify_receipt. Receipts are portable Ed25519 V5 anchored to Solana USDC (PayAI primary facilitator for our Solana proof). (example provides verifyReceiptIfAny stub with wiring TODO + extractPayToFrom402 helper (with usage comments; preflight demo relies on resource_name, extraction shown as illustrative for prod))

• Post-spend: store any receipt leaf for later root_provenance or independent audit if mixed with WZRD protocol.

Concrete runnable TS/JS example (full flow)

The committed minimal prototype lives in sibling example.ts (exact copy of the flow below for self-containment in ClawHub drop-ins). Update both when changing the one concrete flow.

Current status / evidence level: Prototype only; no runtime integration in this package. Self-contained doc + TS sketch.

// example.ts
// Run: npx tsx example.ts   (or ts-node, or compile to .mjs)
// Requires: ClawRouter proxy up for the call step (npx @blockrun/clawrouter or via OpenClaw + clawrouter setup).
// See sibling SKILL.md for full docs, one rule, security, publish command, links.
// This file + SKILL.md = the publishable prototype (keep both copies of the flow in sync).
// Integrity: pin verifier e.g. [email protected] (check npm tarball shasum); proxy via npx @blockrun/clawrouter@\x3Cpinned> or post-setup `ps` + `clawrouter --version`. Proxy identity: after start, check for blockrun models in /v1/models or ClawRouter headers.
//
// Concrete runnable TS prototype for one agent flow:
// TWZRD preflight (ReadinessCard gate) → ClawRouter/BlockRun call (LLM model or Surf data/marketplace) → receipt verify (if paid path used).
// TS preferred (ClawRouter is TS). Self-contained, uses native fetch (node >= 18).

type ReadinessCard = {
  decision: 'allow' | 'warn' | 'block';
  trust_score: number;
  can_spend?: boolean;
  caveats?: string[];
  proof?: any;
  paid_deep_dive?: string;
  gateAvailable?: boolean; // discriminated: false on fail-open / timeout / non-2xx (per security review)
  // plus resource echoes etc.
};

async function twzrdPreflight(params: {
  resource_name: string;
  seller_wallet?: string;
  price_usdc?: number;
  agent_intent: string;
  queried_pubkey?: string;
}): Promise\x3CReadinessCard> {
  // Minimal client guards (no new deps): length/format allow-list style on key fields.
  // Invalid input is a programming error in the CALLER - throw (hard error).
  // This is deliberately distinct from gate-unavailability below, which fails OPEN per spec.
  if (typeof params.resource_name !== 'string' || params.resource_name.length === 0 || params.resource_name.length > 128) {
    throw new Error('[twzrd-clawrouter] invalid resource_name (must be a 1-128 char string)');
  }
  if (params.price_usdc != null && (typeof params.price_usdc !== 'number' || params.price_usdc \x3C 0 || params.price_usdc > 10)) {
    throw new Error('[twzrd-clawrouter] price_usdc out of sanity range (0-10 USDC)');
  }
  const base = 'https://intel.twzrd.xyz';
  const controller = new AbortController();
  const to = setTimeout(() => controller.abort(), 10000); // top-level timeout on preflight step
  try {
    const res = await fetch(`${base}/v1/intel/preflight`, {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify(params),
      signal: controller.signal,
    });
    clearTimeout(to);
    if (!res.ok) {
      const status = res.status;
      console.warn('[twzrd-clawrouter] preflight non-2xx (' + status + ') - fail open (per spec)');
      return { decision: 'allow', trust_score: 50, gateAvailable: false };
    }
    const json: any = await res.json();
    const card: ReadinessCard = json.readiness_card || json;
    console.log('[twzrd-clawrouter] preflight decision=' + card.decision + ' trust_score=' + card.trust_score);
    if (card.caveats && card.caveats.length) {
      console.log('  first caveat:', String(card.caveats[0]).slice(0, 200));
    }
    return { ...card, gateAvailable: true };
  } catch (err: any) {
    clearTimeout(to);
    const safe = String(err?.message || err).slice(0, 200); // truncation
    console.warn('[twzrd-clawrouter] preflight error/timeout - fail open:', safe);
    return { decision: 'allow', trust_score: 50, gateAvailable: false };
  }
}

async function callClawRouterProxy(path: string, init?: RequestInit): Promise\x3CResponse> {
  // Local proxy (default port from ClawRouter). Handles wallet auth + x402 to BlockRun/Surf internally.
  // For Surf: see ClawRouter's skills/surf/SKILL.md (83+ endpoints, no separate account; same wallet).
  // Pricing tiers in research: T1 $0.001, T2 $0.005, T3 $0.020.
  const proxyBase = process.env.CLAWROUTER_PROXY_BASE || 'http://localhost:8402';
  // allow-list style path guard (prototype): only /v1/ prefixes for known surfaces + explicit root for the HEAD probe in main()
  if (path !== '/' && !path.startsWith('/v1/')) {
    throw new Error('disallowed proxy path (prototype allow-list)');
  }
  const controller = new AbortController();
  const to = setTimeout(() => controller.abort(), 15000);
  try {
    const resp = await fetch(proxyBase + path, { ...(init||{}), signal: controller.signal });
    clearTimeout(to);
    return resp;
  } catch (e) {
    clearTimeout(to);
    throw e;
  }
}

async function verifyReceiptIfAny(receipt: unknown, note: string): Promise\x3Cboolean> {
  // If the flow used a paid TWZRD path (0.05 USDC V5 receipt) alongside or instead, verify offline.
  // Command (portable, trusts only the published signer): npx twzrd-receipt-verifier receipt.json --pubkey \x3Ckey from .well-known/x402>
  // Or via MCP: the twzrd server's verify_receipt tool.
  // For ClawRouter settles themselves: the on-chain USDC tx (Base or Sol) + facilitator receipt is the proof; preflight already scored the seller.
  if (!receipt) {
    console.log('[twzrd-clawrouter] verify step: no receipt provided (e.g. free T1 path or ClawRouter internal settle); skipping.');
    return true;
  }
  console.log('[twzrd-clawrouter] verify step for paid path (' + note + '):');
  console.log('  npx twzrd-receipt-verifier \x3Creceipt.json> --pubkey $(curl -s https://intel.twzrd.xyz/.well-known/x402 | ... signer)');
  console.log('  (or MCP verify_receipt). Persist leaf + preimage.');
  // TODO: integrate real verification (subprocess to npx twzrd-receipt-verifier or MCP call) that returns false and exits on failure.
  // Example (commented, uses builtin; pin version for integrity):
  // const { execSync } = await import('child_process');
  // try {
  //   execSync('npx [email protected] --version', { stdio: 'inherit' });
  //   // ... actual verify command; on !pass: process.exit(1); return false;
  // } catch { console.error('VERIFY FAIL'); process.exit(1); return false; }
  // Real impl asserts PASS or exits. Prototype returns true (see security notes).
  // NOTE for demo: in the executable main() this is always invoked with null (free/internal path); stub returns true without exercising the paid verification branch. Explicit stub for structural prototype only.
  return true;
}

function extractPayToFrom402(resp: Response | null): string | undefined {
  // Helper to extract payTo from 402 response/headers for precise preflight scoring (addresses security review).
  // helper provided for integration; not exercised in this minimal demo (resource_name path used)
  // In real: inspect 402 body (accepts[0].payTo) or x-payment / www-authenticate header from blockrun.ai/sol.blockrun.ai before proxy call.
  // For this prototype demo we pass via comment in preflight; use observed from prior 402 or known treasury.
  if (!resp) return undefined;
  try {
    const h = resp.headers.get('www-authenticate') || resp.headers.get('x-402') || '';
    if (h && h.includes('payTo=')) {
      const m = h.match(/payTo=([^,\s;]+)/i);
      if (m) return m[1];
    }
  } catch {}
  // Fallback note: for Surf/BlockRun the treasury is documented in ClawRouter README (Base primary).
  return undefined;
}

async function main() {
  console.log('=== twzrd-clawrouter prototype flow start ===');

  // Proxy config + cheap startup probe (env override + note for authentic ClawRouter identity)
  const PROXY_BASE = process.env.CLAWROUTER_PROXY_BASE || 'http://localhost:8402';
  console.log('[twzrd-clawrouter] proxy base:', PROXY_BASE, '(override with CLAWROUTER_PROXY_BASE env; must be authentic ClawRouter instance - check version/headers/ps after `npx @blockrun/clawrouter`)');
  // Cheap probe (non-fatal; illustrative integrity): reachability + note on identifying response.
  // In prod: assert response includes ClawRouter-specific marker or /v1/models contains 'blockrun'.
  (async () => {
    try {
      const p = await fetch(PROXY_BASE + '/', { method: 'HEAD', signal: AbortSignal.timeout(1500) });
      console.log('[twzrd-clawrouter] proxy probe (HEAD /):', p.status);
    } catch { /* silent for prototype */ }
  })();

  // STEP 1: TWZRD preflight (ReadinessCard gate) - free, before any ClawRouter/BlockRun spend.
  // resource_name describes the ClawRouter surface. seller_wallet optional but best when you have the payTo (from 402 or treasury).
  // Use observed payTo for Surf/BlockRun treasury when doing direct or logging the challenge.
  // Example extraction (post a 402 if surfaced, or pre-known): const payTo = extractPayToFrom402(...);
  // (helper provided for integration; not exercised in this minimal demo (resource_name path used))
  const card = await twzrdPreflight({
    resource_name: 'ClawRouter Surf crypto data or premium LLM via blockrun',
    // seller_wallet: e.g. the pay_to address from blockrun.ai 402 or sol.blockrun.ai (Base primary for Surf; Solana path supported). Use extractPayToFrom402( priorResp ) in real flows.
    // For demo we rely on resource_name + heuristics in TWZRD corpus. Pass real one in prod agents.
    price_usdc: 0.001,
    agent_intent: 'preflight gate then clawrouter call for surf market data or model inference',
    // queried_pubkey: set to the ClawRouter wallet pubkey (printed on setup; EVM 0x... or Solana base58) for better attribution
  });

  if (card.gateAvailable === false) {
    console.log('[twzrd-clawrouter] gate unavailable (fail-open; no distinguishable hard block from gate)');
  }
  if (card.decision === 'block') {
    console.error('BLOCK from TWZRD preflight - aborting per the one rule. Do not call ClawRouter.');
    process.exit(1);
  }
  if (card.decision === 'warn') {
    console.warn('WARN from TWZRD - low signal or caveats; proceeding cautiously (per spec).');
  } else {
    console.log('ALLOW from TWZRD preflight - safe to proceed to ClawRouter/BlockRun.');
  }

  // STEP 2: ClawRouter/BlockRun call (for LLM model or Surf data/marketplace).
  // This is where x402 happens inside ClawRouter (from its local wallet). Our gate was before.
  // Real example uses the Surf catalog (or /v1/chat/completions with blockrun/auto etc.).
  // See ClawRouter README + skills/surf/SKILL.md for exact endpoints + tiers.
  console.log('Proceeding to ClawRouter proxy call (post preflight gate)...');
  const surfPath = '/v1/surf/market/price?symbol=BTC'; // T1 cheap example; onchain/sql is T3.
  const surfResp = await callClawRouterProxy(surfPath);
  // post-response handling + minimal status check (per review)
  if (!surfResp.ok) {
    console.warn('[twzrd-clawrouter] post-call non-ok status from proxy (may be handled 402 inside or error):', surfResp.status);
    // real: could inspect for settlement simulation errs etc; here we still read body for shape
  }
  let surfData: any = { status: surfResp.status, note: 'see proxy response; 402s auto-handled by ClawRouter' };
  try {
    surfData = await surfResp.json();
  } catch {}
  // truncate full downstream in log
  console.log('ClawRouter/BlockRun Surf (or model) response shape:', String(JSON.stringify(surfData)).slice(0, 300));

  // (LLM example would be similar: POST /v1/chat/completions with model blockrun/..., apiKey x402 at proxy)
  // const chatResp = await callClawRouterProxy('/v1/chat/completions', { method: 'POST', headers: {'content-type': 'application/json'}, body: JSON.stringify({model: 'blockrun/auto', messages: [{role:'user', content: 'hi via gated clawrouter'}] }) });

  // STEP 3: receipt verify (if paid path used).
  // - If you called a paid TWZRD resource (e.g. /v1/intel/trust) in same session: verify its V5 receipt.
  // - ClawRouter's own settles have their on-chain proof (USDC tx on Base/Sol); preflight + corpus is the TWZRD annotation.
  // - Always persist receipts for audit / onBeforeSettle style hooks.
  // Demo exercises the null case only (stub returns true); real paid receipt verification is the TODO for prod.
  await verifyReceiptIfAny(null, 'post-clawrouter paid path or TWZRD intel');

  console.log('=== flow complete (preflight gate → ClawRouter call → verify) ===');
  console.log('Reminders from SKILL.md: dedicated wallet only, smallest amounts, fail-open preflight, verify all receipts, extract real seller_wallet from 402 when possible.');
}

// Direct invocation: this is a demo script, not a library.
// Do NOT gate on import.meta.main - it is Bun/Deno/node>=24.2 only and silently
// skips main() on node 18/20/22 (the stated supported runtimes).
main().catch((err) => {
  console.error('prototype error:', err);
  process.exit(1);
});

Save as example.ts next to this SKILL.md. Run with npx tsx example.ts (or node --loader ts-node/esm / compile). The proxy step assumes ClawRouter is up (see ClawRouter README quickstart). The example now includes: env-configurable proxy, AbortSignal timeouts + log truncation + param guards, discriminated gateAvailable, payTo extraction helper, post-response status check, verify with TODO real-wiring sketch (prototype stub always succeeds for the null demo receipt).

Security notes

• Dedicated wallet: ClawRouter auto-gens on first run (EVM primary + Solana mnemonic; Base balance monitor primary; Solana derivation supported). Backup the printed mnemonic/wallet.key immediately. Never put significant funds here.

• Smallest amounts: Free tier (6 NVIDIA models) or T1 Surf ($0.001) first. Top up $1-5 USDC on Base (or Sol for SVM). Use /model free or blockrun/auto with fallbacks.

• Verify receipts: Always for any paid TWZRD V5 (npx twzrd-receipt-verifier or MCP). For ClawRouter settles, the proxy + facilitator provide the on-chain tx; cross with our corpus via preflight. The verifyReceiptIfAny in example is a documented stub (TODO real subprocess/MCP; returns true for demo).

• Fail-open: preflight unavailability must not block ClawRouter usage. Log "TWZRD preflight skipped (unavailable)" and continue. The ReadinessCard now includes gateAvailable (false on fail-open paths); callers can distinguish.

• Extract real seller_wallet: inspect the 402 Payment header from blockrun.ai (or sol.blockrun.ai) before/after proxy; pass the payTo for accurate scoring (example.ts now ships extractPayToFrom402 helper + call site comments). Resource_name alone works for coarse gate.

• Cross with AgentCash when mixing surfaces (stables + TWZRD + others); it handles 402 sign/retry + SIWS.

• No browser secrets, no shared wallets in prod agents. Monitor balance (ClawRouter has built-in pre-checks). Prototype adds AbortSignal timeouts, truncated logs, input guards, proxy allow-list, env config + probe.

• Proxy / verifier provenance (informational): pin versions ([email protected]; npx @blockrun/clawrouter); after launch use ps + version output or /v1/models content for identity assertion. No embedded hash in prototype (add in prod integration).

Links

• TWZRD: https://intel.twzrd.xyz/.well-known/x402 (exact Solana USDC descriptor + receipt spec), /llms.txt, /openapi.json, /mcp

• ClawRouter: https://github.com/BlockRunAI/ClawRouter (raw README, openclaw.plugin.json, skills/surf/SKILL.md with 83+ endpoints (see catalog for exact), proxy.ts/auth.ts for x402 wallet flow)

• BlockRun: https://blockrun.ai (gateway, models, marketplace/surf, "one install", Base+Sol)

• Moltbook: https://www.moltbook.com/skill.md (agent social/heartbeat for OpenClaw; no x402; human X claim for verified)

• AgentCash (buyer client, our origin registered): https://agentcash.dev/ + MCP (use for preflight + fetch patterns)

• x402 Bazaar + peers: https://docs.cdp.coinbase.com/x402/bazaar , https://x402.org , Dexter (free Solana), pay.sh

• Verifier + packages: npm/pip twzrd-receipt-verifier; packages/twzrd-agent-intel (AGENT_USAGE.md, examples/agent_preflight_example.py, MCP tools)

Publish prep for ClawHub/OpenClaw

• Version: 0.1.0 (prototype implementing the top bet)

• Changelog:

  • 0.1.0: Initial self-contained SKILL.md + concrete TS example.ts for ClawRouter/OpenClaw preflight integration prototype. Exact one-rule gate + full preflight→ClawRouter/BlockRun→verify flow. No new runtime code; docs + example only.

• Tags: x402, clawrouter, openclaw, preflight, trust, solana, usdc, blockrun, surf, agentcash, receipt

• Publish command (verified against local clawhub CLI 0.7.0 - it takes the folder path, there is NO skill subcommand; re-check clawhub publish --help at publish time, the CLI is evolving):

# Publisher (founder keystroke - interactive MIT-0 license accept, no --accept-license flag exists):
clawhub publish packages/twzrd-agent-intel/skills/twzrd-clawrouter \
  --slug twzrd-clawrouter --name "TWZRD Preflight for ClawRouter" --version 0.1.0 \
  --tags x402,clawrouter,openclaw,preflight,trust,solana,usdc,blockrun,surf
# NOTE: ClawHub skills are licensed MIT-0 (compulsory, no per-skill override) - this covers
# both SKILL.md and example.ts. Crypto/payment skills get the strictest post-publish scanning
# (VirusTotal + Code Insight + coherence audit, result public at /\x3Cowner>/\x3Cslug>/security-audit).

# Consumers (after the skill is live on ClawHub):
openclaw skills install twzrd-clawrouter
# Wire the MCP backend:
openclaw mcp add twzrd --url https://intel.twzrd.xyz/mcp --transport streamable-http
# Instruct orchestrator/agent: "read skills/twzrd-clawrouter/SKILL.md and obey the one rule before any ClawRouter/BlockRun x402."

Self-contained. Drop the SKILL.md (and example.ts) into ClawHub/OpenClaw skill surfaces or workspace. No server changes needed.

More

• Machine-readable: https://intel.twzrd.xyz/.well-known/x402
• Agent usage + preflight py reference: packages/twzrd-agent-intel/AGENT_USAGE.md + examples/
• SDK for Solana side (receipts, protocol): sdk/
• Live MCP tools (twzrd + agentcash for payer): get_readiness_card_tool before any spend.

Use the gate. Stop the pay-then-discover-bad pattern.