@blockrun/llm 3.8.2 → 3.8.4

package/README.md

@@ -1,6 +1,6 @@
 # @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.
+> **@blockrun/llm** is a TypeScript/Node.js SDK for accessing <!-- br:models.chatVisible -->66<!-- /br:models.chatVisible --> 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 7 fully-free NVIDIA-hosted models** (5 visible in `/v1/models`, 2 hidden but directly callable) — DeepSeek V4 Flash (1M context), Nemotron Nano Omni (vision), Qwen3 Coder, Llama 4, Mistral, plus the gpt-oss pair. Zero USDC, no rate-limit gimmicks. Use `routingProfile: 'free'` or call any `nvidia/*` model directly.
 
@@ -232,7 +232,7 @@ const client = new LLMClient();
 const result = await client.smartChat('What is 2+2?');
 console.log(result.response);     // '4'
 console.log(result.model);        // 'moonshot/kimi-k2.5' (cheap, fast)
-console.log(`Saved ${(result.routing.savings * 100).toFixed(0)}%`); // 'Saved 78%'
+console.log(`Saved ${(result.routing.savings * 100).toFixed(0)}%`); // 'Saved 87%'
 
 // Complex reasoning task -> routes to reasoning model
 const complex = await client.smartChat('Prove the Riemann hypothesis step by step');
