@blockrun/llm 2.3.0 → 2.5.0

package/README.md

@@ -41,6 +41,53 @@ 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`,
+`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:
@@ -455,6 +502,50 @@ 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`.