@blockrun/llm 1.10.1 → 1.13.0

package/README.md

@@ -1,6 +1,8 @@
 # @blockrun/llm (TypeScript SDK)
 
 > **@blockrun/llm** is a TypeScript/Node.js SDK for accessing 41+ 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 9 fully-free NVIDIA-hosted models** — DeepSeek V4 Pro/Flash (1M context), Nemotron Nano Omni (vision), Qwen3, Llama 4, GLM-4.7, Mistral. Zero USDC, no rate-limit gimmicks. Use `routingProfile: 'free'` or call any `nvidia/*` model directly.
 
 [![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)
@@ -39,6 +41,40 @@ const response = await client.chat('openai/gpt-4o', 'Hello!');
 
 That's it. The SDK handles x402 payment automatically.
 
+### 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/qwen3-next-80b-a3b-thinking', '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'
+```
+
+**Available free models** (input + output both $0, all NVIDIA-hosted, last refreshed 2026-04-28):
+
+| Model ID | Context | Best For |
+|----------|---------|----------|
+| `nvidia/deepseek-v4-pro` | 1M | Flagship reasoning — MMLU-Pro 87.5, GPQA 90.1, SWE-bench 80.6, LiveCodeBench 93.5 |
+| `nvidia/deepseek-v4-flash` | 1M | ~5× faster than V4 Pro — chat, summarization, light reasoning (weaker factual recall) |
+| `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning` | 256K | Only vision-capable free model — text + images + video (≤2 min) + audio (≤1 hr) |
+| `nvidia/qwen3-next-80b-a3b-thinking` | 131K | 116 tok/s reasoning with thinking mode |
+| `nvidia/mistral-small-4-119b` | 131K | 114 tok/s — fastest free chat |
+| `nvidia/glm-4.7` | 131K | 237 tok/s — GLM-4.7 with thinking mode |
+| `nvidia/llama-4-maverick` | 131K | Meta Llama 4 Maverick MoE |
+| `nvidia/qwen3-coder-480b` | 131K | Coding-optimised 480B MoE |
+| `nvidia/deepseek-v3.2` | 131K | Legacy V3.2 — auto-upgrades to V4 Pro via fallback |
+
+> Note: `nvidia/gpt-oss-120b` and `nvidia/gpt-oss-20b` were retired 2026-04-28 — NVIDIA's free build.nvidia.com tier reserves the right to use prompts/outputs for service improvement, which conflicts with our data-privacy policy.
+
 ## Quick Start (Solana)
 
 ```typescript
@@ -115,7 +151,7 @@ console.log(complex.model);  // 'xai/grok-4-1-fast-reasoning'
 
 | Profile | Description | Best For |
 |---------|-------------|----------|
-| `free` | nvidia/gpt-oss-120b only (FREE) | Testing, development |
+| `free` | NVIDIA free tier — smart-routes across 9 models (DeepSeek V4 Pro/Flash, Nemotron Nano Omni, Qwen3, GLM-4.7, Llama 4, Mistral) | 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 |
@@ -151,6 +187,13 @@ The classifier runs in <1ms, 100% locally, and routes to one of four tiers:
 
 ## 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 |
 |-------|-------------|--------------|
@@ -238,20 +281,23 @@ The classifier runs in <1ms, 100% locally, and routes to one of four tiers:
 
 ### NVIDIA (Free) + Moonshot
 
-Free tier refreshed 2026-04-21: retired the Nemotron family, `mistral-large-3-675b`,
-`devstral-2-123b`, and paid `nvidia/kimi-k2.5`. The backend auto-redirects the
-old IDs; the recommended replacements are listed below.
+Free tier refreshed 2026-04-28: added DeepSeek V4 Pro/Flash and Nemotron Nano
+Omni (vision); retired `nvidia/gpt-oss-120b` / `nvidia/gpt-oss-20b` over data
+privacy (NVIDIA's free build.nvidia.com tier reserves the right to use prompts
+for service improvement, which conflicts with our policy). Backend
+auto-redirects retired IDs to the replacements below.
 
 | Model | Input Price | Output Price | Notes |
 |-------|-------------|--------------|-------|
-| `nvidia/qwen3-next-80b-a3b-thinking` | **FREE** | **FREE** | Reasoning flagship — 116 tok/s, thinking mode |
-| `nvidia/mistral-small-4-119b` | **FREE** | **FREE** | Fastest free chat — 114 tok/s |
-| `nvidia/glm-4.7` | **FREE** | **FREE** | GLM-4.7 with thinking — 237 tok/s |
-| `nvidia/llama-4-maverick` | **FREE** | **FREE** | Llama 4 Maverick MoE |
+| `nvidia/deepseek-v4-pro` | **FREE** | **FREE** | 1.6T MoE / 49B active, 1M context — flagship reasoning (MMLU-Pro 87.5, GPQA 90.1) |
+| `nvidia/deepseek-v4-flash` | **FREE** | **FREE** | 284B / 13B active MoE, 1M context — ~5× faster than V4 Pro |
+| `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning` | **FREE** | **FREE** | 31B / 3.2B active MoE, 256K — only vision-capable free model |
+| `nvidia/qwen3-next-80b-a3b-thinking` | **FREE** | **FREE** | 116 tok/s — reasoning flagship with thinking mode |
+| `nvidia/mistral-small-4-119b` | **FREE** | **FREE** | 114 tok/s — fastest free chat |
+| `nvidia/glm-4.7` | **FREE** | **FREE** | 237 tok/s — GLM-4.7 with thinking mode |
+| `nvidia/llama-4-maverick` | **FREE** | **FREE** | Meta Llama 4 Maverick MoE |
 | `nvidia/qwen3-coder-480b` | **FREE** | **FREE** | Coding-optimised 480B MoE |
-| `nvidia/deepseek-v3.2` | **FREE** | **FREE** | DeepSeek V3.2 hosted |
-| `nvidia/gpt-oss-120b` | **FREE** | **FREE** | OpenAI open-weight 120B — 123 tok/s |
-| `nvidia/gpt-oss-20b` | **FREE** | **FREE** | OpenAI open-weight 20B — 155 tok/s |
+| `nvidia/deepseek-v3.2` | **FREE** | **FREE** | Legacy V3.2 — auto-upgrades to V4 Pro via fallback |
 | `moonshot/kimi-k2.5` | $0.60/M | $3.00/M | Direct from Moonshot — replaces `nvidia/kimi-k2.5` |
 
 ### E2E Verified Models
@@ -537,7 +583,7 @@ const premium = await client.smartChat('Write a legal brief', { routingProfile:
 
 | Profile | Description | Best For |
 |---------|-------------|----------|
-| `free` | NVIDIA free models only | Testing, simple queries |
+| `free` | NVIDIA free tier (9 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 |

package/dist/index.cjs

@@ -1686,6 +1686,8 @@ var DEFAULT_API_URL2 = "https://blockrun.ai/api";
 var DEFAULT_MODEL = "google/nano-banana";
 var DEFAULT_SIZE = "1024x1024";
 var DEFAULT_TIMEOUT2 = 2e5;
+var POLL_INTERVAL_MS = 3e3;
+var POLL_MAX_DURATION_MS = 3e5;
 var ImageClient = class {
   account;
   privateKey;
@@ -1870,7 +1872,70 @@ var ImageClient = class {
         sanitizeErrorResponse(errorBody)
       );
     }
-    return retryResponse.json();
+    const responseBody = await retryResponse.json();
+    if (retryResponse.status === 202 || responseBody.status === "queued" || responseBody.status === "in_progress") {
+      if (!responseBody.poll_url) {
+        throw new APIError(
+          `Server returned ${retryResponse.status} but no poll_url to follow.`,
+          retryResponse.status,
+          sanitizeErrorResponse(responseBody)
+        );
+      }
+      return this.pollImageJob(responseBody.poll_url, paymentPayload);
+    }
+    return responseBody;
+  }
+  /**
+   * Poll the async image generation endpoint until the job reaches a terminal
+   * state (completed/failed). Used when the POST returns 202 + poll_url for
+   * slow models that exceeded the server's inline window.
+   *
+   * Sends the SAME payment header on every poll — the server binds the payer
+   * to the job id and re-verifies on each call. Settlement happens server-side
+   * on the first poll where status=completed.
+   */
+  async pollImageJob(pollPath, paymentHeader) {
+    const pollUrl = pollPath.startsWith("/api/") ? `${this.apiUrl.replace(/\/api$/, "")}${pollPath}` : `${this.apiUrl}${pollPath.startsWith("/") ? "" : "/"}${pollPath}`;
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < POLL_MAX_DURATION_MS) {
+      await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+      const pollResp = await this.fetchWithTimeout(pollUrl, {
+        method: "GET",
+        headers: {
+          "PAYMENT-SIGNATURE": paymentHeader,
+          "X-PAYMENT": paymentHeader
+        }
+      });
+      if (pollResp.status === 202) {
+        continue;
+      }
+      const pollBody = await pollResp.json().catch(() => ({}));
+      if (!pollResp.ok) {
+        throw new APIError(
+          `API error during poll: ${pollResp.status}`,
+          pollResp.status,
+          sanitizeErrorResponse(pollBody)
+        );
+      }
+      if (pollBody.status === "failed") {
+        throw new APIError(
+          pollBody.error || "Upstream image generation failed",
+          200,
+          sanitizeErrorResponse(pollBody)
+        );
+      }
+      if (pollBody.data) {
+        return pollBody;
+      }
+      if (pollBody.status === "queued" || pollBody.status === "in_progress") {
+        continue;
+      }
+    }
+    throw new APIError(
+      `Image generation poll timed out after ${POLL_MAX_DURATION_MS / 1e3}s`,
+      504,
+      { error: "poll_timeout", poll_url: pollPath }
+    );
   }
   /**
    * Fetch with timeout.
@@ -2759,13 +2824,13 @@ var path2 = __toESM(require("path"), 1);
 var os2 = __toESM(require("os"), 1);
 var WALLET_DIR2 = path2.join(os2.homedir(), ".blockrun");
 var SOLANA_WALLET_FILE = path2.join(WALLET_DIR2, ".solana-session");
-function createSolanaWallet() {
-  const { Keypair } = require("@solana/web3.js");
-  const bs58 = require("bs58");
+async function createSolanaWallet() {
+  const { Keypair } = await import("@solana/web3.js");
+  const bs58 = await import("bs58");
   const keypair = Keypair.generate();
   return {
     address: keypair.publicKey.toBase58(),
-    privateKey: bs58.default?.encode(keypair.secretKey) ?? bs58.encode(keypair.secretKey)
+    privateKey: (bs58.default ?? bs58).encode(keypair.secretKey)
   };
 }
 async function solanaKeyToBytes(privateKey) {
@@ -2858,7 +2923,7 @@ async function getOrCreateSolanaWallet() {
       return { privateKey: fileKey, address: address2, isNew: false };
     }
   }
-  const { address, privateKey } = createSolanaWallet();
+  const { address, privateKey } = await createSolanaWallet();
   saveSolanaWallet(privateKey);
   return { address, privateKey, isNew: true };
 }

package/dist/index.d.cts

@@ -1195,6 +1195,16 @@ declare class ImageClient {
      * Handle 402 response: parse requirements, sign payment, retry.
      */
     private handlePaymentAndRetry;
+    /**
+     * Poll the async image generation endpoint until the job reaches a terminal
+     * state (completed/failed). Used when the POST returns 202 + poll_url for
+     * slow models that exceeded the server's inline window.
+     *
+     * Sends the SAME payment header on every poll — the server binds the payer
+     * to the job id and re-verifies on each call. Settlement happens server-side
+     * on the first poll where status=completed.
+     */
+    private pollImageJob;
     /**
      * Fetch with timeout.
      */
@@ -1736,12 +1746,14 @@ interface SolanaWalletInfo {
 }
 /**
  * Create a new Solana wallet.
- * Requires @solana/web3.js (optional dep).
+ * Requires @solana/web3.js (optional dep) — loaded lazily via dynamic
+ * import so callers that never touch Solana don't pay the resolution cost
+ * and ESM consumers don't trip over esbuild's __require shim.
  */
-declare function createSolanaWallet(): {
+declare function createSolanaWallet(): Promise<{
     address: string;
     privateKey: string;
-};
+}>;
 /**
  * Convert a bs58 private key string to Uint8Array (64 bytes).
  * Accepts: bs58-encoded 64-byte key (standard Solana format).

package/dist/index.d.ts

@@ -1195,6 +1195,16 @@ declare class ImageClient {
      * Handle 402 response: parse requirements, sign payment, retry.
      */
     private handlePaymentAndRetry;
+    /**
+     * Poll the async image generation endpoint until the job reaches a terminal
+     * state (completed/failed). Used when the POST returns 202 + poll_url for
+     * slow models that exceeded the server's inline window.
+     *
+     * Sends the SAME payment header on every poll — the server binds the payer
+     * to the job id and re-verifies on each call. Settlement happens server-side
+     * on the first poll where status=completed.
+     */
+    private pollImageJob;
     /**
      * Fetch with timeout.
      */
@@ -1736,12 +1746,14 @@ interface SolanaWalletInfo {
 }
 /**
  * Create a new Solana wallet.
- * Requires @solana/web3.js (optional dep).
+ * Requires @solana/web3.js (optional dep) — loaded lazily via dynamic
+ * import so callers that never touch Solana don't pay the resolution cost
+ * and ESM consumers don't trip over esbuild's __require shim.
  */
-declare function createSolanaWallet(): {
+declare function createSolanaWallet(): Promise<{
     address: string;
     privateKey: string;
-};
+}>;
 /**
  * Convert a bs58 private key string to Uint8Array (64 bytes).
  * Accepts: bs58-encoded 64-byte key (standard Solana format).

package/dist/index.js

@@ -1,10 +1,3 @@
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
-
 // src/client.ts
 import { privateKeyToAccount } from "viem/accounts";
 
@@ -1597,6 +1590,8 @@ var DEFAULT_API_URL2 = "https://blockrun.ai/api";
 var DEFAULT_MODEL = "google/nano-banana";
 var DEFAULT_SIZE = "1024x1024";
 var DEFAULT_TIMEOUT2 = 2e5;
+var POLL_INTERVAL_MS = 3e3;
+var POLL_MAX_DURATION_MS = 3e5;
 var ImageClient = class {
   account;
   privateKey;
@@ -1781,7 +1776,70 @@ var ImageClient = class {
         sanitizeErrorResponse(errorBody)
       );
     }
-    return retryResponse.json();
+    const responseBody = await retryResponse.json();
+    if (retryResponse.status === 202 || responseBody.status === "queued" || responseBody.status === "in_progress") {
+      if (!responseBody.poll_url) {
+        throw new APIError(
+          `Server returned ${retryResponse.status} but no poll_url to follow.`,
+          retryResponse.status,
+          sanitizeErrorResponse(responseBody)
+        );
+      }
+      return this.pollImageJob(responseBody.poll_url, paymentPayload);
+    }
+    return responseBody;
+  }
+  /**
+   * Poll the async image generation endpoint until the job reaches a terminal
+   * state (completed/failed). Used when the POST returns 202 + poll_url for
+   * slow models that exceeded the server's inline window.
+   *
+   * Sends the SAME payment header on every poll — the server binds the payer
+   * to the job id and re-verifies on each call. Settlement happens server-side
+   * on the first poll where status=completed.
+   */
+  async pollImageJob(pollPath, paymentHeader) {
+    const pollUrl = pollPath.startsWith("/api/") ? `${this.apiUrl.replace(/\/api$/, "")}${pollPath}` : `${this.apiUrl}${pollPath.startsWith("/") ? "" : "/"}${pollPath}`;
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < POLL_MAX_DURATION_MS) {
+      await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+      const pollResp = await this.fetchWithTimeout(pollUrl, {
+        method: "GET",
+        headers: {
+          "PAYMENT-SIGNATURE": paymentHeader,
+          "X-PAYMENT": paymentHeader
+        }
+      });
+      if (pollResp.status === 202) {
+        continue;
+      }
+      const pollBody = await pollResp.json().catch(() => ({}));
+      if (!pollResp.ok) {
+        throw new APIError(
+          `API error during poll: ${pollResp.status}`,
+          pollResp.status,
+          sanitizeErrorResponse(pollBody)
+        );
+      }
+      if (pollBody.status === "failed") {
+        throw new APIError(
+          pollBody.error || "Upstream image generation failed",
+          200,
+          sanitizeErrorResponse(pollBody)
+        );
+      }
+      if (pollBody.data) {
+        return pollBody;
+      }
+      if (pollBody.status === "queued" || pollBody.status === "in_progress") {
+        continue;
+      }
+    }
+    throw new APIError(
+      `Image generation poll timed out after ${POLL_MAX_DURATION_MS / 1e3}s`,
+      504,
+      { error: "poll_timeout", poll_url: pollPath }
+    );
   }
   /**
    * Fetch with timeout.
@@ -2670,13 +2728,13 @@ import * as path2 from "path";
 import * as os2 from "os";
 var WALLET_DIR2 = path2.join(os2.homedir(), ".blockrun");
 var SOLANA_WALLET_FILE = path2.join(WALLET_DIR2, ".solana-session");
-function createSolanaWallet() {
-  const { Keypair } = __require("@solana/web3.js");
-  const bs58 = __require("bs58");
+async function createSolanaWallet() {
+  const { Keypair } = await import("@solana/web3.js");
+  const bs58 = await import("bs58");
   const keypair = Keypair.generate();
   return {
     address: keypair.publicKey.toBase58(),
-    privateKey: bs58.default?.encode(keypair.secretKey) ?? bs58.encode(keypair.secretKey)
+    privateKey: (bs58.default ?? bs58).encode(keypair.secretKey)
   };
 }
 async function solanaKeyToBytes(privateKey) {
@@ -2769,7 +2827,7 @@ async function getOrCreateSolanaWallet() {
       return { privateKey: fileKey, address: address2, isNew: false };
     }
   }
-  const { address, privateKey } = createSolanaWallet();
+  const { address, privateKey } = await createSolanaWallet();
   saveSolanaWallet(privateKey);
   return { address, privateKey, isNew: true };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/llm",
-  "version": "1.10.1",
+  "version": "1.13.0",
   "type": "module",
   "description": "BlockRun SDK - Pay-per-request AI (LLM, Image, Video, Music) via x402 on Base and Solana",
   "main": "dist/index.cjs",