@blockrun/llm 3.20.0 → 3.21.0

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 -->82<!-- /br:models.chatVisible --> models — every request goes to the cheapest model that can handle it,
+The smart-routing SDK for <!-- br:models.chatVisible -->86<!-- /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)
@@ -44,7 +44,7 @@ console.log(r.response);         // the proof
 ## Why This SDK
 
 - 🧠 **Smart routing that pays for itself** — the bundled [Router Core V3](https://github.com/BlockRunAI/router-core) engine (shared with [ClawRouter](https://github.com/BlockRunAI/ClawRouter)) classifies every request locally in <1ms across <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions --> dimensions and routes to the cheapest capable model. The main event.
-- 🆓 **<!-- br:models.free -->6<!-- /br:models.free --> genuinely free models** — $0 in and out, incl. two 1M-context Nemotrons, a multimodal one, and free coding models from Cohere and Poolside. No rate-limit gimmicks.
+- 🆓 **<!-- br:models.free -->7<!-- /br:models.free --> genuinely free models** — $0 in and out, incl. two 1M-context Nemotrons, a multimodal one, and free coding models from Cohere and Poolside. No rate-limit gimmicks.
 - 🔐 **Two ways to connect** — a **BlockRun API key** billed against account credit ([sign up at user.blockrun.ai](https://user.blockrun.ai), [create a key](https://user.blockrun.ai/dashboard/keys), [add credit](https://user.blockrun.ai/dashboard/credits)), or a wallet signature with x402 micropayments and no account at all. Same code either way.
 - 💸 **Pay per request in USDC** — x402 micropayments on Solana or Base. $5 covers thousands of requests; agents can pay their own way.
 - 🛡️ **Automatic failover** — transient errors (timeouts, 429, 5xx) before payment walk the router's ranked fallback chain instead of failing your request; a failure after a payment was sent never buys a second model.
@@ -56,8 +56,8 @@ 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 -->82<!-- /br:models.chatVisible -->, one credential** |
-| **Free tier**      | ✗              | Rate-limited      | ✗                | **<!-- br:models.free -->6<!-- /br:models.free --> models, no signup**  |
+| **Models**         | GPT only       | 200+              | 100+ (BYO keys)  | **<!-- br:models.chatVisible -->86<!-- /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**                                  |
 | **Agent-ready**    | ✗              | ✗                 | ✗                | **✓ — one key, or agents fund their own wallet**                        |
@@ -318,13 +318,19 @@ a retry disposition, which `retryDisposition(err)` returns:
 
 - `'unpaid'`: nothing chargeable was sent — the unpaid first request and its
   402 challenge, or signing the payment. A 429, 5xx, timeout or network error
-  here moves on to the next model.
+  here moves on to the next model. On Solana, a `503
+  PAYMENT_VERIFICATION_UNAVAILABLE` in answer to the payment is `'unpaid'`
+  too: the gateway sends it only when verification could not run, so nothing
+  was settled or broadcast (the batch path already treats it as a refusal).
+  This holds on every exact-paid Solana endpoint, not only chat.
 - `'paid-or-in-doubt'`: the signed payment (exact or batch) was sent and may
   have been charged — a timeout, abort or network error after sending it, any
   error status in answer to it, or a 2xx whose body could not be read. The
   error propagates; no other model is bought for the call. With an API key
-  the request itself is billed, so only the account API's explicit 4xx
-  answer (such as a 429) is `'unpaid'`; a 5xx or a timeout is not.
+  the request itself is billed, so only the account API's explicit answers
+  are `'unpaid'`: a 4xx (such as a 429), or a 5xx carrying its JSON error
+  envelope (api.blockrun.ai debits only an accepted 2xx). An HTML or empty
+  5xx from a proxy, or a timeout, is not.
 
 An error without a disposition counts as `'paid-or-in-doubt'`. Use the same
 check in your own retry wrapper:
@@ -353,7 +359,7 @@ const reply = await client.chat('nvidia/nemotron-3.5-lightning', 'hello', {
 
 | Profile | Strategy | Savings vs Opus 5 | Best For |
 |---------|----------|-------------------|----------|
-| `eco` | Cheapest capable model — ranks the <!-- br:models.free -->6<!-- /br:models.free -->-model free tier first | **<!-- br:savings.ecoVsBaselinePct -->98<!-- /br:savings.ecoVsBaselinePct -->%** | Cost-sensitive production, zero-cost testing |
+| `eco` | Cheapest capable model — ranks the <!-- br:models.free -->7<!-- /br:models.free -->-model free tier first | **<!-- br:savings.ecoVsBaselinePct -->98<!-- /br:savings.ecoVsBaselinePct -->%** | Cost-sensitive production, zero-cost testing |
 | `auto` | Best balance of cost/quality (default) | **<!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->%** | General use |
 | `premium` | Top-tier models (OpenAI, Anthropic) | 0% | Quality-critical tasks |
 
@@ -484,6 +490,25 @@ const tweet = await client.chat('xai/grok-4.5', 'What is trending on X?', { sear
 **Supported endpoint:** `https://sol.blockrun.ai/api`
 **Payment:** Solana USDC (SPL, mainnet)
 
+**Images, music and video on Solana:**
+
+```typescript
+const image = await client.image('a lighthouse at dusk', { model: 'openai/gpt-image-2' });
+const track = await client.music('chill lo-fi beats with piano');
+const video = await client.video('a red apple slowly spinning', { duration_seconds: 5 });
+```
+
+Slow jobs answer `202 { id, poll_url }` and the client polls for you. Each poll
+proves the job is yours with a wallet signature (`x-poll-wallet`,
+`x-poll-timestamp`, `x-poll-signature`: ed25519 over
+`blockrun-poll:v1:<kind>:<job id>:<unix seconds>`), not a payment, so a
+multi-minute job no longer signs a Solana transaction every few seconds. Image
+and music are paid when submitted. A video is charged only once it is finished:
+the client signs one payment for the completed job, and a failed job costs
+nothing. If the gateway does not accept the poll signature for a job, the client
+falls back to paying each poll the old way (logged to stderr). Base polling is
+unchanged.
+
 ### Batch settlement (optional metered billing)
 
 By default, every Solana call uses x402 `exact`: one SPL transfer per call,
@@ -1482,7 +1507,7 @@ const free = await client.chat('nvidia/nemotron-3.5-lightning', 'Hello!');
 
 | Profile | Description | Best For |
 |---------|-------------|----------|
-| `eco` | Budget-optimized — ranks the <!-- br:models.free -->6<!-- /br:models.free -->-model free tier first | Cost-sensitive workloads, zero-cost testing |
+| `eco` | Budget-optimized — ranks the <!-- br:models.free -->7<!-- /br:models.free -->-model free tier first | Cost-sensitive workloads, zero-cost testing |
 | `auto` | Intelligent routing (default) | General use |
 | `premium` | Best quality models | Critical tasks |
 
@@ -2081,7 +2106,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 -->82<!-- /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 -->86<!-- /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.