@blockrun/llm 3.14.3 → 3.15.1

package/README.md

@@ -4,7 +4,7 @@
 
 ### Cut your LLM bill by <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->%. One line of TypeScript.
 
-The smart-routing SDK for <!-- br:models.chatVisible -->74<!-- /br:models.chatVisible --> models — every request goes to the cheapest model that can handle it,
+The smart-routing SDK for <!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> models — every request goes to the cheapest model that can handle it,
 paid with an API key or per-request USDC on Solana or Base. No vendor lock-in.
 
 [![npm](https://img.shields.io/npm/v/@blockrun/llm.svg?style=flat-square)](https://www.npmjs.com/package/@blockrun/llm)
@@ -56,7 +56,7 @@ console.log(r.response);         // the proof
 |                    | OpenAI SDK     | OpenRouter        | LiteLLM          | **@blockrun/llm**                                                       |
 | ------------------ | -------------- | ----------------- | ---------------- | ----------------------------------------------------------------------- |
 | **Cost routing**   | ✗ one vendor   | Manual selection  | Manual selection | **Automatic — <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->% cheaper** |
-| **Models**         | GPT only       | 200+              | 100+ (BYO keys)  | **<!-- br:models.chatVisible -->74<!-- /br:models.chatVisible -->, one credential** |
+| **Models**         | GPT only       | 200+              | 100+ (BYO keys)  | **<!-- br:models.chatVisible -->76<!-- /br:models.chatVisible -->, one credential** |
 | **Free tier**      | ✗              | Rate-limited      | ✗                | **<!-- br:models.free -->7<!-- /br:models.free --> models, no signup**  |
 | **Auth**           | API key        | Account + API key | Your API keys    | **API key *or* wallet signature**                                       |
 | **Payment**        | Card + invoice | Credit card       | BYO keys         | **Account credit or USDC per-request**                                  |
@@ -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
 
@@ -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 |
 |---|---|
@@ -1714,7 +1749,7 @@ The `AnthropicClient` wraps the official `@anthropic-ai/sdk` with a custom fetch
 ## Frequently Asked Questions
 
 ### What is @blockrun/llm?
-@blockrun/llm is a TypeScript SDK that cuts LLM costs by up to <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->% with built-in smart routing: every request is routed to the cheapest of <!-- br:models.chatVisible -->74<!-- /br:models.chatVisible --> models (OpenAI, Anthropic, Google, xAI, DeepSeek, Moonshot, and more) that can handle it, then paid per-request in USDC via the x402 protocol — with API key account billing or x402 wallet payments on Solana or Base.
+@blockrun/llm is a TypeScript SDK that cuts LLM costs by up to <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->% with built-in smart routing: every request is routed to the cheapest of <!-- br:models.chatVisible -->76<!-- /br:models.chatVisible --> models (OpenAI, Anthropic, Google, xAI, DeepSeek, Moonshot, and more) that can handle it, then paid per-request in USDC via the x402 protocol — with API key account billing or x402 wallet payments on Solana or Base.
 
 ### 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.