@blockrun/llm 3.18.0 → 3.19.0

package/dist/index.js

@@ -163,7 +163,7 @@ var TRANSIENT_RETRIES = 2;
 var TRANSIENT_BACKOFF_MS = 1e3;
 function retryDelay(ms, signal) {
   signal?.throwIfAborted();
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     const onAbort = () => {
       clearTimeout(timer);
       signal?.removeEventListener("abort", onAbort);
@@ -171,7 +171,7 @@ function retryDelay(ms, signal) {
     };
     const timer = setTimeout(() => {
       signal?.removeEventListener("abort", onAbort);
-      resolve();
+      resolve2();
     }, ms);
     signal?.addEventListener("abort", onAbort, { once: true });
   });
@@ -207,8 +207,8 @@ var ApiKeyAuth = class {
     this.#key = key;
   }
   /** Resolve gateway poll paths without forwarding credentials to another origin. */
-  resolveUrl(path6) {
-    const url = new URL(path6, this.apiUrl + "/");
+  resolveUrl(path7) {
+    const url = new URL(path7, 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.");
     }
@@ -274,7 +274,7 @@ var ApiKeyAuth = class {
       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()))));
+      await new Promise((resolve2) => setTimeout(resolve2, Math.min(interval, Math.max(0, deadline - Date.now()))));
       const remaining = deadline - Date.now();
       if (remaining <= 0) break;
       try {
@@ -4539,7 +4539,7 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.18.0";
+var SDK_VERSION = "3.19.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
@@ -5648,8 +5648,8 @@ var LLMClient = class _LLMClient {
    * @example
    * const results = await client.exa("search", { query: "latest AI research", numResults: 5 });
    */
-  async exa(path6, body) {
-    return this.requestWithPaymentRaw(`/v1/exa/${path6}`, body);
+  async exa(path7, body) {
+    return this.requestWithPaymentRaw(`/v1/exa/${path7}`, body);
   }
   /**
    * Neural web search via Exa. Returns semantically relevant URLs and metadata.
@@ -5797,8 +5797,8 @@ var LLMClient = class _LLMClient {
    * const market = await client.pm("kalshi/markets/KXBTC-25MAR14");
    * const results = await client.pm("polymarket/search", { q: "bitcoin" });
    */
-  async pm(path6, params) {
-    return this.getWithPaymentRaw(`/v1/pm/${path6}`, params);
+  async pm(path7, params) {
+    return this.getWithPaymentRaw(`/v1/pm/${path7}`, params);
   }
   /**
    * Structured query for Predexon prediction market data (POST endpoints).
@@ -5814,8 +5814,8 @@ var LLMClient = class _LLMClient {
    *   addresses: ["0xabc...", "0xdef..."],
    * });
    */
-  async pmQuery(path6, query) {
-    return this.requestWithPaymentRaw(`/v1/pm/${path6}`, query);
+  async pmQuery(path7, query) {
+    return this.requestWithPaymentRaw(`/v1/pm/${path7}`, query);
   }
   // ── PM convenience helpers (Predexon v2) ─────────────────────────────────
   // Thin wrappers over pm() / pmQuery() for the most common v2 endpoints.
@@ -5903,8 +5903,8 @@ var LLMClient = class _LLMClient {
    *               "prices/coingecko:bitcoin,base:0x..."
    * @param params - Query parameters passed through to DefiLlama
    */
-  async defi(path6, params) {
-    return this.getWithPaymentRaw(`/v1/defillama/${path6}`, params);
+  async defi(path7, params) {
+    return this.getWithPaymentRaw(`/v1/defillama/${path7}`, params);
   }
   /** All DeFi protocols with TVL. */
   async defiProtocols() {
@@ -5940,9 +5940,9 @@ var LLMClient = class _LLMClient {
    * @param params - Query params (chainId, sellToken, buyToken, sellAmount, taker, ...)
    * @param body - JSON body — pass to switch to POST (gasless/submit only)
    */
-  async dex(path6, params, body) {
-    if (body) return this.requestWithPaymentRaw(`/v1/zerox/${path6}`, body);
-    return this.getWithPaymentRaw(`/v1/zerox/${path6}`, params);
+  async dex(path7, params, body) {
+    if (body) return this.requestWithPaymentRaw(`/v1/zerox/${path7}`, body);
+    return this.getWithPaymentRaw(`/v1/zerox/${path7}`, params);
   }
   /** Indicative Permit2 swap price — no commitment (free). */
   async dexPrice(params) {
@@ -5986,8 +5986,8 @@ var LLMClient = class _LLMClient {
    *               "sandbox/status", "sandbox/terminate"
    * @param body - JSON body for the endpoint
    */
-  async modal(path6, body) {
-    return this.requestWithPaymentRaw(`/v1/modal/${path6}`, body ?? {});
+  async modal(path7, body) {
+    return this.requestWithPaymentRaw(`/v1/modal/${path7}`, body ?? {});
   }
   /** Create a sandboxed compute environment (CPU / GPU tiers). */
   async modalSandboxCreate(body) {
@@ -6295,7 +6295,7 @@ var ImageClient = class {
     const pollUrl = pollPath.startsWith("/api/") ? `${this.apiUrl.replace(/\/api$/, "")}${pollPath}` : `${this.apiUrl}${pollPath.startsWith("/") ? "" : "/"}${pollPath}`;
     const startedAt = Date.now();
     while (Date.now() - startedAt < POLL_MAX_DURATION_MS) {
-      await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+      await new Promise((resolve2) => setTimeout(resolve2, POLL_INTERVAL_MS));
       const pollResp = await this.fetchWithTimeout(pollUrl, {
         method: "GET",
         headers: {
@@ -7493,8 +7493,8 @@ var PhoneClient = class {
     return data;
   }
   // ─── Internals ─────────────────────────────────────────────────────────
-  async request(path6, body) {
-    const url = `${this.apiUrl}/v1/phone/${path6}`;
+  async request(path7, body) {
+    const url = `${this.apiUrl}/v1/phone/${path7}`;
     const response = await this.fetchWithTimeout(url, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
@@ -7935,10 +7935,10 @@ var PriceClient = class {
   }
   async price(category, symbol, options) {
     if (!symbol) throw new Error("symbol is required");
-    const path6 = categoryPath(category, options?.market, "price", symbol);
+    const path7 = categoryPath(category, options?.market, "price", symbol);
     const query = {};
     if (options?.session) query.session = options.session;
-    const data = await this.getWithPayment(path6, query);
+    const data = await this.getWithPayment(path7, query);
     return {
       symbol: data.symbol ?? symbol.toUpperCase(),
       price: data.price,
@@ -7957,14 +7957,14 @@ var PriceClient = class {
     if (!options.from || options.from <= 0) {
       throw new Error("history requires options.from (unix seconds)");
     }
-    const path6 = categoryPath(category, options.market, "history", symbol);
+    const path7 = categoryPath(category, options.market, "history", symbol);
     const query = {
       resolution: options.resolution ?? "D",
       from: String(options.from)
     };
     if (options.to) query.to = String(options.to);
     if (options.session) query.session = options.session;
-    const data = await this.getWithPayment(path6, query);
+    const data = await this.getWithPayment(path7, query);
     return {
       symbol: data.symbol ?? symbol.toUpperCase(),
       resolution: data.resolution ?? (options.resolution ?? "D"),
@@ -7976,12 +7976,12 @@ var PriceClient = class {
     };
   }
   async listSymbols(category, options) {
-    const path6 = categoryPath(category, options?.market, "list");
+    const path7 = categoryPath(category, options?.market, "list");
     const query = {
       limit: String(options?.limit && options.limit > 0 ? options.limit : 100)
     };
     if (options?.query) query.q = options.query;
-    const data = await this.getWithPayment(path6, query);
+    const data = await this.getWithPayment(path7, query);
     if (Array.isArray(data)) {
       return { symbols: data, count: data.length };
     }
@@ -8154,19 +8154,19 @@ var SurfClient = class {
    * `/v1/surf` is tolerated and stripped). Query params are URL-encoded;
    * arrays become repeated keys (`?a=1&a=2`).
    */
-  async get(path6, params) {
-    const url = this.buildUrl(path6, params);
+  async get(path7, params) {
+    const url = this.buildUrl(path7, params);
     return this.requestWithPayment(url, "GET");
   }
   /**
    * POST a Surf endpoint with a JSON body. Same path normalization as `get`.
    */
-  async post(path6, body) {
-    const url = this.buildUrl(path6);
+  async post(path7, body) {
+    const url = this.buildUrl(path7);
     return this.requestWithPayment(url, "POST", body);
   }
-  buildUrl(path6, params) {
-    let normalized = path6.startsWith("/") ? path6 : `/${path6}`;
+  buildUrl(path7, params) {
+    let normalized = path7.startsWith("/") ? path7 : `/${path7}`;
     if (!normalized.startsWith(SURF_PREFIX)) {
       normalized = `${SURF_PREFIX}${normalized}`;
     }
@@ -8624,15 +8624,15 @@ var BlockrunClient = class {
    * `/api` is tolerated and stripped). Query params are URL-encoded; arrays
    * become repeated keys (`?a=1&a=2`); undefined/null are dropped.
    */
-  async get(path6, params) {
-    const url = this.buildUrl(path6, params);
+  async get(path7, params) {
+    const url = this.buildUrl(path7, params);
     return this.requestWithPayment(url, "GET");
   }
   /**
    * POST a BlockRun endpoint with a JSON body.
    */
-  async post(path6, body) {
-    const url = this.buildUrl(path6);
+  async post(path7, body) {
+    const url = this.buildUrl(path7);
     return this.requestWithPayment(url, "POST", body);
   }
   /**
@@ -8656,8 +8656,8 @@ var BlockrunClient = class {
    * short-circuits and returns the body. Most long-running endpoints (image,
    * video, music, voice) return 202 with a poll_url.
    */
-  async poll(path6, body, options) {
-    const submitUrl = this.buildUrl(path6);
+  async poll(path7, body, options) {
+    const submitUrl = this.buildUrl(path7);
     const budgetMs = options?.budgetMs ?? DEFAULT_POLL_BUDGET_MS;
     const intervalMs = options?.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
     const resp402 = await this.fetchWithTimeout(submitUrl, {
@@ -8757,8 +8757,8 @@ var BlockrunClient = class {
    *     process.stdout.write(chunk.choices?.[0]?.delta?.content ?? "");
    *   }
    */
-  async *stream(path6, body) {
-    const url = this.buildUrl(path6);
+  async *stream(path7, body) {
+    const url = this.buildUrl(path7);
     const requestBody = JSON.stringify(body ?? {});
     const resp402 = await this.fetchWithTimeout(url, {
       method: "POST",
@@ -8801,8 +8801,8 @@ var BlockrunClient = class {
   // --------------------------------------------------------------------
   // Internal: shared infrastructure
   // --------------------------------------------------------------------
-  buildUrl(path6, params) {
-    let normalized = path6.startsWith("/") ? path6 : `/${path6}`;
+  buildUrl(path7, params) {
+    let normalized = path7.startsWith("/") ? path7 : `/${path7}`;
     if (normalized.startsWith("/api/")) {
       normalized = normalized.slice(4);
     }
@@ -9448,6 +9448,332 @@ async function getOrCreateSolanaWallet() {
   return { address, privateKey, isNew: true };
 }
 
+// src/solana-batch.ts
+import * as fs6 from "fs";
+import * as path5 from "path";
+var BATCH_SCHEME = "batch-settlement";
+var INSTALL_HINT2 = "npm install @x402/core@~2.28.0 @x402/svm@~2.28.0 @solana/kit";
+async function load(pkg, importer) {
+  try {
+    return await importer();
+  } catch (err) {
+    throw new Error(
+      `@blockrun/llm: Solana batch-settlement requires the optional peer dependency "${pkg}", which is not installed.
+
+  ${INSTALL_HINT2}
+
+Original error: ${err instanceof Error ? err.message : String(err)}`,
+      { cause: err }
+    );
+  }
+}
+var FileChannelStorage = class {
+  constructor(file) {
+    this.file = file;
+  }
+  file;
+  read() {
+    try {
+      const parsed = JSON.parse(fs6.readFileSync(this.file, "utf8"));
+      return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+    } catch (err) {
+      if (err.code === "ENOENT") return {};
+      throw err;
+    }
+  }
+  write(all) {
+    fs6.mkdirSync(path5.dirname(this.file), { recursive: true, mode: 448 });
+    const tmp = `${this.file}.${process.pid}.tmp`;
+    fs6.writeFileSync(tmp, JSON.stringify(all, null, 2), { mode: 384 });
+    fs6.renameSync(tmp, this.file);
+  }
+  async get(key) {
+    return this.read()[key];
+  }
+  async set(key, record) {
+    const all = this.read();
+    all[key] = record;
+    this.write(all);
+  }
+  async delete(key) {
+    const all = this.read();
+    if (!(key in all)) return;
+    delete all[key];
+    this.write(all);
+  }
+  /** Forget every channel in this file. */
+  clear() {
+    try {
+      fs6.unlinkSync(this.file);
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+    }
+  }
+};
+function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+var heldLocks = /* @__PURE__ */ new Set();
+var exitHookInstalled = false;
+function lockChannelFile(file) {
+  if (heldLocks.has(file)) return void 0;
+  const lock = `${file}.lock`;
+  fs6.mkdirSync(path5.dirname(lock), { recursive: true, mode: 448 });
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      fs6.writeFileSync(lock, String(process.pid), { flag: "wx", mode: 384 });
+      heldLocks.add(file);
+      if (!exitHookInstalled) {
+        exitHookInstalled = true;
+        process.once("exit", () => {
+          for (const held of heldLocks) {
+            try {
+              fs6.unlinkSync(`${held}.lock`);
+            } catch {
+            }
+          }
+        });
+      }
+      return void 0;
+    } catch (err) {
+      if (err.code !== "EEXIST") throw err;
+    }
+    const owner = Number(fs6.readFileSync(lock, "utf8").trim());
+    if (Number.isInteger(owner) && owner > 0 && owner !== process.pid && processAlive(owner)) return owner;
+    try {
+      fs6.unlinkSync(lock);
+    } catch {
+    }
+  }
+  return -1;
+}
+function pendingDeposit(pending) {
+  const entries = Array.isArray(pending) ? pending : [pending];
+  return entries.some(
+    (entry) => entry?.payment?.payload?.type === "deposit"
+  );
+}
+function dropOrphanedPending(storage) {
+  return {
+    get: async (key) => {
+      const record = await storage.get(key);
+      if (!record?.pending || record.channelConfig?.voucherSigner !== "server") return record;
+      if (!record.hasConfirmedState || pendingDeposit(record.pending)) {
+        await storage.delete(key);
+        return void 0;
+      }
+      const { pending: _pending, hasConfirmedState: _confirmed, ...confirmed } = record;
+      await storage.set(key, confirmed);
+      return confirmed;
+    },
+    set: (key, record) => storage.set(key, record),
+    delete: (key) => storage.delete(key)
+  };
+}
+function offersBatch(paymentRequired) {
+  return (paymentRequired.accepts ?? []).some((accept) => accept.scheme === BATCH_SCHEME);
+}
+function atomicToUsd(amount) {
+  return amount !== void 0 && /^\d+$/.test(amount) ? Number(amount) / 1e6 : void 0;
+}
+async function isBatchRefusal(response) {
+  if (response.status === 402) return "payment_required";
+  if (![400, 403, 409, 503].includes(response.status)) return void 0;
+  let body;
+  try {
+    body = await response.clone().json();
+  } catch {
+    return void 0;
+  }
+  const { error, code } = body ?? {};
+  if (code === "PAYMENT_VERIFICATION_UNAVAILABLE") return code;
+  return typeof error === "string" && error.startsWith("batch_") ? error : void 0;
+}
+var wallets = /* @__PURE__ */ new Map();
+var SolanaBatchPayer = class {
+  constructor(init) {
+    this.init = init;
+    const { operators } = init.options;
+    if (!Array.isArray(operators) || operators.length === 0 || operators.some((o) => typeof o !== "string" || !o)) {
+      throw new Error("batch.operators must list at least one base58 operator public key");
+    }
+  }
+  init;
+  state;
+  async storeFile() {
+    const { channelStore } = this.init.options;
+    if (channelStore === false) return void 0;
+    return path5.resolve(channelStore ?? path5.join(paths().dir, "solana-batch", `${await this.init.address()}.json`));
+  }
+  /**
+   * This wallet's shared batch state, or why this client cannot use batch:
+   * another client in this process holds the wallet with a different trust
+   * configuration, or another live process owns its channel file.
+   */
+  wallet() {
+    this.state ??= (async () => {
+      const address = await this.init.address();
+      const file = await this.storeFile();
+      const { operators, maxDeposit } = this.init.options;
+      const config = JSON.stringify([[...operators].sort(), String(maxDeposit ?? ""), file ?? null, this.init.rpcUrl]);
+      const existing = wallets.get(address);
+      if (existing) {
+        return existing.config === config ? existing : "another client in this process uses this wallet with different batch options";
+      }
+      if (file) {
+        const owner = lockChannelFile(file);
+        if (owner !== void 0) return `channel store ${file} is in use by process ${owner}`;
+      }
+      const created = { config, busy: false, warned: /* @__PURE__ */ new Set() };
+      wallets.set(address, created);
+      return created;
+    })();
+    return this.state;
+  }
+  build(wallet) {
+    wallet.client ??= (async () => {
+      const [core, svm, kit] = await Promise.all([
+        load("@x402/core", () => import("@x402/core/client")),
+        load("@x402/svm", () => import("@x402/svm/batch-settlement/client")),
+        load("@solana/kit", () => import("@solana/kit"))
+      ]);
+      const signer = await kit.createKeyPairSignerFromBytes(await this.init.secretKey());
+      const file = await this.storeFile();
+      const storage = file ? dropOrphanedPending(new FileChannelStorage(file)) : void 0;
+      const scheme = new svm.BatchSvmScheme(signer, {
+        rpcUrl: this.init.rpcUrl,
+        serverSignedChannelsPolicy: {
+          allowedOperators: this.init.options.operators,
+          maxDeposit: this.init.options.maxDeposit ?? svm.DEFAULT_SERVER_SIGNED_MAX_DEPOSIT
+        },
+        ...storage ? { channelStorage: storage } : {}
+      });
+      const client = new core.x402Client().register("solana:*", scheme).registerPolicy(scheme.paymentPolicy);
+      client.setSpendControls({ maxAmountPerPayment: false });
+      return {
+        http: new core.x402HTTPClient(client),
+        refund: (url) => scheme.refund(url)
+      };
+    })();
+    wallet.client.catch(() => {
+      wallet.client = void 0;
+    });
+    return wallet.client;
+  }
+  /**
+   * Drop everything this wallet knows about its channel, on disk and in
+   * memory. The next call rebuilds the scheme, which reads the channel's real
+   * state (deposit, open or closed) from the chain.
+   */
+  async forget(wallet) {
+    wallet.client = void 0;
+    const file = await this.storeFile();
+    if (file) new FileChannelStorage(file).clear();
+  }
+  warn(wallet, reason) {
+    if (wallet?.warned.has(reason)) return;
+    wallet?.warned.add(reason);
+    console.error(`[@blockrun/llm] batch-settlement unavailable (${reason}); paying with exact`);
+  }
+  /**
+   * Pay one 402 with batch-settlement, or say why the caller should use exact.
+   *
+   * `send` replays the original request with the payment headers. The
+   * returned response is 2xx; any other answer either becomes a fallback (the
+   * gateway charged nothing) or is returned to the caller's own error path.
+   */
+  async pay(paymentRequired, send) {
+    if (!offersBatch(paymentRequired)) return { kind: "fallback", reason: "not_offered" };
+    const wallet = await this.wallet();
+    if (typeof wallet === "string") {
+      this.warn(void 0, wallet);
+      return { kind: "fallback", reason: wallet };
+    }
+    if (wallet.busy) return { kind: "fallback", reason: "channel_busy" };
+    wallet.busy = true;
+    try {
+      let http;
+      let payload;
+      try {
+        http = (await this.build(wallet)).http;
+        payload = await http.createPaymentPayload(paymentRequired);
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        this.warn(wallet, reason);
+        return { kind: "fallback", reason };
+      }
+      const deposit = payload.payload?.type === "deposit";
+      let response;
+      try {
+        response = await send(http.encodePaymentSignatureHeader(payload));
+      } catch (err) {
+        if (deposit) await this.forget(wallet);
+        else await this.settle(http, payload, () => null, 0);
+        throw err;
+      }
+      const getHeader = (name) => response.headers.get(name);
+      const settled = await this.settle(http, payload, getHeader, response.status);
+      if (deposit && !(response.ok && settled?.success === true)) await this.forget(wallet);
+      if (response.ok) {
+        const charged = atomicToUsd(settled?.amount) ?? atomicToUsd(payload.accepted?.amount) ?? 0;
+        return { kind: "paid", response, chargedUsd: charged };
+      }
+      const refusal = await isBatchRefusal(response);
+      if (refusal) {
+        this.warn(wallet, refusal);
+        return { kind: "fallback", reason: refusal };
+      }
+      return { kind: "failed", response };
+    } finally {
+      wallet.busy = false;
+    }
+  }
+  /**
+   * Hand the gateway's answer to the scheme, which verifies the operator's
+   * voucher and advances (or rolls back) the channel's local state.
+   *
+   * A malformed receipt must not lose a response the caller has been served,
+   * so a scheme error is logged rather than thrown.
+   */
+  async settle(http, payload, getHeader, status2) {
+    try {
+      return (await http.processPaymentResult(payload, getHeader, status2)).settleResponse;
+    } catch (err) {
+      console.error(
+        `[@blockrun/llm] batch-settlement receipt not reconciled: ${err instanceof Error ? err.message : String(err)}`
+      );
+      return void 0;
+    }
+  }
+  /**
+   * Close the channel and return its unused escrow to the wallet.
+   *
+   * The scheme keeps a closed channel in its records, and would go on paying
+   * into it, so a successful close forgets the channel. The next batch call
+   * finds no open channel on-chain and opens a new one.
+   *
+   * @param url - any batch-enabled route on the gateway the channel was opened with.
+   */
+  async close(url) {
+    const wallet = await this.wallet();
+    if (typeof wallet === "string") throw new Error(`batch-settlement unavailable: ${wallet}`);
+    if (wallet.busy) throw new Error("batch-settlement channel has a request in flight; close it when the call returns");
+    wallet.busy = true;
+    try {
+      const result = await (await this.build(wallet)).refund(url);
+      await this.forget(wallet);
+      return result;
+    } finally {
+      wallet.busy = false;
+    }
+  }
+};
+
 // src/solana-client.ts
 var SOLANA_API_URL = "https://sol.blockrun.ai/api";
 var DEFAULT_MAX_TOKENS2 = 1024;
@@ -9511,7 +9837,7 @@ async function isSafeStaleBlockhashResponse(response) {
 }
 async function waitForStaleRetry(attempt) {
   await new Promise(
-    (resolve) => setTimeout(resolve, STALE_BLOCKHASH_RETRY_BACKOFFS_MS[attempt])
+    (resolve2) => setTimeout(resolve2, STALE_BLOCKHASH_RETRY_BACKOFFS_MS[attempt])
   );
 }
 var DEFAULT_SOLANA_RPC_URL = "https://sol.blockrun.ai/api/v1/solana/rpc";
@@ -9555,6 +9881,7 @@ var SolanaLLMClient = class {
   addressCache = null;
   modelPricingCache = null;
   modelPricingPromise = null;
+  batchPayer;
   constructor(options = {}) {
     this.apiAuth = resolveApiKeyAuth(options);
     if (!this.apiAuth) {
@@ -9574,6 +9901,25 @@ var SolanaLLMClient = class {
     this.rpcUrl = rpc.url;
     this.rpcHeaders = rpc.headers;
     this.timeout = options.timeout || DEFAULT_TIMEOUT14;
+    if (options.batch && !this.apiAuth) {
+      this.batchPayer = new SolanaBatchPayer({
+        options: options.batch,
+        secretKey: () => solanaKeyToBytes(this.privateKey),
+        address: () => this.getWalletAddress(),
+        rpcUrl: this.rpcUrl
+      });
+    }
+  }
+  /**
+   * Close this wallet's batch-settlement channel and return its unused escrow.
+   *
+   * The gateway closes it cooperatively when it can; otherwise this starts a
+   * payer-forced close and the escrow comes back after the channel's grace
+   * period. Only meaningful with the `batch` option.
+   */
+  async closeBatchChannel() {
+    if (!this.batchPayer) throw new Error("closeBatchChannel() requires the `batch` option in wallet mode");
+    return this.batchPayer.close(`${this.apiUrl}/v1/chat/completions`);
   }
   /** Get Solana wallet address (public key in base58). */
   async getWalletAddress() {
@@ -9767,8 +10113,8 @@ var SolanaLLMClient = class {
    *   how you end up debugging a request you did not send.
    * @returns each decoded SSE frame, in order.
    */
-  async *stream(path6, body) {
-    const url = this.buildUrl(path6);
+  async *stream(path7, body) {
+    const url = this.buildUrl(path7);
     const response = await this.openPaidStream(url, JSON.stringify(body ?? {}));
     yield* readSseFrames(
       response,
@@ -9840,8 +10186,8 @@ var SolanaLLMClient = class {
    * @param path - endpoint path, with or without a leading slash.
    * @returns the absolute URL to call.
    */
-  buildUrl(path6) {
-    let normalized = path6.startsWith("/") ? path6 : `/${path6}`;
+  buildUrl(path7) {
+    let normalized = path7.startsWith("/") ? path7 : `/${path7}`;
     if (normalized.startsWith("/api/")) normalized = normalized.slice(4);
     return `${this.apiUrl}${normalized}`;
   }
@@ -9920,11 +10266,11 @@ var SolanaLLMClient = class {
     return data;
   }
   // ── Prediction Markets (Powered by Predexon) ────────────────────────────
-  async pm(path6, params) {
-    return this.getWithPaymentRaw(`/v1/pm/${path6}`, params);
+  async pm(path7, params) {
+    return this.getWithPaymentRaw(`/v1/pm/${path7}`, params);
   }
-  async pmQuery(path6, query) {
-    return this.requestWithPaymentRaw(`/v1/pm/${path6}`, query);
+  async pmQuery(path7, query) {
+    return this.requestWithPaymentRaw(`/v1/pm/${path7}`, query);
   }
   // ── Exa Web Search (Powered by Exa) ──────────────────────────────────────
   /**
@@ -9936,8 +10282,8 @@ var SolanaLLMClient = class {
    * @example
    * const results = await client.exa("search", { query: "latest AI research", numResults: 5 });
    */
-  async exa(path6, body) {
-    return this.requestWithPaymentRaw(`/v1/exa/${path6}`, body);
+  async exa(path7, body) {
+    return this.requestWithPaymentRaw(`/v1/exa/${path7}`, body);
   }
   /**
    * Neural and keyword web search via Exa (Solana payment).
@@ -9987,8 +10333,8 @@ var SolanaLLMClient = class {
    *               "prices/coingecko:bitcoin,base:0x..."
    * @param params - Query parameters passed through to DefiLlama
    */
-  async defi(path6, params) {
-    return this.getWithPaymentRaw(`/v1/defillama/${path6}`, params);
+  async defi(path7, params) {
+    return this.getWithPaymentRaw(`/v1/defillama/${path7}`, params);
   }
   /** All DeFi protocols with TVL. */
   async defiProtocols() {
@@ -10024,9 +10370,9 @@ var SolanaLLMClient = class {
    * @param params - Query params (chainId, sellToken, buyToken, sellAmount, taker, ...)
    * @param body - JSON body — pass to switch to POST (gasless/submit only)
    */
-  async dex(path6, params, body) {
-    if (body) return this.requestWithPaymentRaw(`/v1/zerox/${path6}`, body);
-    return this.getWithPaymentRaw(`/v1/zerox/${path6}`, params);
+  async dex(path7, params, body) {
+    if (body) return this.requestWithPaymentRaw(`/v1/zerox/${path7}`, body);
+    return this.getWithPaymentRaw(`/v1/zerox/${path7}`, params);
   }
   /** Indicative Permit2 swap price — no commitment (free). */
   async dexPrice(params) {
@@ -10070,8 +10416,8 @@ var SolanaLLMClient = class {
    *               "sandbox/status", "sandbox/terminate"
    * @param body - JSON body for the endpoint
    */
-  async modal(path6, body) {
-    return this.requestWithPaymentRaw(`/v1/modal/${path6}`, body ?? {});
+  async modal(path7, body) {
+    return this.requestWithPaymentRaw(`/v1/modal/${path7}`, body ?? {});
   }
   /** Create a sandboxed compute environment (CPU / GPU tiers). */
   async modalSandboxCreate(body) {
@@ -10108,7 +10454,31 @@ var SolanaLLMClient = class {
       });
       if (response.status === 402) {
         try {
-          return await this.handlePaymentAndRetry(url, body, response, staleRetries > 0);
+          const paymentRequired = await this.readPaymentRequired(response);
+          if (this.batchPayer && staleRetries === 0) {
+            const batch = await this.batchPayer.pay(
+              paymentRequired,
+              (paymentHeaders) => this.fetchWithTimeout(url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT, ...paymentHeaders },
+                body: JSON.stringify(body)
+              })
+            );
+            if (batch.kind === "paid") {
+              this.recordSettlement(batch.chargedUsd);
+              return batch.response.json();
+            }
+            if (batch.kind === "failed") {
+              let errorBody;
+              try {
+                errorBody = await batch.response.json();
+              } catch {
+                errorBody = { error: "Request failed" };
+              }
+              throw new APIError(`API error after payment: ${batch.response.status}`, batch.response.status, sanitizeErrorResponse(errorBody));
+            }
+          }
+          return await this.handlePaymentAndRetry(url, body, paymentRequired, staleRetries > 0);
         } catch (error) {
           if (!(error instanceof SafeStaleBlockhashError) || staleRetries >= STALE_BLOCKHASH_RETRY_BACKOFFS_MS.length) throw error;
           await waitForStaleRetry(staleRetries++);
@@ -10229,6 +10599,15 @@ var SolanaLLMClient = class {
     );
   }
   async signPaymentFrom402(url, response, forceFreshBlockhash, resourceFallback = url) {
+    return this.signExactPayment(
+      url,
+      await this.readPaymentRequired(response),
+      forceFreshBlockhash,
+      resourceFallback
+    );
+  }
+  /** Read a `402`'s payment requirements from its header, or its JSON body. */
+  async readPaymentRequired(response) {
     let paymentHeader = response.headers.get("payment-required");
     if (!paymentHeader) {
       try {
@@ -10242,8 +10621,14 @@ var SolanaLLMClient = class {
     if (!paymentHeader) {
       throw new PaymentError("402 response but no payment requirements found");
     }
-    const paymentRequired = parsePaymentRequired(paymentHeader);
-    const details = extractPaymentDetails(paymentRequired, SOLANA_NETWORK);
+    return parsePaymentRequired(paymentHeader);
+  }
+  /** Sign the `exact` accept of a 402 as an SPL TransferChecked payment. */
+  async signExactPayment(url, paymentRequired, forceFreshBlockhash, resourceFallback = url) {
+    const details = extractPaymentDetails(
+      { ...paymentRequired, accepts: paymentRequired.accepts.filter((accept) => accept.scheme !== BATCH_SCHEME) },
+      SOLANA_NETWORK
+    );
     if (!details.network?.startsWith("solana:")) {
       throw new PaymentError(
         `Expected Solana payment network, got: ${details.network}. Use LLMClient for Base payments.`
@@ -10276,10 +10661,10 @@ var SolanaLLMClient = class {
     );
     return { paymentPayload, costUsd: parseFloat(details.amount) / 1e6 };
   }
-  async handlePaymentAndRetry(url, body, response, forceFreshBlockhash = false) {
-    const { paymentPayload, costUsd } = await this.signPaymentFrom402(
+  async handlePaymentAndRetry(url, body, paymentRequired, forceFreshBlockhash = false) {
+    const { paymentPayload, costUsd } = await this.signExactPayment(
       url,
-      response,
+      paymentRequired,
       forceFreshBlockhash,
       `${this.apiUrl}/v1/chat/completions`
     );
@@ -10440,13 +10825,13 @@ function solanaClient(options = {}) {
 }
 
 // src/cache.ts
-import * as fs6 from "fs";
-import * as path5 from "path";
+import * as fs7 from "fs";
+import * as path6 from "path";
 import * as os4 from "os";
 import * as crypto2 from "crypto";
-var CACHE_DIR = path5.join(os4.homedir(), ".blockrun", "cache");
-var DATA_DIR = path5.join(os4.homedir(), ".blockrun", "data");
-var COST_LOG_FILE2 = path5.join(os4.homedir(), ".blockrun", "cost_log.jsonl");
+var CACHE_DIR = path6.join(os4.homedir(), ".blockrun", "cache");
+var DATA_DIR = path6.join(os4.homedir(), ".blockrun", "data");
+var COST_LOG_FILE2 = path6.join(os4.homedir(), ".blockrun", "cost_log.jsonl");
 var DEFAULT_TTL = {
   "/v1/partner/": 3600 * 1e3,
   "/v1/pm/": 1800 * 1e3,
@@ -10466,19 +10851,19 @@ function cacheKey(endpoint, body) {
   return crypto2.createHash("sha256").update(keyData).digest("hex").slice(0, 16);
 }
 function cachePath(key) {
-  return path5.join(CACHE_DIR, `${key}.json`);
+  return path6.join(CACHE_DIR, `${key}.json`);
 }
 function getCached(key) {
   const filePath = cachePath(key);
-  if (!fs6.existsSync(filePath)) return null;
+  if (!fs7.existsSync(filePath)) return null;
   try {
-    const raw = fs6.readFileSync(filePath, "utf-8");
+    const raw = fs7.readFileSync(filePath, "utf-8");
     const entry = JSON.parse(raw);
     const ttl = entry.ttlMs ?? getTtl(entry.endpoint ?? "");
     if (ttl <= 0) return null;
     if (Date.now() - entry.cachedAt > ttl) {
       try {
-        fs6.unlinkSync(filePath);
+        fs7.unlinkSync(filePath);
       } catch {
       }
       return null;
@@ -10497,7 +10882,7 @@ function getCachedByRequest(endpoint, body) {
 function setCache(key, data, ttlMs) {
   if (ttlMs <= 0) return;
   try {
-    fs6.mkdirSync(CACHE_DIR, { recursive: true });
+    fs7.mkdirSync(CACHE_DIR, { recursive: true });
   } catch {
   }
   const entry = {
@@ -10506,7 +10891,7 @@ function setCache(key, data, ttlMs) {
     ttlMs
   };
   try {
-    fs6.writeFileSync(cachePath(key), JSON.stringify(entry));
+    fs7.writeFileSync(cachePath(key), JSON.stringify(entry));
   } catch {
   }
 }
@@ -10527,7 +10912,7 @@ function readableFilename(endpoint, body) {
 }
 function saveReadable(endpoint, body, response, costUsd) {
   try {
-    fs6.mkdirSync(DATA_DIR, { recursive: true });
+    fs7.mkdirSync(DATA_DIR, { recursive: true });
   } catch {
   }
   const filename = readableFilename(endpoint, body);
@@ -10539,14 +10924,14 @@ function saveReadable(endpoint, body, response, costUsd) {
     response
   };
   try {
-    fs6.writeFileSync(path5.join(DATA_DIR, filename), JSON.stringify(entry, null, 2));
+    fs7.writeFileSync(path6.join(DATA_DIR, filename), JSON.stringify(entry, null, 2));
   } catch {
   }
 }
 function appendCostLog(endpoint, costUsd) {
   if (costUsd <= 0) return;
   try {
-    fs6.mkdirSync(path5.dirname(COST_LOG_FILE2), { recursive: true });
+    fs7.mkdirSync(path6.dirname(COST_LOG_FILE2), { recursive: true });
   } catch {
   }
   const entry = {
@@ -10555,7 +10940,7 @@ function appendCostLog(endpoint, costUsd) {
     cost_usd: costUsd
   };
   try {
-    fs6.appendFileSync(COST_LOG_FILE2, JSON.stringify(entry) + "\n");
+    fs7.appendFileSync(COST_LOG_FILE2, JSON.stringify(entry) + "\n");
   } catch {
   }
 }
@@ -10563,7 +10948,7 @@ function saveToCache(endpoint, body, response, costUsd = 0) {
   const ttl = getTtl(endpoint);
   if (ttl > 0) {
     try {
-      fs6.mkdirSync(CACHE_DIR, { recursive: true });
+      fs7.mkdirSync(CACHE_DIR, { recursive: true });
     } catch {
     }
     const key = cacheKey(endpoint, body);
@@ -10575,7 +10960,7 @@ function saveToCache(endpoint, body, response, costUsd = 0) {
       costUsd
     };
     try {
-      fs6.writeFileSync(cachePath(key), JSON.stringify(entry));
+      fs7.writeFileSync(cachePath(key), JSON.stringify(entry));
     } catch {
     }
   }
@@ -10583,14 +10968,14 @@ function saveToCache(endpoint, body, response, costUsd = 0) {
   appendCostLog(endpoint, costUsd);
 }
 function clearCache() {
-  if (!fs6.existsSync(CACHE_DIR)) return 0;
+  if (!fs7.existsSync(CACHE_DIR)) return 0;
   let count = 0;
   try {
-    const files = fs6.readdirSync(CACHE_DIR);
+    const files = fs7.readdirSync(CACHE_DIR);
     for (const file of files) {
       if (file.endsWith(".json")) {
         try {
-          fs6.unlinkSync(path5.join(CACHE_DIR, file));
+          fs7.unlinkSync(path6.join(CACHE_DIR, file));
           count++;
         } catch {
         }
@@ -10601,14 +10986,14 @@ function clearCache() {
   return count;
 }
 function getCostLogSummary() {
-  if (!fs6.existsSync(COST_LOG_FILE2)) {
+  if (!fs7.existsSync(COST_LOG_FILE2)) {
     return { totalUsd: 0, calls: 0, byEndpoint: {} };
   }
   let totalUsd = 0;
   let calls = 0;
   const byEndpoint = {};
   try {
-    const content = fs6.readFileSync(COST_LOG_FILE2, "utf-8").trim();
+    const content = fs7.readFileSync(COST_LOG_FILE2, "utf-8").trim();
     if (!content) return { totalUsd: 0, calls: 0, byEndpoint: {} };
     for (const line of content.split("\n")) {
       if (!line) continue;
@@ -10628,9 +11013,9 @@ function getCostLogSummary() {
 }
 
 // src/setup.ts
-import { readFileSync as readFileSync6 } from "fs";
+import { readFileSync as readFileSync7 } from "fs";
 import { homedir as homedir5 } from "os";
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 function setupAgentWallet(options) {
   const { address, privateKey, isNew } = getOrCreateWallet();
   if (isNew) {
@@ -10679,7 +11064,7 @@ async function setupAgentClient(options = {}) {
   if (!chain) {
     for (const file of ["payment-chain", ".chain"]) {
       try {
-        const saved = readFileSync6(join6(homedir5(), ".blockrun", file), "utf8").trim();
+        const saved = readFileSync7(join7(homedir5(), ".blockrun", file), "utf8").trim();
         if (saved === "solana" || saved === "base") {
           chain = saved;
           break;