@blockrun/llm 3.8.3 → 3.9.0

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

@@ -144,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",
@@ -230,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);
@@ -239,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: {
@@ -504,7 +564,7 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.8.3";
+var SDK_VERSION = "3.9.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
@@ -4843,16 +4903,51 @@ async function createSolanaWallet() {
   };
 }
 async function solanaKeyToBytes(privateKey) {
+  const key = privateKey.trim();
+  if (key.startsWith("[")) {
+    let parsed;
+    try {
+      parsed = JSON.parse(key);
+    } catch {
+      throw new Error(
+        "Invalid Solana private key: looks like a JSON byte array but is not valid JSON"
+      );
+    }
+    if (!Array.isArray(parsed) || !parsed.every((n) => Number.isInteger(n) && n >= 0 && n <= 255)) {
+      throw new Error(
+        "Invalid Solana private key: JSON array must contain only byte values (0-255)"
+      );
+    }
+    if (parsed.length !== 64) {
+      throw new Error(
+        `Invalid Solana key length: expected 64 bytes, got ${parsed.length}`
+      );
+    }
+    return Uint8Array.from(parsed);
+  }
+  const hex = key.startsWith("0x") || key.startsWith("0X") ? key.slice(2) : key;
+  if (/^[0-9a-fA-F]+$/.test(hex) && (hex.length === 64 || hex.length === 128)) {
+    if (hex.length === 64) {
+      throw new Error(
+        "Invalid Solana private key: this is a 32-byte hex key \u2014 the EVM (Base) wallet format, not a Solana key. Solana keys are 64 bytes, usually base58-encoded (86-88 characters)."
+      );
+    }
+    const bytes = new Uint8Array(64);
+    for (let i = 0; i < 64; i++) bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    return bytes;
+  }
   try {
     const bs58 = await import("bs58");
-    const bytes = (bs58.default ?? bs58).decode(privateKey);
+    const bytes = (bs58.default ?? bs58).decode(key);
     if (bytes.length !== 64) {
       throw new Error(`Invalid Solana key length: expected 64 bytes, got ${bytes.length}`);
     }
     return bytes;
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    throw new Error(`Invalid Solana private key: ${msg}`);
+    throw new Error(
+      `Invalid Solana private key: ${msg}. Expected a base58-encoded 64-byte key (standard Solana format), a 64-byte hex string, or a Solana CLI JSON byte array.`
+    );
   }
 }
 async function solanaPublicKey(privateKey) {
@@ -4992,16 +5087,27 @@ Your current wallet is backed up first. You can also set
 SOLANA_WALLET_KEY=<private-key> for a single run without changing anything.
 `;
 }
+async function solanaPublicKeyFrom(privateKey, source) {
+  try {
+    return await solanaPublicKey(privateKey);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`${msg} (key loaded from ${source})`);
+  }
+}
 async function getOrCreateSolanaWallet() {
   const envKey = typeof process !== "undefined" && process.env ? process.env.SOLANA_WALLET_KEY : void 0;
   if (envKey) {
-    const address2 = await solanaPublicKey(envKey);
+    const address2 = await solanaPublicKeyFrom(
+      envKey,
+      "the SOLANA_WALLET_KEY environment variable"
+    );
     return { privateKey: envKey, address: address2, isNew: false };
   }
   if (fs3.existsSync(SOLANA_WALLET_FILE)) {
     const fileKey = fs3.readFileSync(SOLANA_WALLET_FILE, "utf-8").trim();
     if (fileKey) {
-      const address2 = await solanaPublicKey(fileKey);
+      const address2 = await solanaPublicKeyFrom(fileKey, SOLANA_WALLET_FILE);
       return { privateKey: fileKey, address: address2, isNew: false };
     }
   }

package/dist/index.d.cts

@@ -2860,8 +2860,11 @@ declare function createSolanaWallet(): Promise<{
     privateKey: string;
 }>;
 /**
- * Convert a bs58 private key string to Uint8Array (64 bytes).
- * Accepts: bs58-encoded 64-byte key (standard Solana format).
+ * Convert a Solana private key string to Uint8Array (64 bytes).
+ * Accepts: bs58-encoded 64-byte key (standard Solana format), the Solana CLI
+ * JSON byte-array format (~/.config/solana/id.json), or a 64-byte hex string
+ * (with or without 0x). A 32-byte hex key is rejected with an explicit hint
+ * that it is the EVM (Base) wallet format, not a Solana key.
  */
 declare function solanaKeyToBytes(privateKey: string): Promise<Uint8Array>;
 /**

package/dist/index.d.ts

@@ -2860,8 +2860,11 @@ declare function createSolanaWallet(): Promise<{
     privateKey: string;
 }>;
 /**
- * Convert a bs58 private key string to Uint8Array (64 bytes).
- * Accepts: bs58-encoded 64-byte key (standard Solana format).
+ * Convert a Solana private key string to Uint8Array (64 bytes).
+ * Accepts: bs58-encoded 64-byte key (standard Solana format), the Solana CLI
+ * JSON byte-array format (~/.config/solana/id.json), or a 64-byte hex string
+ * (with or without 0x). A 32-byte hex key is rejected with an explicit hint
+ * that it is the EVM (Base) wallet format, not a Solana key.
  */
 declare function solanaKeyToBytes(privateKey: string): Promise<Uint8Array>;
 /**

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: {
@@ -391,7 +451,7 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.8.3";
+var SDK_VERSION = "3.9.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
@@ -4730,16 +4790,51 @@ async function createSolanaWallet() {
   };
 }
 async function solanaKeyToBytes(privateKey) {
+  const key = privateKey.trim();
+  if (key.startsWith("[")) {
+    let parsed;
+    try {
+      parsed = JSON.parse(key);
+    } catch {
+      throw new Error(
+        "Invalid Solana private key: looks like a JSON byte array but is not valid JSON"
+      );
+    }
+    if (!Array.isArray(parsed) || !parsed.every((n) => Number.isInteger(n) && n >= 0 && n <= 255)) {
+      throw new Error(
+        "Invalid Solana private key: JSON array must contain only byte values (0-255)"
+      );
+    }
+    if (parsed.length !== 64) {
+      throw new Error(
+        `Invalid Solana key length: expected 64 bytes, got ${parsed.length}`
+      );
+    }
+    return Uint8Array.from(parsed);
+  }
+  const hex = key.startsWith("0x") || key.startsWith("0X") ? key.slice(2) : key;
+  if (/^[0-9a-fA-F]+$/.test(hex) && (hex.length === 64 || hex.length === 128)) {
+    if (hex.length === 64) {
+      throw new Error(
+        "Invalid Solana private key: this is a 32-byte hex key \u2014 the EVM (Base) wallet format, not a Solana key. Solana keys are 64 bytes, usually base58-encoded (86-88 characters)."
+      );
+    }
+    const bytes = new Uint8Array(64);
+    for (let i = 0; i < 64; i++) bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    return bytes;
+  }
   try {
     const bs58 = await import("bs58");
-    const bytes = (bs58.default ?? bs58).decode(privateKey);
+    const bytes = (bs58.default ?? bs58).decode(key);
     if (bytes.length !== 64) {
       throw new Error(`Invalid Solana key length: expected 64 bytes, got ${bytes.length}`);
     }
     return bytes;
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    throw new Error(`Invalid Solana private key: ${msg}`);
+    throw new Error(
+      `Invalid Solana private key: ${msg}. Expected a base58-encoded 64-byte key (standard Solana format), a 64-byte hex string, or a Solana CLI JSON byte array.`
+    );
   }
 }
 async function solanaPublicKey(privateKey) {
@@ -4879,16 +4974,27 @@ Your current wallet is backed up first. You can also set
 SOLANA_WALLET_KEY=<private-key> for a single run without changing anything.
 `;
 }
+async function solanaPublicKeyFrom(privateKey, source) {
+  try {
+    return await solanaPublicKey(privateKey);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`${msg} (key loaded from ${source})`);
+  }
+}
 async function getOrCreateSolanaWallet() {
   const envKey = typeof process !== "undefined" && process.env ? process.env.SOLANA_WALLET_KEY : void 0;
   if (envKey) {
-    const address2 = await solanaPublicKey(envKey);
+    const address2 = await solanaPublicKeyFrom(
+      envKey,
+      "the SOLANA_WALLET_KEY environment variable"
+    );
     return { privateKey: envKey, address: address2, isNew: false };
   }
   if (fs3.existsSync(SOLANA_WALLET_FILE)) {
     const fileKey = fs3.readFileSync(SOLANA_WALLET_FILE, "utf-8").trim();
     if (fileKey) {
-      const address2 = await solanaPublicKey(fileKey);
+      const address2 = await solanaPublicKeyFrom(fileKey, SOLANA_WALLET_FILE);
       return { privateKey: fileKey, address: address2, isNew: false };
     }
   }

package/package.json

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