@bridgenode/llm 0.1.0 → 0.2.1

package/README.md

@@ -1,1442 +1,82 @@
-# @blockrun/llm (TypeScript SDK)
+# @bridgenode/llm (TypeScript SDK)
 
-> **@blockrun/llm** is a TypeScript/Node.js SDK for accessing <!-- br:models.chatVisible -->66<!-- /br:models.chatVisible --> 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.
+> **@bridgenode/llm** — TypeScript/Node.js SDK for BridgeNode: pay-per-request AI inference via x402 micropayments on Solana. No API keys required — your wallet signature is your authentication.
 
-[![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)
+**Protocol:** x402 v2
+**Payment:** USDC (Solana SPL)
+**Gasless:** Solana fee sponsorship — agent needs 0 SOL
 
-## 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 |
+## Supported Models (3)
 
+| Model | Type | Use case |
+|-------|------|----------|
+| `deepseek-v4-flash` | Chat | Default — fast, 1M context, 284B MoE |
+| `groq-llama-3.3-70b` | Chat | Eco tier — cheapest, fastest |
+| `deepseek-v4-pro` | Chat | Premium — complex reasoning |
 
-**Protocol:** x402 v2 (CDP Facilitator)
+*More models added as BridgeNode expands.*
+
+---
 
 ## Installation
 
 ```bash
-# Base and Solana support (optional Solana deps auto-installed)
-npm install @blockrun/llm
-# or
-pnpm add @blockrun/llm
+npm install @bridgenode/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'
+pnpm add @bridgenode/llm
 ```
 
-**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)
+## Quick Start
 
 ```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.bridgenode.cc):
-
-```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.bridgenode.cc/api`
-**Payment:** Solana USDC (SPL, mainnet)
-
-## How Payment Works
-
-No API keys, no subscription. You hold USDC in your own wallet, and **every request pays for itself** with an on-chain micropayment. Two phases:
-
-### Phase 1 — Fund your wallet once
-
-You only do this when your balance runs low. Three ways to get USDC into your wallet:
-
-- **(a) Buy with a card (Base USDC).** Call the new `onramp()` method to mint a one-time Coinbase Onramp link, then open the returned `pay.coinbase.com` URL — pay by card/bank in 60+ fiat currencies and the USDC lands in your wallet. The call itself is **free**. Onramp is **Base-only** (buying USDC with a card always lands Base USDC), and the funding address must equal your signing wallet:
-
-  ```typescript
-  const { url } = await client.onramp(client.getWalletAddress());
-  console.log(`Fund your wallet: ${url}`);  // single-use, expires ~5 min — mint at click time
-  ```
-
-- **(b) Transfer existing USDC.** Send USDC you already hold to your wallet address (`client.getWalletAddress()`). On Base, send Base USDC; on Solana (`SolanaLLMClient`), send Solana SPL USDC.
-
-- **(c) Skip funding entirely.** Use the free NVIDIA models (e.g. `nvidia/deepseek-v4-flash`) — every call is **$0**, no balance required.
-
-$5 of USDC covers thousands of paid requests. Check your balance any time:
-
-```typescript
-const balance = await client.getBalance();        // USDC on Base
-console.log(`Balance: $${balance.toFixed(2)} USDC`);
-```
-
-### Phase 2 — Every request pays itself (automatic x402)
-
-You just call e.g. `client.chat(...)` — the payment is invisible:
-
-1. You send a request to BlockRun's API.
-2. The gateway returns **402 Payment Required** with the price.
-3. The SDK signs a USDC payment **locally** (EIP-712) — on **Base** for `LLMClient`, on **Solana** for `SolanaLLMClient` — using your wallet key.
-4. The request is retried automatically with the payment proof.
-5. The gateway settles on-chain and returns the AI response.
-
-One call, no separate pay step. Free NVIDIA models settle at **$0** (no payment signed).
-
-### Track spend and verify settlements
-
-```typescript
-import { getCostSummary } from '@blockrun/llm';
-
-const spent = client.getSpending();               // this session
-console.log(`Spent $${spent.totalUsd.toFixed(4)} across ${spent.calls} calls`);
-
-const summary = getCostSummary();                  // across sessions (~/.blockrun/data/costs.jsonl)
-console.log(`Lifetime: $${summary.totalUsd.toFixed(2)} over ${summary.calls} calls`);
-```
-
-Every paid request is a real on-chain USDC transfer — look up your wallet address on [Basescan](https://basescan.org) (or a Solana explorer) to verify each settlement independently.
-
-**Non-custodial by design: your private key never leaves your machine** — it is only used for local signing, and no funds are ever held by BlockRun.
-
-## 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 87%'
-
-// 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 <!-- br:models.free -->8<!-- /br:models.free --> 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-fable-5` | $10.00/M | $50.00/M | **1M** | Mythos-class flagship above Opus — always-on thinking, 128K output, fallback `claude-opus-4.8`. Alias: `claude-fable-5` |
-| `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.
+import { LLMClient } from "@bridgenode/llm";
 
-| 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://bridgenode.cc/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`.
-
-### DeFi Data, DEX Swaps & Cloud Compute
-
-Three passthrough families live directly on `LLMClient` / `SolanaLLMClient`:
-
-```ts
-const client = new LLMClient();
-
-// DefiLlama — protocols / TVL / yields / prices ($0.005/call, prices $0.001)
-const protocols = await client.defiProtocols();
-const aave = await client.defiProtocol('aave');
-const prices = await client.defiPrices(['coingecko:bitcoin', 'base:0x833589...']);
-
-// 0x DEX — swap + gasless quotes (FREE; BlockRun takes an on-chain affiliate
-// fee on executed swaps instead of x402)
-const quote = await client.dexQuote({
-  chainId: '8453', sellToken: '0x...', buyToken: '0x...',
-  sellAmount: '1000000', taker: '0xYourWallet',
-});
-const gq = await client.dexGaslessQuote({ /* ... */ });
-const res = await client.dexGaslessSubmit({ trade: { /* signed eip712 */ } });
-const status = await client.dexGaslessStatus(res.tradeHash as string);
-
-// Modal — sandboxed compute ($0.01 create CPU / $0.05 GPU, $0.001 exec)
-const sb = await client.modalSandboxCreate({ image: 'python:3.11' });
-const out = await client.modalSandboxExec(sb.sandbox_id as string, ['python', '-c', 'print(42)']);
-await client.modalSandboxTerminate(sb.sandbox_id as string);
-```
-
-Generic escape hatches: `client.defi(path, params)`, `client.dex(path, params, body?)`,
-`client.modal(path, body)`.
-
-### 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' },
+const client = new LLMClient({ privateKey: "0x..." });
+const response = await client.chat("deepseek-v4-flash", [
+  { role: "user", content: "Hello!" }
 ]);
