@blockrun/llm 3.13.6 → 3.14.0

package/dist/index.cjs

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   APIError: () => APIError,
+  API_KEY_URL: () => API_KEY_URL,
   AnthropicClient: () => AnthropicClient,
   BASE_CHAIN_ID: () => BASE_CHAIN_ID,
   BlockrunClient: () => BlockrunClient,
@@ -42,6 +43,7 @@ __export(index_exports, {
   NETWORK_ALIASES: () => NETWORK_ALIASES,
   OpenAI: () => OpenAI,
   PHONE_PRICES: () => PHONE_PRICES,
+  PORTAL_URL: () => PORTAL_URL,
   PORTRAIT_ENROLLMENT_PRICE_USD: () => PORTRAIT_ENROLLMENT_PRICE_USD,
   PaymentError: () => PaymentError,
   PhoneClient: () => PhoneClient,
@@ -99,6 +101,7 @@ __export(index_exports, {
   scanSolanaWallets: () => scanSolanaWallets,
   scanWallets: () => scanWallets2,
   setCache: () => setCache,
+  setupAgentClient: () => setupAgentClient,
   setupAgentSolanaWallet: () => setupAgentSolanaWallet,
   setupAgentWallet: () => setupAgentWallet,
   solanaClient: () => solanaClient,
@@ -112,9 +115,6 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/client.ts
-var import_accounts2 = require("viem/accounts");
-
 // src/types.ts
 var BlockrunError = class extends Error {
   constructor(message) {
@@ -136,6 +136,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);
@@ -145,6 +147,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
+var import_accounts2 = require("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) {
@@ -4275,9 +4519,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) {
@@ -4308,130 +4554,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
 var fs = __toESM(require("fs"), 1);
 var path = __toESM(require("path"), 1);
@@ -4478,7 +4600,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
@@ -4526,8 +4648,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;
@@ -4545,17 +4678,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 = (0, import_accounts2.privateKeyToAccount)(privateKey);
     }
-    validatePrivateKey(privateKey);
-    this.privateKey = privateKey;
-    this.account = (0, import_accounts2.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;
@@ -4596,7 +4732,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 }
     );
   }
   /**
@@ -5182,6 +5318,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();
   }
   /**
@@ -5434,7 +5571,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
       });
@@ -5935,6 +6072,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
@@ -5958,8 +6096,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;
@@ -5970,17 +6119,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 = (0, import_accounts3.privateKeyToAccount)(privateKey);
     }
-    validatePrivateKey(privateKey);
-    this.privateKey = privateKey;
-    this.account = (0, import_accounts3.privateKeyToAccount)(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;
@@ -6107,6 +6259,7 @@ var ImageClient = class {
         sanitizeErrorResponse(errorBody)
       );
     }
+    if (this.apiAuth) return this.apiAuth.poll(response, POLL_MAX_DURATION_MS, POLL_INTERVAL_MS);
     return response.json();
   }
   /**
@@ -6244,7 +6397,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
       });
@@ -6263,6 +6416,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
@@ -6276,24 +6430,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 = (0, import_accounts4.privateKeyToAccount)(privateKey);
     }
-    validatePrivateKey(privateKey);
-    this.privateKey = privateKey;
-    this.account = (0, import_accounts4.privateKeyToAccount)(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;
@@ -6350,6 +6518,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) {
@@ -6412,7 +6581,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);
     }
@@ -6421,6 +6590,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 };
   }
 };
@@ -6432,24 +6602,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 = (0, import_accounts5.privateKeyToAccount)(privateKey);
     }
-    validatePrivateKey(privateKey);
-    this.privateKey = privateKey;
-    this.account = (0, import_accounts5.privateKeyToAccount)(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;
@@ -6611,7 +6795,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);
     }
@@ -6620,6 +6804,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 };
   }
 };
@@ -6634,24 +6819,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 = (0, import_accounts6.privateKeyToAccount)(privateKey);
     }
-    validatePrivateKey(privateKey);
-    this.privateKey = privateKey;
-    this.account = (0, import_accounts6.privateKeyToAccount)(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;
@@ -6777,6 +6976,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");
     }
@@ -6924,7 +7124,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);
     }
@@ -6933,6 +7133,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 };
   }
 };
@@ -6944,24 +7145,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 = (0, import_accounts7.privateKeyToAccount)(privateKey);
     }
-    validatePrivateKey(privateKey);
-    this.privateKey = privateKey;
-    this.account = (0, import_accounts7.privateKeyToAccount)(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;
@@ -7125,7 +7340,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);
     }
@@ -7134,6 +7349,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 };
   }
 };
@@ -7163,24 +7379,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 = (0, import_accounts8.privateKeyToAccount)(privateKey);
     }
-    validatePrivateKey(privateKey);
-    this.privateKey = privateKey;
-    this.account = (0, import_accounts8.privateKeyToAccount)(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;
@@ -7191,6 +7421,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 ────────────────────────────────────────────────────────────
@@ -7350,7 +7581,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);
     }
@@ -7363,24 +7594,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 = (0, import_accounts9.privateKeyToAccount)(privateKey);
     }
-    validatePrivateKey(privateKey);
-    this.privateKey = privateKey;
-    this.account = (0, import_accounts9.privateKeyToAccount)(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;
@@ -7391,6 +7636,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 };
   }
   /**
@@ -7504,7 +7750,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);
     }
@@ -7516,22 +7762,36 @@ var import_accounts10 = require("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 = (0, import_accounts10.privateKeyToAccount)(privateKey);
     }
-    validatePrivateKey(privateKey);
-    this.privateKey = privateKey;
-    this.account = (0, import_accounts10.privateKeyToAccount)(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;
@@ -7637,7 +7897,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);
     }
@@ -7652,15 +7912,20 @@ var import_accounts11 = require("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."
       );
@@ -7670,7 +7935,7 @@ var PriceClient = class {
       this.privateKey = privateKey;
       this.account = (0, import_accounts11.privateKeyToAccount)(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;
@@ -7823,7 +8088,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);
     }
@@ -7857,22 +8122,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 = (0, import_accounts12.privateKeyToAccount)(privateKey);
     }
-    validatePrivateKey(privateKey);
-    this.privateKey = privateKey;
-    this.account = (0, import_accounts12.privateKeyToAccount)(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;
@@ -7996,7 +8275,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);
     }
@@ -8085,24 +8364,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 = (0, import_accounts13.privateKeyToAccount)(privateKey);
     }
-    validatePrivateKey(privateKey);
-    this.privateKey = privateKey;
-    this.account = (0, import_accounts13.privateKeyToAccount)(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;
@@ -8246,7 +8539,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);
     }
@@ -8255,6 +8548,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 };
   }
 };
@@ -8267,24 +8561,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 = (0, import_accounts14.privateKeyToAccount)(privateKey);
     }
-    validatePrivateKey(privateKey);
-    this.privateKey = privateKey;
-    this.account = (0, import_accounts14.privateKeyToAccount)(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;
@@ -8326,6 +8634,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();
     }
@@ -8618,7 +8927,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);
     }
@@ -8630,6 +8939,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 };
   }
 };
@@ -8640,7 +8950,7 @@ function sleep(ms) {
 // src/wallet.ts
 var import_accounts16 = require("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
 var fs2 = __toESM(require("fs"), 1);
 var os2 = __toESM(require("os"), 1);
 var path2 = __toESM(require("path"), 1);
@@ -8662,7 +8972,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
 var fs3 = __toESM(require("fs"), 1);
 var path3 = __toESM(require("path"), 1);
 var import_accounts15 = require("viem/accounts");
@@ -8958,7 +9268,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 }
     );
   }
 }
@@ -9104,7 +9415,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() {
@@ -9218,7 +9529,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;
@@ -9229,15 +9547,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);
@@ -9350,7 +9671,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
       }
     );
   }
@@ -9379,7 +9700,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, {
@@ -9632,6 +9953,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. */
@@ -9768,6 +10090,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();
     }
   }
@@ -9954,7 +10277,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);
     }