@@ -263,7 +263,7 @@ const reply = await client.chat('nvidia/deepseek-v4-flash', 'hello', {
 
 | Profile | Description | Best For |
 |---------|-------------|----------|
-| `free` | NVIDIA free tier — smart-routes across 8 models (DeepSeek V4 Flash, Nemotron Nano Omni, Qwen3, Llama 4, Mistral, plus 2 hidden gpt-oss) | Zero-cost testing, dev, prod |
+| `free` | NVIDIA free tier — smart-routes across <!-- br:models.free -->8<!-- /br:models.free --> models (DeepSeek V4 Flash, Nemotron Nano Omni, Qwen3, Llama 4, Mistral, plus 2 hidden gpt-oss) | 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 |
@@ -748,7 +748,7 @@ Generic escape hatches: `client.defi(path, params)`, `client.dex(path, params, b
 ### Multi-chain RPC
 
 `RpcClient` wraps `POST /v1/rpc/{network}` — standard JSON-RPC 2.0 access to
-40+ chains through one endpoint (Ethereum, Base, Solana, Polygon, BSC,
+<!-- 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: flat **$0.002 per call** in
 USDC; a JSON-RPC batch charges per element.
@@ -858,7 +858,7 @@ const response2 = await client.chat('anthropic/claude-sonnet-4', 'Write a haiku'
 
 ### Smart Routing (ClawRouter)
 
-Save up to 78% on inference costs with intelligent model routing. ClawRouter uses a 14-dimension rule-based scoring algorithm to select the cheapest model that can handle your request (<1ms, 100% local).
+Save up to <!-- br:savings.autoVsBaselinePct -->87<!-- /br:savings.autoVsBaselinePct -->% on inference costs with intelligent model routing. ClawRouter uses a <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions -->-dimension rule-based scoring algorithm to select the cheapest model that can handle your request (<1ms, 100% local).
 
 ```typescript
 import { LLMClient } from '@blockrun/llm';
@@ -870,7 +870,7 @@ const result = await client.smartChat('What is 2+2?');
 console.log(result.response);     // '4'
 console.log(result.model);        // 'google/gemini-2.5-flash'
 console.log(result.routing.tier); // 'SIMPLE'
-console.log(`Saved ${(result.routing.savings * 100).toFixed(0)}%`); // 'Saved 78%'
+console.log(`Saved ${(result.routing.savings * 100).toFixed(0)}%`); // 'Saved 87%'
 
 // Routing profiles
 const free = await client.smartChat('Hello!', { routingProfile: 'free' });     // Zero cost
@@ -883,7 +883,7 @@ const premium = await client.smartChat('Write a legal brief', { routingProfile:
 
 | Profile | Description | Best For |
 |---------|-------------|----------|
-| `free` | NVIDIA free tier (9 models, smart-routed) | Zero-cost testing, dev, prod |
+| `free` | NVIDIA free tier (<!-- br:models.free -->8<!-- /br:models.free --> 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 |
@@ -1427,7 +1427,7 @@ The `AnthropicClient` wraps the official `@anthropic-ai/sdk` with a custom fetch
 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.
 
 ### What is smart routing / ClawRouter?
-ClawRouter is a built-in smart routing engine that analyzes your request across 14 dimensions and automatically picks the cheapest model capable of handling it. Routing happens locally in under 1ms. It can save up to 78% on LLM costs compared to using premium models for every request.
+ClawRouter is a built-in smart routing engine that analyzes your request across <!-- br:clawrouter.dimensions -->15<!-- /br:clawrouter.dimensions --> dimensions and automatically picks the cheapest model capable of handling it. Routing happens locally in under 1ms. It can save up to <!-- br:savings.autoVsBaselinePct -->87<!-- /br:savings.autoVsBaselinePct -->% on LLM costs compared to using premium models for every request.
 
 ### Does it support streaming?
 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).

package/dist/index.cjs

@@ -38,7 +38,6 @@ __export(index_exports, {
   ImageClient: () => ImageClient,
   KNOWN_PROVIDERS: () => KNOWN_PROVIDERS,
   LLMClient: () => LLMClient,
-  MAX_TOKENS_SANITY_LIMIT: () => MAX_TOKENS_SANITY_LIMIT,
   MusicClient: () => MusicClient,
   NETWORK_ALIASES: () => NETWORK_ALIASES,
   OpenAI: () => OpenAI,
@@ -145,8 +144,47 @@ var BASE_CHAIN_ID = 8453;
 var USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
 var SOLANA_NETWORK = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
 var USDC_SOLANA = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+var SOLANA_USDC_DECIMALS = 6;
 var DEFAULT_COMPUTE_UNIT_PRICE_MICROLAMPORTS = 1;
 var DEFAULT_COMPUTE_UNIT_LIMIT = 8e3;
+var BLOCKHASH_TTL_MS = 1e4;
+var MAX_FEE_NONCE_STEPS = 64;
+var MAX_TRACKED_BLOCKHASHES = 8;
+var MAX_TRACKED_ENDPOINTS = 8;
+var blockhashCache = /* @__PURE__ */ new Map();
+function trimOldest(map, limit) {
+  while (map.size > limit) {
+    const oldest = map.keys().next().value;
+    map.delete(oldest);
+  }
+}
+var issuedByBlockhash = /* @__PURE__ */ new Map();
+function issuedFor(blockhash) {
+  let issued = issuedByBlockhash.get(blockhash);
+  if (!issued) {
+    issued = /* @__PURE__ */ new Set();
+    issuedByBlockhash.set(blockhash, issued);
+    trimOldest(issuedByBlockhash, MAX_TRACKED_BLOCKHASHES);
+  }
+  return issued;
+}
+async function getBlockhashEntry(connection, rpcUrl, forceRefresh) {
+  const now = Date.now();
+  const cached = blockhashCache.get(rpcUrl);
+  if (!forceRefresh && cached && now - cached.fetchedAt < BLOCKHASH_TTL_MS) {
+    return cached;
+  }
+  const { blockhash } = await connection.getLatestBlockhash();
+  const current = blockhashCache.get(rpcUrl);
+  if (current?.blockhash === blockhash) {
+    current.fetchedAt = now;
+    return current;
+  }
+  const entry = { blockhash, fetchedAt: now };
+  blockhashCache.set(rpcUrl, entry);
+  trimOldest(blockhashCache, MAX_TRACKED_ENDPOINTS);
+  return entry;
+}
 var USDC_DOMAIN = {
   name: "USD Coin",
   version: "2",
@@ -231,7 +269,7 @@ async function createPaymentPayload(privateKey, fromAddress, recipient, amount,
 }
 async function createSolanaPaymentPayload(secretKey, fromAddress, recipient, amount, feePayer, options = {}) {
   const { Connection, PublicKey, TransactionMessage, VersionedTransaction, ComputeBudgetProgram } = await import("@solana/web3.js");
-  const { getAssociatedTokenAddress, createTransferCheckedInstruction, getMint } = await import("@solana/spl-token");
+  const { getAssociatedTokenAddress, createTransferCheckedInstruction } = await import("@solana/spl-token");
   const { Keypair } = await import("@solana/web3.js");
   const rpcUrl = options.rpcUrl || "https://sol.blockrun.ai/api/v1/solana/rpc";
   const connection = options.rpcHeaders ? new Connection(rpcUrl, { httpHeaders: options.rpcHeaders }) : new Connection(rpcUrl);
@@ -240,32 +278,53 @@ async function createSolanaPaymentPayload(secretKey, fromAddress, recipient, amo
   const ownerPubkey = keypair.publicKey;
   const tokenMint = new PublicKey(USDC_SOLANA);
   const payToPubkey = new PublicKey(recipient);
-  const mintInfo = await getMint(connection, tokenMint);
   const sourceATA = await getAssociatedTokenAddress(tokenMint, ownerPubkey, false);
   const destinationATA = await getAssociatedTokenAddress(tokenMint, payToPubkey, false);
-  const { blockhash } = await connection.getLatestBlockhash();
-  const setComputeUnitPriceIx = ComputeBudgetProgram.setComputeUnitPrice({
-    microLamports: DEFAULT_COMPUTE_UNIT_PRICE_MICROLAMPORTS
-  });
-  const setComputeUnitLimitIx = ComputeBudgetProgram.setComputeUnitLimit({
-    units: DEFAULT_COMPUTE_UNIT_LIMIT
-  });
   const transferIx = createTransferCheckedInstruction(
     sourceATA,
     tokenMint,
     destinationATA,
     ownerPubkey,
     BigInt(amount),
-    mintInfo.decimals
+    SOLANA_USDC_DECIMALS
   );
-  const messageV0 = new TransactionMessage({
-    payerKey: feePayerPubkey,
-    recentBlockhash: blockhash,
-    instructions: [setComputeUnitLimitIx, setComputeUnitPriceIx, transferIx]
-  }).compileToV0Message();
-  const transaction = new VersionedTransaction(messageV0);
-  transaction.sign([keypair]);
-  const serializedTx = Buffer.from(transaction.serialize()).toString("base64");
+  const buildSignedTx = (blockhash, unitPriceMicroLamports) => {
+    const messageV0 = new TransactionMessage({
+      payerKey: feePayerPubkey,
+      recentBlockhash: blockhash,
+      instructions: [
+        ComputeBudgetProgram.setComputeUnitLimit({ units: DEFAULT_COMPUTE_UNIT_LIMIT }),
+        ComputeBudgetProgram.setComputeUnitPrice({ microLamports: unitPriceMicroLamports }),
+        transferIx
+      ]
+    }).compileToV0Message();
+    const transaction = new VersionedTransaction(messageV0);
+    transaction.sign([keypair]);
+    return Buffer.from(transaction.serialize()).toString("base64");
+  };
+  const findDistinctTx = (candidate) => {
+    const issued = issuedFor(candidate.blockhash);
+    for (let step = 0; step <= MAX_FEE_NONCE_STEPS; step++) {
+      const tx = buildSignedTx(
+        candidate.blockhash,
+        DEFAULT_COMPUTE_UNIT_PRICE_MICROLAMPORTS + step
+      );
+      if (!issued.has(tx)) return tx;
+    }
+    return null;
+  };
+  let entry = await getBlockhashEntry(connection, rpcUrl, false);
+  let serializedTx = findDistinctTx(entry);
+  if (serializedTx === null) {
+    entry = await getBlockhashEntry(connection, rpcUrl, true);
+    serializedTx = findDistinctTx(entry);
+  }
+  if (serializedTx === null) {
+    throw new Error(
+      `Solana payment: ${MAX_FEE_NONCE_STEPS + 1} identical payments already issued against blockhash ${entry.blockhash}. Retry once it rotates.`
+    );
+  }
+  issuedFor(entry.blockhash).add(serializedTx);
   const paymentData = {
     x402Version: 2,
     resource: {
@@ -356,7 +415,6 @@ function validateModel(model) {
     throw new Error("Model must be a non-empty string");
   }
 }
-var MAX_TOKENS_SANITY_LIMIT = 1e6;
 function validateMaxTokens(maxTokens) {
   if (maxTokens === void 0 || maxTokens === null) {
     return;
@@ -367,14 +425,6 @@ function validateMaxTokens(maxTokens) {
   if (maxTokens < 1) {
     throw new Error("maxTokens must be positive (minimum: 1)");
   }
-  if (maxTokens > MAX_TOKENS_SANITY_LIMIT) {
-    throw Object.assign(
-      new Error(
-        `maxTokens implausibly large (client-side sanity limit: ${MAX_TOKENS_SANITY_LIMIT}). This is not a model limit \u2014 the gateway enforces the real per-model ceiling and reports it.`
-      ),
-      { code: "MAX_TOKENS_SANITY_LIMIT", limit: MAX_TOKENS_SANITY_LIMIT }
-    );
-  }
 }
 function validateTemperature(temperature) {
   if (temperature === void 0 || temperature === null) {
@@ -514,7 +564,7 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.8.2";
+var SDK_VERSION = "3.8.4";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
@@ -6139,7 +6189,6 @@ var AnthropicClient = class {
   ImageClient,
   KNOWN_PROVIDERS,
   LLMClient,
-  MAX_TOKENS_SANITY_LIMIT,
   MusicClient,
   NETWORK_ALIASES,
   OpenAI,

package/dist/index.d.cts

@@ -3161,37 +3161,26 @@ declare const KNOWN_PROVIDERS: Set<string>;
  */
 declare function validateModel(model: string): void;
 /**
- * Client-side typo guard, NOT a model limit. The gateway already enforces the
- * real per-model ceiling and rejects with that model's own number, so anything
- * hardcoded here can only be wrong in one direction: too low.
- *
- * This was 100000. Note what it was and was not doing: until this change no
- * client called `validateMaxTokens` at all, so the bound bound nothing on a
- * real request — it only rejected callers who imported the validator directly
- * off the package's public surface. The guard is now wired into
- * `LLMClient.chatCompletion`, `LLMClient.chatCompletionStream`, and
- * `SolanaLLMClient.chatCompletion`, which is exactly why the number had to go
- * up first: at 100000 it would have started rejecting real requests.
- *
- * Verified against the live gateway 2026-07-21
- * with the guard bypassed: zai/glm-5.2 accepted 262144, and the whole 128000
- * class accepted 128000 (claude-opus-4.8, claude-sonnet-5, claude-fable-5,
- * gpt-5.6-sol/terra/luna, gpt-5.5, gpt-5.4, gpt-5.3-codex, glm-5/5.1/5-turbo).
- * 19 models advertised above 100000; all 19 accepted their ceiling. Those are
- * as-of-date probe results, not a maintained invariant — nothing in this repo
- * ships a model catalog, so CI cannot detect when they go stale.
- *
- * Keep a bound so an obvious mistake (1e9, a byte count, a timestamp) fails
- * fast locally instead of becoming a payment quote. Set it far above any real
- * model so it can never be the binding constraint again.
- */
-declare const MAX_TOKENS_SANITY_LIMIT = 1000000;
-/**
- * Validates that max_tokens is a positive integer no larger than
- * {@link MAX_TOKENS_SANITY_LIMIT}.
+ * Mirrors the gateway's own contract for `max_tokens`, which is exactly
+ * `z.number().int().min(1).optional()` — an integer, at least 1, and
+ * deliberately **no upper bound**.
+ *
+ * There is no ceiling here on purpose. The gateway clamps every request with
+ * `min(requested, model.maxOutput, contextHeadroom)` and then quotes only a
+ * fraction of the clamped value, so an oversized `maxTokens` cannot inflate a
+ * payment: 1e9 and 1_000_000 produce a byte-identical quote, because both land
+ * on the same `model.maxOutput`. A client-side ceiling could therefore only
+ * ever reject a request the gateway would have accepted and handled correctly.
+ *
+ * Earlier versions of this file did carry one, justified in a comment as
+ * stopping a stray 1e9 from "becoming a payment quote". That was never true —
+ * it was asserted here without being checked against the route handler, which
+ * is the same mistake as the old `"maxTokens too large (maximum: 100000)"`
+ * message that got recorded downstream as an upstream model ceiling. Verify
+ * against the gateway before reintroducing any number in this file.
  *
  * @param maxTokens - Maximum number of tokens to generate
- * @throws {Error} If maxTokens is invalid
+ * @throws {Error} If maxTokens is not a positive integer
  *
  * @example
  * validateMaxTokens(1000);
@@ -3218,4 +3207,4 @@ declare function validateTemperature(temperature?: number): void;
  */
 declare function validateTopP(topP?: number): void;
 
-export { APIError, AnthropicClient, type AudioModel, type AudioTrack, BASE_CHAIN_ID, type BarResolution, type BlockRunAnthropicOptions, BlockrunClient, type BlockrunClientOptions, BlockrunError, type CallInitiatedResponse, type CallModel, type CallOptions, type CallStatusResponse, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, MAX_TOKENS_SANITY_LIMIT, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, NETWORK_ALIASES, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PHONE_PRICES, PORTRAIT_ENROLLMENT_PRICE_USD, PaymentError, type PaymentLinks, type PhoneBuyOptions, type PhoneBuyResponse, PhoneClient, type PhoneClientOptions, type PhoneListResponse, type PhoneLookupResponse, type PhoneNumberRecord, type PhoneReleaseResponse, type PhoneRenewResponse, type PollOptions, PortraitClient, type PortraitClientOptions, type PortraitEnrollOptions, type PortraitEnrollResponse, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, RPC_PRICE_USD, type ResponseFormat, type RoutingDecision, type RoutingProfile, type RoutingTier, type RpcBatchRequest, RpcClient, type RpcClientOptions, type RpcError, type RpcNetwork, type RpcResponse, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SUPPORTED_NETWORKS, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type SoundEffectOptions, type SpeechAudio, SpeechClient, type SpeechClientOptions, type SpeechGenerateOptions, type SpeechModel, type SpeechResponse, type SpeechVoice, type Spending, type SpendingReport, type StockMarket, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoiceInfo, type VoicePreset, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XSearchSource, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatSolanaWalletMigrationNotice, formatWalletCreatedMessage, formatWalletMigrationNotice, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, importSolanaWallet, importWallet, listDiscoveredSolanaWallets, listDiscoveredWallets, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, validateMaxTokens, validateModel, validateTemperature, validateTopP };
+export { APIError, AnthropicClient, type AudioModel, type AudioTrack, BASE_CHAIN_ID, type BarResolution, type BlockRunAnthropicOptions, BlockrunClient, type BlockrunClientOptions, BlockrunError, type CallInitiatedResponse, type CallModel, type CallOptions, type CallStatusResponse, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, NETWORK_ALIASES, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PHONE_PRICES, PORTRAIT_ENROLLMENT_PRICE_USD, PaymentError, type PaymentLinks, type PhoneBuyOptions, type PhoneBuyResponse, PhoneClient, type PhoneClientOptions, type PhoneListResponse, type PhoneLookupResponse, type PhoneNumberRecord, type PhoneReleaseResponse, type PhoneRenewResponse, type PollOptions, PortraitClient, type PortraitClientOptions, type PortraitEnrollOptions, type PortraitEnrollResponse, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, RPC_PRICE_USD, type ResponseFormat, type RoutingDecision, type RoutingProfile, type RoutingTier, type RpcBatchRequest, RpcClient, type RpcClientOptions, type RpcError, type RpcNetwork, type RpcResponse, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SUPPORTED_NETWORKS, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type SoundEffectOptions, type SpeechAudio, SpeechClient, type SpeechClientOptions, type SpeechGenerateOptions, type SpeechModel, type SpeechResponse, type SpeechVoice, type Spending, type SpendingReport, type StockMarket, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoiceInfo, type VoicePreset, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XSearchSource, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatSolanaWalletMigrationNotice, formatWalletCreatedMessage, formatWalletMigrationNotice, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, importSolanaWallet, importWallet, listDiscoveredSolanaWallets, listDiscoveredWallets, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, validateMaxTokens, validateModel, validateTemperature, validateTopP };

package/dist/index.d.ts

@@ -3161,37 +3161,26 @@ declare const KNOWN_PROVIDERS: Set<string>;
  */
 declare function validateModel(model: string): void;
 /**
- * Client-side typo guard, NOT a model limit. The gateway already enforces the
- * real per-model ceiling and rejects with that model's own number, so anything
- * hardcoded here can only be wrong in one direction: too low.
- *
- * This was 100000. Note what it was and was not doing: until this change no
- * client called `validateMaxTokens` at all, so the bound bound nothing on a
- * real request — it only rejected callers who imported the validator directly
- * off the package's public surface. The guard is now wired into
- * `LLMClient.chatCompletion`, `LLMClient.chatCompletionStream`, and
- * `SolanaLLMClient.chatCompletion`, which is exactly why the number had to go
- * up first: at 100000 it would have started rejecting real requests.
- *
- * Verified against the live gateway 2026-07-21
- * with the guard bypassed: zai/glm-5.2 accepted 262144, and the whole 128000
- * class accepted 128000 (claude-opus-4.8, claude-sonnet-5, claude-fable-5,
- * gpt-5.6-sol/terra/luna, gpt-5.5, gpt-5.4, gpt-5.3-codex, glm-5/5.1/5-turbo).
- * 19 models advertised above 100000; all 19 accepted their ceiling. Those are
- * as-of-date probe results, not a maintained invariant — nothing in this repo
- * ships a model catalog, so CI cannot detect when they go stale.
- *
- * Keep a bound so an obvious mistake (1e9, a byte count, a timestamp) fails
- * fast locally instead of becoming a payment quote. Set it far above any real
- * model so it can never be the binding constraint again.
- */
-declare const MAX_TOKENS_SANITY_LIMIT = 1000000;
-/**
- * Validates that max_tokens is a positive integer no larger than
- * {@link MAX_TOKENS_SANITY_LIMIT}.
+ * Mirrors the gateway's own contract for `max_tokens`, which is exactly
+ * `z.number().int().min(1).optional()` — an integer, at least 1, and
+ * deliberately **no upper bound**.
+ *
+ * There is no ceiling here on purpose. The gateway clamps every request with
+ * `min(requested, model.maxOutput, contextHeadroom)` and then quotes only a
+ * fraction of the clamped value, so an oversized `maxTokens` cannot inflate a
+ * payment: 1e9 and 1_000_000 produce a byte-identical quote, because both land
+ * on the same `model.maxOutput`. A client-side ceiling could therefore only
+ * ever reject a request the gateway would have accepted and handled correctly.
+ *
+ * Earlier versions of this file did carry one, justified in a comment as
+ * stopping a stray 1e9 from "becoming a payment quote". That was never true —
+ * it was asserted here without being checked against the route handler, which
+ * is the same mistake as the old `"maxTokens too large (maximum: 100000)"`
+ * message that got recorded downstream as an upstream model ceiling. Verify
+ * against the gateway before reintroducing any number in this file.
  *
  * @param maxTokens - Maximum number of tokens to generate
- * @throws {Error} If maxTokens is invalid
+ * @throws {Error} If maxTokens is not a positive integer
  *
  * @example
  * validateMaxTokens(1000);
@@ -3218,4 +3207,4 @@ declare function validateTemperature(temperature?: number): void;
  */
 declare function validateTopP(topP?: number): void;
 
-export { APIError, AnthropicClient, type AudioModel, type AudioTrack, BASE_CHAIN_ID, type BarResolution, type BlockRunAnthropicOptions, BlockrunClient, type BlockrunClientOptions, BlockrunError, type CallInitiatedResponse, type CallModel, type CallOptions, type CallStatusResponse, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, MAX_TOKENS_SANITY_LIMIT, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, NETWORK_ALIASES, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PHONE_PRICES, PORTRAIT_ENROLLMENT_PRICE_USD, PaymentError, type PaymentLinks, type PhoneBuyOptions, type PhoneBuyResponse, PhoneClient, type PhoneClientOptions, type PhoneListResponse, type PhoneLookupResponse, type PhoneNumberRecord, type PhoneReleaseResponse, type PhoneRenewResponse, type PollOptions, PortraitClient, type PortraitClientOptions, type PortraitEnrollOptions, type PortraitEnrollResponse, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, RPC_PRICE_USD, type ResponseFormat, type RoutingDecision, type RoutingProfile, type RoutingTier, type RpcBatchRequest, RpcClient, type RpcClientOptions, type RpcError, type RpcNetwork, type RpcResponse, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SUPPORTED_NETWORKS, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type SoundEffectOptions, type SpeechAudio, SpeechClient, type SpeechClientOptions, type SpeechGenerateOptions, type SpeechModel, type SpeechResponse, type SpeechVoice, type Spending, type SpendingReport, type StockMarket, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoiceInfo, type VoicePreset, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XSearchSource, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatSolanaWalletMigrationNotice, formatWalletCreatedMessage, formatWalletMigrationNotice, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, importSolanaWallet, importWallet, listDiscoveredSolanaWallets, listDiscoveredWallets, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, validateMaxTokens, validateModel, validateTemperature, validateTopP };
+export { APIError, AnthropicClient, type AudioModel, type AudioTrack, BASE_CHAIN_ID, type BarResolution, type BlockRunAnthropicOptions, BlockrunClient, type BlockrunClientOptions, BlockrunError, type CallInitiatedResponse, type CallModel, type CallOptions, type CallStatusResponse, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, NETWORK_ALIASES, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PHONE_PRICES, PORTRAIT_ENROLLMENT_PRICE_USD, PaymentError, type PaymentLinks, type PhoneBuyOptions, type PhoneBuyResponse, PhoneClient, type PhoneClientOptions, type PhoneListResponse, type PhoneLookupResponse, type PhoneNumberRecord, type PhoneReleaseResponse, type PhoneRenewResponse, type PollOptions, PortraitClient, type PortraitClientOptions, type PortraitEnrollOptions, type PortraitEnrollResponse, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, RPC_PRICE_USD, type ResponseFormat, type RoutingDecision, type RoutingProfile, type RoutingTier, type RpcBatchRequest, RpcClient, type RpcClientOptions, type RpcError, type RpcNetwork, type RpcResponse, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SUPPORTED_NETWORKS, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type SoundEffectOptions, type SpeechAudio, SpeechClient, type SpeechClientOptions, type SpeechGenerateOptions, type SpeechModel, type SpeechResponse, type SpeechVoice, type Spending, type SpendingReport, type StockMarket, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoiceInfo, type VoicePreset, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XSearchSource, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatSolanaWalletMigrationNotice, formatWalletCreatedMessage, formatWalletMigrationNotice, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, importSolanaWallet, importWallet, listDiscoveredSolanaWallets, listDiscoveredWallets, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, validateMaxTokens, validateModel, validateTemperature, validateTopP };

package/dist/index.js

@@ -31,8 +31,47 @@ var BASE_CHAIN_ID = 8453;
 var USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
 var SOLANA_NETWORK = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
 var USDC_SOLANA = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+var SOLANA_USDC_DECIMALS = 6;
 var DEFAULT_COMPUTE_UNIT_PRICE_MICROLAMPORTS = 1;
 var DEFAULT_COMPUTE_UNIT_LIMIT = 8e3;
+var BLOCKHASH_TTL_MS = 1e4;
+var MAX_FEE_NONCE_STEPS = 64;
+var MAX_TRACKED_BLOCKHASHES = 8;
+var MAX_TRACKED_ENDPOINTS = 8;
+var blockhashCache = /* @__PURE__ */ new Map();
+function trimOldest(map, limit) {
+  while (map.size > limit) {
+    const oldest = map.keys().next().value;
+    map.delete(oldest);
+  }
+}
+var issuedByBlockhash = /* @__PURE__ */ new Map();
+function issuedFor(blockhash) {
+  let issued = issuedByBlockhash.get(blockhash);
+  if (!issued) {
+    issued = /* @__PURE__ */ new Set();
+    issuedByBlockhash.set(blockhash, issued);
+    trimOldest(issuedByBlockhash, MAX_TRACKED_BLOCKHASHES);
+  }
+  return issued;
+}
+async function getBlockhashEntry(connection, rpcUrl, forceRefresh) {
+  const now = Date.now();
+  const cached = blockhashCache.get(rpcUrl);
+  if (!forceRefresh && cached && now - cached.fetchedAt < BLOCKHASH_TTL_MS) {
+    return cached;
+  }
+  const { blockhash } = await connection.getLatestBlockhash();
+  const current = blockhashCache.get(rpcUrl);
+  if (current?.blockhash === blockhash) {
+    current.fetchedAt = now;
+    return current;
+  }
+  const entry = { blockhash, fetchedAt: now };
+  blockhashCache.set(rpcUrl, entry);
+  trimOldest(blockhashCache, MAX_TRACKED_ENDPOINTS);
+  return entry;
+}
 var USDC_DOMAIN = {
   name: "USD Coin",
   version: "2",
@@ -117,7 +156,7 @@ async function createPaymentPayload(privateKey, fromAddress, recipient, amount,
 }
 async function createSolanaPaymentPayload(secretKey, fromAddress, recipient, amount, feePayer, options = {}) {
   const { Connection, PublicKey, TransactionMessage, VersionedTransaction, ComputeBudgetProgram } = await import("@solana/web3.js");
-  const { getAssociatedTokenAddress, createTransferCheckedInstruction, getMint } = await import("@solana/spl-token");
+  const { getAssociatedTokenAddress, createTransferCheckedInstruction } = await import("@solana/spl-token");
   const { Keypair } = await import("@solana/web3.js");
   const rpcUrl = options.rpcUrl || "https://sol.blockrun.ai/api/v1/solana/rpc";
   const connection = options.rpcHeaders ? new Connection(rpcUrl, { httpHeaders: options.rpcHeaders }) : new Connection(rpcUrl);
@@ -126,32 +165,53 @@ async function createSolanaPaymentPayload(secretKey, fromAddress, recipient, amo
   const ownerPubkey = keypair.publicKey;
   const tokenMint = new PublicKey(USDC_SOLANA);
   const payToPubkey = new PublicKey(recipient);
-  const mintInfo = await getMint(connection, tokenMint);
   const sourceATA = await getAssociatedTokenAddress(tokenMint, ownerPubkey, false);
   const destinationATA = await getAssociatedTokenAddress(tokenMint, payToPubkey, false);
-  const { blockhash } = await connection.getLatestBlockhash();
-  const setComputeUnitPriceIx = ComputeBudgetProgram.setComputeUnitPrice({
-    microLamports: DEFAULT_COMPUTE_UNIT_PRICE_MICROLAMPORTS
-  });
-  const setComputeUnitLimitIx = ComputeBudgetProgram.setComputeUnitLimit({
-    units: DEFAULT_COMPUTE_UNIT_LIMIT
-  });
   const transferIx = createTransferCheckedInstruction(
     sourceATA,
     tokenMint,
     destinationATA,
     ownerPubkey,
     BigInt(amount),
-    mintInfo.decimals
+    SOLANA_USDC_DECIMALS
   );
-  const messageV0 = new TransactionMessage({
-    payerKey: feePayerPubkey,
-    recentBlockhash: blockhash,
-    instructions: [setComputeUnitLimitIx, setComputeUnitPriceIx, transferIx]
-  }).compileToV0Message();
-  const transaction = new VersionedTransaction(messageV0);
-  transaction.sign([keypair]);
-  const serializedTx = Buffer.from(transaction.serialize()).toString("base64");
+  const buildSignedTx = (blockhash, unitPriceMicroLamports) => {
+    const messageV0 = new TransactionMessage({
+      payerKey: feePayerPubkey,
+      recentBlockhash: blockhash,
+      instructions: [
+        ComputeBudgetProgram.setComputeUnitLimit({ units: DEFAULT_COMPUTE_UNIT_LIMIT }),
+        ComputeBudgetProgram.setComputeUnitPrice({ microLamports: unitPriceMicroLamports }),
+        transferIx
+      ]
+    }).compileToV0Message();
+    const transaction = new VersionedTransaction(messageV0);
+    transaction.sign([keypair]);
+    return Buffer.from(transaction.serialize()).toString("base64");
+  };
+  const findDistinctTx = (candidate) => {
+    const issued = issuedFor(candidate.blockhash);
+    for (let step = 0; step <= MAX_FEE_NONCE_STEPS; step++) {
+      const tx = buildSignedTx(
+        candidate.blockhash,
+        DEFAULT_COMPUTE_UNIT_PRICE_MICROLAMPORTS + step
+      );
+      if (!issued.has(tx)) return tx;
+    }
+    return null;
+  };
+  let entry = await getBlockhashEntry(connection, rpcUrl, false);
+  let serializedTx = findDistinctTx(entry);
+  if (serializedTx === null) {
+    entry = await getBlockhashEntry(connection, rpcUrl, true);
+    serializedTx = findDistinctTx(entry);
+  }
+  if (serializedTx === null) {
+    throw new Error(
+      `Solana payment: ${MAX_FEE_NONCE_STEPS + 1} identical payments already issued against blockhash ${entry.blockhash}. Retry once it rotates.`
+    );
+  }
+  issuedFor(entry.blockhash).add(serializedTx);
   const paymentData = {
     x402Version: 2,
     resource: {
@@ -242,7 +302,6 @@ function validateModel(model) {
     throw new Error("Model must be a non-empty string");
   }
 }
-var MAX_TOKENS_SANITY_LIMIT = 1e6;
 function validateMaxTokens(maxTokens) {
   if (maxTokens === void 0 || maxTokens === null) {
     return;
@@ -253,14 +312,6 @@ function validateMaxTokens(maxTokens) {
   if (maxTokens < 1) {
     throw new Error("maxTokens must be positive (minimum: 1)");
   }
-  if (maxTokens > MAX_TOKENS_SANITY_LIMIT) {
-    throw Object.assign(
-      new Error(
-        `maxTokens implausibly large (client-side sanity limit: ${MAX_TOKENS_SANITY_LIMIT}). This is not a model limit \u2014 the gateway enforces the real per-model ceiling and reports it.`
-      ),
-      { code: "MAX_TOKENS_SANITY_LIMIT", limit: MAX_TOKENS_SANITY_LIMIT }
-    );
-  }
 }
 function validateTemperature(temperature) {
   if (temperature === void 0 || temperature === null) {
@@ -400,7 +451,7 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.8.2";
+var SDK_VERSION = "3.8.4";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
@@ -6024,7 +6075,6 @@ export {
   ImageClient,
   KNOWN_PROVIDERS,
   LLMClient,
-  MAX_TOKENS_SANITY_LIMIT,
   MusicClient,
   NETWORK_ALIASES,
   OpenAI,

package/package.json

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