-
-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
+The SDK handles the full x402 handshake automatically:
+1. Sends request → receives `402 PAYMENT-REQUIRED`
+2. Signs USDC transfer authorization locally (key never leaves your machine)
+3. Retries with `PAYMENT-SIGNATURE` header
+4. Returns the AI response
 
-### Simple Chat
+## `BridgeNodeClient` — universal primitive
 
 ```typescript
-import { LLMClient } from '@blockrun/llm';
+import { BridgeNodeClient } from "@bridgenode/llm";
 
-const client = new LLMClient();  // Uses BASE_CHAIN_WALLET_KEY (never sent to server)
+const br = new BridgeNodeClient({ privateKey: "0x..." });
 
-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.',
+// POST
+const result = await br.post("/v1/chat/completions", {
+  model: "deepseek-v4-flash",
+  messages: [{ role: "user", content: "Hi" }],
 });
-```
-
-### Smart Routing (ClawRouter)
-
-Save up to <!-- br:savings.autoVsBaselinePct -->87<!-- /br:savings.autoVsBaselinePct -->% on inference costs with intelligent model routing. ClawRouter uses a <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions -->-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 87%'
-
-// 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 (<!-- br:models.free -->8<!-- /br:models.free --> 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' }],
+// Streaming
+for await (const chunk of br.stream("/v1/chat/completions", {
+  model: "deepseek-v4-flash",
+  messages: [{ role: "user", content: "Write a poem" }],
   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://bridgenode.cc/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`) |
-| `BRIDGENODE_API_URL` | API endpoint (optional, default: https://bridgenode.cc/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 Discovery and Migration
-
-The SDK can discover compatible wallets for an explicit, user-confirmed
-migration. It never automatically makes a discovered provider wallet active:
-
-```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()` always uses `~/.blockrun/.session` (or an explicit
-wallet environment variable, or the legacy `~/.blockrun/wallet.key`). Review
-the discovered addresses and import one explicitly if you intend to switch
-wallets.
-
-### Upgrading from a provider wallet
-
-Earlier versions adopted the most recently written provider wallet
-automatically. If you relied on that, the first run after upgrading creates a
-fresh BlockRun wallet and prints the addresses it found, so you can import the
-one you actually own:
-
-```
-NOTICE: BlockRun created a new wallet, but also found existing wallet(s)
-belonging to other applications on this system:
-
-  0x88f9B82462f6C4bf4a0Fb15e5c3971559a316e7f
-...
-```
-
-Adopt one deliberately:
-
-```typescript
-import { listDiscoveredWallets, importWallet } from '@blockrun/llm';
-
-for (const w of listDiscoveredWallets()) {
-  console.log(w.address, 'from', w.source);
+})) {
+  process.stdout.write(chunk.choices?.[0]?.delta?.content ?? "");
 }
-
-importWallet('0x88f9B82462f6C4bf4a0Fb15e5c3971559a316e7f');
 ```
 
-`importWallet()` writes your current wallet to
-`~/.blockrun/.session.backup-<timestamp>` before switching, so adopting a wallet
-never strands funds in the old one. Solana: `listDiscoveredSolanaWallets()` and
-`importSolanaWallet()`.
-
-Addresses shown are derived from the discovered key itself, and `importWallet()`
-matches on that derived address — so a wallet file cannot claim an address it
-cannot sign for, nor be adopted by one. `listDiscoveredWallets()` never returns
-private keys.
-
-For a single run without changing anything, use
-`export BRIDGENODE_WALLET_KEY=<private-key>`.
-
-## 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. The Mythos-class `claude-fable-5` alias is available here too (1M context, always-on thinking).
-
-## Links
-
-- [Website](https://bridgenode.cc)
-- [Documentation](https://github.com/bridgenode/awesome-blockrun/tree/main/docs)
-- [GitHub](https://github.com/blockrunai/bridgenode-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 <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions --> dimensions and automatically picks the cheapest model capable of handling it. Routing happens locally in under 1ms. It can save up to <!-- br:savings.autoVsBaselinePct -->87<!-- /br:savings.autoVsBaselinePct -->% 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).
+## Supported Chain
 
-### 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.
+| Chain | Payment | Status |
+|-------|---------|--------|
+| **Solana Mainnet** | USDC (SPL) | ✅ Active |
 
-### 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