@@ -10153,6 +10476,9 @@ function getCostLogSummary() {
 }
 
 // src/setup.ts
+var import_node_fs = require("fs");
+var import_node_os = require("os");
+var import_node_path = require("path");
 function setupAgentWallet(options) {
   const { address, privateKey, isNew } = getOrCreateWallet();
   if (isNew) {
@@ -10195,6 +10521,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 = (0, import_node_fs.readFileSync)((0, import_node_path.join)((0, import_node_os.homedir)(), ".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 {
@@ -10326,13 +10670,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
     });
@@ -10351,17 +10699,29 @@ var import_accounts17 = require("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 = (0, import_accounts17.privateKeyToAccount)(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 = (0, import_accounts17.privateKeyToAccount)(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;
@@ -10385,6 +10745,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");
@@ -10457,6 +10818,7 @@ var AnthropicClient = class {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   APIError,
+  API_KEY_URL,
   AnthropicClient,
   BASE_CHAIN_ID,
   BlockrunClient,
@@ -10468,6 +10830,7 @@ var AnthropicClient = class {
   NETWORK_ALIASES,
   OpenAI,
   PHONE_PRICES,
+  PORTAL_URL,
   PORTRAIT_ENROLLMENT_PRICE_USD,
   PaymentError,
   PhoneClient,
@@ -10524,6 +10887,7 @@ var AnthropicClient = class {
   scanSolanaWallets,
   scanWallets,
   setCache,
+  setupAgentClient,
   setupAgentSolanaWallet,
   setupAgentWallet,
   solanaClient,