@blockrun/llm 3.14.2 → 3.15.0

package/README.md

@@ -65,7 +65,7 @@ console.log(r.response);         // the proof
 ## Installation
 
 ```bash
-npm install @blockrun/llm   # Base / EVM payments — smart routing included, nothing else needed
+npm install @blockrun/llm   # Account API keys or Base wallets; smart routing included
 ```
 
 <details>
@@ -98,6 +98,8 @@ without them throws an error naming the exact install command.
 
 </details>
 
+The Anthropic SDK is a runtime dependency because the public compatibility wrapper exposes its types. Solana signing dependencies remain optional and are unnecessary for account billing.
+
 ## Quick Start: API Key
 
 1. [Sign up or sign in](https://user.blockrun.ai).
@@ -130,9 +132,14 @@ wallet mode even when `BLOCKRUN_API_KEY` is set; passing both explicit credentia
 is an error. With no explicit credential, `BLOCKRUN_API_KEY` beats the wallet key
 env vars — a process holding both runs in account mode. Invalid or exhausted API keys never fall back to wallet payments.
 Errors preserve `statusCode`, account error `response.code`, and `retryAfter`.
-Account credentials are restricted to the configured origin, including polling.
+Account credentials are restricted to the configured origin, including polling. Account POSTs are not automatically replayed, including through the Anthropic wrapper. GET/HEAD requests can retry temporary gateway errors; accepted jobs keep polling the same job within the original timeout. A 429 returns `retryAfter` to the caller.
+
+Check [Activity](https://user.blockrun.ai/dashboard/activity) for account usage and charges. Chat uses token usage; media and data can use duration, image, or per-request units. When adding credit, the checkout shows the credit amount and total card charge, including any processing fee. Keep API keys in server or local environment variables, never in browser code or logs.
+
+For asynchronous jobs, retain the complete returned `poll_url`, including its query parameters. If polling times out, check the original job and Activity before submitting again.
+
+To switch back to a wallet, unset `BLOCKRUN_API_KEY` and create a new wallet client, or pass an explicit `privateKey` to the appropriate client. Existing clients retain their original credentials; changing a wallet chain does not change account billing.
 
-Use the [account dashboard](https://user.blockrun.ai/dashboard) for account usage.
 `getSpending()` reports x402 settlements only and throws in account mode; wallet
 address/balance helpers require a wallet. Account credit does not sign trades or
 transfer wallet funds. Service availability depends on the account gateway and model.
@@ -1017,8 +1024,7 @@ Generic escape hatches: `client.defi(path, params)`, `client.dex(path, params, b
 `RpcClient` wraps `POST /v1/rpc/{network}` — standard JSON-RPC 2.0 access to
 <!-- br:chains.rpc -->40<!-- /br:chains.rpc --> 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: one flat per-call rate in
-USDC; a JSON-RPC batch charges per element.
+gateway). Use account credits or the selected x402 wallet; no separate Tatum key is needed. A JSON-RPC batch is priced per element.
 
 ```ts
 import { RpcClient } from '@blockrun/llm';
@@ -1233,6 +1239,35 @@ while (true) {
 }
 ```
 
+#### Solana
+
+`SolanaLLMClient.stream()` is the Solana counterpart, with the same shape as
+`BlockrunClient.stream()`: it yields each `data:` frame already parsed as JSON
+and stops at `[DONE]`. The x402 handshake happens before the first frame — 402,
+sign an SPL TransferChecked authorization locally, replay with
+`PAYMENT-SIGNATURE` — including the fresh-blockhash re-sign on a
+verification-phase rejection. A free model, or an account key, is answered `200`
+with no handshake at all and settles nothing.
+
+```typescript
+import { SolanaLLMClient } from '@blockrun/llm';
+
+const client = new SolanaLLMClient(); // SOLANA_WALLET_KEY, or { apiKey: 'brk_live_…' }
+
+for await (const chunk of client.stream('/v1/chat/completions', {
+  model: 'deepseek/deepseek-chat',
+  messages: [{ role: 'user', content: 'Hi' }],
+  max_tokens: 64,
+  stream: true,
+})) {
+  process.stdout.write(chunk?.choices?.[0]?.delta?.content ?? '');
+}
+```
+
+Set `stream: true` yourself — the method does not inject it, because the gateway
+prices a streaming and a non-streaming request the same and rewriting a caller's
+body silently is how you end up debugging a request you did not send.
+
 #### Payment + streaming flow
 
 ```
@@ -1278,7 +1313,7 @@ const [gpt, claude, gemini] = await Promise.all([
 
 ## 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.
+Access real-time prediction market data from Polymarket, Kalshi, and Binance Futures via [Predexon](https://predexon.com). Use a BlockRun account API key or x402 wallet payments; no separate Predexon key is needed.
 
 ### Polymarket
 
@@ -1292,35 +1327,35 @@ 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)
+// List events
 const events = await client.pm("polymarket/events");
 
-// Historical trades ($0.001/request)
+// Historical trades
 const trades = await client.pm("polymarket/trades");
 
-// OHLCV candlestick data for a specific condition ($0.001/request)
+// OHLCV candlestick data for a specific condition
 const candles = await client.pm("polymarket/candlesticks/0x1234abcd...");
 
-// Wallet profile ($0.005/request — tier 2)
+// Wallet profile (tier 2)
 const profile = await client.pm("polymarket/wallet/0xABC123...");
 
-// Wallet P&L ($0.005/request — tier 2)
+// Wallet P&L (tier 2)
 const pnl = await client.pm("polymarket/wallet/pnl/0xABC123...");
 
-// Global leaderboard ($0.001/request)
+// Global leaderboard
 const leaderboard = await client.pm("polymarket/leaderboard");
 ```
 
 ### Kalshi & Binance
 
 ```typescript
-// Kalshi markets ($0.001/request)
+// Kalshi markets
 const kalshiMarkets = await client.pm("kalshi/markets");
 
-// Kalshi trades ($0.001/request)
+// Kalshi trades
 const kalshiTrades = await client.pm("kalshi/trades");
 
-// Binance candles for supported pairs ($0.001/request)
+// Binance candles for supported pairs
 const btcCandles = await client.pm("binance/candles/BTCUSDT");
 const ethCandles = await client.pm("binance/candles/ETHUSDT");
 // Also: SOLUSDT, XRPUSDT
@@ -1329,7 +1364,7 @@ const ethCandles = await client.pm("binance/candles/ETHUSDT");
 ### Cross-Platform
 
 ```typescript
-// Cross-platform matching pairs ($0.001/request)
+// Cross-platform matching pairs
 const pairs = await client.pm("matching-markets/pairs");
 ```
 
@@ -1339,7 +1374,7 @@ 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.
+Access [Exa](https://exa.ai)'s neural web search using account credits or x402 wallet payments; no separate Exa key is needed. Use `SolanaLLMClient` for a Solana wallet or `LLMClient` for a Base wallet. Availability depends on the selected gateway.
 
 | Method | Description |
 |---|---|
@@ -1354,17 +1389,17 @@ import { LLMClient } from '@blockrun/llm';
 
 const client = new LLMClient();
 
-// Neural web search ($0.01/request)
+// Neural web search
 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)
+// Find similar pages
 const similar = await client.exaFindSimilar("https://openai.com/research/gpt-4", { numResults: 5 });
 
-// Extract content from URLs ($0.002/URL)
+// Extract content from URLs
 const content = await client.exaContents(["https://arxiv.org/abs/2303.08774"]);
 
-// AI-generated answer from live web ($0.01/request)
+// AI-generated answer from live web
 const answer = await client.exaAnswer("What is the current state of AI safety research?");
 
 // Generic proxy for any Exa endpoint
@@ -1436,7 +1471,7 @@ npm test -- --coverage            # Run with coverage report
 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
+- Integration tests make real paid calls; cost depends on the models exercised
 
 ```bash
 export BASE_CHAIN_WALLET_KEY=0x...
@@ -1726,7 +1761,7 @@ Router Core V3 is bundled into the SDK — the same deterministic routing engine
 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.
+Pay only for what you use. There are no minimums, subscriptions, or monthly fees, and $5 in USDC gets you thousands of requests. Live per-model rates are at [blockrun.ai/models](https://blockrun.ai/models).
 
 ### Does it support both Solana and Base?
 Yes. Use `SolanaLLMClient` for Solana payments (recommended) and `LLMClient` for Base payments. Use `apiKey` for account billing without selecting a chain.