@blockrun/llm 3.23.1 → 3.23.2

package/README.md

@@ -1600,9 +1600,9 @@ await status();
 
 `getOrCreateWallet()` resolves the Base wallet in a fixed order:
 `BLOCKRUN_WALLET_KEY` or `BASE_CHAIN_WALLET_KEY`, then `~/.blockrun/.session`,
-then the legacy `~/.blockrun/wallet.key`. `LLMClient` itself reads only
-`BASE_CHAIN_WALLET_KEY` (or an explicit `privateKey`). For a single run of the
-helpers without changing anything, use `export BLOCKRUN_WALLET_KEY=<private-key>`.
+then the legacy `~/.blockrun/wallet.key`. `LLMClient` reads an explicit
+`privateKey`, then `BASE_CHAIN_WALLET_KEY`, then `BLOCKRUN_WALLET_KEY`. For a
+single run without changing anything, use `export BLOCKRUN_WALLET_KEY=<private-key>`.
 
 ### Wallet discovery and migration
 
@@ -1686,7 +1686,7 @@ const configured = new LLMClient({
 | `BLOCKRUN_API_KEY` | Account key (`brk_...`): account billing, no wallet needed. Create one at [user.blockrun.ai/dashboard/keys](https://user.blockrun.ai/dashboard/keys) |
 | `BLOCKRUN_API_BASE_URL` | Account API endpoint (default `https://api.blockrun.ai`) |
 | `BASE_CHAIN_WALLET_KEY` | EVM wallet private key for `LLMClient` (Base / Arc) and every EVM client |
-| `BLOCKRUN_WALLET_KEY` | EVM wallet key honoured by the service clients, `BlockrunClient`, `setupAgentWallet()` and `AnthropicClient` (checked before `BASE_CHAIN_WALLET_KEY`); **not** read by `LLMClient` |
+| `BLOCKRUN_WALLET_KEY` | EVM wallet key read by every EVM client. The service clients, `BlockrunClient`, `setupAgentWallet()` and `AnthropicClient` check it before `BASE_CHAIN_WALLET_KEY`; `LLMClient` checks it after, so a process holding both keeps paying from the same wallet |
 | `SOLANA_WALLET_KEY` | Solana secret key, bs58-encoded, for `SolanaLLMClient` |
 | `SOLANA_RPC_URL` | Solana RPC for payments and balance (also `rpcUrl`) |
 | `SOLANA_RPC_API_KEY` / `SOLANA_RPC_HEADERS` | Header auth for that RPC (also `rpcHeaders`) |

package/dist/index.cjs

@@ -4833,7 +4833,7 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.23.1";
+var SDK_VERSION = "3.23.2";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
@@ -4908,16 +4908,16 @@ var LLMClient = class _LLMClient {
   /**
    * Initialize the BlockRun LLM client.
    *
-   * @param options - Client configuration options (optional if BASE_CHAIN_WALLET_KEY env var is set)
+   * @param options - Client configuration options (optional if BLOCKRUN_API_KEY, BASE_CHAIN_WALLET_KEY or BLOCKRUN_WALLET_KEY is set)
    */
   constructor(options = {}) {
     this.apiAuth = resolveApiKeyAuth(options);
     if (!this.apiAuth) {
-      const envKey = typeof process !== "undefined" && process.env ? process.env.BASE_CHAIN_WALLET_KEY : void 0;
+      const envKey = typeof process !== "undefined" && process.env ? process.env.BASE_CHAIN_WALLET_KEY || process.env.BLOCKRUN_WALLET_KEY : void 0;
       const privateKey = options.privateKey || envKey;
       if (!privateKey) {
         throw new Error(
-          "Private key required. Pass privateKey in options or set BASE_CHAIN_WALLET_KEY environment variable."
+          "Private key required. Pass privateKey in options or set BASE_CHAIN_WALLET_KEY (or BLOCKRUN_WALLET_KEY) environment variable."
         );
       }
       validatePrivateKey(privateKey);
@@ -5606,7 +5606,7 @@ var LLMClient = class _LLMClient {
   }
   /**
    * Make a request with automatic x402 payment handling, returning raw JSON.
-   * Used for non-ChatResponse endpoints (X/Twitter, search, image edit, etc.).
+   * Used for non-ChatResponse endpoints (search, image edit, etc.).
    */
   async requestWithPaymentRaw(endpoint, body) {
     const url = `${this.apiUrl}${endpoint}`;
@@ -6014,7 +6014,8 @@ var LLMClient = class _LLMClient {
     return data;
   }
   /**
-   * Standalone search (web, X/Twitter, news).
+   * Standalone search over web and news. For X/Twitter, use chat on an
+   * `xai/*` model with an `x_search` tool.
    *
    * @param query - Search query
    * @param options - Optional search parameters
@@ -8508,6 +8509,7 @@ var import_accounts12 = require("viem/accounts");
 var DEFAULT_API_URL11 = "https://blockrun.ai/api";
 var DEFAULT_TIMEOUT11 = 6e4;
 var SURF_PREFIX = "/v1/surf";
+var warnedRetired = false;
 var SurfClient = class {
   _account;
   get account() {
@@ -8525,6 +8527,12 @@ var SurfClient = class {
   apiUrl;
   timeout;
   constructor(options = {}) {
+    if (!warnedRetired) {
+      warnedRetired = true;
+      console.warn(
+        "[blockrun] SurfClient is deprecated: the gateway retired /v1/surf/* (410 endpoint_retired). Use PriceClient, LLMClient.defi*, LLMClient.pm() or LLMClient.dex* instead."
+      );
+    }
     this.apiAuth = resolveApiKeyAuth(options);
     if (!this.apiAuth) {
       const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;

package/dist/index.d.cts

@@ -499,7 +499,7 @@ interface PaymentRequired {
     extensions?: Record<string, unknown>;
 }
 interface LLMClientOptions extends ApiKeyOptions {
-    /** EVM wallet private key (hex string starting with 0x). Optional if BASE_CHAIN_WALLET_KEY env var is set. */
+    /** EVM wallet private key (hex string starting with 0x). Optional if BASE_CHAIN_WALLET_KEY (or BLOCKRUN_WALLET_KEY) is set. */
     privateKey?: `0x${string}` | string;
     /** API endpoint URL (default: https://blockrun.ai/api) */
     apiUrl?: string;
@@ -975,7 +975,10 @@ interface VideoGenerateOptions {
     returnLastFrame?: boolean;
 }
 interface SearchOptions {
-    /** Source types to search (e.g. ["web", "x", "news"]) */
+    /**
+     * Source types to search: `"web"` and/or `"news"` (default `["web"]`). `"x"` is
+     * rejected by the gateway; X search runs in chat on `xai/*` models (`x_search`).
+     */
     sources?: string[];
     /** Maximum number of results (default: 10) */
     maxResults?: number;
@@ -1119,6 +1122,7 @@ interface PriceClientOptions extends ApiKeyOptions {
     /** If false, construction succeeds without a wallet (free endpoints only). */
     requireWallet?: boolean;
 }
+/** @deprecated Surf is retired; see {@link SurfClient}. */
 interface SurfClientOptions extends ApiKeyOptions {
     privateKey?: `0x${string}` | string;
     apiUrl?: string;
@@ -1351,7 +1355,7 @@ declare class LLMClient {
     /**
      * Initialize the BlockRun LLM client.
      *
-     * @param options - Client configuration options (optional if BASE_CHAIN_WALLET_KEY env var is set)
+     * @param options - Client configuration options (optional if BLOCKRUN_API_KEY, BASE_CHAIN_WALLET_KEY or BLOCKRUN_WALLET_KEY is set)
      */
     constructor(options?: LLMClientOptions);
     /**
@@ -1510,7 +1514,7 @@ declare class LLMClient {
     chatCompletionStream(model: string, messages: ChatMessage[], options?: ChatCompletionOptions): Promise<Response>;
     /**
      * Make a request with automatic x402 payment handling, returning raw JSON.
-     * Used for non-ChatResponse endpoints (X/Twitter, search, image edit, etc.).
+     * Used for non-ChatResponse endpoints (search, image edit, etc.).
      */
     private requestWithPaymentRaw;
     /**
@@ -1574,7 +1578,8 @@ declare class LLMClient {
      */
     imageEdit(prompt: string, image: string | string[], options?: ImageEditOptions): Promise<ImageResponse>;
     /**
-     * Standalone search (web, X/Twitter, news).
+     * Standalone search over web and news. For X/Twitter, use chat on an
+     * `xai/*` model with an `x_search` tool.
      *
      * @param query - Search query
      * @param options - Optional search parameters
@@ -2328,6 +2333,7 @@ declare class PriceClient {
 
 type QueryValue$1 = string | number | boolean | null | undefined;
 type QueryParams$1 = Record<string, QueryValue$1 | QueryValue$1[]>;
+/** @deprecated Surf is retired (`410 endpoint_retired`); see the module docs for replacements. */
 declare class SurfClient {
     private _account?;
     private get account();

package/dist/index.d.ts

@@ -499,7 +499,7 @@ interface PaymentRequired {
     extensions?: Record<string, unknown>;
 }
 interface LLMClientOptions extends ApiKeyOptions {
-    /** EVM wallet private key (hex string starting with 0x). Optional if BASE_CHAIN_WALLET_KEY env var is set. */
+    /** EVM wallet private key (hex string starting with 0x). Optional if BASE_CHAIN_WALLET_KEY (or BLOCKRUN_WALLET_KEY) is set. */
     privateKey?: `0x${string}` | string;
     /** API endpoint URL (default: https://blockrun.ai/api) */
     apiUrl?: string;
@@ -975,7 +975,10 @@ interface VideoGenerateOptions {
     returnLastFrame?: boolean;
 }
 interface SearchOptions {
-    /** Source types to search (e.g. ["web", "x", "news"]) */
+    /**
+     * Source types to search: `"web"` and/or `"news"` (default `["web"]`). `"x"` is
+     * rejected by the gateway; X search runs in chat on `xai/*` models (`x_search`).
+     */
     sources?: string[];
     /** Maximum number of results (default: 10) */
     maxResults?: number;
@@ -1119,6 +1122,7 @@ interface PriceClientOptions extends ApiKeyOptions {
     /** If false, construction succeeds without a wallet (free endpoints only). */
     requireWallet?: boolean;
 }
+/** @deprecated Surf is retired; see {@link SurfClient}. */
 interface SurfClientOptions extends ApiKeyOptions {
     privateKey?: `0x${string}` | string;
     apiUrl?: string;
@@ -1351,7 +1355,7 @@ declare class LLMClient {
     /**
      * Initialize the BlockRun LLM client.
      *
-     * @param options - Client configuration options (optional if BASE_CHAIN_WALLET_KEY env var is set)
+     * @param options - Client configuration options (optional if BLOCKRUN_API_KEY, BASE_CHAIN_WALLET_KEY or BLOCKRUN_WALLET_KEY is set)
      */
     constructor(options?: LLMClientOptions);
     /**
@@ -1510,7 +1514,7 @@ declare class LLMClient {
     chatCompletionStream(model: string, messages: ChatMessage[], options?: ChatCompletionOptions): Promise<Response>;
     /**
      * Make a request with automatic x402 payment handling, returning raw JSON.
-     * Used for non-ChatResponse endpoints (X/Twitter, search, image edit, etc.).
+     * Used for non-ChatResponse endpoints (search, image edit, etc.).
      */
     private requestWithPaymentRaw;
     /**
@@ -1574,7 +1578,8 @@ declare class LLMClient {
      */
     imageEdit(prompt: string, image: string | string[], options?: ImageEditOptions): Promise<ImageResponse>;
     /**
-     * Standalone search (web, X/Twitter, news).
+     * Standalone search over web and news. For X/Twitter, use chat on an
+     * `xai/*` model with an `x_search` tool.
      *
      * @param query - Search query
      * @param options - Optional search parameters
@@ -2328,6 +2333,7 @@ declare class PriceClient {
 
 type QueryValue$1 = string | number | boolean | null | undefined;
 type QueryParams$1 = Record<string, QueryValue$1 | QueryValue$1[]>;
+/** @deprecated Surf is retired (`410 endpoint_retired`); see the module docs for replacements. */
 declare class SurfClient {
     private _account?;
     private get account();

package/dist/index.js

@@ -4702,7 +4702,7 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.23.1";
+var SDK_VERSION = "3.23.2";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
@@ -4777,16 +4777,16 @@ var LLMClient = class _LLMClient {
   /**
    * Initialize the BlockRun LLM client.
    *
-   * @param options - Client configuration options (optional if BASE_CHAIN_WALLET_KEY env var is set)
+   * @param options - Client configuration options (optional if BLOCKRUN_API_KEY, BASE_CHAIN_WALLET_KEY or BLOCKRUN_WALLET_KEY is set)
    */
   constructor(options = {}) {
     this.apiAuth = resolveApiKeyAuth(options);
     if (!this.apiAuth) {
-      const envKey = typeof process !== "undefined" && process.env ? process.env.BASE_CHAIN_WALLET_KEY : void 0;
+      const envKey = typeof process !== "undefined" && process.env ? process.env.BASE_CHAIN_WALLET_KEY || process.env.BLOCKRUN_WALLET_KEY : void 0;
       const privateKey = options.privateKey || envKey;
       if (!privateKey) {
         throw new Error(
-          "Private key required. Pass privateKey in options or set BASE_CHAIN_WALLET_KEY environment variable."
+          "Private key required. Pass privateKey in options or set BASE_CHAIN_WALLET_KEY (or BLOCKRUN_WALLET_KEY) environment variable."
         );
       }
       validatePrivateKey(privateKey);
@@ -5475,7 +5475,7 @@ var LLMClient = class _LLMClient {
   }
   /**
    * Make a request with automatic x402 payment handling, returning raw JSON.
-   * Used for non-ChatResponse endpoints (X/Twitter, search, image edit, etc.).
+   * Used for non-ChatResponse endpoints (search, image edit, etc.).
    */
   async requestWithPaymentRaw(endpoint, body) {
     const url = `${this.apiUrl}${endpoint}`;
@@ -5883,7 +5883,8 @@ var LLMClient = class _LLMClient {
     return data;
   }
   /**
-   * Standalone search (web, X/Twitter, news).
+   * Standalone search over web and news. For X/Twitter, use chat on an
+   * `xai/*` model with an `x_search` tool.
    *
    * @param query - Search query
    * @param options - Optional search parameters
@@ -8377,6 +8378,7 @@ import { privateKeyToAccount as privateKeyToAccount11 } from "viem/accounts";
 var DEFAULT_API_URL11 = "https://blockrun.ai/api";
 var DEFAULT_TIMEOUT11 = 6e4;
 var SURF_PREFIX = "/v1/surf";
+var warnedRetired = false;
 var SurfClient = class {
   _account;
   get account() {
@@ -8394,6 +8396,12 @@ var SurfClient = class {
   apiUrl;
   timeout;
   constructor(options = {}) {
+    if (!warnedRetired) {
+      warnedRetired = true;
+      console.warn(
+        "[blockrun] SurfClient is deprecated: the gateway retired /v1/surf/* (410 endpoint_retired). Use PriceClient, LLMClient.defi*, LLMClient.pm() or LLMClient.dex* instead."
+      );
+    }
     this.apiAuth = resolveApiKeyAuth(options);
     if (!this.apiAuth) {
       const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/llm",
-  "version": "3.23.1",
+  "version": "3.23.2",
   "type": "module",
   "description": "TypeScript SDK for BlockRun - every frontier model behind one OpenAI-compatible client. Pay with a BlockRun API key or per-call in USDC. Smart routing picks the cheapest capable model. No rate limits.",
   "main": "dist/index.cjs",