@blockrun/llm 3.14.3 → 3.15.0

package/README.md

@@ -65,7 +65,7 @@ console.log(r.response);         // the proof
 ## Installation
 
 ```bash
-npm install @blockrun/llm   # Base / EVM payments — smart routing included, nothing else needed
+npm install @blockrun/llm   # Account API keys or Base wallets; smart routing included
 ```
 
 <details>
@@ -98,6 +98,8 @@ without them throws an error naming the exact install command.
 
 </details>
 
+The Anthropic SDK is a runtime dependency because the public compatibility wrapper exposes its types. Solana signing dependencies remain optional and are unnecessary for account billing.
+
 ## Quick Start: API Key
 
 1. [Sign up or sign in](https://user.blockrun.ai).
@@ -130,9 +132,14 @@ wallet mode even when `BLOCKRUN_API_KEY` is set; passing both explicit credentia
 is an error. With no explicit credential, `BLOCKRUN_API_KEY` beats the wallet key
 env vars — a process holding both runs in account mode. Invalid or exhausted API keys never fall back to wallet payments.
 Errors preserve `statusCode`, account error `response.code`, and `retryAfter`.
-Account credentials are restricted to the configured origin, including polling.
+Account credentials are restricted to the configured origin, including polling. Account POSTs are not automatically replayed, including through the Anthropic wrapper. GET/HEAD requests can retry temporary gateway errors; accepted jobs keep polling the same job within the original timeout. A 429 returns `retryAfter` to the caller.
+
+Check [Activity](https://user.blockrun.ai/dashboard/activity) for account usage and charges. Chat uses token usage; media and data can use duration, image, or per-request units. When adding credit, the checkout shows the credit amount and total card charge, including any processing fee. Keep API keys in server or local environment variables, never in browser code or logs.
+
+For asynchronous jobs, retain the complete returned `poll_url`, including its query parameters. If polling times out, check the original job and Activity before submitting again.
+
+To switch back to a wallet, unset `BLOCKRUN_API_KEY` and create a new wallet client, or pass an explicit `privateKey` to the appropriate client. Existing clients retain their original credentials; changing a wallet chain does not change account billing.
 
-Use the [account dashboard](https://user.blockrun.ai/dashboard) for account usage.
 `getSpending()` reports x402 settlements only and throws in account mode; wallet
 address/balance helpers require a wallet. Account credit does not sign trades or
 transfer wallet funds. Service availability depends on the account gateway and model.
@@ -1017,8 +1024,7 @@ Generic escape hatches: `client.defi(path, params)`, `client.dex(path, params, b
 `RpcClient` wraps `POST /v1/rpc/{network}` — standard JSON-RPC 2.0 access to
 <!-- br:chains.rpc -->40<!-- /br:chains.rpc --> chains through one endpoint (Ethereum, Base, Solana, Polygon, BSC,
 Arbitrum, Optimism, Avalanche, Bitcoin, Sui, and more; powered by Tatum's RPC
-gateway). No API key, no per-chain endpoints: one flat per-call rate in
-USDC; a JSON-RPC batch charges per element.
+gateway). Use account credits or the selected x402 wallet; no separate Tatum key is needed. A JSON-RPC batch is priced per element.
 
 ```ts
 import { RpcClient } from '@blockrun/llm';
@@ -1233,6 +1239,35 @@ while (true) {
 }
 ```
 
+#### Solana
+
+`SolanaLLMClient.stream()` is the Solana counterpart, with the same shape as
+`BlockrunClient.stream()`: it yields each `data:` frame already parsed as JSON
+and stops at `[DONE]`. The x402 handshake happens before the first frame — 402,
+sign an SPL TransferChecked authorization locally, replay with
+`PAYMENT-SIGNATURE` — including the fresh-blockhash re-sign on a
+verification-phase rejection. A free model, or an account key, is answered `200`
+with no handshake at all and settles nothing.
+
+```typescript
+import { SolanaLLMClient } from '@blockrun/llm';
+
+const client = new SolanaLLMClient(); // SOLANA_WALLET_KEY, or { apiKey: 'brk_live_…' }
+
+for await (const chunk of client.stream('/v1/chat/completions', {
+  model: 'deepseek/deepseek-chat',
+  messages: [{ role: 'user', content: 'Hi' }],
+  max_tokens: 64,
+  stream: true,
+})) {
+  process.stdout.write(chunk?.choices?.[0]?.delta?.content ?? '');
+}
+```
+
+Set `stream: true` yourself — the method does not inject it, because the gateway
+prices a streaming and a non-streaming request the same and rewriting a caller's
+body silently is how you end up debugging a request you did not send.
+
 #### Payment + streaming flow
 
 ```
@@ -1278,7 +1313,7 @@ const [gpt, claude, gemini] = await Promise.all([
 
 ## Prediction Markets (Powered by Predexon)
 
-Access real-time prediction market data from Polymarket, Kalshi, and Binance Futures via [Predexon](https://predexon.com). No API keys needed — pay-per-request via x402.
+Access real-time prediction market data from Polymarket, Kalshi, and Binance Futures via [Predexon](https://predexon.com). Use a BlockRun account API key or x402 wallet payments; no separate Predexon key is needed.
 
 ### Polymarket
 
@@ -1339,7 +1374,7 @@ Works on both `LLMClient` (Base) and `SolanaLLMClient`.
 
 ## Exa Web Search (Powered by Exa)
 
-Access [Exa](https://exa.ai)'s neural web search via x402. No API keys needed — pay-per-request. Available on **`LLMClient` (Base USDC)** and `SolanaLLMClient` (Solana USDC). Use Base as the primary path; the Solana gateway is awaiting `EXA_API_KEY` provisioning.
+Access [Exa](https://exa.ai)'s neural web search using account credits or x402 wallet payments; no separate Exa key is needed. Use `SolanaLLMClient` for a Solana wallet or `LLMClient` for a Base wallet. Availability depends on the selected gateway.
 
 | Method | Description |
 |---|---|

package/dist/index.cjs

@@ -275,6 +275,21 @@ function validateResourceUrl(url, baseUrl) {
 var TRANSIENT_STATUS = /* @__PURE__ */ new Set([502, 503, 504, 522, 524]);
 var TRANSIENT_RETRIES = 2;
 var TRANSIENT_BACKOFF_MS = 1e3;
+function retryDelay(ms, signal) {
+  signal?.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      reject(signal?.reason);
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
 var API_KEY_URL = "https://api.blockrun.ai";
 var PORTAL_URL = "https://user.blockrun.ai";
 function resolveApiKeyAuth(options) {
@@ -324,6 +339,7 @@ var ApiKeyAuth = class {
     headers.set("authorization", `Bearer ${this.#key}`);
     const method = (init?.method ?? request?.method ?? "GET").toUpperCase();
     const retries = method === "GET" || method === "HEAD" ? TRANSIENT_RETRIES : 0;
+    const signal = init?.signal ?? request?.signal;
     let response;
     for (let attempt = 0; ; attempt++) {
       response = await globalThis.fetch(request ? new Request(url, request) : url, {
@@ -332,7 +348,8 @@ var ApiKeyAuth = class {
         redirect: "error"
       });
       if (attempt >= retries || !TRANSIENT_STATUS.has(response.status)) break;
-      await new Promise((resolve) => setTimeout(resolve, TRANSIENT_BACKOFF_MS * (attempt + 1)));
+      await response.body?.cancel();
+      await retryDelay(TRANSIENT_BACKOFF_MS * (attempt + 1), signal);
     }
     if (raiseErrors && !response.ok) {
       let body;
@@ -4600,7 +4617,7 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.14.3";
+var SDK_VERSION = "3.15.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
@@ -6861,7 +6878,7 @@ var VideoClient = class {
    * Submits an async job, then polls until the video is ready. Typical total
    * wall-time is 60-180s, but upstream status can lag several minutes behind
    * actual completion. If upstream runs past the budget (default 15min),
-   * throws without charging — the job stays claimable ~48h via poll_url.
+   * throws with the existing poll URL; check billing before submitting again.
    *
    * @param prompt - Text description of the video
    * @param options - Optional generation parameters
@@ -7061,7 +7078,7 @@ var VideoClient = class {
       }
     }
     throw new APIError(
-      `Video generation did not complete within ${Math.round(budgetMs / 1e3)}s (last status: ${lastStatus}). No payment was taken. The job is NOT lost: it stays claimable for ~48h \u2014 re-GET poll_url with a fresh signature from the same wallet to fetch (and settle) the finished video.`,
+      `Video generation did not complete within ${Math.round(budgetMs / 1e3)}s (last status: ${lastStatus}). A polling timeout does not confirm billing status. Resume the existing poll_url using the same account or wallet; check account Activity or wallet receipts before submitting another job.`,
       504,
       { id: submitData.id, last_status: lastStatus, poll_url: pollUrl }
     );
@@ -8553,6 +8570,35 @@ var RpcClient = class {
   }
 };
 
+// src/sse.ts
+async function* readSseFrames(response, onMissingBody) {
+  if (!response.body) throw onMissingBody(response.status);
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() || "";
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || !trimmed.startsWith("data: ")) continue;
+        const data = trimmed.slice(6);
+        if (data === "[DONE]") return;
+        try {
+          yield JSON.parse(data);
+        } catch {
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
 // src/blockrun.ts
 var import_accounts14 = require("viem/accounts");
 var DEFAULT_API_URL13 = "https://blockrun.ai/api";
@@ -8762,33 +8808,10 @@ var BlockrunClient = class {
       await this.throwApiError(resp402, `stream failed (${url})`);
       return;
     }
-    if (!streamResp.body) {
-      throw new APIError("Stream response has no body", streamResp.status, {});
-    }
-    const reader = streamResp.body.getReader();
-    const decoder = new TextDecoder();
-    let buffer = "";
-    try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        buffer += decoder.decode(value, { stream: true });
-        const lines = buffer.split("\n");
-        buffer = lines.pop() || "";
-        for (const line of lines) {
-          const trimmed = line.trim();
-          if (!trimmed || !trimmed.startsWith("data: ")) continue;
-          const data = trimmed.slice(6);
-          if (data === "[DONE]") return;
-          try {
-            yield JSON.parse(data);
-          } catch {
-          }
-        }
-      }
-    } finally {
-      reader.releaseLock();
-    }
+    yield* readSseFrames(
+      streamResp,
+      (status2) => new APIError("Stream response has no body", status2, {})
+    );
   }
   // --------------------------------------------------------------------
   // Internal: shared infrastructure
@@ -9719,6 +9742,123 @@ var SolanaLLMClient = class {
     response.routing = decision;
     return { response, model: decision.model, routing: decision };
   }
+  /**
+   * Stream a Server-Sent Events endpoint, paid on Solana.
+   *
+   * The Solana counterpart to `BlockrunClient.stream`, and the reason it had to
+   * exist: a streaming harness cannot use this client at all without it, so
+   * "BlockRun supports Solana" stopped being true the moment a caller streamed.
+   * `chatCompletion` buffers the whole answer, which is the wrong shape for an
+   * agent loop and for anything that shows tokens as they arrive.
+   *
+   * The handshake is the one the non-streaming paths use — `402`, sign an SPL
+   * TransferChecked authorization locally, replay with `PAYMENT-SIGNATURE` —
+   * with the same verification-phase re-sign on a stale blockhash. What differs
+   * is that the paid response is not read as JSON: it is handed to the SSE
+   * reader with its body untouched.
+   *
+   * A `200` on the first request is returned as-is and settles nothing. That is
+   * the free tier (the gateway answers a `billing_mode: "free"` model without a
+   * 402 at all) and it is also API-key mode, where billing is on the account
+   * rather than on a wallet.
+   *
+   * Yields each `data:` frame parsed as JSON, and stops at `data: [DONE]`.
+   * Malformed frames are skipped rather than thrown — see {@link readSseFrames}.
+   *
+   * @example
+   * for await (const chunk of client.stream<ChatChunk>("/v1/chat/completions", {
+   *   model: "deepseek/deepseek-chat",
+   *   messages: [{ role: "user", content: "Hi" }],
+   *   stream: true,
+   * })) {
+   *   process.stdout.write(chunk.choices?.[0]?.delta?.content ?? "");
+   * }
+   *
+   * @param path - endpoint after the API root; a leading `/api` is tolerated.
+   * @param body - JSON request body. Set `stream: true` yourself — this method
+   *   does not inject it, because the gateway prices a streaming and a
+   *   non-streaming request the same and silently rewriting a caller's body is
+   *   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);
+    const response = await this.openPaidStream(url, JSON.stringify(body ?? {}));
+    yield* readSseFrames(
+      response,
+      (status2) => new APIError("Stream response has no body", status2, {})
+    );
+  }
+  /**
+   * Get to a streaming response, paying for it if the gateway asks.
+   *
+   * Separate from {@link SolanaLLMClient.stream} because a generator cannot
+   * retry cleanly around a `yield`: the stale-blockhash re-sign has to finish
+   * before the first frame is handed out, and putting the loop here keeps the
+   * payment decision entirely ahead of any output the caller has seen.
+   *
+   * @param url - resolved endpoint URL.
+   * @param requestBody - the serialized body, reused verbatim on the paid retry
+   *   so the gateway prices and answers the same request it quoted for.
+   * @returns a response whose body has not been read.
+   */
+  async openPaidStream(url, requestBody) {
+    for (let staleRetries = 0; ; ) {
+      const response = await this.fetchWithTimeout(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT },
+        body: requestBody
+      });
+      if (response.ok) return response;
+      if (response.status !== 402) {
+        let errorBody;
+        try {
+          errorBody = await response.json();
+        } catch {
+          errorBody = { error: "Request failed" };
+        }
+        throw new APIError(`API error: ${response.status}`, response.status, sanitizeErrorResponse(errorBody));
+      }
+      try {
+        const { paymentPayload, costUsd } = await this.signPaymentFrom402(
+          url,
+          response,
+          staleRetries > 0
+        );
+        const paid = await this.fetchWithTimeout(url, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "User-Agent": USER_AGENT,
+            "PAYMENT-SIGNATURE": paymentPayload
+          },
+          body: requestBody
+        });
+        await this.assertPaid(paid);
+        this.recordSettlement(costUsd);
+        return paid;
+      } catch (error) {
+        if (!(error instanceof SafeStaleBlockhashError) || staleRetries >= STALE_BLOCKHASH_RETRY_BACKOFFS_MS.length) throw error;
+        await waitForStaleRetry(staleRetries++);
+        continue;
+      }
+    }
+  }
+  /**
+   * Resolve an endpoint path against this client's API root.
+   *
+   * A leading `/api` is stripped for the same reason `BlockrunClient` strips
+   * it: the documented paths are written `/api/v1/…` on the website and
+   * `/v1/…` in this SDK, and a caller who copies one into the other should get
+   * their request rather than a 404.
+   * @param path - endpoint path, with or without a leading slash.
+   * @returns the absolute URL to call.
+   */
+  buildUrl(path6) {
+    let normalized = path6.startsWith("/") ? path6 : `/${path6}`;
+    if (normalized.startsWith("/api/")) normalized = normalized.slice(4);
+    return `${this.apiUrl}${normalized}`;
+  }
   /** List available models. */
   async listModels() {
     const response = await this.fetchWithTimeout(`${this.apiUrl}/v1/models`, { method: "GET" });
@@ -9989,7 +10129,25 @@ var SolanaLLMClient = class {
       return response.json();
     }
   }
-  async handlePaymentAndRetry(url, body, response, forceFreshBlockhash = false) {
+  /**
+   * Turn a `402` into a signed Solana payment payload.
+   *
+   * Extracted because four call sites need it — chat, the raw POST helpers, the
+   * raw GET helper, and {@link SolanaLLMClient.stream} — and it had been
+   * written out three times before this. That mattered more than ordinary
+   * duplication: this is the code that signs a transfer of the caller's USDC,
+   * so three copies meant every fix to it had to be applied three times or
+   * quietly apply to two thirds of the paths.
+   *
+   * @param url - the request being paid for.
+   * @param response - the gateway's `402`, not yet consumed.
+   * @param forceFreshBlockhash - set on a re-sign after a stale-blockhash
+   *   rejection, so the retry cannot produce byte-identical transaction bytes.
+   * @param resourceFallback - resource URL to claim when the 402 states none.
+   * @returns the header value to replay with, and what it will settle for.
+   * @throws PaymentError when the 402 carries no usable Solana requirements.
+   */
+  async signPaymentFrom402(url, response, forceFreshBlockhash, resourceFallback = url) {
     let paymentHeader = response.headers.get("payment-required");
     if (!paymentHeader) {
       try {
@@ -10023,7 +10181,7 @@ var SolanaLLMClient = class {
       feePayer,
       {
         resourceUrl: validateResourceUrl(
-          details.resource?.url || `${this.apiUrl}/v1/chat/completions`,
+          details.resource?.url || resourceFallback,
           this.apiUrl
         ),
         resourceDescription: details.resource?.description || "BlockRun Solana AI API call",
@@ -10035,6 +10193,15 @@ var SolanaLLMClient = class {
         forceFreshBlockhash
       }
     );
+    return { paymentPayload, costUsd: parseFloat(details.amount) / 1e6 };
+  }
+  async handlePaymentAndRetry(url, body, response, forceFreshBlockhash = false) {
+    const { paymentPayload, costUsd } = await this.signPaymentFrom402(
+      url,
+      response,
+      forceFreshBlockhash,
+      `${this.apiUrl}/v1/chat/completions`
+    );
     const retryResponse = await this.fetchWithTimeout(url, {
       method: "POST",
       headers: {
@@ -10044,24 +10211,8 @@ var SolanaLLMClient = class {
       },
       body: JSON.stringify(body)
     });
-    if (retryResponse.status === 402) {
-      if (await isSafeStaleBlockhashResponse(retryResponse)) {
-        throw new SafeStaleBlockhashError();
-      }
-      throw new PaymentError("Payment was rejected. Check your Solana USDC balance.");
-    }
-    if (!retryResponse.ok) {
-      let errorBody;
-      try {
-        errorBody = await retryResponse.json();
-      } catch {
-        errorBody = { error: "Request failed" };
-      }
-      throw new APIError(`API error after payment: ${retryResponse.status}`, retryResponse.status, sanitizeErrorResponse(errorBody));
-    }
-    const costUsd = parseFloat(details.amount) / 1e6;
-    this.sessionCalls += 1;
-    this.sessionTotalUsd += costUsd;
+    await this.assertPaid(retryResponse);
+    this.recordSettlement(costUsd);
     return retryResponse.json();
   }
   async requestWithPaymentRaw(endpoint, body) {
@@ -10095,51 +10246,7 @@ var SolanaLLMClient = class {
     }
   }
   async handlePaymentAndRetryRaw(url, body, response, forceFreshBlockhash = false) {
-    let paymentHeader = response.headers.get("payment-required");
-    if (!paymentHeader) {
-      try {
-        const respBody = await response.json();
-        if (respBody.accepts || respBody.x402Version) {
-          paymentHeader = btoa(JSON.stringify(respBody));
-        }
-      } catch {
-      }
-    }
-    if (!paymentHeader) {
-      throw new PaymentError("402 response but no payment requirements found");
-    }
-    const paymentRequired = parsePaymentRequired(paymentHeader);
-    const details = extractPaymentDetails(paymentRequired, SOLANA_NETWORK);
-    if (!details.network?.startsWith("solana:")) {
-      throw new PaymentError(
-        `Expected Solana payment network, got: ${details.network}. Use LLMClient for Base payments.`
-      );
-    }
-    const feePayer = details.extra?.feePayer;
-    if (!feePayer) throw new PaymentError("Missing feePayer in 402 extra field");
-    const fromAddress = await this.getWalletAddress();
-    const secretKey = await solanaKeyToBytes(this.privateKey);
-    const extensions = paymentRequired.extensions;
-    const paymentPayload = await createSolanaPaymentPayload(
-      secretKey,
-      fromAddress,
-      details.recipient,
-      details.amount,
-      feePayer,
-      {
-        resourceUrl: validateResourceUrl(
-          details.resource?.url || url,
-          this.apiUrl
-        ),
-        resourceDescription: details.resource?.description || "BlockRun Solana AI API call",
-        maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
-        extra: details.extra,
-        extensions,
-        rpcUrl: this.rpcUrl,
-        rpcHeaders: this.rpcHeaders,
-        forceFreshBlockhash
-      }
-    );
+    const { paymentPayload, costUsd } = await this.signPaymentFrom402(url, response, forceFreshBlockhash);
     const retryResponse = await this.fetchWithTimeout(url, {
       method: "POST",
       headers: {
@@ -10149,24 +10256,8 @@ var SolanaLLMClient = class {
       },
       body: JSON.stringify(body)
     });
-    if (retryResponse.status === 402) {
-      if (await isSafeStaleBlockhashResponse(retryResponse)) {
-        throw new SafeStaleBlockhashError();
-      }
-      throw new PaymentError("Payment was rejected. Check your Solana USDC balance.");
-    }
-    if (!retryResponse.ok) {
-      let errorBody;
-      try {
-        errorBody = await retryResponse.json();
-      } catch {
-        errorBody = { error: "Request failed" };
-      }
-      throw new APIError(`API error after payment: ${retryResponse.status}`, retryResponse.status, sanitizeErrorResponse(errorBody));
-    }
-    const costUsd = parseFloat(details.amount) / 1e6;
-    this.sessionCalls += 1;
-    this.sessionTotalUsd += costUsd;
+    await this.assertPaid(retryResponse);
+    this.recordSettlement(costUsd);
     return retryResponse.json();
   }
   async getWithPaymentRaw(endpoint, params) {
@@ -10199,51 +10290,7 @@ var SolanaLLMClient = class {
     }
   }
   async handleGetPaymentAndRetryRaw(url, endpoint, params, response, forceFreshBlockhash = false) {
-    let paymentHeader = response.headers.get("payment-required");
-    if (!paymentHeader) {
-      try {
-        const respBody = await response.json();
-        if (respBody.accepts || respBody.x402Version) {
-          paymentHeader = btoa(JSON.stringify(respBody));
-        }
-      } catch {
-      }
-    }
-    if (!paymentHeader) {
-      throw new PaymentError("402 response but no payment requirements found");
-    }
-    const paymentRequired = parsePaymentRequired(paymentHeader);
-    const details = extractPaymentDetails(paymentRequired, SOLANA_NETWORK);
-    if (!details.network?.startsWith("solana:")) {
-      throw new PaymentError(
-        `Expected Solana payment network, got: ${details.network}. Use LLMClient for Base payments.`
-      );
-    }
-    const feePayer = details.extra?.feePayer;
-    if (!feePayer) throw new PaymentError("Missing feePayer in 402 extra field");
-    const fromAddress = await this.getWalletAddress();
-    const secretKey = await solanaKeyToBytes(this.privateKey);
-    const extensions = paymentRequired.extensions;
-    const paymentPayload = await createSolanaPaymentPayload(
-      secretKey,
-      fromAddress,
-      details.recipient,
-      details.amount,
-      feePayer,
-      {
-        resourceUrl: validateResourceUrl(
-          details.resource?.url || url,
-          this.apiUrl
-        ),
-        resourceDescription: details.resource?.description || "BlockRun Solana AI API call",
-        maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
-        extra: details.extra,
-        extensions,
-        rpcUrl: this.rpcUrl,
-        rpcHeaders: this.rpcHeaders,
-        forceFreshBlockhash
-      }
-    );
+    const { paymentPayload, costUsd } = await this.signPaymentFrom402(url, response, forceFreshBlockhash);
     const query = params ? "?" + new URLSearchParams(params).toString() : "";
     const retryUrl = `${this.apiUrl}${endpoint}${query}`;
     const retryResponse = await this.fetchWithTimeout(retryUrl, {
@@ -10253,25 +10300,44 @@ var SolanaLLMClient = class {
         "PAYMENT-SIGNATURE": paymentPayload
       }
     });
-    if (retryResponse.status === 402) {
-      if (await isSafeStaleBlockhashResponse(retryResponse)) {
+    await this.assertPaid(retryResponse);
+    this.recordSettlement(costUsd);
+    return retryResponse.json();
+  }
+  /**
+   * Fail a post-payment response, telling a re-signable rejection from a real one.
+   *
+   * A `402` here is not "pay again": it is the gateway refusing the payment we
+   * just signed. Only a rejection the gateway attributes to the VERIFICATION
+   * phase is safe to re-sign — anything settled, or ambiguous about which
+   * phase it failed in, could already have moved USDC, and re-signing it would
+   * pay twice. {@link isSafeStaleBlockhashResponse} is where that judgement
+   * lives.
+   * @param response - the reply to the paid request.
+   * @throws SafeStaleBlockhashError when the caller should re-sign, PaymentError
+   *   when it should not, APIError for any other failure.
+   */
+  async assertPaid(response) {
+    if (response.status === 402) {
+      if (await isSafeStaleBlockhashResponse(response)) {
         throw new SafeStaleBlockhashError();
       }
       throw new PaymentError("Payment was rejected. Check your Solana USDC balance.");
     }
-    if (!retryResponse.ok) {
+    if (!response.ok) {
       let errorBody;
       try {
-        errorBody = await retryResponse.json();
+        errorBody = await response.json();
       } catch {
         errorBody = { error: "Request failed" };
       }
-      throw new APIError(`API error after payment: ${retryResponse.status}`, retryResponse.status, sanitizeErrorResponse(errorBody));
+      throw new APIError(`API error after payment: ${response.status}`, response.status, sanitizeErrorResponse(errorBody));
     }
-    const costUsd = parseFloat(details.amount) / 1e6;
+  }
+  /** Count one settled x402 payment against the session total. */
+  recordSettlement(costUsd) {
     this.sessionCalls += 1;
     this.sessionTotalUsd += costUsd;
-    return retryResponse.json();
   }
   async fetchWithTimeout(url, options) {
     const controller = new AbortController();
@@ -10675,7 +10741,8 @@ var OpenAI = class {
   }
   client;
   constructor(options = {}) {
-    const privateKey = options.walletKey || options.privateKey;
+    const aliases = [options.walletKey, options.privateKey].filter((k) => k !== void 0);
+    const privateKey = aliases.find((k) => k !== "") ?? aliases[0];
     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({
@@ -10734,7 +10801,9 @@ var AnthropicClient = class {
       this._client = new Anthropic({
         baseURL: this._apiUrl,
         apiKey: "blockrun",
-        fetch: this._x402Fetch.bind(this)
+        fetch: this._x402Fetch.bind(this),
+        // Account POSTs may already be billed when an upstream error arrives.
+        ...this.apiAuth ? { maxRetries: 0 } : {}
       });
       return this._client;
     })();
@@ -10743,6 +10812,10 @@ var AnthropicClient = class {
   async _x402Fetch(input, init) {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this._timeout);
+    const callerSignal = init?.signal ?? (input instanceof Request ? input.signal : void 0);
+    const onAbort = () => controller.abort(callerSignal?.reason);
+    callerSignal?.addEventListener("abort", onAbort, { once: true });
+    if (callerSignal?.aborted) onAbort();
     try {
       const mergedInit = { ...init, signal: controller.signal };
       if (this.apiAuth) return await this.apiAuth.fetch(input, mergedInit, false);
@@ -10796,6 +10869,7 @@ var AnthropicClient = class {
       }
       return response;
     } finally {
+      callerSignal?.removeEventListener("abort", onAbort);
       clearTimeout(timeoutId);
     }
   }