@blockrun/llm 2.12.0 → 3.0.0

package/README.md

@@ -1,1302 +1,1323 @@
-# @blockrun/llm (TypeScript SDK)
-
-> **@blockrun/llm** is a TypeScript/Node.js SDK for accessing 41+ large language models (GPT-5, Claude, Gemini, Grok, DeepSeek, Kimi, and more) with automatic pay-per-request USDC micropayments via the x402 protocol. No API keys required — your wallet signature is your authentication. Supports **streaming**, smart routing, Base and Solana chains.
->
-> 🆓 **Includes 8 fully-free NVIDIA-hosted models** (6 visible in `/v1/models`, 2 hidden but directly callable) — DeepSeek V4 Flash (1M context), Nemotron Nano Omni (vision), Qwen3, Llama 4, Mistral, plus the gpt-oss pair. Zero USDC, no rate-limit gimmicks. Use `routingProfile: 'free'` or call any `nvidia/*` model directly.
-
-[![npm](https://img.shields.io/npm/v/@blockrun/llm.svg)](https://www.npmjs.com/package/@blockrun/llm)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-
-## Supported Chains
-
-| Chain | Network | Payment | Status |
-|-------|---------|---------|--------|
-| **Base** | Base Mainnet (Chain ID: 8453) | USDC | Primary |
-| **Base Testnet** | Base Sepolia (Chain ID: 84532) | Testnet USDC | Development |
-| **Solana** | Solana Mainnet | USDC (SPL) | New |
-
-> **XRPL (RLUSD):** Use [@blockrun/llm-xrpl](https://www.npmjs.com/package/@blockrun/llm-xrpl) for XRPL payments
-
-**Protocol:** x402 v2 (CDP Facilitator)
-
-## Installation
-
-```bash
-# Base and Solana support (optional Solana deps auto-installed)
-npm install @blockrun/llm
-# or
-pnpm add @blockrun/llm
-# or
-yarn add @blockrun/llm
-```
-
-## Quick Start (Base - Default)
-
-```typescript
-import { LLMClient } from '@blockrun/llm';
-
-const client = new LLMClient();  // Uses BASE_CHAIN_WALLET_KEY (never sent to server)
-const response = await client.chat('openai/gpt-4o', 'Hello!');
-```
-
-That's it. The SDK handles x402 payment automatically.
-
-## `BlockrunClient` — the universal primitive (recommended for new code)
-
-Starting in `2.5.0`, the SDK ships a single `BlockrunClient` that speaks to
-**every** BlockRun endpoint over x402. New API surfaces are intended to be
-distributed as [Claude Code skills](https://github.com/anthropics/skills)
-that drive this primitive — no SDK release required to add an endpoint.
-
-```typescript
-import { BlockrunClient } from '@blockrun/llm';
-
-const br = new BlockrunClient();
-
-// Sync GET — Surf market price (Tier 1, $0.001)
-const btc = await br.get('/v1/surf/market/price', { symbol: 'BTC' });
-
-// Sync POST — raw on-chain SQL (Tier 3, $0.020)
-const rows = await br.post('/v1/surf/onchain/sql', {
-  query: 'SELECT block_number FROM ethereum.blocks ORDER BY block_number DESC LIMIT 1',
-});
-
-// Submit + poll — long-running video gen (settled only on completion)
-const video = await br.poll('/v1/videos/generations', {
-  model: 'xai/grok-imagine-video',
-  prompt: 'a red apple spinning',
-});
-
-// Streaming SSE — chat completions
-for await (const chunk of br.stream('/v1/chat/completions', {
-  model: 'anthropic/claude-sonnet-4-6',
-  messages: [{ role: 'user', content: 'Hi' }],
-  stream: true,
-})) {
-  process.stdout.write(chunk?.choices?.[0]?.delta?.content ?? '');
-}
-```
-
-Four call shapes cover every endpoint type:
-- `get<T>(path, params?)` — synchronous GET (price, ranking, list, news)
-- `post<T>(path, body?)` — synchronous POST (on-chain SQL, search)
-- `poll<T>(path, body?, { budgetMs, intervalMs })` — submit + poll (image, video, music, voice)
-- `stream<T>(path, body?)` — async iterator over SSE chunks (chat)
-
-The per-API client classes (`LLMClient`, `ImageClient`, `VideoClient`,
-`PortraitClient`, `VoiceClient`, `MusicClient`, `SearchClient`, `XClient`,
-`PriceClient`, `SurfClient`) all remain — they will be soft-deprecated in 2.6 (rewritten as
-shims over `BlockrunClient`) and removed in 3.0.
-
-### Try It Free (No USDC Required)
-
-Want to kick the tires before funding a wallet? Route to BlockRun's free NVIDIA tier:
-
-```typescript
-import { LLMClient } from '@blockrun/llm';
-
-const client = new LLMClient();  // Wallet still required for signing, but $0 charged
-
-// Option 1: call a free model directly
-const reply = await client.chat('nvidia/qwen3-next-80b-a3b-thinking', 'Explain x402 in 1 sentence');
-
-// Option 2: let the smart router pick the best free model per request
-const result = await client.smartChat('What is 2+2?', { routingProfile: 'free' });
-console.log(result.model);     // e.g. 'nvidia/deepseek-v4-flash' (cheapest capable for SIMPLE tier)
-console.log(result.response);  // '4'
-```
-
-**Available free models** (input + output both $0, all NVIDIA-hosted, last refreshed 2026-04-28):
-
-| Model ID | Context | Best For |
-|----------|---------|----------|
-| `nvidia/deepseek-v4-flash` | 1M | DeepSeek V4 Flash — 284B / 13B active MoE, ~5× faster than V4 Pro. Best free chat / summarization / light reasoning |
-| `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning` | 256K | Only vision-capable free model — text + images + video (≤2 min) + audio (≤1 hr) |
-| `nvidia/qwen3-next-80b-a3b-thinking` | 131K | 116 tok/s reasoning with thinking mode |
-| `nvidia/mistral-small-4-119b` | 131K | 114 tok/s — fastest free chat |
-| `nvidia/llama-4-maverick` | 131K | Meta Llama 4 Maverick MoE |
-| `nvidia/qwen3-coder-480b` | 131K | Coding-optimised 480B MoE |
-| `nvidia/gpt-oss-120b` | 128K | OpenAI open-weight 120B — 123 tok/s. Hidden from `/v1/models` for privacy but direct calls still work |
-| `nvidia/gpt-oss-20b` | 128K | OpenAI open-weight 20B — 155 tok/s. Hidden from `/v1/models` but direct calls still work |
-
-> Need V4-Pro-class reasoning? Use the paid `deepseek/deepseek-v4-pro` ($0.435/$0.87 — the 75% launch promo became the permanent list price after 2026-05-31) — `nvidia/deepseek-v4-pro` is currently hidden because NVIDIA's NIM deployment is hung; backend MODEL_REDIRECTS forwards calls to V4 Flash.
-
-> Privacy note: `nvidia/gpt-oss-120b` and `nvidia/gpt-oss-20b` are hidden from `/v1/models` because NVIDIA's free build.nvidia.com tier reserves the right to use prompts/outputs for service improvement. Direct calls by full model ID still work — opt in only when your data isn't sensitive.
-
-## Quick Start (Solana)
-
-```typescript
-import { SolanaLLMClient } from '@blockrun/llm';
-
-// SOLANA_WALLET_KEY env var (bs58-encoded Solana secret key)
-const client = new SolanaLLMClient();
-const response = await client.chat('openai/gpt-4o', 'gm Solana');
-console.log(response);
-```
-
-Set `SOLANA_WALLET_KEY` to your bs58-encoded Solana secret key. Payments are automatic via x402 — your key never leaves your machine.
-
-## Solana Support
-
-Pay for AI calls with Solana USDC via [sol.blockrun.ai](https://sol.blockrun.ai):
-
-```typescript
-import { SolanaLLMClient } from '@blockrun/llm';
-
-// SOLANA_WALLET_KEY env var (bs58-encoded Solana secret key)
-const client = new SolanaLLMClient();
-
-// Or pass key directly
-const client2 = new SolanaLLMClient({ privateKey: 'your-bs58-solana-key' });
-
-// Same API as LLMClient
-const response = await client.chat('openai/gpt-4o', 'gm Solana');
-console.log(response);
-
-// Live Search with Grok (Solana payment)
-const tweet = await client.chat('xai/grok-3-mini', 'What is trending on X?', { search: true });
-```
-
-**Setup:**
-1. Export your Solana wallet key: `export SOLANA_WALLET_KEY="your-bs58-key"`
-2. Fund with USDC on Solana mainnet
-3. That's it — payments are automatic via x402
-
-**Supported endpoint:** `https://sol.blockrun.ai/api`
-**Payment:** Solana USDC (SPL, mainnet)
-
-## How It Works
-
-1. You send a request to BlockRun's API
-2. The API returns a 402 Payment Required with the price
-3. The SDK automatically signs a USDC payment on Base
-4. The request is retried with the payment proof
-5. You receive the AI response
-
-**Your private key never leaves your machine** - it's only used for local signing.
-
-## Smart Routing (ClawRouter)
-
-Let the SDK automatically pick the cheapest capable model for each request:
-
-```typescript
-import { LLMClient } from '@blockrun/llm';
-
-const client = new LLMClient();
-
-// Auto-routes to cheapest capable model
-const result = await client.smartChat('What is 2+2?');
-console.log(result.response);     // '4'
-console.log(result.model);        // 'moonshot/kimi-k2.5' (cheap, fast)
-console.log(`Saved ${(result.routing.savings * 100).toFixed(0)}%`); // 'Saved 78%'
-
-// Complex reasoning task -> routes to reasoning model
-const complex = await client.smartChat('Prove the Riemann hypothesis step by step');
-console.log(complex.model);  // 'xai/grok-4-1-fast-reasoning'
-
-// Inspect the fallback chain SmartChat will walk on transient errors.
-console.log(complex.routing.fallbacks);  // ['anthropic/claude-opus-4.7', ...]
-```
-
-### Automatic Fallback on Transient Errors
-
-`smartChat()` populates a tier-specific fallback chain and `chat()` /
-`chatCompletion()` walk it automatically when the primary model returns a
-transient error — timeouts, network failures, or 5xx responses (502/503/504/
-522/524). 4xx errors and `PaymentError` propagate immediately so wallet /
-auth issues surface fast.
-
-```typescript
-// Manually pass a fallback chain to chat() / chatCompletion()
-const reply = await client.chat('nvidia/deepseek-v4-flash', 'hello', {
-  fallbackModels: ['nvidia/llama-4-maverick', 'nvidia/mistral-small-4-119b'],
-});
-// If deepseek-v4-flash times out, the SDK retries against the next model
-// and logs each hop to stderr: "[@blockrun/llm] <from> -> <to> (...)".
-```
-
-### Routing Profiles
-
-| Profile | Description | Best For |
-|---------|-------------|----------|
-| `free` | NVIDIA free tier — smart-routes across 8 models (DeepSeek V4 Flash, Nemotron Nano Omni, Qwen3, Llama 4, Mistral, plus 2 hidden gpt-oss) | Zero-cost testing, dev, prod |
-| `eco` | Cheapest models per tier (DeepSeek, xAI) | Cost-sensitive production |
-| `auto` | Best balance of cost/quality (default) | General use |
-| `premium` | Top-tier models (OpenAI, Anthropic) | Quality-critical tasks |
-
-```typescript
-// Use premium models for complex tasks
-const result = await client.smartChat(
-  'Write production-grade async TypeScript code',
-  { routingProfile: 'premium' }
-);
-console.log(result.model);  // 'anthropic/claude-opus-4.7'
-```
-
-### How ClawRouter Works
-
-ClawRouter uses a 14-dimension rule-based classifier to analyze each request:
-
-- **Token count** - Short vs long prompts
-- **Code presence** - Programming keywords
-- **Reasoning markers** - "prove", "step by step", etc.
-- **Technical terms** - Architecture, optimization, etc.
-- **Creative markers** - Story, poem, brainstorm, etc.
-- **Agentic patterns** - Multi-step, tool use indicators
-
-The classifier runs in <1ms, 100% locally, and routes to one of four tiers:
-
-| Tier | Example Tasks | Auto Profile Model |
-|------|---------------|-------------------|
-| SIMPLE | "What is 2+2?", definitions | moonshot/kimi-k2.5 |
-| MEDIUM | Code snippets, explanations | xai/grok-code-fast-1 |
-| COMPLEX | Architecture, long documents | google/gemini-3.1-pro |
-| REASONING | Proofs, multi-step reasoning | xai/grok-4-1-fast-reasoning |
-
-## Available Models
-
-### OpenAI GPT-5.5 Family
-Released 2026-04-23 — first fully retrained base since GPT-4.5. 1M context, 128K output, native agent + computer use.
-
-| Model | Input Price | Output Price |
-|-------|-------------|--------------|
-| `openai/gpt-5.5` | $5.00/M | $30.00/M |
-
-### OpenAI GPT-5.4 Family
-| Model | Input Price | Output Price |
-|-------|-------------|--------------|
-| `openai/gpt-5.4` | $2.50/M | $15.00/M |
-| `openai/gpt-5.4-pro` | $30.00/M | $180.00/M |
-| `openai/gpt-5.4-nano` | $0.20/M | $1.25/M |
-
-### OpenAI GPT-5 Family
-| Model | Input Price | Output Price |
-|-------|-------------|--------------|
-| `openai/gpt-5.3` | $1.75/M | $14.00/M |
-| `openai/gpt-5.2` | $1.75/M | $14.00/M |
-| `openai/gpt-5-mini` | $0.25/M | $2.00/M |
-| `openai/gpt-5.2-pro` | $21.00/M | $168.00/M |
-| `openai/gpt-5.2-codex` | $1.75/M | $14.00/M |
-
-### OpenAI GPT-4 Family
-| Model | Input Price | Output Price |
-|-------|-------------|--------------|
-| `openai/gpt-4.1` | $2.00/M | $8.00/M |
-| `openai/gpt-4.1-mini` | $0.40/M | $1.60/M |
-| `openai/gpt-4.1-nano` | $0.10/M | $0.40/M |
-| `openai/gpt-4o` | $2.50/M | $10.00/M |
-| `openai/gpt-4o-mini` | $0.15/M | $0.60/M |
-
-### OpenAI O-Series (Reasoning)
-| Model | Input Price | Output Price |
-|-------|-------------|--------------|
-| `openai/o1` | $15.00/M | $60.00/M |
-| `openai/o1-mini` | $1.10/M | $4.40/M |
-| `openai/o3` | $2.00/M | $8.00/M |
-| `openai/o3-mini` | $1.10/M | $4.40/M |
-| `openai/o4-mini` | $1.10/M | $4.40/M |
-
-### Anthropic Claude
-| Model | Input Price | Output Price | Context | Notes |
-|-------|-------------|--------------|---------|-------|
-| `anthropic/claude-opus-4.8` | $5.00/M | $25.00/M | **1M** | Flagship — agentic coding + adaptive thinking, 128K output |
-| `anthropic/claude-opus-4.7` | $5.00/M | $25.00/M | **1M** | Agentic coding + adaptive thinking, 128K output |
-| `anthropic/claude-opus-4.6` | $5.00/M | $25.00/M | 200K | Hidden but still callable — kept as in-family hot-swap fallback |
-| `anthropic/claude-opus-4.5` | $5.00/M | $25.00/M | 200K | |
-| `anthropic/claude-opus-4` | $15.00/M | $75.00/M | 200K | |
-| `anthropic/claude-sonnet-4.6` | $3.00/M | $15.00/M | 200K | Best for reasoning/instructions |
-| `anthropic/claude-sonnet-4` | $3.00/M | $15.00/M | 200K | |
-| `anthropic/claude-haiku-4.5` | $1.00/M | $5.00/M | 200K | |
-
-### Google Gemini
-| Model | Input Price | Output Price |
-|-------|-------------|--------------|
-| `google/gemini-3.1-pro` | $2.00/M | $12.00/M |
-| `google/gemini-3.5-flash` | $0.50/M | $3.00/M |
-| `google/gemini-3.1-flash-lite` | $0.25/M | $1.50/M |
-| `google/gemini-3-flash-preview` | $0.50/M | $3.00/M |
-| `google/gemini-2.5-pro` | $1.25/M | $10.00/M |
-| `google/gemini-2.5-flash` | $0.30/M | $2.50/M |
-| `google/gemini-2.5-flash-lite` | $0.10/M | $0.40/M |
-
-### DeepSeek
-
-V4 family launched 2026-04-24. DeepSeek upstream now serves the legacy
-`deepseek-chat` / `deepseek-reasoner` aliases as V4 Flash non-thinking /
-thinking modes. V4 Pro is the new flagship paid SKU — 1.6T MoE / 49B active,
-1M context, MMLU-Pro 87.5, GPQA 90.1, SWE-bench 80.6, LiveCodeBench 93.5.
-
-| Model | Input Price | Output Price | Context | Notes |
-|-------|-------------|--------------|---------|-------|
-| `deepseek/deepseek-v4-pro` | $0.435/M | $0.87/M | 1M | V4 flagship — strongest open-weight reasoner. The 75% launch promo became the permanent list price after 2026-05-31 |
-| `deepseek/deepseek-chat` | $0.20/M | $0.40/M | 1M | V4 Flash non-thinking (paid endpoint with 5MB request bodies; same upstream as `nvidia/deepseek-v4-flash`) |
-| `deepseek/deepseek-reasoner` | $0.20/M | $0.40/M | 1M | V4 Flash thinking (same upstream as `deepseek-chat`, thinking enabled by default) |
-
-### xAI Grok
-
-Grok 4.3 and Grok Build are resold through BlockRun's OpenRouter credit pool
-(same pattern as `deepseek/deepseek-v4-pro` and `minimax/minimax-m3`). The
-older Grok chat SKUs (grok-3/3-mini, grok-4-fast / 4-1-fast families,
-grok-code-fast-1, grok-4-0709, grok-2-vision) are now **hidden from
-`/v1/models`** — direct calls by full ID still work, but SmartChat won't
-auto-pick them.
-
-| Model | Input Price | Output Price | Context | Notes |
-|-------|-------------|--------------|---------|-------|
-| `xai/grok-4.3` | $1.50/M | $4.00/M | 1M | Reasoning model, vision-capable, tuned for agentic workflows |
-| `xai/grok-build-0.1` | $1.50/M | $3.00/M | 256K | Fast agentic coding model — interactive software-engineering workflows |
-
-### Moonshot Kimi
-| Model | Input Price | Output Price |
-|-------|-------------|--------------|
-| `moonshot/kimi-k2.6` | $0.95/M | $4.00/M |
-| `moonshot/kimi-k2.5` | $0.60/M | $3.00/M |
-
-### MiniMax
-| Model | Input Price | Output Price |
-|-------|-------------|--------------|
-| `minimax/minimax-m3` | $0.30/M | $1.20/M |
-| `minimax/minimax-m2.7` | $0.30/M | $1.20/M |
-
-### NVIDIA (Free) + Moonshot
-
-Free tier refreshed 2026-04-28: added `nvidia/deepseek-v4-flash` (1M context)
-and Nemotron Nano Omni (vision). `nvidia/gpt-oss-120b` and
-`nvidia/gpt-oss-20b` were briefly delisted over privacy concerns then
-**re-enabled 2026-04-30** with `available: true` + `hidden: true` — they
-no longer appear in `/v1/models` (so SmartChat won't auto-pick them) but
-direct calls by full ID still return HTTP 200. `nvidia/deepseek-v4-pro`,
-`nvidia/deepseek-v3.2`, and `nvidia/glm-4.7` are hidden because NVIDIA's
-NIM deployment is hung — backend MODEL_REDIRECTS forwards calls to V4
-Flash / qwen3-coder.
-
-| Model | Input Price | Output Price | Notes |
-|-------|-------------|--------------|-------|
-| `nvidia/deepseek-v4-flash` | **FREE** | **FREE** | 284B / 13B active MoE, 1M context — best free chat / summarization / light reasoning |
-| `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning` | **FREE** | **FREE** | 31B / 3.2B active MoE, 256K — only vision-capable free model |
-| `nvidia/qwen3-next-80b-a3b-thinking` | **FREE** | **FREE** | 116 tok/s — reasoning flagship with thinking mode |
-| `nvidia/mistral-small-4-119b` | **FREE** | **FREE** | 114 tok/s — fastest free chat |
-| `nvidia/llama-4-maverick` | **FREE** | **FREE** | Meta Llama 4 Maverick MoE |
-| `nvidia/qwen3-coder-480b` | **FREE** | **FREE** | Coding-optimised 480B MoE |
-| `nvidia/gpt-oss-120b` | **FREE** | **FREE** | Hidden from `/v1/models` for privacy but direct calls still work — 123 tok/s |
-| `nvidia/gpt-oss-20b` | **FREE** | **FREE** | Hidden from `/v1/models` but direct calls still work — 155 tok/s |
-| `moonshot/kimi-k2.5` | $0.60/M | $3.00/M | Direct from Moonshot — replaces `nvidia/kimi-k2.5` |
-
-### E2E Verified Models
-
-All models below have been tested end-to-end via the TypeScript SDK (Feb 2026):
-
-| Provider | Model | Status |
-|----------|-------|--------|
-| OpenAI | `openai/gpt-4o-mini` | Passed |
-| OpenAI | `openai/gpt-5.2-codex` | Passed |
-| Anthropic | `anthropic/claude-opus-4.6` | Passed |
-| Anthropic | `anthropic/claude-sonnet-4` | Passed |
-| Google | `google/gemini-2.5-flash` | Passed |
-| DeepSeek | `deepseek/deepseek-chat` | Passed |
-| xAI | `xai/grok-3` | Passed |
-| Moonshot | `moonshot/kimi-k2.6` | Passed |
-
-### Image Generation
-| Model | Price |
-|-------|-------|
-| `openai/dall-e-3` | $0.04-0.08/image |
-| `openai/gpt-image-1` | $0.02-0.04/image |
-| `openai/gpt-image-2` | $0.06-0.12/image (reasoning-driven, multilingual text rendering, character consistency) |
-| `google/nano-banana` | $0.05/image |
-| `google/nano-banana-pro` | $0.10-0.15/image |
-| `xai/grok-imagine-image` | $0.02/image |
-| `xai/grok-imagine-image-pro` | $0.07/image |
-| `zai/cogview-4` | $0.015/image |
-
-Image editing (`client.edit`) via `/v1/images/image2image`: `openai/gpt-image-1`, `openai/gpt-image-2`, `google/nano-banana`, and `google/nano-banana-pro`. Pass a single base64 `data:image/...` URI to edit one image, or an array of 2–4 URIs to **fuse** them (e.g. a subject + a brand logo). Fusion caps: `openai/*` up to 4 source images, `google/*` up to 3. A `mask` cannot be combined with multiple source images.
-
-```ts
-// Multi-image fusion with Nano Banana
-const fused = await client.edit(
-  "Place the logo on the t-shirt",
-  [subjectDataUri, logoDataUri],
-  { model: "google/nano-banana" }
-);
-console.log(fused.data[0].url);
-```
-
-### Video Generation
-| Model | Price |
-|-------|-------|
-| `xai/grok-imagine-video` | $0.05/sec (8s default → $0.42/clip) |
-| `bytedance/seedance-1.5-pro` | $0.03/sec (5s default, up to 10s, 720p) |
-| `bytedance/seedance-2.0-fast` | $0.15/sec (~60-80s gen, sweet-spot price/quality) |
-| `bytedance/seedance-2.0` | $0.30/sec (720p Pro) |
-
-```ts
-import { VideoClient } from '@blockrun/llm';
-
-const client = new VideoClient();
-const result = await client.generate('a red apple slowly spinning on a wooden table');
-console.log(result.data[0].url);             // permanent MP4 URL
-console.log(result.data[0].duration_seconds); // 8
-
-// Image-to-video
-const r2 = await client.generate('the subject turns and smiles', {
-  imageUrl: 'https://example.com/portrait.jpg',
-});
-
-// Token360 / Seedance options (silently ignored by xAI Grok video)
-const r3 = await client.generate('aerial drone shot over a snowy mountain', {
-  model: 'bytedance/seedance-2.0-fast',
-  aspectRatio: '21:9',
-  resolution: '1080p',
-  generateAudio: true,    // omit to use the model's default
-  seed: 42,
-  watermark: false,
-  returnLastFrame: true,  // useful for clip chaining
-});
-```
-
-### Text-to-Speech & Sound Effects
-
-`SpeechClient` wraps BlockRun Voice (ElevenLabs): `POST /v1/audio/speech`
-(OpenAI-compatible TTS), `POST /v1/audio/sound-effects`, and the free
-`GET /v1/audio/voices`. TTS price scales with character count:
-`(chars / 1000) × model rate`, minimum $0.001/request. Synthesis is
-synchronous (<1s for Flash).
-
-| Model | Price | Max Input | Notes |
-|-------|-------|-----------|-------|
-| `elevenlabs/flash-v2.5` | $0.05/1k chars | 40k chars | ~75ms latency, 32 languages (default) |
-| `elevenlabs/turbo-v2.5` | $0.05/1k chars | 40k chars | ~250ms latency, balanced quality |
-| `elevenlabs/multilingual-v2` | $0.10/1k chars | 10k chars | Long-form narration, audiobooks |
-| `elevenlabs/v3` | $0.10/1k chars | 5k chars | Max expressiveness, 70+ languages |
-| `elevenlabs/sound-effects` | $0.05/generation | 1k chars | Sound effects up to 22s |
-
-```ts
-import { SpeechClient } from '@blockrun/llm';
-
-const client = new SpeechClient();
-
-// Text-to-speech (voice aliases: sarah, george, laura, charlie,
-// river, roger, callum, harry — or any raw ElevenLabs voice_id)
-const result = await client.generate('Welcome to BlockRun.', { voice: 'george' });
-console.log(result.data[0].url);  // audio URL (mp3 by default)
-
-// Other formats / speed
-const wav = await client.generate('Breaking news from the world of micropayments.', {
-  model: 'elevenlabs/v3',
-  responseFormat: 'wav',
-  speed: 1.1,
-});
-
-// Sound effects (flat $0.05/generation)
-const fx = await client.soundEffect('rain on a tin roof, distant thunder');
-
-// List voices (free, rate-limited)
-const voices = await client.listVoices();
-```
-
-### Virtual Portraits
-
-`PortraitClient` wraps `POST /v1/portrait/enroll` (paid, flat **$0.01** promo,
-no KYC). Enroll a face image by URL and get back a Token360 asset id (`ta_xxxxxx`).
-Pass that id as `realFaceAssetId` on a Seedance 2.0 video generation to keep the
-same AI character across clips. Payment settles only after Token360 confirms the
-enrollment, so a failed enrollment never charges your wallet. The returned
-`image_url` is a gateway-mirrored copy of your source image (see `mirrored` /
-`source_image_url`). (Real-person likeness is not supported on BlockRun —
-enrolled portraits are AI characters.)
-
-```ts
-import { PortraitClient, VideoClient } from '@blockrun/llm';
-
-const portraits = new PortraitClient();
-const { asset_id } = await portraits.enroll({
-  name: 'Spokesperson',
-  imageUrl: 'https://example.com/face.jpg',  // public https JPG/PNG/WEBP, ≤10 MB
-});
-
-// Reuse the same character across Seedance 2.0 clips
-const video = new VideoClient();
-const clip = await video.generate('she waves and smiles', {
-  model: 'bytedance/seedance-2.0-fast',
-  realFaceAssetId: asset_id,
-});
-console.log(clip.data[0].url);
-```
-
-### Voice Calls
-
-`VoiceClient` wraps `POST /v1/voice/call` (paid, $0.54/call) and
-`GET /v1/voice/call/{callId}` (free polling) — AI-powered outbound phone
-calls powered by Bland.ai. The agent dials the recipient and runs a real-time
-conversation based on your `task` instructions. US + Canada destinations.
-
-```ts
-import { VoiceClient } from '@blockrun/llm';
-
-const client = new VoiceClient();
-
-// Initiate (paid $0.54)
-const result = await client.call({
-  to: '+14155552671',
-  task: 'You are a friendly assistant calling to confirm a 3pm dentist appointment.',
-  voice: 'maya',     // 'nat' | 'josh' | 'maya' | 'june' | 'paige' | 'derek' | 'florian'
-  max_duration: 5,   // minutes (1–30)
-});
-console.log(result.call_id);
-
-// Poll for transcript + recording (free)
-const status = await client.getStatus(result.call_id);
-console.log(status.status, status.recording_url);
-```
-
-Bring your own caller-ID: pass `from: '+14155552671'` (must be a BlockRun
-phone number you own; buy via `/v1/phone/numbers/buy`).
-
-### Standalone Search
-
-`SearchClient` wraps `POST /v1/search` — standalone Grok Live Search.
-Pricing: `$0.025/source + margin` (10 sources ≈ `$0.26`).
-
-```ts
-import { SearchClient } from '@blockrun/llm';
-
-const client = new SearchClient();
-const result = await client.search('Latest news on x402 adoption', {
-  sources: ['x', 'web'],
-  maxResults: 10,
-});
-console.log(result.summary);
-for (const url of result.citations ?? []) console.log(url);
-```
-
-### X/Twitter (AttentionVC)
-
-`XClient` covers the full `/v1/x/*` endpoint family — previously the `X*`
-types were exported but there was no client to call them with.
-
-```ts
-import { XClient } from '@blockrun/llm';
-
-const x = new XClient();
-const info = await x.userInfo('elonmusk');
-const followers = await x.followers('paulg');
-const results = await x.search('x402 micropayments', { queryType: 'Latest' });
-const tweets = await x.userTweets({ username: 'vitalikbuterin', includeReplies: false });
-```
-
-### Surf Crypto Data
-
-`SurfClient` exposes the full `/v1/surf/*` catalog — 84+ pay-per-call
-endpoints across CEX/DEX market data, on-chain SQL, wallet intelligence,
-prediction markets (Polymarket + Kalshi), social analytics, news, VC fund
-data, and an OpenAI-compatible chat surface. Flat pricing per call:
-
-| Tier | Price/call | Examples |
-|------|-----------|----------|
-| 1 | $0.001 | `/market/price`, `/market/ranking`, `/news/feed`, prediction-market reads, social tweets |
-| 2 | $0.005 | `/exchange/depth`, `/exchange/klines`, `/wallet/detail`, `/search/*`, `/social/ranking` |
-| 3 | $0.020 | `/onchain/sql`, `/onchain/query`, `/onchain/schema`, `/chat/completions` |
-
-Because the catalog is broad and evolving, the client deliberately ships a
-generic `get` / `post` pair instead of 84 typed wrappers. Pass the path
-(with or without the `/v1/surf` prefix), query params, or a JSON body —
-type the response via a generic if you want.
-
-```ts
-import { SurfClient } from '@blockrun/llm';
-
-const surf = new SurfClient();
-
-// Tier 1 — token price ($0.001)
-const btc = await surf.get('/market/price', { symbol: 'BTC' });
-
-// Tier 2 — order book depth ($0.005)
-const book = await surf.get('/exchange/depth', {
-  exchange: 'binance',
-  symbol: 'BTC-USDT',
-});
-
-// Tier 3 — raw on-chain SQL against 80+ ClickHouse tables ($0.020)
-const rows = await surf.post('/onchain/sql', {
-  query: 'SELECT block_number FROM ethereum.blocks ORDER BY block_number DESC LIMIT 5',
-});
-
-// Typed response via generic
-type Price = { symbol: string; price: number; timestamp: string };
-const eth = await surf.get<Price>('/market/price', { symbol: 'ETH' });
-```
-
-Full endpoint inventory: <https://blockrun.ai/marketplace/surf>.
-
-Methods: `userLookup`, `userInfo`, `followers`, `following`, `followings`,
-`verifiedFollowers`, `userTweets`, `mentions`, `tweetLookup`, `tweetReplies`,
-`tweetThread`, `search`, `trending`, `articlesRising`.
-
-### Market Data (Pyth)
-
-`PriceClient` wraps the Pyth-backed market-data endpoints. Crypto, FX and
-commodity are fully free (price + history + list); 12 global stock markets
-and the `usstock` legacy alias charge `$0.001` for price + history (list is
-always free). Pass `requireWallet: false` to construct a free-only client.
-
-```ts
-import { PriceClient } from '@blockrun/llm';
-
-const p = new PriceClient({ requireWallet: false });
-const btc = await p.price('crypto', 'BTC-USD');
-const eur = await p.price('fx', 'EUR-USD');
-
-// Paid — requires a wallet
-const p2 = new PriceClient();
-const aapl = await p2.price('stocks', 'AAPL', { market: 'us' });
-const bars = await p2.history('stocks', 'AAPL', {
-  market: 'us',
-  resolution: 'D',
-  from: 1700000000,
-  to: 1710000000,
-});
-const symbols = await p.listSymbols('crypto', { query: 'sol', limit: 20 });
-```
-
-Supported `StockMarket` values: `us, hk, jp, kr, gb, de, fr, nl, ie, lu, cn, ca`.
-
-### Testnet Models (Base Sepolia)
-| Model | Price |
-|-------|-------|
-| `openai/gpt-oss-20b` | $0.001/request |
-| `openai/gpt-oss-120b` | $0.002/request |
-
-*Testnet models use flat pricing (no token counting) for simplicity.*
-
-## X/Twitter Data (Powered by AttentionVC)
-
-Access X/Twitter user profiles, followers, and followings via [AttentionVC](https://attentionvc.ai) partner API. No API keys needed — pay-per-request via x402.
-
-```typescript
-import { LLMClient } from '@blockrun/llm';
-
-const client = new LLMClient();
-
-// Look up user profiles ($0.002/user, min $0.02)
-const users = await client.xUserLookup(['elonmusk', 'blockaborr']);
-for (const user of users.users) {
-  console.log(`@${user.userName}: ${user.followers} followers`);
-}
-
-// Get followers ($0.05/page, ~200 accounts)
-let result = await client.xFollowers('blockaborr');
-for (const f of result.followers) {
-  console.log(`  @${f.screen_name}`);
-}
-
-// Paginate through all followers
-while (result.has_next_page) {
-  result = await client.xFollowers('blockaborr', result.next_cursor);
-}
-
-// Get followings ($0.05/page)
-const followings = await client.xFollowings('blockaborr');
-```
-
-Works on both `LLMClient` (Base) and `SolanaLLMClient`.
-
-## Standalone Search
-
-Search web, X/Twitter, and news without using a chat model:
-
-```typescript
-import { LLMClient } from '@blockrun/llm';
-
-const client = new LLMClient();
-
-const result = await client.search('latest AI agent frameworks 2026');
-console.log(result.summary);
-for (const cite of result.citations ?? []) {
-  console.log(`  - ${cite}`);
-}
-
-// Filter by source type and date range
-const filtered = await client.search('BlockRun x402', {
-  sources: ['web', 'x'],
-  fromDate: '2026-01-01',
-  maxResults: 5,
-});
-```
-
-## Image Editing (img2img)
-
-Edit existing images with text prompts:
-
-```typescript
-import { LLMClient } from '@blockrun/llm';
-
-const client = new LLMClient();
-
-const result = await client.imageEdit(
-  'Make the sky purple and add northern lights',
-  'data:image/png;base64,...',  // base64 or URL
-  { model: 'openai/gpt-image-1' }
-);
-console.log(result.data[0].url);
-```
-
-## Usage Examples
-
-### Simple Chat
-
-```typescript
-import { LLMClient } from '@blockrun/llm';
-
-const client = new LLMClient();  // Uses BASE_CHAIN_WALLET_KEY (never sent to server)
-
-const response = await client.chat('openai/gpt-4o', 'Explain quantum computing');
-console.log(response);
-
-// With system prompt
-const response2 = await client.chat('anthropic/claude-sonnet-4', 'Write a haiku', {
-  system: 'You are a creative poet.',
-});
-```
-
-### Smart Routing (ClawRouter)
-
-Save up to 78% on inference costs with intelligent model routing. ClawRouter uses a 14-dimension rule-based scoring algorithm to select the cheapest model that can handle your request (<1ms, 100% local).
-
-```typescript
-import { LLMClient } from '@blockrun/llm';
-
-const client = new LLMClient();
-
-// Auto-route to cheapest capable model
-const result = await client.smartChat('What is 2+2?');
-console.log(result.response);     // '4'
-console.log(result.model);        // 'google/gemini-2.5-flash'
-console.log(result.routing.tier); // 'SIMPLE'
-console.log(`Saved ${(result.routing.savings * 100).toFixed(0)}%`); // 'Saved 78%'
-
-// Routing profiles
-const free = await client.smartChat('Hello!', { routingProfile: 'free' });     // Zero cost
-const eco = await client.smartChat('Explain AI', { routingProfile: 'eco' });   // Budget optimized
-const auto = await client.smartChat('Code review', { routingProfile: 'auto' }); // Balanced (default)
-const premium = await client.smartChat('Write a legal brief', { routingProfile: 'premium' }); // Best quality
-```
-
-**Routing Profiles:**
-
-| Profile | Description | Best For |
-|---------|-------------|----------|
-| `free` | NVIDIA free tier (9 models, smart-routed) | Zero-cost testing, dev, prod |
-| `eco` | Budget-optimized | Cost-sensitive workloads |
-| `auto` | Intelligent routing (default) | General use |
-| `premium` | Best quality models | Critical tasks |
-
-**Tiers:**
-
-| Tier | Example Tasks | Typical Models |
-|------|---------------|----------------|
-| SIMPLE | Greetings, math, lookups | Gemini Flash, GPT-4o-mini |
-| MEDIUM | Explanations, summaries | GPT-4o, Claude Sonnet |
-| COMPLEX | Analysis, code generation | GPT-5.2, Claude Opus |
-| REASONING | Multi-step logic, planning | o3, DeepSeek Reasoner |
-
-### Full Chat Completion
-
-```typescript
-import { LLMClient, type ChatMessage } from '@blockrun/llm';
-
-const client = new LLMClient();  // Uses BASE_CHAIN_WALLET_KEY (never sent to server)
-
-const messages: ChatMessage[] = [
-  { role: 'system', content: 'You are a helpful assistant.' },
-  { role: 'user', content: 'How do I read a file in Node.js?' },
-];
-
-const result = await client.chatCompletion('openai/gpt-4o', messages);
-console.log(result.choices[0].message.content);
-```
-
-### Streaming
-
-Stream responses token-by-token with automatic x402 payment. Uses a **pre-auth cache** to skip the 402 round-trip on repeat calls to the same model (~200ms saved per request after the first).
-
-#### OpenAI-compatible (recommended)
-
-```typescript
-import { OpenAI } from '@blockrun/llm';
-
-const client = new OpenAI({ walletKey: process.env.BASE_CHAIN_WALLET_KEY });
-
-const stream = await client.chat.completions.create({
-  model: 'openai/gpt-5.4',
-  messages: [{ role: 'user', content: 'Write a short story about AI agents' }],
-  stream: true,
-});
-
-for await (const chunk of stream) {
-  process.stdout.write(chunk.choices[0]?.delta?.content || '');
-}
-```
-
-#### Native client
-
-```typescript
-import { LLMClient, type ChatMessage } from '@blockrun/llm';
-
-const client = new LLMClient();
-
-const messages: ChatMessage[] = [
-  { role: 'user', content: 'Explain quantum computing in simple terms' },
-];
-
-// Returns a raw fetch Response with SSE body
-const response = await client.chatCompletionStream('google/gemini-2.5-flash', messages);
-
-const reader = response.body!.getReader();
-const decoder = new TextDecoder();
-
-while (true) {
-  const { done, value } = await reader.read();
-  if (done) break;
-
-  const chunk = decoder.decode(value, { stream: true });
-  for (const line of chunk.split('\n')) {
-    if (!line.startsWith('data: ') || line === 'data: [DONE]') continue;
-    const data = JSON.parse(line.slice(6));
-    process.stdout.write(data.choices?.[0]?.delta?.content || '');
-  }
-}
-```
-
-#### Payment + streaming flow
-
-```
-First call (cache miss):
-  1. Send request → 402 response (BlockRun returns price)
-  2. Sign USDC payment locally (key never leaves machine)
-  3. Retry with PAYMENT-SIGNATURE header + stream: true
-  4. Cache payment requirements for this model (1h TTL)
-  5. Stream tokens as they arrive
-
-Subsequent calls (cache hit):
-  1. Pre-sign payment from cache — skip 402 round-trip
-  2. Send request with PAYMENT-SIGNATURE upfront
-  3. Stream tokens immediately (~200ms faster)
-```
-
-### List Available Models
-
-```typescript
-import { LLMClient } from '@blockrun/llm';
-
-const client = new LLMClient();  // Uses BASE_CHAIN_WALLET_KEY (never sent to server)
-const models = await client.listModels();
-
-for (const model of models) {
-  console.log(`${model.id}: $${model.inputPrice}/M input`);
-}
-```
-
-### Multiple Requests
-
-```typescript
-import { LLMClient } from '@blockrun/llm';
-
-const client = new LLMClient();  // Uses BASE_CHAIN_WALLET_KEY (never sent to server)
-
-const [gpt, claude, gemini] = await Promise.all([
-  client.chat('openai/gpt-4o', 'What is 2+2?'),
-  client.chat('anthropic/claude-sonnet-4', 'What is 3+3?'),
-  client.chat('google/gemini-2.5-flash', 'What is 4+4?'),
-]);
-```
-
-## Prediction Markets (Powered by Predexon)
-
-Access real-time prediction market data from Polymarket, Kalshi, and Binance Futures via [Predexon](https://predexon.com). No API keys needed — pay-per-request via x402.
-
-### Polymarket
-
-```typescript
-import { LLMClient } from '@blockrun/llm';
-
-const client = new LLMClient();
-
-// List markets with optional filters ($0.001/request)
-const markets = await client.pm("polymarket/markets");
-const filtered = await client.pm("polymarket/markets", { status: "active", limit: 10 });
-const searched = await client.pm("polymarket/markets", { search: "bitcoin" });
-
-// List events ($0.001/request)
-const events = await client.pm("polymarket/events");
-
-// Historical trades ($0.001/request)
-const trades = await client.pm("polymarket/trades");
-
-// OHLCV candlestick data for a specific condition ($0.001/request)
-const candles = await client.pm("polymarket/candlesticks/0x1234abcd...");
-
-// Wallet profile ($0.005/request — tier 2)
-const profile = await client.pm("polymarket/wallet/0xABC123...");
-
-// Wallet P&L ($0.005/request — tier 2)
-const pnl = await client.pm("polymarket/wallet/pnl/0xABC123...");
-
-// Global leaderboard ($0.001/request)
-const leaderboard = await client.pm("polymarket/leaderboard");
-```
-
-### Kalshi & Binance
-
-```typescript
-// Kalshi markets ($0.001/request)
-const kalshiMarkets = await client.pm("kalshi/markets");
-
-// Kalshi trades ($0.001/request)
-const kalshiTrades = await client.pm("kalshi/trades");
-
-// Binance candles for supported pairs ($0.001/request)
-const btcCandles = await client.pm("binance/candles/BTCUSDT");
-const ethCandles = await client.pm("binance/candles/ETHUSDT");
-// Also: SOLUSDT, XRPUSDT
-```
-
-### Cross-Platform
-
-```typescript
-// Cross-platform matching pairs ($0.001/request)
-const pairs = await client.pm("matching-markets/pairs");
-```
-
-All current endpoints are GET. The `pmQuery()` method is available for future POST endpoints.
-
-Works on both `LLMClient` (Base) and `SolanaLLMClient`.
-
-## Exa Web Search (Powered by Exa)
-
-Access [Exa](https://exa.ai)'s neural web search via x402. No API keys needed — pay-per-request. Available on **`LLMClient` (Base USDC)** and `SolanaLLMClient` (Solana USDC). Use Base as the primary path; the Solana gateway is awaiting `EXA_API_KEY` provisioning.
-
-| Method | Description | Price |
-|---|---|---|
-| `exaSearch(query, options?)` | Neural/keyword web search | $0.01/request |
-| `exaFindSimilar(url, options?)` | Find semantically similar pages | $0.01/request |
-| `exaContents(urls, options?)` | Extract full text from URLs | $0.002/URL |
-| `exaAnswer(query, options?)` | AI answer grounded in web search | $0.01/request |
-| `exa(path, body)` | Generic proxy for any Exa endpoint | varies |
-
-```typescript
-import { LLMClient } from '@blockrun/llm';
-
-const client = new LLMClient();
-
-// Neural web search ($0.01/request)
-const results = await client.exaSearch("latest AI safety research", { numResults: 5 });
-const news = await client.exaSearch("bitcoin ETF news", { category: "news", numResults: 10 });
-
-// Find similar pages ($0.01/request)
-const similar = await client.exaFindSimilar("https://openai.com/research/gpt-4", { numResults: 5 });
-
-// Extract content from URLs ($0.002/URL)
-const content = await client.exaContents(["https://arxiv.org/abs/2303.08774"]);
-
-// AI-generated answer from live web ($0.01/request)
-const answer = await client.exaAnswer("What is the current state of AI safety research?");
-
-// Generic proxy for any Exa endpoint
-const custom = await client.exa("search", { query: "transformer architecture", numResults: 5 });
-```
-
-Same surface on `SolanaLLMClient` once Solana-side `EXA_API_KEY` is provisioned.
-
-## Configuration
-
-```typescript
-// Default: reads BASE_CHAIN_WALLET_KEY from environment
-const client = new LLMClient();
-
-// Or pass options explicitly
-const client = new LLMClient({
-  privateKey: '0x...',           // Your wallet key (never sent to server)
-  apiUrl: 'https://blockrun.ai/api',   // Optional
-  timeout: 60000,                // Optional (ms)
-});
-```
-
-## Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `BASE_CHAIN_WALLET_KEY` | Your Base chain wallet private key (for Base / `LLMClient`) |
-| `SOLANA_WALLET_KEY` | Your Solana wallet secret key - bs58 encoded (for `SolanaLLMClient`) |
-| `BLOCKRUN_API_URL` | API endpoint (optional, default: https://blockrun.ai/api) |
-
-## Error Handling
-
-```typescript
-import { LLMClient, APIError, PaymentError } from '@blockrun/llm';
-
-const client = new LLMClient();
-
-try {
-  const response = await client.chat('openai/gpt-4o', 'Hello!');
-} catch (error) {
-  if (error instanceof PaymentError) {
-    console.error('Payment failed - check USDC balance');
-  } else if (error instanceof APIError) {
-    console.error(`API error: ${error.message}`);
-  }
-}
-```
-
-## Testing
-
-### Running Unit Tests
-
-Unit tests do not require API access or funded wallets:
-
-```bash
-npm test                          # Run tests in watch mode
-npm test run                      # Run tests once
-npm test -- --coverage            # Run with coverage report
-```
-
-### Running Integration Tests
-
-Integration tests call the production API and require:
-- A funded Base wallet with USDC ($1+ recommended)
-- `BASE_CHAIN_WALLET_KEY` environment variable set
-- Estimated cost: ~$0.05 per test run
-
-```bash
-export BASE_CHAIN_WALLET_KEY=0x...
-npm test -- test/integration       # Run integration tests only
-```
-
-Integration tests are automatically skipped if `BASE_CHAIN_WALLET_KEY` is not set.
-
-## Setting Up Your Wallet
-
-### Base (EVM)
-1. Create a wallet on Base (Coinbase Wallet, MetaMask, etc.)
-2. Get USDC on Base for API payments
-3. Export your private key and set as `BASE_CHAIN_WALLET_KEY`
-
-```bash
-# .env
-BASE_CHAIN_WALLET_KEY=0x...
-```
-
-### Solana
-1. Create a Solana wallet (Phantom, Backpack, Solflare, etc.)
-2. Get USDC on Solana for API payments
-3. Export your secret key and set as `SOLANA_WALLET_KEY`
-
-```bash
-# .env
-SOLANA_WALLET_KEY=...your_bs58_secret_key
-```
-
-Note: Solana transactions are gasless for the user - the CDP facilitator pays for transaction fees.
-
-## Security
-
-### Private Key Safety
-
-- **Private key stays local**: Your key is only used for signing on your machine
-- **No custody**: BlockRun never holds your funds
-- **Verify transactions**: All payments are on-chain and verifiable
-
-### Best Practices
-
-**Private Key Management:**
-- Use environment variables, never hard-code keys
-- Use dedicated wallets for API payments (separate from main holdings)
-- Set spending limits by only funding payment wallets with small amounts
-- Never commit `.env` files to version control
-- Rotate keys periodically
-
-**Input Validation:**
-The SDK validates all inputs before API requests:
-- Private keys (format, length, valid hex)
-- API URLs (HTTPS required for production, HTTP allowed for localhost)
-- Model names and parameters (ranges for max\_tokens, temperature, top\_p)
-
-**Error Sanitization:**
-API errors are automatically sanitized to prevent sensitive information leaks.
-
-**Monitoring:**
-```typescript
-const address = client.getWalletAddress();
-console.log(`View transactions: https://basescan.org/address/${address}`);
-```
-
-**Keep Updated:**
-```bash
-npm update @blockrun/llm  # Get security patches
-```
-
-## TypeScript Support
-
-Full TypeScript support with exported types:
-
-```typescript
-import {
-  LLMClient,
-  OpenAI,
-  type ChatMessage,
-  type ChatResponse,
-  type ChatOptions,
-  type ChatCompletionOptions,
-  type Model,
-  // Smart routing types
-  type SmartChatOptions,
-  type SmartChatResponse,
-  type RoutingDecision,
-  type RoutingProfile,
-  type RoutingTier,
-  APIError,
-  PaymentError,
-} from '@blockrun/llm';
-
-// chatCompletionStream returns a standard fetch Response with SSE body
-const streamResponse: Response = await client.chatCompletionStream(model, messages, options);
-
-// OpenAI-compat stream returns AsyncIterable
-const stream: AsyncIterable<OpenAIChatCompletionChunk> = await openaiClient.chat.completions.create({
-  model, messages, stream: true
-});
-```
-
-## Agent Wallet Setup
-
-One-line setup for agent runtimes (Claude Code skills, MCP servers, etc.):
-
-```typescript
-import { setupAgentWallet } from '@blockrun/llm';
-
-// Auto-creates wallet if none exists, returns ready client
-const client = setupAgentWallet();
-const response = await client.chat('openai/gpt-5.4', 'Hello!');
-```
-
-For Solana:
-
-```typescript
-import { setupAgentSolanaWallet } from '@blockrun/llm';
-
-const client = await setupAgentSolanaWallet();
-const response = await client.chat('anthropic/claude-sonnet-4.6', 'Hello!');
-```
-
-Check wallet status:
-
-```typescript
-import { status } from '@blockrun/llm';
-
-await status();
-// Wallet: 0xCC8c...5EF8
-// Balance: $5.30 USDC
-```
-
-## Wallet Scanning
-
-The SDK auto-detects wallets from any provider on your system:
-
-```typescript
-import { scanWallets, scanSolanaWallets } from '@blockrun/llm';
-
-// Scans ~/.<dir>/wallet.json for Base wallets
-const baseWallets = scanWallets();
-
-// Scans ~/.<dir>/solana-wallet.json and ~/.brcc/wallet.json
-const solWallets = scanSolanaWallets();
-```
-
-`getOrCreateWallet()` checks scanned wallets first, so if you already have a wallet from another BlockRun tool, it will be reused automatically.
-
-## Response Caching
-
-The SDK caches responses to avoid duplicate payments:
-
-```typescript
-import { getCachedByRequest, saveToCache, clearCache } from '@blockrun/llm';
-
-// Automatic TTLs by endpoint:
-// - X/Twitter: 1 hour
-// - Search: 15 minutes
-// - Models: 24 hours
-// - Chat/Image: no cache (every call is unique)
-
-// Manual cache management
-clearCache(); // Remove all cached responses
-```
-
-## Cost Logging
-
-Track spending across sessions:
-
-```typescript
-import { logCost, getCostSummary } from '@blockrun/llm';
-
-// Costs are logged to ~/.blockrun/data/costs.jsonl
-const summary = getCostSummary();
-console.log(`Total: $${summary.totalUsd.toFixed(2)}`);
-console.log(`Calls: ${summary.calls}`);
-console.log(`By model:`, summary.byModel);
-```
-
-## Anthropic SDK Compatibility
-
-Use the official Anthropic SDK interface with BlockRun's pay-per-request backend:
-
-```typescript
-import { AnthropicClient } from '@blockrun/llm';
-
-const client = new AnthropicClient();  // Auto-detects wallet, auto-pays
-
-const response = await client.messages.create({
-  model: 'claude-sonnet-4-6',
-  max_tokens: 1024,
-  messages: [{ role: 'user', content: 'Hello!' }],
-});
-console.log(response.content[0].text);
-
-// Any model works in Anthropic format
-const gptResponse = await client.messages.create({
-  model: 'openai/gpt-5.4',
-  max_tokens: 1024,
-  messages: [{ role: 'user', content: 'Hello from GPT!' }],
-});
-```
-
-The `AnthropicClient` wraps the official `@anthropic-ai/sdk` with a custom fetch that handles x402 payment automatically. Your private key never leaves your machine.
-
-## Links
-
-- [Website](https://blockrun.ai)
-- [Documentation](https://github.com/BlockRunAI/awesome-blockrun/tree/main/docs)
-- [GitHub](https://github.com/blockrunai/blockrun-llm-ts)
-- [Telegram](https://t.me/+mroQv4-4hGgzOGUx)
-
-## Frequently Asked Questions
-
-### What is @blockrun/llm?
-@blockrun/llm is a TypeScript SDK that provides pay-per-request access to 40+ large language models from OpenAI, Anthropic, Google, xAI, DeepSeek, Moonshot, and more. It uses the x402 protocol for automatic USDC micropayments — no API keys, no subscriptions, no vendor lock-in.
-
-### How does payment work?
-When you make an API call, the SDK automatically handles x402 payment. It signs a USDC transaction locally using your wallet private key (which never leaves your machine), and includes the payment proof in the request header. Settlement is non-custodial and instant on Base or Solana.
-
-### What is smart routing / ClawRouter?
-ClawRouter is a built-in smart routing engine that analyzes your request across 14 dimensions and automatically picks the cheapest model capable of handling it. Routing happens locally in under 1ms. It can save up to 78% on LLM costs compared to using premium models for every request.
-
-### Does it support streaming?
-Yes — as of v1.6.1. Use `client.chatCompletionStream()` for native streaming or `stream: true` in the OpenAI-compatible client. Payment is handled automatically: the SDK signs USDC payment before streaming begins, and caches payment requirements per model so subsequent calls skip the 402 round-trip (~200ms faster).
-
-### How much does it cost?
-Pay only for what you use. Prices start at $0.0002 per request (GPT-5 Nano). There are no minimums, subscriptions, or monthly fees. $5 in USDC gets you thousands of requests.
-
-### Does it support both Base and Solana?
-Yes. Use `LLMClient` for Base (EVM) payments and `SolanaLLMClient` for Solana payments. Same API, different payment chain.
-
-## License
-
-MIT
+# @blockrun/llm (TypeScript SDK)
+
+> **@blockrun/llm** is a TypeScript/Node.js SDK for accessing 41+ large language models (GPT-5, Claude, Gemini, Grok, DeepSeek, Kimi, and more) with automatic pay-per-request USDC micropayments via the x402 protocol. No API keys required — your wallet signature is your authentication. Supports **streaming**, smart routing, Base and Solana chains.
+>
+> 🆓 **Includes 7 fully-free NVIDIA-hosted models** (5 visible in `/v1/models`, 2 hidden but directly callable) — DeepSeek V4 Flash (1M context), Nemotron Nano Omni (vision), Qwen3 Coder, Llama 4, Mistral, plus the gpt-oss pair. Zero USDC, no rate-limit gimmicks. Use `routingProfile: 'free'` or call any `nvidia/*` model directly.
+
+[![npm](https://img.shields.io/npm/v/@blockrun/llm.svg)](https://www.npmjs.com/package/@blockrun/llm)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+## Supported Chains
+
+| Chain | Network | Payment | Status |
+|-------|---------|---------|--------|
+| **Base** | Base Mainnet (Chain ID: 8453) | USDC | Primary |
+| **Base Testnet** | Base Sepolia (Chain ID: 84532) | Testnet USDC | Development |
+| **Solana** | Solana Mainnet | USDC (SPL) | New |
+
+
+**Protocol:** x402 v2 (CDP Facilitator)
+
+## Installation
+
+```bash
+# Base and Solana support (optional Solana deps auto-installed)
+npm install @blockrun/llm
+# or
+pnpm add @blockrun/llm
+# or
+yarn add @blockrun/llm
+```
+
+## Quick Start (Base - Default)
+
+```typescript
+import { LLMClient } from '@blockrun/llm';
+
+const client = new LLMClient();  // Uses BASE_CHAIN_WALLET_KEY (never sent to server)
+const response = await client.chat('openai/gpt-4o', 'Hello!');
+```
+
+That's it. The SDK handles x402 payment automatically.
+
+## `BlockrunClient` — the universal primitive (recommended for new code)
+
+Starting in `2.5.0`, the SDK ships a single `BlockrunClient` that speaks to
+**every** BlockRun endpoint over x402. New API surfaces are intended to be
+distributed as [Claude Code skills](https://github.com/anthropics/skills)
+that drive this primitive — no SDK release required to add an endpoint.
+
+```typescript
+import { BlockrunClient } from '@blockrun/llm';
+
+const br = new BlockrunClient();
+
+// Sync GET — Surf market price (Tier 1, $0.001)
+const btc = await br.get('/v1/surf/market/price', { symbol: 'BTC' });
+
+// Sync POST — raw on-chain SQL (Tier 3, $0.020)
+const rows = await br.post('/v1/surf/onchain/sql', {
+  query: 'SELECT block_number FROM ethereum.blocks ORDER BY block_number DESC LIMIT 1',
+});
+
+// Submit + poll — long-running video gen (settled only on completion)
+const video = await br.poll('/v1/videos/generations', {
+  model: 'xai/grok-imagine-video',
+  prompt: 'a red apple spinning',
+});
+
+// Streaming SSE — chat completions
+for await (const chunk of br.stream('/v1/chat/completions', {
+  model: 'anthropic/claude-sonnet-4-6',
+  messages: [{ role: 'user', content: 'Hi' }],
+  stream: true,
+})) {
+  process.stdout.write(chunk?.choices?.[0]?.delta?.content ?? '');
+}
+```
+
+Four call shapes cover every endpoint type:
+- `get<T>(path, params?)` — synchronous GET (price, ranking, list, news)
+- `post<T>(path, body?)` — synchronous POST (on-chain SQL, search)
+- `poll<T>(path, body?, { budgetMs, intervalMs })` — submit + poll (image, video, music, voice)
+- `stream<T>(path, body?)` — async iterator over SSE chunks (chat)
+
+The per-API client classes (`LLMClient`, `ImageClient`, `VideoClient`,
+`PortraitClient`, `VoiceClient`, `MusicClient`, `SearchClient`, `RpcClient`,
+`PriceClient`, `SurfClient`) all remain — they will be soft-deprecated in 2.6 (rewritten as
+shims over `BlockrunClient`) and removed in 3.0.
+
+### Try It Free (No USDC Required)
+
+Want to kick the tires before funding a wallet? Route to BlockRun's free NVIDIA tier:
+
+```typescript
+import { LLMClient } from '@blockrun/llm';
+
+const client = new LLMClient();  // Wallet still required for signing, but $0 charged
+
+// Option 1: call a free model directly
+const reply = await client.chat('nvidia/deepseek-v4-flash', 'Explain x402 in 1 sentence');
+
+// Option 2: let the smart router pick the best free model per request
+const result = await client.smartChat('What is 2+2?', { routingProfile: 'free' });
+console.log(result.model);     // e.g. 'nvidia/deepseek-v4-flash' (cheapest capable for SIMPLE tier)
+console.log(result.response);  // '4'
+```
+
+**Available free models** (input + output both $0, all NVIDIA-hosted, last refreshed 2026-06-07):
+
+| Model ID | Context | Best For |
+|----------|---------|----------|
+| `nvidia/deepseek-v4-flash` | 1M | DeepSeek V4 Flash — 284B / 13B active MoE, ~5× faster than V4 Pro. Best free chat / summarization / light reasoning |
+| `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning` | 256K | Only vision-capable free model — text + images + video (≤2 min) + audio (≤1 hr) |
+| `nvidia/llama-4-maverick` | 131K | Meta Llama 4 Maverick MoE |
+| `nvidia/qwen3-coder-480b` | 131K | Coding-optimised 480B MoE |
+| `nvidia/mistral-small-4-119b` | 131K | ⚠️ Upstream timing out as of 2026-06-07 — avoid until NVIDIA recovers it |
+| `nvidia/gpt-oss-120b` | 128K | OpenAI open-weight 120B — 123 tok/s. Hidden from `/v1/models` for privacy but direct calls still work |
+| `nvidia/gpt-oss-20b` | 128K | OpenAI open-weight 20B — 155 tok/s. Hidden from `/v1/models` but direct calls still work |
+
+> Need V4-Pro-class reasoning? Use the paid `deepseek/deepseek-v4-pro` ($0.435/$0.87 — the 75% launch promo became the permanent list price after 2026-05-31) — `nvidia/deepseek-v4-pro` is currently hidden because NVIDIA's NIM deployment is hung; backend MODEL_REDIRECTS forwards calls to V4 Flash.
+
+> Privacy note: `nvidia/gpt-oss-120b` and `nvidia/gpt-oss-20b` are hidden from `/v1/models` because NVIDIA's free build.nvidia.com tier reserves the right to use prompts/outputs for service improvement. Direct calls by full model ID still work — opt in only when your data isn't sensitive.
+
+> Retired: `nvidia/qwen3-next-80b-a3b-thinking` hit NVIDIA end-of-life 2026-05-21 (HTTP 410). The gateway auto-redirects pinned callers to `nvidia/llama-4-maverick`.
+
+## Quick Start (Solana)
+
+```typescript
+import { SolanaLLMClient } from '@blockrun/llm';
+
+// SOLANA_WALLET_KEY env var (bs58-encoded Solana secret key)
+const client = new SolanaLLMClient();
+const response = await client.chat('openai/gpt-4o', 'gm Solana');
+console.log(response);
+```
+
+Set `SOLANA_WALLET_KEY` to your bs58-encoded Solana secret key. Payments are automatic via x402 — your key never leaves your machine.
+
+## Solana Support
+
+Pay for AI calls with Solana USDC via [sol.blockrun.ai](https://sol.blockrun.ai):
+
+```typescript
+import { SolanaLLMClient } from '@blockrun/llm';
+
+// SOLANA_WALLET_KEY env var (bs58-encoded Solana secret key)
+const client = new SolanaLLMClient();
+
+// Or pass key directly
+const client2 = new SolanaLLMClient({ privateKey: 'your-bs58-solana-key' });
+
+// Same API as LLMClient
+const response = await client.chat('openai/gpt-4o', 'gm Solana');
+console.log(response);
+
+// Live Search with Grok (Solana payment)
+const tweet = await client.chat('xai/grok-3-mini', 'What is trending on X?', { search: true });
+```
+
+**Setup:**
+1. Export your Solana wallet key: `export SOLANA_WALLET_KEY="your-bs58-key"`
+2. Fund with USDC on Solana mainnet
+3. That's it — payments are automatic via x402
+
+**Supported endpoint:** `https://sol.blockrun.ai/api`
+**Payment:** Solana USDC (SPL, mainnet)
+
+## How It Works
+
+1. You send a request to BlockRun's API
+2. The API returns a 402 Payment Required with the price
+3. The SDK automatically signs a USDC payment on Base
+4. The request is retried with the payment proof
+5. You receive the AI response
+
+**Your private key never leaves your machine** - it's only used for local signing.
+
+## Smart Routing (ClawRouter)
+
+Let the SDK automatically pick the cheapest capable model for each request:
+
+```typescript
+import { LLMClient } from '@blockrun/llm';
+
+const client = new LLMClient();
+
+// Auto-routes to cheapest capable model
+const result = await client.smartChat('What is 2+2?');
+console.log(result.response);     // '4'
+console.log(result.model);        // 'moonshot/kimi-k2.5' (cheap, fast)
+console.log(`Saved ${(result.routing.savings * 100).toFixed(0)}%`); // 'Saved 78%'
+
+// Complex reasoning task -> routes to reasoning model
+const complex = await client.smartChat('Prove the Riemann hypothesis step by step');
+console.log(complex.model);  // 'xai/grok-4-1-fast-reasoning'
+
+// Inspect the fallback chain SmartChat will walk on transient errors.
+console.log(complex.routing.fallbacks);  // ['anthropic/claude-opus-4.7', ...]
+```
+
+### Automatic Fallback on Transient Errors
+
+`smartChat()` populates a tier-specific fallback chain and `chat()` /
+`chatCompletion()` walk it automatically when the primary model returns a
+transient error — timeouts, network failures, or 5xx responses (502/503/504/
+522/524). 4xx errors and `PaymentError` propagate immediately so wallet /
+auth issues surface fast.
+
+```typescript
+// Manually pass a fallback chain to chat() / chatCompletion()
+const reply = await client.chat('nvidia/deepseek-v4-flash', 'hello', {
+  fallbackModels: ['nvidia/llama-4-maverick', 'nvidia/mistral-small-4-119b'],
+});
+// If deepseek-v4-flash times out, the SDK retries against the next model
+// and logs each hop to stderr: "[@blockrun/llm] <from> -> <to> (...)".
+```
+
+### Routing Profiles
+
+| Profile | Description | Best For |
+|---------|-------------|----------|
+| `free` | NVIDIA free tier — smart-routes across 8 models (DeepSeek V4 Flash, Nemotron Nano Omni, Qwen3, Llama 4, Mistral, plus 2 hidden gpt-oss) | Zero-cost testing, dev, prod |
+| `eco` | Cheapest models per tier (DeepSeek, xAI) | Cost-sensitive production |
+| `auto` | Best balance of cost/quality (default) | General use |
+| `premium` | Top-tier models (OpenAI, Anthropic) | Quality-critical tasks |
+
+```typescript
+// Use premium models for complex tasks
+const result = await client.smartChat(
+  'Write production-grade async TypeScript code',
+  { routingProfile: 'premium' }
+);
+console.log(result.model);  // 'anthropic/claude-opus-4.7'
+```
+
+### How ClawRouter Works
+
+ClawRouter uses a 14-dimension rule-based classifier to analyze each request:
+
+- **Token count** - Short vs long prompts
+- **Code presence** - Programming keywords
+- **Reasoning markers** - "prove", "step by step", etc.
+- **Technical terms** - Architecture, optimization, etc.
+- **Creative markers** - Story, poem, brainstorm, etc.
+- **Agentic patterns** - Multi-step, tool use indicators
+
+The classifier runs in <1ms, 100% locally, and routes to one of four tiers:
+
+| Tier | Example Tasks | Auto Profile Model |
+|------|---------------|-------------------|
+| SIMPLE | "What is 2+2?", definitions | moonshot/kimi-k2.5 |
+| MEDIUM | Code snippets, explanations | xai/grok-code-fast-1 |
+| COMPLEX | Architecture, long documents | google/gemini-3.1-pro |
+| REASONING | Proofs, multi-step reasoning | xai/grok-4-1-fast-reasoning |
+
+## Available Models
+
+### OpenAI GPT-5.5 Family
+Released 2026-04-23 — first fully retrained base since GPT-4.5. 1M context, 128K output, native agent + computer use.
+
+| Model | Input Price | Output Price |
+|-------|-------------|--------------|
+| `openai/gpt-5.5` | $5.00/M | $30.00/M |
+
+### OpenAI GPT-5.4 Family
+| Model | Input Price | Output Price |
+|-------|-------------|--------------|
+| `openai/gpt-5.4` | $2.50/M | $15.00/M |
+| `openai/gpt-5.4-pro` | $30.00/M | $180.00/M |
+| `openai/gpt-5.4-nano` | $0.20/M | $1.25/M |
+
+### OpenAI GPT-5 Family
+| Model | Input Price | Output Price |
+|-------|-------------|--------------|
+| `openai/gpt-5.3` | $1.75/M | $14.00/M |
+| `openai/gpt-5.2` | $1.75/M | $14.00/M |
+| `openai/gpt-5-mini` | $0.25/M | $2.00/M |
+| `openai/gpt-5.2-pro` | $21.00/M | $168.00/M |
+| `openai/gpt-5.2-codex` | $1.75/M | $14.00/M |
+
+### OpenAI GPT-4 Family
+| Model | Input Price | Output Price |
+|-------|-------------|--------------|
+| `openai/gpt-4.1` | $2.00/M | $8.00/M |
+| `openai/gpt-4.1-mini` | $0.40/M | $1.60/M |
+| `openai/gpt-4.1-nano` | $0.10/M | $0.40/M |
+| `openai/gpt-4o` | $2.50/M | $10.00/M |
+| `openai/gpt-4o-mini` | $0.15/M | $0.60/M |
+
+### OpenAI O-Series (Reasoning)
+| Model | Input Price | Output Price |
+|-------|-------------|--------------|
+| `openai/o1` | $15.00/M | $60.00/M |
+| `openai/o3` | $2.00/M | $8.00/M |
+| `openai/o3-mini` | $1.10/M | $4.40/M |
+| `openai/o4-mini` | $1.10/M | $4.40/M |
+
+### Anthropic Claude
+| Model | Input Price | Output Price | Context | Notes |
+|-------|-------------|--------------|---------|-------|
+| `anthropic/claude-opus-4.8` | $5.00/M | $25.00/M | **1M** | Flagship — agentic coding + adaptive thinking, 128K output |
+| `anthropic/claude-opus-4.7` | $5.00/M | $25.00/M | **1M** | Agentic coding + adaptive thinking, 128K output |
+| `anthropic/claude-opus-4.6` | $5.00/M | $25.00/M | 200K | Hidden but still callable — kept as in-family hot-swap fallback |
+| `anthropic/claude-opus-4.5` | $5.00/M | $25.00/M | 200K | |
+| `anthropic/claude-opus-4` | $15.00/M | $75.00/M | 200K | |
+| `anthropic/claude-sonnet-4.6` | $3.00/M | $15.00/M | 200K | Best for reasoning/instructions |
+| `anthropic/claude-sonnet-4` | $3.00/M | $15.00/M | 200K | |
+| `anthropic/claude-haiku-4.5` | $1.00/M | $5.00/M | 200K | |
+
+### Google Gemini
+| Model | Input Price | Output Price |
+|-------|-------------|--------------|
+| `google/gemini-3.1-pro` | $2.00/M | $12.00/M |
+| `google/gemini-3.5-flash` | $0.50/M | $3.00/M |
+| `google/gemini-3.1-flash-lite` | $0.25/M | $1.50/M |
+| `google/gemini-3-flash-preview` | $0.50/M | $3.00/M |
+| `google/gemini-2.5-pro` | $1.25/M | $10.00/M |
+| `google/gemini-2.5-flash` | $0.30/M | $2.50/M |
+| `google/gemini-2.5-flash-lite` | $0.10/M | $0.40/M |
+
+### DeepSeek
+
+V4 family launched 2026-04-24. DeepSeek upstream now serves the legacy
+`deepseek-chat` / `deepseek-reasoner` aliases as V4 Flash non-thinking /
+thinking modes. V4 Pro is the new flagship paid SKU — 1.6T MoE / 49B active,
+1M context, MMLU-Pro 87.5, GPQA 90.1, SWE-bench 80.6, LiveCodeBench 93.5.
+
+| Model | Input Price | Output Price | Context | Notes |
+|-------|-------------|--------------|---------|-------|
+| `deepseek/deepseek-v4-pro` | $0.435/M | $0.87/M | 1M | V4 flagship — strongest open-weight reasoner. The 75% launch promo became the permanent list price after 2026-05-31 |
+| `deepseek/deepseek-chat` | $0.20/M | $0.40/M | 1M | V4 Flash non-thinking (paid endpoint with 5MB request bodies; same upstream as `nvidia/deepseek-v4-flash`) |
+| `deepseek/deepseek-reasoner` | $0.20/M | $0.40/M | 1M | V4 Flash thinking (same upstream as `deepseek-chat`, thinking enabled by default) |
+
+### xAI Grok
+
+Grok 4.3 and Grok Build are resold through BlockRun's OpenRouter credit pool
+(same pattern as `deepseek/deepseek-v4-pro` and `minimax/minimax-m3`). The
+older Grok chat SKUs (grok-3/3-mini, grok-4-fast / 4-1-fast families,
+grok-code-fast-1, grok-4-0709, grok-2-vision) are now **hidden from
+`/v1/models`** — direct calls by full ID still work, but SmartChat won't
+auto-pick them.
+
+| Model | Input Price | Output Price | Context | Notes |
+|-------|-------------|--------------|---------|-------|
+| `xai/grok-4.3` | $1.50/M | $4.00/M | 1M | Reasoning model, vision-capable, tuned for agentic workflows |
+| `xai/grok-build-0.1` | $1.50/M | $3.00/M | 256K | Fast agentic coding model — interactive software-engineering workflows |
+
+### Moonshot Kimi
+| Model | Input Price | Output Price |
+|-------|-------------|--------------|
+| `moonshot/kimi-k2.6` | $0.95/M | $4.00/M |
+| `moonshot/kimi-k2.5` | $0.60/M | $3.00/M |
+
+### MiniMax
+| Model | Input Price | Output Price |
+|-------|-------------|--------------|
+| `minimax/minimax-m3` | $0.30/M | $1.20/M |
+| `minimax/minimax-m2.7` | $0.30/M | $1.20/M |
+
+### NVIDIA (Free) + Moonshot
+
+Free tier refreshed 2026-04-28: added `nvidia/deepseek-v4-flash` (1M context)
+and Nemotron Nano Omni (vision). `nvidia/gpt-oss-120b` and
+`nvidia/gpt-oss-20b` were briefly delisted over privacy concerns then
+**re-enabled 2026-04-30** with `available: true` + `hidden: true` — they
+no longer appear in `/v1/models` (so SmartChat won't auto-pick them) but
+direct calls by full ID still return HTTP 200. `nvidia/deepseek-v4-pro`,
+`nvidia/deepseek-v3.2`, and `nvidia/glm-4.7` are hidden because NVIDIA's
+NIM deployment is hung — backend MODEL_REDIRECTS forwards calls to V4
+Flash / qwen3-coder. `nvidia/qwen3-next-80b-a3b-thinking` hit NVIDIA
+end-of-life 2026-05-21 (HTTP 410) and is auto-redirected to
+`nvidia/llama-4-maverick`.
+
+| Model | Input Price | Output Price | Notes |
+|-------|-------------|--------------|-------|
+| `nvidia/deepseek-v4-flash` | **FREE** | **FREE** | 284B / 13B active MoE, 1M context — best free chat / summarization / light reasoning |
+| `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning` | **FREE** | **FREE** | 31B / 3.2B active MoE, 256K — only vision-capable free model |
+| `nvidia/mistral-small-4-119b` | **FREE** | **FREE** | ⚠️ Upstream timing out as of 2026-06-07 |
+| `nvidia/llama-4-maverick` | **FREE** | **FREE** | Meta Llama 4 Maverick MoE |
+| `nvidia/qwen3-coder-480b` | **FREE** | **FREE** | Coding-optimised 480B MoE |
+| `nvidia/gpt-oss-120b` | **FREE** | **FREE** | Hidden from `/v1/models` for privacy but direct calls still work — 123 tok/s |
+| `nvidia/gpt-oss-20b` | **FREE** | **FREE** | Hidden from `/v1/models` but direct calls still work — 155 tok/s |
+| `moonshot/kimi-k2.5` | $0.60/M | $3.00/M | Direct from Moonshot — replaces `nvidia/kimi-k2.5` |
+
+### E2E Verified Models
+
+All models below have been tested end-to-end via the TypeScript SDK (Feb 2026):
+
+| Provider | Model | Status |
+|----------|-------|--------|
+| OpenAI | `openai/gpt-4o-mini` | Passed |
+| OpenAI | `openai/gpt-5.2-codex` | Passed |
+| Anthropic | `anthropic/claude-opus-4.6` | Passed |
+| Anthropic | `anthropic/claude-sonnet-4` | Passed |
+| Google | `google/gemini-2.5-flash` | Passed |
+| DeepSeek | `deepseek/deepseek-chat` | Passed |
+| xAI | `xai/grok-3` | Passed |
+| Moonshot | `moonshot/kimi-k2.6` | Passed |
+
+### Image Generation
+| Model | Price |
+|-------|-------|
+| `openai/dall-e-3` | $0.04-0.08/image |
+| `openai/gpt-image-1` | $0.02-0.04/image |
+| `openai/gpt-image-2` | $0.06-0.12/image (reasoning-driven, multilingual text rendering, character consistency) |
+| `google/nano-banana` | $0.05/image |
+| `google/nano-banana-pro` | $0.10-0.15/image |
+| `xai/grok-imagine-image` | $0.02/image |
+| `xai/grok-imagine-image-pro` | $0.07/image |
+| `zai/cogview-4` | $0.015/image |
+
+Image editing (`client.edit`) via `/v1/images/image2image`: `openai/gpt-image-1`, `openai/gpt-image-2`, `google/nano-banana`, and `google/nano-banana-pro`. Pass a single base64 `data:image/...` URI to edit one image, or an array of 2–4 URIs to **fuse** them (e.g. a subject + a brand logo). Fusion caps: `openai/*` up to 4 source images, `google/*` up to 3. A `mask` cannot be combined with multiple source images.
+
+```ts
+// Multi-image fusion with Nano Banana
+const fused = await client.edit(
+  "Place the logo on the t-shirt",
+  [subjectDataUri, logoDataUri],
+  { model: "google/nano-banana" }
+);
+console.log(fused.data[0].url);
+```
+
+### Video Generation
+| Model | Price |
+|-------|-------|
+| `xai/grok-imagine-video` | $0.05/sec (8s default → $0.42/clip) |
+| `bytedance/seedance-1.5-pro` | $0.03/sec (5s default, up to 10s, 720p) |
+| `bytedance/seedance-2.0-fast` | $0.15/sec (~60-80s gen, sweet-spot price/quality) |
+| `bytedance/seedance-2.0` | $0.30/sec (720p Pro) |
+
+```ts
+import { VideoClient } from '@blockrun/llm';
+
+const client = new VideoClient();
+const result = await client.generate('a red apple slowly spinning on a wooden table');
+console.log(result.data[0].url);             // permanent MP4 URL
+console.log(result.data[0].duration_seconds); // 8
+
+// Image-to-video
+const r2 = await client.generate('the subject turns and smiles', {
+  imageUrl: 'https://example.com/portrait.jpg',
+});
+
+// Token360 / Seedance options (silently ignored by xAI Grok video)
+const r3 = await client.generate('aerial drone shot over a snowy mountain', {
+  model: 'bytedance/seedance-2.0-fast',
+  aspectRatio: '21:9',
+  resolution: '1080p',
+  generateAudio: true,    // omit to use the model's default
+  seed: 42,
+  watermark: false,
+  returnLastFrame: true,  // useful for clip chaining
+});
+
+// First-and-last-frame interpolation (Seedance only): the model tweens
+// from imageUrl (first frame) to lastFrameUrl (final frame).
+// Priced identically to image-to-video.
+const r4 = await client.generate('the flower blooms in golden morning light', {
+  model: 'bytedance/seedance-1.5-pro',
+  imageUrl: 'https://example.com/bud.jpg',
+  lastFrameUrl: 'https://example.com/bloom.jpg',
+});
+
+// Omni / multi-reference (Seedance 2.0 only): up to 9 reference images
+// for character/style consistency. Cite them as "image 1", "image 2" in
+// the prompt. Mutually exclusive with imageUrl / lastFrameUrl /
+// realFaceAssetId.
+const r5 = await client.generate(
+  'the character from image 1 walks through the city from image 2',
+  {
+    model: 'bytedance/seedance-2.0',
+    referenceImageUrls: [
+      'https://example.com/character.jpg',
+      'https://example.com/city.jpg',
+    ],
+  }
+);
+```
+
+### Text-to-Speech & Sound Effects
+
+`SpeechClient` wraps BlockRun Voice (ElevenLabs): `POST /v1/audio/speech`
+(OpenAI-compatible TTS), `POST /v1/audio/sound-effects`, and the free
+`GET /v1/audio/voices`. TTS price scales with character count:
+`(chars / 1000) × model rate`, minimum $0.001/request. Synthesis is
+synchronous (<1s for Flash).
+
+| Model | Price | Max Input | Notes |
+|-------|-------|-----------|-------|
+| `elevenlabs/flash-v2.5` | $0.05/1k chars | 40k chars | ~75ms latency, 32 languages (default) |
+| `elevenlabs/turbo-v2.5` | $0.05/1k chars | 40k chars | ~250ms latency, balanced quality |
+| `elevenlabs/multilingual-v2` | $0.10/1k chars | 10k chars | Long-form narration, audiobooks |
+| `elevenlabs/v3` | $0.10/1k chars | 5k chars | Max expressiveness, 70+ languages |
+| `elevenlabs/sound-effects` | $0.05/generation | 1k chars | Sound effects up to 22s |
+
+```ts
+import { SpeechClient } from '@blockrun/llm';
+
+const client = new SpeechClient();
+
+// Text-to-speech (voice aliases: sarah, george, laura, charlie,
+// river, roger, callum, harry — or any raw ElevenLabs voice_id)
+const result = await client.generate('Welcome to BlockRun.', { voice: 'george' });
+console.log(result.data[0].url);  // audio URL (mp3 by default)
+
+// Other formats / speed
+const wav = await client.generate('Breaking news from the world of micropayments.', {
+  model: 'elevenlabs/v3',
+  responseFormat: 'wav',
+  speed: 1.1,
+});
+
+// Sound effects (flat $0.05/generation)
+const fx = await client.soundEffect('rain on a tin roof, distant thunder');
+
+// List voices (free, rate-limited)
+const voices = await client.listVoices();
+```
+
+### Virtual Portraits
+
+`PortraitClient` wraps `POST /v1/portrait/enroll` (paid, flat **$0.01** promo,
+no KYC). Enroll a face image by URL and get back a Token360 asset id (`ta_xxxxxx`).
+Pass that id as `realFaceAssetId` on a Seedance 2.0 video generation to keep the
+same AI character across clips. Payment settles only after Token360 confirms the
+enrollment, so a failed enrollment never charges your wallet. The returned
+`image_url` is a gateway-mirrored copy of your source image (see `mirrored` /
+`source_image_url`). (Real-person likeness is not supported on BlockRun —
+enrolled portraits are AI characters.)
+
+```ts
+import { PortraitClient, VideoClient } from '@blockrun/llm';
+
+const portraits = new PortraitClient();
+const { asset_id } = await portraits.enroll({
+  name: 'Spokesperson',
+  imageUrl: 'https://example.com/face.jpg',  // public https JPG/PNG/WEBP, ≤10 MB
+});
+
+// Reuse the same character across Seedance 2.0 clips
+const video = new VideoClient();
+const clip = await video.generate('she waves and smiles', {
+  model: 'bytedance/seedance-2.0-fast',
+  realFaceAssetId: asset_id,
+});
+console.log(clip.data[0].url);
+```
+
+### Voice Calls
+
+`VoiceClient` wraps `POST /v1/voice/call` (paid, $0.54/call) and
+`GET /v1/voice/call/{callId}` (free polling) — AI-powered outbound phone
+calls powered by Bland.ai. The agent dials the recipient and runs a real-time
+conversation based on your `task` instructions. US + Canada destinations.
+
+```ts
+import { VoiceClient } from '@blockrun/llm';
+
+const client = new VoiceClient();
+
+// Initiate (paid $0.54)
+const result = await client.call({
+  to: '+14155552671',
+  task: 'You are a friendly assistant calling to confirm a 3pm dentist appointment.',
+  voice: 'maya',     // 'nat' | 'josh' | 'maya' | 'june' | 'paige' | 'derek' | 'florian'
+  max_duration: 5,   // minutes (1–30)
+});
+console.log(result.call_id);
+
+// Poll for transcript + recording (free)
+const status = await client.getStatus(result.call_id);
+console.log(status.status, status.recording_url);
+```
+
+Bring your own caller-ID: pass `from: '+14155552671'` (must be a BlockRun
+phone number you own; buy via `/v1/phone/numbers/buy`).
+
+### Standalone Search
+
+`SearchClient` wraps `POST /v1/search` — standalone Grok Live Search.
+Pricing: `$0.025/source + margin` (10 sources ≈ `$0.26`).
+
+```ts
+import { SearchClient } from '@blockrun/llm';
+
+const client = new SearchClient();
+const result = await client.search('Latest news on x402 adoption', {
+  sources: ['x', 'web'],
+  maxResults: 10,
+});
+console.log(result.summary);
+for (const url of result.citations ?? []) console.log(url);
+```
+
+### Surf Crypto Data
+
+`SurfClient` exposes the full `/v1/surf/*` catalog — 84+ pay-per-call
+endpoints across CEX/DEX market data, on-chain SQL, wallet intelligence,
+prediction markets (Polymarket + Kalshi), social analytics, news, VC fund
+data, and an OpenAI-compatible chat surface. Flat pricing per call:
+
+| Tier | Price/call | Examples |
+|------|-----------|----------|
+| 1 | $0.001 | `/market/price`, `/market/ranking`, `/news/feed`, prediction-market reads, social tweets |
+| 2 | $0.005 | `/exchange/depth`, `/exchange/klines`, `/wallet/detail`, `/search/*`, `/social/ranking` |
+| 3 | $0.020 | `/onchain/sql`, `/onchain/query`, `/onchain/schema`, `/chat/completions` |
+
+Because the catalog is broad and evolving, the client deliberately ships a
+generic `get` / `post` pair instead of 84 typed wrappers. Pass the path
+(with or without the `/v1/surf` prefix), query params, or a JSON body —
+type the response via a generic if you want.
+
+```ts
+import { SurfClient } from '@blockrun/llm';
+
+const surf = new SurfClient();
+
+// Tier 1 — token price ($0.001)
+const btc = await surf.get('/market/price', { symbol: 'BTC' });
+
+// Tier 2 — order book depth ($0.005)
+const book = await surf.get('/exchange/depth', {
+  exchange: 'binance',
+  symbol: 'BTC-USDT',
+});
+
+// Tier 3 — raw on-chain SQL against 80+ ClickHouse tables ($0.020)
+const rows = await surf.post('/onchain/sql', {
+  query: 'SELECT block_number FROM ethereum.blocks ORDER BY block_number DESC LIMIT 5',
+});
+
+// Typed response via generic
+type Price = { symbol: string; price: number; timestamp: string };
+const eth = await surf.get<Price>('/market/price', { symbol: 'ETH' });
+```
+
+Full endpoint inventory: <https://blockrun.ai/marketplace/surf>.
+
+Methods: `userLookup`, `userInfo`, `followers`, `following`, `followings`,
+`verifiedFollowers`, `userTweets`, `mentions`, `tweetLookup`, `tweetReplies`,
+`tweetThread`, `search`, `trending`, `articlesRising`.
+
+### Market Data (Pyth)
+
+`PriceClient` wraps the Pyth-backed market-data endpoints. Crypto, FX and
+commodity are fully free (price + history + list); 12 global stock markets
+and the `usstock` legacy alias charge `$0.001` for price + history (list is
+always free). Pass `requireWallet: false` to construct a free-only client.
+
+```ts
+import { PriceClient } from '@blockrun/llm';
+
+const p = new PriceClient({ requireWallet: false });
+const btc = await p.price('crypto', 'BTC-USD');
+const eur = await p.price('fx', 'EUR-USD');
+
+// Paid — requires a wallet
+const p2 = new PriceClient();
+const aapl = await p2.price('stocks', 'AAPL', { market: 'us' });
+const bars = await p2.history('stocks', 'AAPL', {
+  market: 'us',
+  resolution: 'D',
+  from: 1700000000,
+  to: 1710000000,
+});
+const symbols = await p.listSymbols('crypto', { query: 'sol', limit: 20 });
+```
+
+Supported `StockMarket` values: `us, hk, jp, kr, gb, de, fr, nl, ie, lu, cn, ca`.
+
+### Multi-chain RPC
+
+`RpcClient` wraps `POST /v1/rpc/{network}` — standard JSON-RPC 2.0 access to
+40+ chains through one endpoint (Ethereum, Base, Solana, Polygon, BSC,
+Arbitrum, Optimism, Avalanche, Bitcoin, Sui, and more; powered by Tatum's RPC
+gateway). No API key, no per-chain endpoints: flat **$0.002 per call** in
+USDC; a JSON-RPC batch charges per element.
+
+```ts
+import { RpcClient } from '@blockrun/llm';
+
+const client = new RpcClient();
+
+// EVM chains speak eth_* JSON-RPC
+const block = await client.call('ethereum', 'eth_blockNumber');
+console.log(parseInt(block.result as string, 16));
+
+const balance = await client.call('base', 'eth_getBalance', [
+  '0x4200000000000000000000000000000000000006',
+  'latest',
+]);
+
+// Non-EVM chains speak their native JSON-RPC
+const slot = await client.call('solana', 'getSlot');
+const tip = await client.call('bitcoin', 'getblockcount');
+
+// Batch: one payment, per-element pricing ($0.002 x N)
+const out = await client.batch('polygon', [
+  { method: 'eth_blockNumber' },
+  { method: 'eth_gasPrice' },
+]);
+
+console.log(block.network);   // 'ethereum' (canonical key from X-Network)
+console.log(block.cacheHit);  // true if served from the gateway's hot cache
+console.log(block.txHash);    // x402 settlement tx
+```
+
+40 curated chains are exported as `SUPPORTED_NETWORKS`; common aliases
+(`eth`, `arb`, `op`, `matic`, `bnb`, `avax`, `sol`, `btc`, `xrp`, `dot`, ...)
+resolve server-side (`NETWORK_ALIASES`). Unknown but well-formed slugs fall
+through to a generic `{slug}-mainnet` gateway attempt, so new chains work
+without an SDK update. Hot, low-volatility reads (`eth_chainId`, mined
+blocks/receipts, `getTransaction`, ...) are served from a method-aware
+gateway cache — same price, lower latency.
+
+### Testnet Models (Base Sepolia)
+| Model | Price |
+|-------|-------|
+| `openai/gpt-oss-20b` | $0.001/request |
+| `openai/gpt-oss-120b` | $0.002/request |
+
+*Testnet models use flat pricing (no token counting) for simplicity.*
+
+## Standalone Search
+
+Search web, X/Twitter, and news without using a chat model:
+
+```typescript
+import { LLMClient } from '@blockrun/llm';
+
+const client = new LLMClient();
+
+const result = await client.search('latest AI agent frameworks 2026');
+console.log(result.summary);
+for (const cite of result.citations ?? []) {
+  console.log(`  - ${cite}`);
+}
+
+// Filter by source type and date range
+const filtered = await client.search('BlockRun x402', {
+  sources: ['web', 'x'],
+  fromDate: '2026-01-01',
+  maxResults: 5,
+});
+```
+
+## Image Editing (img2img)
+
+Edit existing images with text prompts:
+
+```typescript
+import { LLMClient } from '@blockrun/llm';
+
+const client = new LLMClient();
+
+const result = await client.imageEdit(
+  'Make the sky purple and add northern lights',
+  'data:image/png;base64,...',  // base64 or URL
+  { model: 'openai/gpt-image-1' }
+);
+console.log(result.data[0].url);
+```
+
+## Usage Examples
+
+### Simple Chat
+
+```typescript
+import { LLMClient } from '@blockrun/llm';
+
+const client = new LLMClient();  // Uses BASE_CHAIN_WALLET_KEY (never sent to server)
+
+const response = await client.chat('openai/gpt-4o', 'Explain quantum computing');
+console.log(response);
+
+// With system prompt
+const response2 = await client.chat('anthropic/claude-sonnet-4', 'Write a haiku', {
+  system: 'You are a creative poet.',
+});
+```
+
+### Smart Routing (ClawRouter)
+
+Save up to 78% on inference costs with intelligent model routing. ClawRouter uses a 14-dimension rule-based scoring algorithm to select the cheapest model that can handle your request (<1ms, 100% local).
+
+```typescript
+import { LLMClient } from '@blockrun/llm';
+
+const client = new LLMClient();
+
+// Auto-route to cheapest capable model
+const result = await client.smartChat('What is 2+2?');
+console.log(result.response);     // '4'
+console.log(result.model);        // 'google/gemini-2.5-flash'
+console.log(result.routing.tier); // 'SIMPLE'
+console.log(`Saved ${(result.routing.savings * 100).toFixed(0)}%`); // 'Saved 78%'
+
+// Routing profiles
+const free = await client.smartChat('Hello!', { routingProfile: 'free' });     // Zero cost
+const eco = await client.smartChat('Explain AI', { routingProfile: 'eco' });   // Budget optimized
+const auto = await client.smartChat('Code review', { routingProfile: 'auto' }); // Balanced (default)
+const premium = await client.smartChat('Write a legal brief', { routingProfile: 'premium' }); // Best quality
+```
+
+**Routing Profiles:**
+
+| Profile | Description | Best For |
+|---------|-------------|----------|
+| `free` | NVIDIA free tier (9 models, smart-routed) | Zero-cost testing, dev, prod |
+| `eco` | Budget-optimized | Cost-sensitive workloads |
+| `auto` | Intelligent routing (default) | General use |
+| `premium` | Best quality models | Critical tasks |
+
+**Tiers:**
+
+| Tier | Example Tasks | Typical Models |
+|------|---------------|----------------|
+| SIMPLE | Greetings, math, lookups | Gemini Flash, GPT-4o-mini |
+| MEDIUM | Explanations, summaries | GPT-4o, Claude Sonnet |
+| COMPLEX | Analysis, code generation | GPT-5.2, Claude Opus |
+| REASONING | Multi-step logic, planning | o3, DeepSeek Reasoner |
+
+### Full Chat Completion
+
+```typescript
+import { LLMClient, type ChatMessage } from '@blockrun/llm';
+
+const client = new LLMClient();  // Uses BASE_CHAIN_WALLET_KEY (never sent to server)
+
+const messages: ChatMessage[] = [
+  { role: 'system', content: 'You are a helpful assistant.' },
+  { role: 'user', content: 'How do I read a file in Node.js?' },
+];
+
+const result = await client.chatCompletion('openai/gpt-4o', messages);
+console.log(result.choices[0].message.content);
+```
+
+### Streaming
+
+Stream responses token-by-token with automatic x402 payment. Uses a **pre-auth cache** to skip the 402 round-trip on repeat calls to the same model (~200ms saved per request after the first).
+
+#### OpenAI-compatible (recommended)
+
+```typescript
+import { OpenAI } from '@blockrun/llm';
+
+const client = new OpenAI({ walletKey: process.env.BASE_CHAIN_WALLET_KEY });
+
+const stream = await client.chat.completions.create({
+  model: 'openai/gpt-5.4',
+  messages: [{ role: 'user', content: 'Write a short story about AI agents' }],
+  stream: true,
+});
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta?.content || '');
+}
+```
+
+#### Native client
+
+```typescript
+import { LLMClient, type ChatMessage } from '@blockrun/llm';
+
+const client = new LLMClient();
+
+const messages: ChatMessage[] = [
+  { role: 'user', content: 'Explain quantum computing in simple terms' },
+];
+
+// Returns a raw fetch Response with SSE body
+const response = await client.chatCompletionStream('google/gemini-2.5-flash', messages);
+
+const reader = response.body!.getReader();
+const decoder = new TextDecoder();
+
+while (true) {
+  const { done, value } = await reader.read();
+  if (done) break;
+
+  const chunk = decoder.decode(value, { stream: true });
+  for (const line of chunk.split('\n')) {
+    if (!line.startsWith('data: ') || line === 'data: [DONE]') continue;
+    const data = JSON.parse(line.slice(6));
+    process.stdout.write(data.choices?.[0]?.delta?.content || '');
+  }
+}
+```
+
+#### Payment + streaming flow
+
+```
+First call (cache miss):
+  1. Send request → 402 response (BlockRun returns price)
+  2. Sign USDC payment locally (key never leaves machine)
+  3. Retry with PAYMENT-SIGNATURE header + stream: true
+  4. Cache payment requirements for this model (1h TTL)
+  5. Stream tokens as they arrive
+
+Subsequent calls (cache hit):
+  1. Pre-sign payment from cache — skip 402 round-trip
+  2. Send request with PAYMENT-SIGNATURE upfront
+  3. Stream tokens immediately (~200ms faster)
+```
+
+### List Available Models
+
+```typescript
+import { LLMClient } from '@blockrun/llm';
+
+const client = new LLMClient();  // Uses BASE_CHAIN_WALLET_KEY (never sent to server)
+const models = await client.listModels();
+
+for (const model of models) {
+  console.log(`${model.id}: $${model.inputPrice}/M input`);
+}
+```
+
+### Multiple Requests
+
+```typescript
+import { LLMClient } from '@blockrun/llm';
+
+const client = new LLMClient();  // Uses BASE_CHAIN_WALLET_KEY (never sent to server)
+
+const [gpt, claude, gemini] = await Promise.all([
+  client.chat('openai/gpt-4o', 'What is 2+2?'),
+  client.chat('anthropic/claude-sonnet-4', 'What is 3+3?'),
+  client.chat('google/gemini-2.5-flash', 'What is 4+4?'),
+]);
+```
+
+## Prediction Markets (Powered by Predexon)
+
+Access real-time prediction market data from Polymarket, Kalshi, and Binance Futures via [Predexon](https://predexon.com). No API keys needed — pay-per-request via x402.
+
+### Polymarket
+
+```typescript
+import { LLMClient } from '@blockrun/llm';
+
+const client = new LLMClient();
+
+// List markets with optional filters ($0.001/request)
+const markets = await client.pm("polymarket/markets");
+const filtered = await client.pm("polymarket/markets", { status: "active", limit: 10 });
+const searched = await client.pm("polymarket/markets", { search: "bitcoin" });
+
+// List events ($0.001/request)
+const events = await client.pm("polymarket/events");
+
+// Historical trades ($0.001/request)
+const trades = await client.pm("polymarket/trades");
+
+// OHLCV candlestick data for a specific condition ($0.001/request)
+const candles = await client.pm("polymarket/candlesticks/0x1234abcd...");
+
+// Wallet profile ($0.005/request — tier 2)
+const profile = await client.pm("polymarket/wallet/0xABC123...");
+
+// Wallet P&L ($0.005/request — tier 2)
+const pnl = await client.pm("polymarket/wallet/pnl/0xABC123...");
+
+// Global leaderboard ($0.001/request)
+const leaderboard = await client.pm("polymarket/leaderboard");
+```
+
+### Kalshi & Binance
+
+```typescript
+// Kalshi markets ($0.001/request)
+const kalshiMarkets = await client.pm("kalshi/markets");
+
+// Kalshi trades ($0.001/request)
+const kalshiTrades = await client.pm("kalshi/trades");
+
+// Binance candles for supported pairs ($0.001/request)
+const btcCandles = await client.pm("binance/candles/BTCUSDT");
+const ethCandles = await client.pm("binance/candles/ETHUSDT");
+// Also: SOLUSDT, XRPUSDT
+```
+
+### Cross-Platform
+
+```typescript
+// Cross-platform matching pairs ($0.001/request)
+const pairs = await client.pm("matching-markets/pairs");
+```
+
+All current endpoints are GET. The `pmQuery()` method is available for future POST endpoints.
+
+Works on both `LLMClient` (Base) and `SolanaLLMClient`.
+
+## Exa Web Search (Powered by Exa)
+
+Access [Exa](https://exa.ai)'s neural web search via x402. No API keys needed — pay-per-request. Available on **`LLMClient` (Base USDC)** and `SolanaLLMClient` (Solana USDC). Use Base as the primary path; the Solana gateway is awaiting `EXA_API_KEY` provisioning.
+
+| Method | Description | Price |
+|---|---|---|
+| `exaSearch(query, options?)` | Neural/keyword web search | $0.01/request |
+| `exaFindSimilar(url, options?)` | Find semantically similar pages | $0.01/request |
+| `exaContents(urls, options?)` | Extract full text from URLs | $0.002/URL |
+| `exaAnswer(query, options?)` | AI answer grounded in web search | $0.01/request |
+| `exa(path, body)` | Generic proxy for any Exa endpoint | varies |
+
+```typescript
+import { LLMClient } from '@blockrun/llm';
+
+const client = new LLMClient();
+
+// Neural web search ($0.01/request)
+const results = await client.exaSearch("latest AI safety research", { numResults: 5 });
+const news = await client.exaSearch("bitcoin ETF news", { category: "news", numResults: 10 });
+
+// Find similar pages ($0.01/request)
+const similar = await client.exaFindSimilar("https://openai.com/research/gpt-4", { numResults: 5 });
+
+// Extract content from URLs ($0.002/URL)
+const content = await client.exaContents(["https://arxiv.org/abs/2303.08774"]);
+
+// AI-generated answer from live web ($0.01/request)
+const answer = await client.exaAnswer("What is the current state of AI safety research?");
+
+// Generic proxy for any Exa endpoint
+const custom = await client.exa("search", { query: "transformer architecture", numResults: 5 });
+```
+
+Same surface on `SolanaLLMClient` once Solana-side `EXA_API_KEY` is provisioned.
+
+## Configuration
+
+```typescript
+// Default: reads BASE_CHAIN_WALLET_KEY from environment
+const client = new LLMClient();
+
+// Or pass options explicitly
+const client = new LLMClient({
+  privateKey: '0x...',           // Your wallet key (never sent to server)
+  apiUrl: 'https://blockrun.ai/api',   // Optional
+  timeout: 60000,                // Optional (ms)
+});
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `BASE_CHAIN_WALLET_KEY` | Your Base chain wallet private key (for Base / `LLMClient`) |
+| `SOLANA_WALLET_KEY` | Your Solana wallet secret key - bs58 encoded (for `SolanaLLMClient`) |
+| `BLOCKRUN_API_URL` | API endpoint (optional, default: https://blockrun.ai/api) |
+
+## Error Handling
+
+```typescript
+import { LLMClient, APIError, PaymentError } from '@blockrun/llm';
+
+const client = new LLMClient();
+
+try {
+  const response = await client.chat('openai/gpt-4o', 'Hello!');
+} catch (error) {
+  if (error instanceof PaymentError) {
+    console.error('Payment failed - check USDC balance');
+  } else if (error instanceof APIError) {
+    console.error(`API error: ${error.message}`);
+  }
+}
+```
+
+## Testing
+
+### Running Unit Tests
+
+Unit tests do not require API access or funded wallets:
+
+```bash
+npm test                          # Run tests in watch mode
+npm test run                      # Run tests once
+npm test -- --coverage            # Run with coverage report
+```
+
+### Running Integration Tests
+
+Integration tests call the production API and require:
+- A funded Base wallet with USDC ($1+ recommended)
+- `BASE_CHAIN_WALLET_KEY` environment variable set
+- Estimated cost: ~$0.05 per test run
+
+```bash
+export BASE_CHAIN_WALLET_KEY=0x...
+npm test -- test/integration       # Run integration tests only
+```
+
+Integration tests are automatically skipped if `BASE_CHAIN_WALLET_KEY` is not set.
+
+## Setting Up Your Wallet
+
+### Base (EVM)
+1. Create a wallet on Base (Coinbase Wallet, MetaMask, etc.)
+2. Get USDC on Base for API payments
+3. Export your private key and set as `BASE_CHAIN_WALLET_KEY`
+
+```bash
+# .env
+BASE_CHAIN_WALLET_KEY=0x...
+```
+
+### Solana
+1. Create a Solana wallet (Phantom, Backpack, Solflare, etc.)
+2. Get USDC on Solana for API payments
+3. Export your secret key and set as `SOLANA_WALLET_KEY`
+
+```bash
+# .env
+SOLANA_WALLET_KEY=...your_bs58_secret_key
+```
+
+Note: Solana transactions are gasless for the user - the CDP facilitator pays for transaction fees.
+
+## Security
+
+### Private Key Safety
+
+- **Private key stays local**: Your key is only used for signing on your machine
+- **No custody**: BlockRun never holds your funds
+- **Verify transactions**: All payments are on-chain and verifiable
+
+### Best Practices
+
+**Private Key Management:**
+- Use environment variables, never hard-code keys
+- Use dedicated wallets for API payments (separate from main holdings)
+- Set spending limits by only funding payment wallets with small amounts
+- Never commit `.env` files to version control
+- Rotate keys periodically
+
+**Input Validation:**
+The SDK validates all inputs before API requests:
+- Private keys (format, length, valid hex)
+- API URLs (HTTPS required for production, HTTP allowed for localhost)
+- Model names and parameters (ranges for max\_tokens, temperature, top\_p)
+
+**Error Sanitization:**
+API errors are automatically sanitized to prevent sensitive information leaks.
+
+**Monitoring:**
+```typescript
+const address = client.getWalletAddress();
+console.log(`View transactions: https://basescan.org/address/${address}`);
+```
+
+**Keep Updated:**
+```bash
+npm update @blockrun/llm  # Get security patches
+```
+
+## TypeScript Support
+
+Full TypeScript support with exported types:
+
+```typescript
+import {
+  LLMClient,
+  OpenAI,
+  type ChatMessage,
+  type ChatResponse,
+  type ChatOptions,
+  type ChatCompletionOptions,
+  type Model,
+  // Smart routing types
+  type SmartChatOptions,
+  type SmartChatResponse,
+  type RoutingDecision,
+  type RoutingProfile,
+  type RoutingTier,
+  APIError,
+  PaymentError,
+} from '@blockrun/llm';
+
+// chatCompletionStream returns a standard fetch Response with SSE body
+const streamResponse: Response = await client.chatCompletionStream(model, messages, options);
+
+// OpenAI-compat stream returns AsyncIterable
+const stream: AsyncIterable<OpenAIChatCompletionChunk> = await openaiClient.chat.completions.create({
+  model, messages, stream: true
+});
+```
+
+## Agent Wallet Setup
+
+One-line setup for agent runtimes (Claude Code skills, MCP servers, etc.):
+
+```typescript
+import { setupAgentWallet } from '@blockrun/llm';
+
+// Auto-creates wallet if none exists, returns ready client
+const client = setupAgentWallet();
+const response = await client.chat('openai/gpt-5.4', 'Hello!');
+```
+
+For Solana:
+
+```typescript
+import { setupAgentSolanaWallet } from '@blockrun/llm';
+
+const client = await setupAgentSolanaWallet();
+const response = await client.chat('anthropic/claude-sonnet-4.6', 'Hello!');
+```
+
+Check wallet status:
+
+```typescript
+import { status } from '@blockrun/llm';
+
+await status();
+// Wallet: 0xCC8c...5EF8
+// Balance: $5.30 USDC
+```
+
+## Wallet Scanning
+
+The SDK auto-detects wallets from any provider on your system:
+
+```typescript
+import { scanWallets, scanSolanaWallets } from '@blockrun/llm';
+
+// Scans ~/.<dir>/wallet.json for Base wallets
+const baseWallets = scanWallets();
+
+// Scans ~/.<dir>/solana-wallet.json and ~/.brcc/wallet.json
+const solWallets = scanSolanaWallets();
+```
+
+`getOrCreateWallet()` checks scanned wallets first, so if you already have a wallet from another BlockRun tool, it will be reused automatically.
+
+## Response Caching
+
+The SDK caches responses to avoid duplicate payments:
+
+```typescript
+import { getCachedByRequest, saveToCache, clearCache } from '@blockrun/llm';
+
+// Automatic TTLs by endpoint:
+// - Search: 15 minutes
+// - Models: 24 hours
+// - Chat/Image: no cache (every call is unique)
+
+// Manual cache management
+clearCache(); // Remove all cached responses
+```
+
+## Cost Logging
+
+Track spending across sessions:
+
+```typescript
+import { logCost, getCostSummary } from '@blockrun/llm';
+
+// Costs are logged to ~/.blockrun/data/costs.jsonl
+const summary = getCostSummary();
+console.log(`Total: $${summary.totalUsd.toFixed(2)}`);
+console.log(`Calls: ${summary.calls}`);
+console.log(`By model:`, summary.byModel);
+```
+
+## Anthropic SDK Compatibility
+
+Use the official Anthropic SDK interface with BlockRun's pay-per-request backend:
+
+```typescript
+import { AnthropicClient } from '@blockrun/llm';
+
+const client = new AnthropicClient();  // Auto-detects wallet, auto-pays
+
+const response = await client.messages.create({
+  model: 'claude-sonnet-4-6',
+  max_tokens: 1024,
+  messages: [{ role: 'user', content: 'Hello!' }],
+});
+console.log(response.content[0].text);
+
+// Any model works in Anthropic format
+const gptResponse = await client.messages.create({
+  model: 'openai/gpt-5.4',
+  max_tokens: 1024,
+  messages: [{ role: 'user', content: 'Hello from GPT!' }],
+});
+```
+
+The `AnthropicClient` wraps the official `@anthropic-ai/sdk` with a custom fetch that handles x402 payment automatically. Your private key never leaves your machine.
+
+## Links
+
+- [Website](https://blockrun.ai)
+- [Documentation](https://github.com/BlockRunAI/awesome-blockrun/tree/main/docs)
+- [GitHub](https://github.com/blockrunai/blockrun-llm-ts)
+- [Telegram](https://t.me/+mroQv4-4hGgzOGUx)
+
+## Frequently Asked Questions
+
+### What is @blockrun/llm?
+@blockrun/llm is a TypeScript SDK that provides pay-per-request access to 40+ large language models from OpenAI, Anthropic, Google, xAI, DeepSeek, Moonshot, and more. It uses the x402 protocol for automatic USDC micropayments — no API keys, no subscriptions, no vendor lock-in.
+
+### How does payment work?
+When you make an API call, the SDK automatically handles x402 payment. It signs a USDC transaction locally using your wallet private key (which never leaves your machine), and includes the payment proof in the request header. Settlement is non-custodial and instant on Base or Solana.
+
+### What is smart routing / ClawRouter?
+ClawRouter is a built-in smart routing engine that analyzes your request across 14 dimensions and automatically picks the cheapest model capable of handling it. Routing happens locally in under 1ms. It can save up to 78% on LLM costs compared to using premium models for every request.
+
+### Does it support streaming?
+Yes — as of v1.6.1. Use `client.chatCompletionStream()` for native streaming or `stream: true` in the OpenAI-compatible client. Payment is handled automatically: the SDK signs USDC payment before streaming begins, and caches payment requirements per model so subsequent calls skip the 402 round-trip (~200ms faster).
+
+### How much does it cost?
+Pay only for what you use. Prices start at $0.0002 per request (GPT-5 Nano). There are no minimums, subscriptions, or monthly fees. $5 in USDC gets you thousands of requests.
+
+### Does it support both Base and Solana?
+Yes. Use `LLMClient` for Base (EVM) payments and `SolanaLLMClient` for Solana payments. Same API, different payment chain.
+
+## License
+
+MIT