@blockrun/llm 3.13.6 → 3.14.0

package/dist/index.js

@@ -1,6 +1,3 @@
-// src/client.ts
-import { privateKeyToAccount } from "viem/accounts";
-
 // src/types.ts
 var BlockrunError = class extends Error {
   constructor(message) {
@@ -22,6 +19,8 @@ var PaymentError = class extends BlockrunError {
 };
 var APIError = class extends BlockrunError {
   statusCode;
+  /** Retry-After header returned by the account API. */
+  retryAfter;
   response;
   constructor(message, statusCode, response) {
     super(message);
@@ -31,6 +30,248 @@ var APIError = class extends BlockrunError {
   }
 };
 
+// src/validation.ts
+var LOCALHOST_DOMAINS = ["localhost", "127.0.0.1"];
+var KNOWN_PROVIDERS = /* @__PURE__ */ new Set([
+  "openai",
+  "anthropic",
+  "google",
+  "deepseek",
+  "mistralai",
+  "meta-llama",
+  "together",
+  "xai",
+  "moonshot",
+  "nvidia",
+  "minimax",
+  "zai"
+]);
+function validateModel(model) {
+  if (!model || typeof model !== "string") {
+    throw new Error("Model must be a non-empty string");
+  }
+}
+function validateMaxTokens(maxTokens) {
+  if (maxTokens === void 0 || maxTokens === null) {
+    return;
+  }
+  if (typeof maxTokens !== "number" || !Number.isInteger(maxTokens)) {
+    throw new Error("maxTokens must be an integer");
+  }
+  if (maxTokens < 1) {
+    throw new Error("maxTokens must be positive (minimum: 1)");
+  }
+}
+function validateTemperature(temperature) {
+  if (temperature === void 0 || temperature === null) {
+    return;
+  }
+  if (typeof temperature !== "number") {
+    throw new Error("temperature must be a number");
+  }
+  if (temperature < 0 || temperature > 2) {
+    throw new Error("temperature must be between 0 and 2");
+  }
+}
+function validateTopP(topP) {
+  if (topP === void 0 || topP === null) {
+    return;
+  }
+  if (typeof topP !== "number") {
+    throw new Error("topP must be a number");
+  }
+  if (topP < 0 || topP > 1) {
+    throw new Error("topP must be between 0 and 1");
+  }
+}
+function validatePrivateKey(key) {
+  if (typeof key !== "string") {
+    throw new Error("Private key must be a string");
+  }
+  if (!key.startsWith("0x")) {
+    throw new Error("Private key must start with 0x");
+  }
+  if (key.length !== 66) {
+    throw new Error(
+      "Private key must be 66 characters (0x + 64 hexadecimal characters)"
+    );
+  }
+  if (!/^0x[0-9a-fA-F]{64}$/.test(key)) {
+    throw new Error(
+      "Private key must contain only hexadecimal characters (0-9, a-f, A-F)"
+    );
+  }
+}
+function validateApiUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error("Invalid API URL format");
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(
+      `Invalid protocol: ${parsed.protocol}. Use http:// or https://`
+    );
+  }
+  const isLocalhost = LOCALHOST_DOMAINS.includes(parsed.hostname);
+  if (parsed.protocol !== "https:" && !isLocalhost) {
+    throw new Error(
+      `API URL must use HTTPS for non-localhost endpoints. Use https:// instead of ${parsed.protocol}//`
+    );
+  }
+}
+function sanitizeErrorResponse(errorBody) {
+  if (typeof errorBody !== "object" || errorBody === null) {
+    return { message: "API request failed" };
+  }
+  const body = errorBody;
+  return {
+    message: typeof body.error === "string" ? body.error : "API request failed",
+    code: typeof body.code === "string" ? body.code : void 0
+  };
+}
+function validateResourceUrl(url, baseUrl) {
+  try {
+    const parsed = new URL(url);
+    const baseParsed = new URL(baseUrl);
+    if (parsed.hostname !== baseParsed.hostname) {
+      console.warn(
+        `Resource URL hostname mismatch: ${parsed.hostname} vs ${baseParsed.hostname}. Using safe default instead.`
+      );
+      return `${baseUrl}/v1/chat/completions`;
+    }
+    if (parsed.protocol !== baseParsed.protocol) {
+      console.warn(
+        `Resource URL protocol mismatch: ${parsed.protocol} vs ${baseParsed.protocol}. Using safe default instead.`
+      );
+      return `${baseUrl}/v1/chat/completions`;
+    }
+    return url;
+  } catch {
+    console.warn(`Invalid resource URL format: ${url}. Using safe default.`);
+    return `${baseUrl}/v1/chat/completions`;
+  }
+}
+
+// src/api-key.ts
+var TRANSIENT_STATUS = /* @__PURE__ */ new Set([502, 503, 504, 522, 524]);
+var TRANSIENT_RETRIES = 2;
+var TRANSIENT_BACKOFF_MS = 1e3;
+var API_KEY_URL = "https://api.blockrun.ai";
+var PORTAL_URL = "https://user.blockrun.ai";
+function resolveApiKeyAuth(options) {
+  if (options.apiKey !== void 0 && options.privateKey !== void 0) {
+    throw new Error("Pass either apiKey or privateKey, not both.");
+  }
+  const key = options.apiKey ?? (options.privateKey === void 0 && typeof process !== "undefined" ? process.env?.BLOCKRUN_API_KEY : void 0);
+  if (key === void 0) return void 0;
+  if (!/^brk_[A-Za-z0-9_-]+$/.test(key.trim())) {
+    throw new Error(`Invalid BlockRun API key. Create one at ${PORTAL_URL}/dashboard/keys.`);
+  }
+  const base = options.apiUrl ?? (typeof process !== "undefined" ? process.env?.BLOCKRUN_API_BASE_URL : void 0) ?? API_KEY_URL;
+  return new ApiKeyAuth(key.trim(), base);
+}
+function requireWallet(value) {
+  if (value === void 0) throw new Error("This operation requires a wallet; the client uses API key account billing.");
+  return value;
+}
+var ApiKeyAuth = class {
+  apiUrl;
+  #key;
+  constructor(key, base) {
+    validateApiUrl(base);
+    const url = new URL(base);
+    if (url.username || url.password || url.search || url.hash) {
+      throw new Error("API base URL must not contain credentials, a query, or a fragment.");
+    }
+    this.apiUrl = base.replace(/\/+$/, "").replace(/\/v1$/, "");
+    this.#key = key;
+  }
+  /** Resolve gateway poll paths without forwarding credentials to another origin. */
+  resolveUrl(path6) {
+    const url = new URL(path6, this.apiUrl + "/");
+    if (url.origin !== new URL(this.apiUrl).origin || url.username || url.password) {
+      throw new Error("Refusing to send a BlockRun API key to a different origin.");
+    }
+    if (new URL(this.apiUrl).pathname === "/" && url.pathname.startsWith("/api/v1/")) url.pathname = url.pathname.slice(4);
+    return url.href;
+  }
+  async fetch(input, init, raiseErrors = true) {
+    const request = input instanceof Request ? input : void 0;
+    const url = this.resolveUrl(request?.url ?? String(input));
+    const headers = new Headers(init?.headers ?? request?.headers);
+    for (const name of [...headers.keys()]) {
+      if (name.toLowerCase().includes("payment") || name.toLowerCase() === "x-api-key") headers.delete(name);
+    }
+    headers.set("authorization", `Bearer ${this.#key}`);
+    const method = (init?.method ?? request?.method ?? "GET").toUpperCase();
+    const retries = method === "GET" || method === "HEAD" ? TRANSIENT_RETRIES : 0;
+    let response;
+    for (let attempt = 0; ; attempt++) {
+      response = await globalThis.fetch(request ? new Request(url, request) : url, {
+        ...init,
+        headers,
+        redirect: "error"
+      });
+      if (attempt >= retries || !TRANSIENT_STATUS.has(response.status)) break;
+      await new Promise((resolve) => setTimeout(resolve, TRANSIENT_BACKOFF_MS * (attempt + 1)));
+    }
+    if (raiseErrors && !response.ok) {
+      let body;
+      try {
+        body = await response.json();
+      } catch {
+        body = void 0;
+      }
+      const outer = body && typeof body === "object" ? body : {};
+      const detail = outer.error && typeof outer.error === "object" ? outer.error : outer;
+      const safe = Object.fromEntries(["message", "code", "type", "param"].flatMap((name) => typeof detail[name] === "string" ? [[name, detail[name].split(this.#key).join("[REDACTED]")]] : []));
+      const hint = response.status === 402 ? ` Top up at ${PORTAL_URL}/dashboard/credits.` : response.status === 401 ? ` Check your key at ${PORTAL_URL}/dashboard/keys.` : "";
+      const error = new APIError(`BlockRun account API error: ${response.status}.${hint}`, response.status, safe);
+      error.retryAfter = response.headers.get("retry-after") ?? void 0;
+      throw error;
+    }
+    return response;
+  }
+  /** Poll an account-owned async job without ever entering the x402 signing path. */
+  async poll(response, timeout, interval) {
+    const deadline = Date.now() + timeout;
+    let data = await response.json();
+    if (["failed", "cancelled", "canceled"].includes(String(data.status))) {
+      throw new APIError("Account API job failed or was cancelled", 502);
+    }
+    const pollPath = data.poll_url;
+    if (typeof pollPath !== "string") {
+      if (response.status === 202 || ["queued", "in_progress", "processing"].includes(String(data.status))) {
+        throw new APIError("Async response missing poll_url", response.status);
+      }
+      return data;
+    }
+    const url = this.resolveUrl(pollPath);
+    while (Date.now() < deadline) {
+      if (data.status === "completed") return data;
+      if (["failed", "cancelled", "canceled"].includes(String(data.status))) {
+        throw new APIError("Account API job failed or was cancelled", 502, sanitizeErrorResponse(data));
+      }
+      await new Promise((resolve) => setTimeout(resolve, Math.min(interval, Math.max(0, deadline - Date.now()))));
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      try {
+        const res = await this.fetch(url, { signal: AbortSignal.timeout(remaining) });
+        data = await res.json();
+      } catch (err) {
+        if (!(err instanceof APIError) || !TRANSIENT_STATUS.has(err.statusCode)) throw err;
+      }
+    }
+    if (data.status === "completed") return data;
+    throw new APIError("Account API job polling timed out; check the job before submitting again.", 504, { poll_url: url });
+  }
+};
+
+// src/client.ts
+import { privateKeyToAccount } from "viem/accounts";
+
 // node_modules/.pnpm/@blockrun+router-core@https+++codeload.github.com+BlockRunAI+router-core+tar.gz+814fd3b6bc788_xq5fkcckbb2p7dtp6dodey4yri/node_modules/@blockrun/router-core/dist/index.js
 function scoreTokenCount(estimatedTokens, thresholds) {
   if (estimatedTokens < thresholds.simple) {
@@ -4161,9 +4402,11 @@ function parsePaymentRequired(headerValue) {
       if (error.message.includes("Invalid payment required structure")) {
         throw error;
       }
-      throw new Error("Failed to parse payment required header: invalid format");
+      throw new Error("Failed to parse payment required header: invalid format", {
+        cause: error
+      });
     }
-    throw new Error("Failed to parse payment required header");
+    throw new Error("Failed to parse payment required header", { cause: error });
   }
 }
 function extractPaymentDetails(paymentRequired, preferredNetwork) {
@@ -4194,130 +4437,6 @@ function extractPaymentDetails(paymentRequired, preferredNetwork) {
   };
 }
 
-// src/validation.ts
-var LOCALHOST_DOMAINS = ["localhost", "127.0.0.1"];
-var KNOWN_PROVIDERS = /* @__PURE__ */ new Set([
-  "openai",
-  "anthropic",
-  "google",
-  "deepseek",
-  "mistralai",
-  "meta-llama",
-  "together",
-  "xai",
-  "moonshot",
-  "nvidia",
-  "minimax",
-  "zai"
-]);
-function validateModel(model) {
-  if (!model || typeof model !== "string") {
-    throw new Error("Model must be a non-empty string");
-  }
-}
-function validateMaxTokens(maxTokens) {
-  if (maxTokens === void 0 || maxTokens === null) {
-    return;
-  }
-  if (typeof maxTokens !== "number" || !Number.isInteger(maxTokens)) {
-    throw new Error("maxTokens must be an integer");
-  }
-  if (maxTokens < 1) {
-    throw new Error("maxTokens must be positive (minimum: 1)");
-  }
-}
-function validateTemperature(temperature) {
-  if (temperature === void 0 || temperature === null) {
-    return;
-  }
-  if (typeof temperature !== "number") {
-    throw new Error("temperature must be a number");
-  }
-  if (temperature < 0 || temperature > 2) {
-    throw new Error("temperature must be between 0 and 2");
-  }
-}
-function validateTopP(topP) {
-  if (topP === void 0 || topP === null) {
-    return;
-  }
-  if (typeof topP !== "number") {
-    throw new Error("topP must be a number");
-  }
-  if (topP < 0 || topP > 1) {
-    throw new Error("topP must be between 0 and 1");
-  }
-}
-function validatePrivateKey(key) {
-  if (typeof key !== "string") {
-    throw new Error("Private key must be a string");
-  }
-  if (!key.startsWith("0x")) {
-    throw new Error("Private key must start with 0x");
-  }
-  if (key.length !== 66) {
-    throw new Error(
-      "Private key must be 66 characters (0x + 64 hexadecimal characters)"
-    );
-  }
-  if (!/^0x[0-9a-fA-F]{64}$/.test(key)) {
-    throw new Error(
-      "Private key must contain only hexadecimal characters (0-9, a-f, A-F)"
-    );
-  }
-}
-function validateApiUrl(url) {
-  let parsed;
-  try {
-    parsed = new URL(url);
-  } catch {
-    throw new Error("Invalid API URL format");
-  }
-  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-    throw new Error(
-      `Invalid protocol: ${parsed.protocol}. Use http:// or https://`
-    );
-  }
-  const isLocalhost = LOCALHOST_DOMAINS.includes(parsed.hostname);
-  if (parsed.protocol !== "https:" && !isLocalhost) {
-    throw new Error(
-      `API URL must use HTTPS for non-localhost endpoints. Use https:// instead of ${parsed.protocol}//`
-    );
-  }
-}
-function sanitizeErrorResponse(errorBody) {
-  if (typeof errorBody !== "object" || errorBody === null) {
-    return { message: "API request failed" };
-  }
-  const body = errorBody;
-  return {
-    message: typeof body.error === "string" ? body.error : "API request failed",
-    code: typeof body.code === "string" ? body.code : void 0
-  };
-}
-function validateResourceUrl(url, baseUrl) {
-  try {
-    const parsed = new URL(url);
-    const baseParsed = new URL(baseUrl);
-    if (parsed.hostname !== baseParsed.hostname) {
-      console.warn(
-        `Resource URL hostname mismatch: ${parsed.hostname} vs ${baseParsed.hostname}. Using safe default instead.`
-      );
-      return `${baseUrl}/v1/chat/completions`;
-    }
-    if (parsed.protocol !== baseParsed.protocol) {
-      console.warn(
-        `Resource URL protocol mismatch: ${parsed.protocol} vs ${baseParsed.protocol}. Using safe default instead.`
-      );
-      return `${baseUrl}/v1/chat/completions`;
-    }
-    return url;
-  } catch {
-    console.warn(`Invalid resource URL format: ${url}. Using safe default.`);
-    return `${baseUrl}/v1/chat/completions`;
-  }
-}
-
 // src/cost-log.ts
 import * as fs from "fs";
 import * as path from "path";
@@ -4364,7 +4483,7 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.13.6";
+var SDK_VERSION = "3.14.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
@@ -4412,8 +4531,19 @@ function resolveDefaultTimeout() {
 var DEFAULT_TIMEOUT = resolveDefaultTimeout();
 var LLMClient = class _LLMClient {
   static DEFAULT_API_URL = DEFAULT_API_URL;
-  account;
-  privateKey;
+  _account;
+  get account() {
+    return requireWallet(this._account);
+  }
+  apiAuth;
+  /** Active billing mode. */
+  get authMode() {
+    return this.apiAuth ? "api-key" : "wallet";
+  }
+  _privateKey;
+  get privateKey() {
+    return requireWallet(this._privateKey);
+  }
   apiUrl;
   timeout;
   sessionTotalUsd = 0;
@@ -4431,17 +4561,20 @@ var LLMClient = class _LLMClient {
    * @param options - Client configuration options (optional if BASE_CHAIN_WALLET_KEY env var is set)
    */
   constructor(options = {}) {
-    const envKey = typeof process !== "undefined" && process.env ? process.env.BASE_CHAIN_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."
-      );
+    this.apiAuth = resolveApiKeyAuth(options);
+    if (!this.apiAuth) {
+      const envKey = typeof process !== "undefined" && process.env ? process.env.BASE_CHAIN_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."
+        );
+      }
+      validatePrivateKey(privateKey);
+      this._privateKey = privateKey;
+      this._account = privateKeyToAccount(privateKey);
     }
-    validatePrivateKey(privateKey);
-    this.privateKey = privateKey;
-    this.account = privateKeyToAccount(privateKey);
-    const apiUrl = options.apiUrl || DEFAULT_API_URL;
+    const apiUrl = this.apiAuth?.apiUrl || options.apiUrl || DEFAULT_API_URL;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
     this.timeout = options.timeout || DEFAULT_TIMEOUT;
@@ -4482,7 +4615,7 @@ var LLMClient = class _LLMClient {
       systemPrompt,
       maxOutputTokens,
       await this.getModelPricing(),
-      { ...options, minimumPaymentUsd: BASE_MINIMUM_PAYMENT_USD }
+      { ...options, minimumPaymentUsd: this.apiAuth ? 0 : BASE_MINIMUM_PAYMENT_USD }
     );
   }
   /**
@@ -5068,6 +5201,7 @@ var LLMClient = class _LLMClient {
         sanitizeErrorResponse(errorBody)
       );
     }
+    if (this.apiAuth && endpoint.startsWith("/v1/images/")) return this.apiAuth.poll(response, this.timeout, 2e3);
     return response.json();
   }
   /**
@@ -5320,7 +5454,7 @@ var LLMClient = class _LLMClient {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(url, {
+      const response = await (this.apiAuth ? this.apiAuth.fetch.bind(this.apiAuth) : fetch)(url, {
         ...options,
         signal: controller.signal
       });
@@ -5821,6 +5955,7 @@ var LLMClient = class _LLMClient {
    * console.log(`Spent $${spending.totalUsd.toFixed(4)} across ${spending.calls} calls`);
    */
   getSpending() {
+    if (this.apiAuth) throw new Error("Account usage is available at https://user.blockrun.ai/dashboard; getSpending() tracks x402 settlements only.");
     return {
       totalUsd: this.sessionTotalUsd,
       calls: this.sessionCalls
@@ -5844,8 +5979,19 @@ var DEFAULT_TIMEOUT2 = 2e5;
 var POLL_INTERVAL_MS = 3e3;
 var POLL_MAX_DURATION_MS = 3e5;
 var ImageClient = class {
-  account;
-  privateKey;
+  _account;
+  get account() {
+    return requireWallet(this._account);
+  }
+  apiAuth;
+  /** Active billing mode. */
+  get authMode() {
+    return this.apiAuth ? "api-key" : "wallet";
+  }
+  _privateKey;
+  get privateKey() {
+    return requireWallet(this._privateKey);
+  }
   apiUrl;
   timeout;
   sessionTotalUsd = 0;
@@ -5856,17 +6002,20 @@ var ImageClient = class {
    * @param options - Client configuration options
    */
   constructor(options = {}) {
-    const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
-    const privateKey = options.privateKey || envKey;
-    if (!privateKey) {
-      throw new Error(
-        "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
-      );
+    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;
+      const privateKey = options.privateKey || envKey;
+      if (!privateKey) {
+        throw new Error(
+          "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
+        );
+      }
+      validatePrivateKey(privateKey);
+      this._privateKey = privateKey;
+      this._account = privateKeyToAccount2(privateKey);
     }
-    validatePrivateKey(privateKey);
-    this.privateKey = privateKey;
-    this.account = privateKeyToAccount2(privateKey);
-    const apiUrl = options.apiUrl || DEFAULT_API_URL2;
+    const apiUrl = this.apiAuth?.apiUrl || options.apiUrl || DEFAULT_API_URL2;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
     this.timeout = options.timeout || DEFAULT_TIMEOUT2;
@@ -5993,6 +6142,7 @@ var ImageClient = class {
         sanitizeErrorResponse(errorBody)
       );
     }
+    if (this.apiAuth) return this.apiAuth.poll(response, POLL_MAX_DURATION_MS, POLL_INTERVAL_MS);
     return response.json();
   }
   /**
@@ -6130,7 +6280,7 @@ var ImageClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(url, {
+      const response = await (this.apiAuth ? this.apiAuth.fetch.bind(this.apiAuth) : fetch)(url, {
         ...options,
         signal: controller.signal
       });
@@ -6149,6 +6299,7 @@ var ImageClient = class {
    * Get session spending information.
    */
   getSpending() {
+    if (this.apiAuth) throw new Error("Account usage is available at https://user.blockrun.ai/dashboard; getSpending() tracks x402 settlements only.");
     return {
       totalUsd: this.sessionTotalUsd,
       calls: this.sessionCalls
@@ -6162,24 +6313,38 @@ var DEFAULT_API_URL3 = "https://blockrun.ai/api";
 var DEFAULT_MODEL2 = "minimax/music-2.5+";
 var DEFAULT_TIMEOUT3 = 21e4;
 var MusicClient = class {
-  account;
-  privateKey;
+  _account;
+  get account() {
+    return requireWallet(this._account);
+  }
+  apiAuth;
+  /** Active billing mode. */
+  get authMode() {
+    return this.apiAuth ? "api-key" : "wallet";
+  }
+  _privateKey;
+  get privateKey() {
+    return requireWallet(this._privateKey);
+  }
   apiUrl;
   timeout;
   sessionTotalUsd = 0;
   sessionCalls = 0;
   constructor(options = {}) {
-    const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
-    const privateKey = options.privateKey || envKey;
-    if (!privateKey) {
-      throw new Error(
-        "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
-      );
+    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;
+      const privateKey = options.privateKey || envKey;
+      if (!privateKey) {
+        throw new Error(
+          "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
+        );
+      }
+      validatePrivateKey(privateKey);
+      this._privateKey = privateKey;
+      this._account = privateKeyToAccount3(privateKey);
     }
-    validatePrivateKey(privateKey);
-    this.privateKey = privateKey;
-    this.account = privateKeyToAccount3(privateKey);
-    const apiUrl = options.apiUrl || DEFAULT_API_URL3;
+    const apiUrl = this.apiAuth?.apiUrl || options.apiUrl || DEFAULT_API_URL3;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
     this.timeout = options.timeout || DEFAULT_TIMEOUT3;
@@ -6236,6 +6401,7 @@ var MusicClient = class {
       }
       throw new APIError(`API error: ${response.status}`, response.status, sanitizeErrorResponse(errorBody));
     }
+    if (this.apiAuth) return this.apiAuth.poll(response, this.timeout, 5e3);
     return response.json();
   }
   async handlePaymentAndRetry(url, body, response) {
@@ -6298,7 +6464,7 @@ var MusicClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      return await fetch(url, { ...options, signal: controller.signal });
+      return await (this.apiAuth ? this.apiAuth.fetch.bind(this.apiAuth) : fetch)(url, { ...options, signal: controller.signal });
     } finally {
       clearTimeout(timeoutId);
     }
@@ -6307,6 +6473,7 @@ var MusicClient = class {
     return this.account.address;
   }
   getSpending() {
+    if (this.apiAuth) throw new Error("Account usage is available at https://user.blockrun.ai/dashboard; getSpending() tracks x402 settlements only.");
     return { totalUsd: this.sessionTotalUsd, calls: this.sessionCalls };
   }
 };
@@ -6318,24 +6485,38 @@ var DEFAULT_MODEL3 = "elevenlabs/flash-v2.5";
 var DEFAULT_SOUNDFX_MODEL = "elevenlabs/sound-effects";
 var DEFAULT_TIMEOUT4 = 12e4;
 var SpeechClient = class {
-  account;
-  privateKey;
+  _account;
+  get account() {
+    return requireWallet(this._account);
+  }
+  apiAuth;
+  /** Active billing mode. */
+  get authMode() {
+    return this.apiAuth ? "api-key" : "wallet";
+  }
+  _privateKey;
+  get privateKey() {
+    return requireWallet(this._privateKey);
+  }
   apiUrl;
   timeout;
   sessionTotalUsd = 0;
   sessionCalls = 0;
   constructor(options = {}) {
-    const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
-    const privateKey = options.privateKey || envKey;
-    if (!privateKey) {
-      throw new Error(
-        "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
-      );
+    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;
+      const privateKey = options.privateKey || envKey;
+      if (!privateKey) {
+        throw new Error(
+          "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
+        );
+      }
+      validatePrivateKey(privateKey);
+      this._privateKey = privateKey;
+      this._account = privateKeyToAccount4(privateKey);
     }
-    validatePrivateKey(privateKey);
-    this.privateKey = privateKey;
-    this.account = privateKeyToAccount4(privateKey);
-    const apiUrl = options.apiUrl || DEFAULT_API_URL4;
+    const apiUrl = this.apiAuth?.apiUrl || options.apiUrl || DEFAULT_API_URL4;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
     this.timeout = options.timeout || DEFAULT_TIMEOUT4;
@@ -6497,7 +6678,7 @@ var SpeechClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      return await fetch(url, { ...options, signal: controller.signal });
+      return await (this.apiAuth ? this.apiAuth.fetch.bind(this.apiAuth) : fetch)(url, { ...options, signal: controller.signal });
     } finally {
       clearTimeout(timeoutId);
     }
@@ -6506,6 +6687,7 @@ var SpeechClient = class {
     return this.account.address;
   }
   getSpending() {
+    if (this.apiAuth) throw new Error("Account usage is available at https://user.blockrun.ai/dashboard; getSpending() tracks x402 settlements only.");
     return { totalUsd: this.sessionTotalUsd, calls: this.sessionCalls };
   }
 };
@@ -6520,24 +6702,38 @@ var DEFAULT_GENERATE_BUDGET_MS = 9e5;
 var MAX_TIMEOUT_SECONDS = 600;
 var MAX_POLL_RESIGNS = 2;
 var VideoClient = class {
-  account;
-  privateKey;
+  _account;
+  get account() {
+    return requireWallet(this._account);
+  }
+  apiAuth;
+  /** Active billing mode. */
+  get authMode() {
+    return this.apiAuth ? "api-key" : "wallet";
+  }
+  _privateKey;
+  get privateKey() {
+    return requireWallet(this._privateKey);
+  }
   apiUrl;
   timeout;
   sessionTotalUsd = 0;
   sessionCalls = 0;
   constructor(options = {}) {
-    const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
-    const privateKey = options.privateKey || envKey;
-    if (!privateKey) {
-      throw new Error(
-        "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
-      );
+    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;
+      const privateKey = options.privateKey || envKey;
+      if (!privateKey) {
+        throw new Error(
+          "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
+        );
+      }
+      validatePrivateKey(privateKey);
+      this._privateKey = privateKey;
+      this._account = privateKeyToAccount5(privateKey);
     }
-    validatePrivateKey(privateKey);
-    this.privateKey = privateKey;
-    this.account = privateKeyToAccount5(privateKey);
-    const apiUrl = options.apiUrl || DEFAULT_API_URL5;
+    const apiUrl = this.apiAuth?.apiUrl || options.apiUrl || DEFAULT_API_URL5;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
     this.timeout = options.timeout || DEFAULT_TIMEOUT5;
@@ -6663,6 +6859,7 @@ var VideoClient = class {
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(body)
     });
+    if (this.apiAuth) return this.apiAuth.poll(resp402, budgetMs, POLL_INTERVAL_MS2);
     if (resp402.status !== 402) {
       await this.throwApiError(resp402, "Expected 402 on first POST");
     }
@@ -6810,7 +7007,7 @@ var VideoClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      return await fetch(url, { ...options, signal: controller.signal });
+      return await (this.apiAuth ? this.apiAuth.fetch.bind(this.apiAuth) : fetch)(url, { ...options, signal: controller.signal });
     } finally {
       clearTimeout(timeoutId);
     }
@@ -6819,6 +7016,7 @@ var VideoClient = class {
     return this.account.address;
   }
   getSpending() {
+    if (this.apiAuth) throw new Error("Account usage is available at https://user.blockrun.ai/dashboard; getSpending() tracks x402 settlements only.");
     return { totalUsd: this.sessionTotalUsd, calls: this.sessionCalls };
   }
 };
@@ -6830,24 +7028,38 @@ var DEFAULT_TIMEOUT6 = 6e4;
 var CALL_PRICE_USD = 0.54;
 var VALID_MODELS = /* @__PURE__ */ new Set(["base", "enhanced", "turbo"]);
 var VoiceClient = class {
-  account;
-  privateKey;
+  _account;
+  get account() {
+    return requireWallet(this._account);
+  }
+  apiAuth;
+  /** Active billing mode. */
+  get authMode() {
+    return this.apiAuth ? "api-key" : "wallet";
+  }
+  _privateKey;
+  get privateKey() {
+    return requireWallet(this._privateKey);
+  }
   apiUrl;
   timeout;
   sessionTotalUsd = 0;
   sessionCalls = 0;
   constructor(options = {}) {
-    const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
-    const privateKey = options.privateKey || envKey;
-    if (!privateKey) {
-      throw new Error(
-        "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
-      );
+    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;
+      const privateKey = options.privateKey || envKey;
+      if (!privateKey) {
+        throw new Error(
+          "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
+        );
+      }
+      validatePrivateKey(privateKey);
+      this._privateKey = privateKey;
+      this._account = privateKeyToAccount6(privateKey);
     }
-    validatePrivateKey(privateKey);
-    this.privateKey = privateKey;
-    this.account = privateKeyToAccount6(privateKey);
-    const apiUrl = options.apiUrl || DEFAULT_API_URL6;
+    const apiUrl = this.apiAuth?.apiUrl || options.apiUrl || DEFAULT_API_URL6;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
     this.timeout = options.timeout || DEFAULT_TIMEOUT6;
@@ -7011,7 +7223,7 @@ var VoiceClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      return await fetch(url, { ...options, signal: controller.signal });
+      return await (this.apiAuth ? this.apiAuth.fetch.bind(this.apiAuth) : fetch)(url, { ...options, signal: controller.signal });
     } finally {
       clearTimeout(timeoutId);
     }
@@ -7020,6 +7232,7 @@ var VoiceClient = class {
     return this.account.address;
   }
   getSpending() {
+    if (this.apiAuth) throw new Error("Account usage is available at https://user.blockrun.ai/dashboard; getSpending() tracks x402 settlements only.");
     return { totalUsd: this.sessionTotalUsd, calls: this.sessionCalls };
   }
 };
@@ -7049,24 +7262,38 @@ function requireE164(value) {
   return v;
 }
 var PhoneClient = class {
-  account;
-  privateKey;
+  _account;
+  get account() {
+    return requireWallet(this._account);
+  }
+  apiAuth;
+  /** Active billing mode. */
+  get authMode() {
+    return this.apiAuth ? "api-key" : "wallet";
+  }
+  _privateKey;
+  get privateKey() {
+    return requireWallet(this._privateKey);
+  }
   apiUrl;
   timeout;
   sessionTotalUsd = 0;
   sessionCalls = 0;
   constructor(options = {}) {
-    const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
-    const privateKey = options.privateKey || envKey;
-    if (!privateKey) {
-      throw new Error(
-        "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
-      );
+    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;
+      const privateKey = options.privateKey || envKey;
+      if (!privateKey) {
+        throw new Error(
+          "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
+        );
+      }
+      validatePrivateKey(privateKey);
+      this._privateKey = privateKey;
+      this._account = privateKeyToAccount7(privateKey);
     }
-    validatePrivateKey(privateKey);
-    this.privateKey = privateKey;
-    this.account = privateKeyToAccount7(privateKey);
-    const apiUrl = options.apiUrl || DEFAULT_API_URL7;
+    const apiUrl = this.apiAuth?.apiUrl || options.apiUrl || DEFAULT_API_URL7;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
     this.timeout = options.timeout || DEFAULT_TIMEOUT7;
@@ -7077,6 +7304,7 @@ var PhoneClient = class {
   }
   /** Session-cumulative USD spend + call count across this client instance. */
   getSpending() {
+    if (this.apiAuth) throw new Error("Account usage is available at https://user.blockrun.ai/dashboard; getSpending() tracks x402 settlements only.");
     return { totalUsd: this.sessionTotalUsd, calls: this.sessionCalls };
   }
   // ─── Lookup ────────────────────────────────────────────────────────────
@@ -7236,7 +7464,7 @@ var PhoneClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      return await fetch(url, { ...init, signal: controller.signal });
+      return await (this.apiAuth ? this.apiAuth.fetch.bind(this.apiAuth) : fetch)(url, { ...init, signal: controller.signal });
     } finally {
       clearTimeout(timeoutId);
     }
@@ -7249,24 +7477,38 @@ var DEFAULT_API_URL8 = "https://blockrun.ai/api";
 var DEFAULT_TIMEOUT8 = 6e4;
 var PORTRAIT_ENROLLMENT_PRICE_USD = 0.01;
 var PortraitClient = class {
-  account;
-  privateKey;
+  _account;
+  get account() {
+    return requireWallet(this._account);
+  }
+  apiAuth;
+  /** Active billing mode. */
+  get authMode() {
+    return this.apiAuth ? "api-key" : "wallet";
+  }
+  _privateKey;
+  get privateKey() {
+    return requireWallet(this._privateKey);
+  }
   apiUrl;
   timeout;
   sessionTotalUsd = 0;
   sessionCalls = 0;
   constructor(options = {}) {
-    const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
-    const privateKey = options.privateKey || envKey;
-    if (!privateKey) {
-      throw new Error(
-        "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
-      );
+    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;
+      const privateKey = options.privateKey || envKey;
+      if (!privateKey) {
+        throw new Error(
+          "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
+        );
+      }
+      validatePrivateKey(privateKey);
+      this._privateKey = privateKey;
+      this._account = privateKeyToAccount8(privateKey);
     }
-    validatePrivateKey(privateKey);
-    this.privateKey = privateKey;
-    this.account = privateKeyToAccount8(privateKey);
-    const apiUrl = options.apiUrl || DEFAULT_API_URL8;
+    const apiUrl = this.apiAuth?.apiUrl || options.apiUrl || DEFAULT_API_URL8;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
     this.timeout = options.timeout || DEFAULT_TIMEOUT8;
@@ -7277,6 +7519,7 @@ var PortraitClient = class {
   }
   /** Session-cumulative USD spend + call count across this client instance. */
   getSpending() {
+    if (this.apiAuth) throw new Error("Account usage is available at https://user.blockrun.ai/dashboard; getSpending() tracks x402 settlements only.");
     return { totalUsd: this.sessionTotalUsd, calls: this.sessionCalls };
   }
   /**
@@ -7390,7 +7633,7 @@ var PortraitClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      return await fetch(url, { ...init, signal: controller.signal });
+      return await (this.apiAuth ? this.apiAuth.fetch.bind(this.apiAuth) : fetch)(url, { ...init, signal: controller.signal });
     } finally {
       clearTimeout(timeoutId);
     }
@@ -7402,22 +7645,36 @@ import { privateKeyToAccount as privateKeyToAccount9 } from "viem/accounts";
 var DEFAULT_API_URL9 = "https://blockrun.ai/api";
 var DEFAULT_TIMEOUT9 = 6e4;
 var SearchClient = class {
-  account;
-  privateKey;
+  _account;
+  get account() {
+    return requireWallet(this._account);
+  }
+  apiAuth;
+  /** Active billing mode. */
+  get authMode() {
+    return this.apiAuth ? "api-key" : "wallet";
+  }
+  _privateKey;
+  get privateKey() {
+    return requireWallet(this._privateKey);
+  }
   apiUrl;
   timeout;
   constructor(options = {}) {
-    const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
-    const privateKey = options.privateKey || envKey;
-    if (!privateKey) {
-      throw new Error(
-        "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
-      );
+    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;
+      const privateKey = options.privateKey || envKey;
+      if (!privateKey) {
+        throw new Error(
+          "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
+        );
+      }
+      validatePrivateKey(privateKey);
+      this._privateKey = privateKey;
+      this._account = privateKeyToAccount9(privateKey);
     }
-    validatePrivateKey(privateKey);
-    this.privateKey = privateKey;
-    this.account = privateKeyToAccount9(privateKey);
-    const apiUrl = options.apiUrl || DEFAULT_API_URL9;
+    const apiUrl = this.apiAuth?.apiUrl || options.apiUrl || DEFAULT_API_URL9;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
     this.timeout = options.timeout || DEFAULT_TIMEOUT9;
@@ -7523,7 +7780,7 @@ var SearchClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      return await fetch(url, { ...init, signal: controller.signal });
+      return await (this.apiAuth ? this.apiAuth.fetch.bind(this.apiAuth) : fetch)(url, { ...init, signal: controller.signal });
     } finally {
       clearTimeout(timeoutId);
     }
@@ -7538,15 +7795,20 @@ import { privateKeyToAccount as privateKeyToAccount10 } from "viem/accounts";
 var DEFAULT_API_URL10 = "https://blockrun.ai/api";
 var DEFAULT_TIMEOUT10 = 3e4;
 var PriceClient = class {
+  apiAuth;
+  get authMode() {
+    return this.apiAuth ? "api-key" : "wallet";
+  }
   account = null;
   privateKey = null;
   apiUrl;
   timeout;
   constructor(options = {}) {
+    this.apiAuth = resolveApiKeyAuth(options);
     const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
-    const privateKey = options.privateKey || envKey;
-    const requireWallet = options.requireWallet ?? true;
-    if (!privateKey && requireWallet) {
+    const privateKey = this.apiAuth ? void 0 : options.privateKey || envKey;
+    const requireWallet2 = options.requireWallet ?? true;
+    if (!this.apiAuth && !privateKey && requireWallet2) {
       throw new Error(
         "Private key required for paid endpoints. Pass privateKey in options, set BLOCKRUN_WALLET_KEY, or pass requireWallet: false for free-only usage."
       );
@@ -7556,7 +7818,7 @@ var PriceClient = class {
       this.privateKey = privateKey;
       this.account = privateKeyToAccount10(privateKey);
     }
-    const apiUrl = options.apiUrl || DEFAULT_API_URL10;
+    const apiUrl = this.apiAuth?.apiUrl || options.apiUrl || DEFAULT_API_URL10;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
     this.timeout = options.timeout || DEFAULT_TIMEOUT10;
@@ -7709,7 +7971,7 @@ var PriceClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      return await fetch(url, { ...init, signal: controller.signal });
+      return await (this.apiAuth ? this.apiAuth.fetch.bind(this.apiAuth) : fetch)(url, { ...init, signal: controller.signal });
     } finally {
       clearTimeout(timeoutId);
     }
@@ -7743,22 +8005,36 @@ var DEFAULT_API_URL11 = "https://blockrun.ai/api";
 var DEFAULT_TIMEOUT11 = 6e4;
 var SURF_PREFIX = "/v1/surf";
 var SurfClient = class {
-  account;
-  privateKey;
+  _account;
+  get account() {
+    return requireWallet(this._account);
+  }
+  apiAuth;
+  /** Active billing mode. */
+  get authMode() {
+    return this.apiAuth ? "api-key" : "wallet";
+  }
+  _privateKey;
+  get privateKey() {
+    return requireWallet(this._privateKey);
+  }
   apiUrl;
   timeout;
   constructor(options = {}) {
-    const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
-    const privateKey = options.privateKey || envKey;
-    if (!privateKey) {
-      throw new Error(
-        "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
-      );
+    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;
+      const privateKey = options.privateKey || envKey;
+      if (!privateKey) {
+        throw new Error(
+          "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
+        );
+      }
+      validatePrivateKey(privateKey);
+      this._privateKey = privateKey;
+      this._account = privateKeyToAccount11(privateKey);
     }
-    validatePrivateKey(privateKey);
-    this.privateKey = privateKey;
-    this.account = privateKeyToAccount11(privateKey);
-    const apiUrl = options.apiUrl || DEFAULT_API_URL11;
+    const apiUrl = this.apiAuth?.apiUrl || options.apiUrl || DEFAULT_API_URL11;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
     this.timeout = options.timeout || DEFAULT_TIMEOUT11;
@@ -7882,7 +8158,7 @@ var SurfClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      return await fetch(url, { ...init, signal: controller.signal });
+      return await (this.apiAuth ? this.apiAuth.fetch.bind(this.apiAuth) : fetch)(url, { ...init, signal: controller.signal });
     } finally {
       clearTimeout(timeoutId);
     }
@@ -7971,24 +8247,38 @@ var NETWORK_ALIASES = {
   zec: "zcash"
 };
 var RpcClient = class {
-  account;
-  privateKey;
+  _account;
+  get account() {
+    return requireWallet(this._account);
+  }
+  apiAuth;
+  /** Active billing mode. */
+  get authMode() {
+    return this.apiAuth ? "api-key" : "wallet";
+  }
+  _privateKey;
+  get privateKey() {
+    return requireWallet(this._privateKey);
+  }
   apiUrl;
   timeout;
   sessionTotalUsd = 0;
   sessionCalls = 0;
   constructor(options = {}) {
-    const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
-    const privateKey = options.privateKey || envKey;
-    if (!privateKey) {
-      throw new Error(
-        "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
-      );
+    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;
+      const privateKey = options.privateKey || envKey;
+      if (!privateKey) {
+        throw new Error(
+          "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
+        );
+      }
+      validatePrivateKey(privateKey);
+      this._privateKey = privateKey;
+      this._account = privateKeyToAccount12(privateKey);
     }
-    validatePrivateKey(privateKey);
-    this.privateKey = privateKey;
-    this.account = privateKeyToAccount12(privateKey);
-    const apiUrl = options.apiUrl || DEFAULT_API_URL12;
+    const apiUrl = this.apiAuth?.apiUrl || options.apiUrl || DEFAULT_API_URL12;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
     this.timeout = options.timeout || DEFAULT_TIMEOUT12;
@@ -8132,7 +8422,7 @@ var RpcClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      return await fetch(url, { ...options, signal: controller.signal });
+      return await (this.apiAuth ? this.apiAuth.fetch.bind(this.apiAuth) : fetch)(url, { ...options, signal: controller.signal });
     } finally {
       clearTimeout(timeoutId);
     }
@@ -8141,6 +8431,7 @@ var RpcClient = class {
     return this.account.address;
   }
   getSpending() {
+    if (this.apiAuth) throw new Error("Account usage is available at https://user.blockrun.ai/dashboard; getSpending() tracks x402 settlements only.");
     return { totalUsd: this.sessionTotalUsd, calls: this.sessionCalls };
   }
 };
@@ -8153,24 +8444,38 @@ var DEFAULT_POLL_INTERVAL_MS = 5e3;
 var DEFAULT_POLL_BUDGET_MS = 3e5;
 var MAX_SIGNED_AUTH_SECONDS = 600;
 var BlockrunClient = class {
-  account;
-  privateKey;
+  _account;
+  get account() {
+    return requireWallet(this._account);
+  }
+  apiAuth;
+  /** Active billing mode. */
+  get authMode() {
+    return this.apiAuth ? "api-key" : "wallet";
+  }
+  _privateKey;
+  get privateKey() {
+    return requireWallet(this._privateKey);
+  }
   apiUrl;
   timeout;
   sessionTotalUsd = 0;
   sessionCalls = 0;
   constructor(options = {}) {
-    const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
-    const privateKey = options.privateKey || envKey;
-    if (!privateKey) {
-      throw new Error(
-        "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
-      );
+    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;
+      const privateKey = options.privateKey || envKey;
+      if (!privateKey) {
+        throw new Error(
+          "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
+        );
+      }
+      validatePrivateKey(privateKey);
+      this._privateKey = privateKey;
+      this._account = privateKeyToAccount13(privateKey);
     }
-    validatePrivateKey(privateKey);
-    this.privateKey = privateKey;
-    this.account = privateKeyToAccount13(privateKey);
-    const apiUrl = options.apiUrl || DEFAULT_API_URL13;
+    const apiUrl = this.apiAuth?.apiUrl || options.apiUrl || DEFAULT_API_URL13;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
     this.timeout = options.timeout || DEFAULT_TIMEOUT13;
@@ -8212,6 +8517,7 @@ var BlockrunClient = class {
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(body ?? {})
     });
+    if (this.apiAuth) return this.apiAuth.poll(resp402, budgetMs, intervalMs);
     if (resp402.status === 200) {
       return resp402.json();
     }
@@ -8504,7 +8810,7 @@ var BlockrunClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      return await fetch(url, { ...init, signal: controller.signal });
+      return await (this.apiAuth ? this.apiAuth.fetch.bind(this.apiAuth) : fetch)(url, { ...init, signal: controller.signal });
     } finally {
       clearTimeout(timeoutId);
     }
@@ -8516,6 +8822,7 @@ var BlockrunClient = class {
     return this.account.address;
   }
   getSpending() {
+    if (this.apiAuth) throw new Error("Account usage is available at https://user.blockrun.ai/dashboard; getSpending() tracks x402 settlements only.");
     return { totalUsd: this.sessionTotalUsd, calls: this.sessionCalls };
   }
 };
@@ -8526,7 +8833,7 @@ function sleep(ms) {
 // src/wallet.ts
 import { privateKeyToAccount as privateKeyToAccount15, generatePrivateKey as generatePrivateKey2 } from "viem/accounts";
 
-// node_modules/.pnpm/@blockrun+core@0.1.1_bufferutil@4.1.0_typescript@5.9.3_utf-8-validate@6.0.6_zod@3.25.76/node_modules/@blockrun/core/dist/config.js
+// node_modules/.pnpm/@blockrun+core@0.1.1_bufferutil@4.1.0_typescript@6.0.3_utf-8-validate@6.0.6_zod@3.25.76/node_modules/@blockrun/core/dist/config.js
 import * as fs2 from "fs";
 import * as os2 from "os";
 import * as path2 from "path";
@@ -8548,7 +8855,7 @@ function paths() {
   };
 }
 
-// node_modules/.pnpm/@blockrun+core@0.1.1_bufferutil@4.1.0_typescript@5.9.3_utf-8-validate@6.0.6_zod@3.25.76/node_modules/@blockrun/core/dist/wallet.js
+// node_modules/.pnpm/@blockrun+core@0.1.1_bufferutil@4.1.0_typescript@6.0.3_utf-8-validate@6.0.6_zod@3.25.76/node_modules/@blockrun/core/dist/wallet.js
 import * as fs3 from "fs";
 import * as path3 from "path";
 import { privateKeyToAccount as privateKeyToAccount14, generatePrivateKey } from "viem/accounts";
@@ -8844,7 +9151,8 @@ async function solanaKeyToBytes(privateKey) {
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     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.`
+      `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.`,
+      { cause: err }
     );
   }
 }
@@ -8990,7 +9298,7 @@ async function solanaPublicKeyFrom(privateKey, source) {
     return await solanaPublicKey(privateKey);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    throw new Error(`${msg} (key loaded from ${source})`);
+    throw new Error(`${msg} (key loaded from ${source})`, { cause: err });
   }
 }
 async function getOrCreateSolanaWallet() {
@@ -9104,7 +9412,14 @@ function resolveRpcConfig(rpcUrl, rpcHeaders) {
 }
 var SolanaLLMClient = class {
   static SOLANA_API_URL = SOLANA_API_URL;
-  privateKey;
+  apiAuth;
+  get authMode() {
+    return this.apiAuth ? "api-key" : "wallet";
+  }
+  _privateKey;
+  get privateKey() {
+    return requireWallet(this._privateKey);
+  }
   apiUrl;
   rpcUrl;
   rpcHeaders;
@@ -9115,15 +9430,18 @@ var SolanaLLMClient = class {
   modelPricingCache = null;
   modelPricingPromise = null;
   constructor(options = {}) {
-    const envKey = typeof process !== "undefined" && process.env ? process.env.SOLANA_WALLET_KEY : void 0;
-    const privateKey = options.privateKey || envKey;
-    if (!privateKey) {
-      throw new Error(
-        "Private key required. Pass privateKey in options or set SOLANA_WALLET_KEY environment variable."
-      );
+    this.apiAuth = resolveApiKeyAuth(options);
+    if (!this.apiAuth) {
+      const envKey = typeof process !== "undefined" && process.env ? process.env.SOLANA_WALLET_KEY : void 0;
+      const privateKey = options.privateKey || envKey;
+      if (!privateKey) {
+        throw new Error(
+          "Private key required. Pass privateKey in options or set SOLANA_WALLET_KEY environment variable."
+        );
+      }
+      this._privateKey = privateKey;
     }
-    this.privateKey = privateKey;
-    const apiUrl = options.apiUrl || SOLANA_API_URL;
+    const apiUrl = this.apiAuth?.apiUrl || options.apiUrl || SOLANA_API_URL;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
     const rpc = resolveRpcConfig(options.rpcUrl, options.rpcHeaders);
@@ -9236,7 +9554,7 @@ var SolanaLLMClient = class {
       {
         routingProfile: options?.routingProfile,
         requiresStructuredOutput: options?.responseFormat !== void 0,
-        minimumPaymentUsd: SOLANA_MINIMUM_PAYMENT_USD
+        minimumPaymentUsd: this.apiAuth ? 0 : SOLANA_MINIMUM_PAYMENT_USD
       }
     );
   }
@@ -9265,7 +9583,7 @@ var SolanaLLMClient = class {
         toolChoice: options.toolChoice,
         conversationChars,
         hasVision,
-        minimumPaymentUsd: SOLANA_MINIMUM_PAYMENT_USD
+        minimumPaymentUsd: this.apiAuth ? 0 : SOLANA_MINIMUM_PAYMENT_USD
       }
     );
     const response = await this.chatCompletion(decision.model, messages, {
@@ -9518,6 +9836,7 @@ var SolanaLLMClient = class {
   }
   /** Get session spending. */
   getSpending() {
+    if (this.apiAuth) throw new Error("Account usage is available at https://user.blockrun.ai/dashboard; getSpending() tracks x402 settlements only.");
     return { totalUsd: this.sessionTotalUsd, calls: this.sessionCalls };
   }
   /** True if using sol.blockrun.ai. */
@@ -9654,6 +9973,7 @@ var SolanaLLMClient = class {
         }
         throw new APIError(`API error: ${response.status}`, response.status, sanitizeErrorResponse(errorBody));
       }
+      if (this.apiAuth && endpoint.startsWith("/v1/images/")) return this.apiAuth.poll(response, this.timeout, 2e3);
       return response.json();
     }
   }
@@ -9840,7 +10160,7 @@ var SolanaLLMClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      return await fetch(url, { ...options, signal: controller.signal });
+      return await (this.apiAuth ? this.apiAuth.fetch.bind(this.apiAuth) : fetch)(url, { ...options, signal: controller.signal });
     } finally {
       clearTimeout(timeoutId);
     }
@@ -10039,6 +10359,9 @@ function getCostLogSummary() {
 }
 
 // src/setup.ts
+import { readFileSync as readFileSync6 } from "fs";
+import { homedir as homedir5 } from "os";
+import { join as join6 } from "path";
 function setupAgentWallet(options) {
   const { address, privateKey, isNew } = getOrCreateWallet();
   if (isNew) {
@@ -10081,6 +10404,24 @@ async function status() {
   console.log(`Balance: $${balance.toFixed(2)} USDC`);
   return { address, balance };
 }
+async function setupAgentClient(options = {}) {
+  if (resolveApiKeyAuth(options)) return new LLMClient({ apiKey: options.apiKey });
+  let chain = options.chain;
+  if (!chain) {
+    for (const file of ["payment-chain", ".chain"]) {
+      try {
+        const saved = readFileSync6(join6(homedir5(), ".blockrun", file), "utf8").trim();
+        if (saved === "solana" || saved === "base") {
+          chain = saved;
+          break;
+        }
+      } catch {
+      }
+    }
+  }
+  chain ??= !loadSolanaWallet() && loadWallet() ? "base" : "solana";
+  return chain === "solana" ? setupAgentSolanaWallet(options) : setupAgentWallet(options);
+}
 
 // src/openai-compat.ts
 var StreamingResponse = class {
@@ -10212,13 +10553,17 @@ var Chat = class {
 };
 var OpenAI = class {
   chat;
+  get authMode() {
+    return this.client.authMode;
+  }
   client;
   constructor(options = {}) {
     const privateKey = options.walletKey || options.privateKey;
-    const apiUrl = options.baseURL || "https://blockrun.ai/api";
+    const apiUrl = resolveApiKeyAuth({ apiKey: options.apiKey, privateKey, apiUrl: options.baseURL })?.apiUrl ?? options.baseURL ?? "https://blockrun.ai/api";
     const timeout = options.timeout ?? DEFAULT_TIMEOUT;
     this.client = new LLMClient({
       privateKey,
+      apiKey: options.apiKey,
       apiUrl,
       timeout
     });
@@ -10237,17 +10582,29 @@ import { privateKeyToAccount as privateKeyToAccount16 } from "viem/accounts";
 var AnthropicClient = class {
   _client = null;
   _clientPromise = null;
-  _privateKey;
-  _account;
+  apiAuth;
+  get authMode() {
+    return this.apiAuth ? "api-key" : "wallet";
+  }
+  walletKey;
+  get _privateKey() {
+    return requireWallet(this.walletKey);
+  }
+  walletAccount;
+  get _account() {
+    return requireWallet(this.walletAccount);
+  }
   _apiUrl;
   _timeout;
   constructor(options = {}) {
-    const wallet = getOrCreateWallet();
-    const key = options.privateKey ?? wallet.privateKey;
-    validatePrivateKey(key);
-    this._privateKey = key;
-    this._account = privateKeyToAccount16(this._privateKey);
-    const apiUrl = options.apiUrl ?? "https://blockrun.ai/api";
+    this.apiAuth = resolveApiKeyAuth(options);
+    if (!this.apiAuth) {
+      const key = options.privateKey ?? getOrCreateWallet().privateKey;
+      validatePrivateKey(key);
+      this.walletKey = key;
+      this.walletAccount = privateKeyToAccount16(this.walletKey);
+    }
+    const apiUrl = this.apiAuth?.apiUrl ?? options.apiUrl ?? "https://blockrun.ai/api";
     validateApiUrl(apiUrl);
     this._apiUrl = apiUrl.replace(/\/$/, "");
     this._timeout = options.timeout ?? DEFAULT_TIMEOUT;
@@ -10271,6 +10628,7 @@ var AnthropicClient = class {
     const timeoutId = setTimeout(() => controller.abort(), this._timeout);
     try {
       const mergedInit = { ...init, signal: controller.signal };
+      if (this.apiAuth) return await this.apiAuth.fetch(input, mergedInit, false);
       let response = await globalThis.fetch(input, mergedInit);
       if (response.status === 402) {
         let paymentHeader = response.headers.get("payment-required");
@@ -10342,6 +10700,7 @@ var AnthropicClient = class {
 };
 export {
   APIError,
+  API_KEY_URL,
   AnthropicClient,
   BASE_CHAIN_ID,
   BlockrunClient,
@@ -10353,6 +10712,7 @@ export {
   NETWORK_ALIASES,
   OpenAI,
   PHONE_PRICES,
+  PORTAL_URL,
   PORTRAIT_ENROLLMENT_PRICE_USD,
   PaymentError,
   PhoneClient,
@@ -10410,6 +10770,7 @@ export {
   scanSolanaWallets,
   scanWallets2 as scanWallets,
   setCache,
+  setupAgentClient,
   setupAgentSolanaWallet,
   setupAgentWallet,
   solanaClient,