feat: add BlockRun / ClawRouter as native LLM provider with x402 micropayments

[1bcMax]

What this PR does

Adds BlockRun (blockrun.ai) as a first-class provider in hermes-agent, alongside OpenRouter, Nous, and Anthropic. BlockRun is an OpenAI-compatible model gateway that uses x402 micropayments instead of API keys — your crypto wallet IS your credential.

Why it's different from OpenRouter

	OpenRouter	BlockRun
Auth	API key	Crypto wallet (non-custodial)
Payment	Monthly subscription or prepaid credits	Per-request USDC (Base or Solana)
Models	200+	50+
Unique data	—	X/Twitter, prediction markets, live crypto
Agent-native	No	Yes — autonomous x402 payments

Files added

tools/blockrun_tool.py          10 tools: wallet (Base+Solana), images, prediction markets
hermes_cli/blockrun_provider.py x402-aware httpx transport + provider resolver
skills/blockrun/SKILL.md        Full user-facing documentation for the Skills Hub
tests/test_blockrun.py          51 tests (37 unit + 14 live: 4 model families + streaming + tools)

Files modified (minimal)

hermes_cli/runtime_provider.py  +15 lines: add "blockrun"/"clawrouter" branch
toolsets.py                     +24 lines: register "blockrun" toolset
.env.example                    +18 lines: BLOCKRUN_WALLET_KEY, SOLANA_WALLET_KEY
cli-config.yaml.example         +18 lines: blockrun provider example
pyproject.toml                  +9 lines: optional [blockrun] and [blockrun-solana] extras

---

How it works

hermes-agent  →  openai.OpenAI(http_client=BlockRunX402Transport)
                      │
                      ▼  on HTTP 402 response
                 sign payment locally (EIP-712 or Ed25519)
                 retry with PAYMENT-SIGNATURE header
                      │
                      ▼
                 blockrun.ai/api/v1  →  model provider  →  response

Payment signing is non-custodial — the private key never leaves the user's machine. Only the cryptographic signature is transmitted to BlockRun's servers.

Every request carries User-Agent: hermes-agent/blockrun-integration/1.0.0 so BlockRun can track hermes traffic.

---

User setup (3 steps)

# 1. Install
pip install "hermes-agent[blockrun]"

# 2. Create wallet (inside hermes, or from terminal)
blockrun_wallet_setup   # hermes tool — creates ~/.blockrun/.session

# 3. Configure
# cli-config.yaml:
model:
  provider: "blockrun"
  default: "openai/gpt-5.2"

Fund with $5–$20 USDC on Base: https://blockrun.ai/fund

---

Supported chains

Chain	Gateway	Signing	Env var
Base (default)	blockrun.ai/api/v1	EIP-712	BLOCKRUN_WALLET_KEY=0x...
Solana	sol.blockrun.ai/api/v1	Ed25519	SOLANA_WALLET_KEY=<base58>

Chain auto-detected from which env var is set. Override: BLOCKRUN_CHAIN=solana.

---

Tools included

Wallet management

Tool	Description
blockrun_wallet_setup	Create/load Base wallet, show address + QR
blockrun_wallet_balance	Check USDC balance + session spend
blockrun_wallet_address	Get address + funding links (no key exposure)
blockrun_solana_wallet_setup	Create/load Solana wallet
blockrun_solana_wallet_balance	Check SPL-USDC balance

Image generation (x402, $0.02–$0.10/image)

Tool	Description
blockrun_image_generate	DALL-E 3, GPT Image 1, Flux, Nano Banana (up to 4K)
blockrun_image_edit	Inpainting with GPT Image 1

Prediction markets (x402, $0.001–$0.005/call)

Tool	Description
blockrun_prediction_markets	Polymarket, Kalshi, dFlow, Binance candles, cross-platform

---

Test coverage

37 unit tests  — no network, no wallet needed
14 live tests  — real x402 payments (~$0.02 total cost)

pytest tests/ -v            # unit only
pytest tests/ -v -m live    # + live API

Multi-model live tests (TestLiveMultiModel)

Test	Model	What it checks
test_nvidia_basic	nvidia/gpt-oss-20b	Free model, basic completion
test_openai_basic	openai/gpt-5-mini	OpenAI family
test_anthropic_basic	anthropic/claude-haiku-4.5	Anthropic family
test_google_basic	google/gemini-2.5-flash	Google family
test_system_prompt	openai/gpt-5-mini	System prompt respected
test_multi_turn	openai/gpt-5-mini	Conversation history maintained
test_streaming	openai/gpt-5-mini	Stream chunking works
test_tool_calling	openai/gpt-5-mini	Function calling / tools
test_models_endpoint	—	/models lists all 4 families
test_user_agent_header_sent	nvidia/gpt-oss-20b	hermes-agent in User-Agent

All 51 tests pass.

---

Dependencies

New optional extras (zero impact on existing installs):

[project.optional-dependencies]
blockrun        = ["blockrun-llm>=0.10.0", "eth-account>=0.13.0"]
blockrun-solana = ["blockrun-llm>=0.10.0", "solders>=0.21.0", "base58>=2.1.1"]