@blockrun/llm 3.20.0 → 3.21.0

package/dist/index.js

@@ -206,7 +206,13 @@ function resolveApiKeyAuth(options) {
   return new ApiKeyAuth(key.trim(), base);
 }
 function accountErrorDisposition(err) {
-  return err instanceof APIError && err.statusCode >= 400 && err.statusCode < 500 ? "unpaid" : "paid-or-in-doubt";
+  if (!(err instanceof APIError)) return "paid-or-in-doubt";
+  if (err.statusCode >= 400 && err.statusCode < 500) return "unpaid";
+  if (err.statusCode >= 500 && hasGatewayErrorEnvelope(err.response)) return "unpaid";
+  return "paid-or-in-doubt";
+}
+function hasGatewayErrorEnvelope(response) {
+  return !!response && typeof response === "object" && typeof response.message === "string" && response.message.length > 0;
 }
 function requireWallet(value) {
   if (value === void 0) throw new Error("This operation requires a wallet; the client uses API key account billing.");
@@ -4558,7 +4564,7 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.20.0";
+var SDK_VERSION = "3.21.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
@@ -9323,11 +9329,11 @@ var WALLET_DIR = path4.join(os3.homedir(), ".blockrun");
 var SOLANA_WALLET_FILE = path4.join(WALLET_DIR, ".solana-session");
 async function createSolanaWallet() {
   const { Keypair } = await loadSolanaWeb3("Solana wallet operations");
-  const bs582 = await import("bs58");
+  const bs583 = await import("bs58");
   const keypair = Keypair.generate();
   return {
     address: keypair.publicKey.toBase58(),
-    privateKey: (bs582.default ?? bs582).encode(keypair.secretKey)
+    privateKey: (bs583.default ?? bs583).encode(keypair.secretKey)
   };
 }
 async function solanaKeyToBytes(privateKey) {
@@ -9365,8 +9371,8 @@ async function solanaKeyToBytes(privateKey) {
     return bytes;
   }
   try {
-    const bs582 = await import("bs58");
-    const bytes = (bs582.default ?? bs582).decode(key);
+    const bs583 = await import("bs58");
+    const bytes = (bs583.default ?? bs583).decode(key);
     if (bytes.length !== 64) {
       throw new Error(`Invalid Solana key length: expected 64 bytes, got ${bytes.length}`);
     }
@@ -9545,12 +9551,52 @@ async function getOrCreateSolanaWallet() {
   return { address, privateKey, isNew: true };
 }
 
+// src/poll-ownership.ts
+import { createPrivateKey, createPublicKey, sign as ed25519Sign } from "crypto";
+import bs58 from "bs58";
+var POLL_AUTH_HEADERS = {
+  wallet: "x-poll-wallet",
+  timestamp: "x-poll-timestamp",
+  signature: "x-poll-signature"
+};
+function pollAuthMessage(kind, jobId, timestampS) {
+  return `blockrun-poll:v1:${kind}:${jobId}:${timestampS}`;
+}
+function pollJobIdFromUrl(pollUrl) {
+  const path7 = new URL(pollUrl, "https://placeholder.invalid").pathname.replace(/\/+$/, "");
+  const segment = path7.slice(path7.lastIndexOf("/") + 1);
+  if (!segment) throw new Error(`poll_url has no job id segment: ${pollUrl}`);
+  return decodeURIComponent(segment);
+}
+var ED25519_PKCS8_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
+function signPollOwnership(secretKey, kind, jobId, nowMs = Date.now()) {
+  if (secretKey.length !== 64 && secretKey.length !== 32) {
+    throw new Error(`Solana secret key must be 64 bytes (or a 32-byte seed), got ${secretKey.length}`);
+  }
+  const seed = Buffer.from(secretKey.subarray(0, 32));
+  const privateKey = createPrivateKey({
+    key: Buffer.concat([ED25519_PKCS8_PREFIX, seed]),
+    format: "der",
+    type: "pkcs8"
+  });
+  const jwk = createPublicKey(privateKey).export({ format: "jwk" });
+  if (!jwk.x) throw new Error("Could not derive the Ed25519 public key");
+  const publicKey = Buffer.from(jwk.x, "base64url");
+  const timestampS = Math.floor(nowMs / 1e3);
+  const signature = ed25519Sign(null, Buffer.from(pollAuthMessage(kind, jobId, timestampS), "utf8"), privateKey);
+  return {
+    [POLL_AUTH_HEADERS.wallet]: bs58.encode(publicKey),
+    [POLL_AUTH_HEADERS.timestamp]: String(timestampS),
+    [POLL_AUTH_HEADERS.signature]: bs58.encode(signature)
+  };
+}
+
 // src/solana-batch.ts
 import { AsyncLocalStorage } from "async_hooks";
 import { randomUUID } from "crypto";
 import * as fs6 from "fs";
 import * as path5 from "path";
-import bs58 from "bs58";
+import bs582 from "bs58";
 var BATCH_SCHEME = "batch-settlement";
 var BLOCKRUN_SOL_OPERATOR = "5YKPQUFjw5WQqhSUkEGKNNfYYVqnRRNbpYyL71qQ1vm3";
 var DEFAULT_BATCH_RATE_LIMIT = { maxAttempts: 3, maxWaitMs: 6e4 };
@@ -10110,7 +10156,7 @@ function decodeChannelAccount(owner, data) {
     return void 0;
   }
   const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
-  const key = (offset) => bs58.encode(data.subarray(offset, offset + 32));
+  const key = (offset) => bs582.encode(data.subarray(offset, offset + 32));
   return {
     deposit: view.getBigUint64(CHANNEL.deposit, true),
     settled: view.getBigUint64(CHANNEL.settled, true),
@@ -11406,7 +11452,7 @@ var SolanaBatchPayer = class {
             cause: await afterPaymentError(response)
           };
         }
-        return { kind: "not_charged", reason: "payment_required", status: status2, depositSafe: false };
+        return { kind: "not_charged", reason: "payment_required", status: status2, errorReason: receipt?.errorReason, depositSafe: provesNothingBroadcast(receipt) };
       }
       const refusal = await batchRefusal(response);
       if (refusal) {
@@ -11670,6 +11716,39 @@ var DEFAULT_MAX_TOKENS2 = 1024;
 var DEFAULT_TIMEOUT14 = 6e4;
 var STALE_BLOCKHASH_RETRY_BACKOFFS_MS = [500, 2e3];
 var MAX_PAYMENT_FAILURE_BYTES = 64 * 1024;
+var DEFAULT_VIDEO_MODEL = "xai/grok-imagine-video";
+var DEFAULT_MUSIC_MODEL = "minimax/music-2.5+";
+var DEFAULT_VIDEO_BUDGET_MS = 9e5;
+var DEFAULT_MUSIC_BUDGET_MS = 3e5;
+var VIDEO_POLL_INTERVAL_MS = 5e3;
+var MAX_PAID_POLL_REFUSALS = 4;
+var MAX_RETRY_AFTER_MS2 = 12e4;
+var MEDIA_SUBMIT_TIMEOUT_MS = 12e4;
+function sleep3(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+async function readJsonOrEmpty(response) {
+  try {
+    const parsed = await response.json();
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function isPendingPollStatus(status2) {
+  return status2 === 202 || status2 === 503 || status2 === 504;
+}
+function retryAfterMs(response) {
+  const raw = response.headers.get("retry-after");
+  if (!raw || !/^\d+$/.test(raw.trim())) return void 0;
+  return Math.min(Number(raw.trim()) * 1e3, MAX_RETRY_AFTER_MS2);
+}
+function pollKindFor(url) {
+  const path7 = new URL(url).pathname;
+  if (path7.includes("/v1/videos")) return "video";
+  if (path7.includes("/v1/audio/")) return "audio";
+  return "image";
+}
 var SafeStaleBlockhashError = class extends PaymentError {
   constructor() {
     super("Payment verification used an expired Solana blockhash; retrying with a fresh quote.");
@@ -12179,6 +12258,54 @@ var SolanaLLMClient = class {
     const data = await this.requestWithPaymentRaw("/v1/images/image2image", body);
     return data;
   }
+  /**
+   * Generate a short video on Solana.
+   *
+   * The POST is verified, not charged. The job is then polled with a wallet
+   * signature (no payment) until it finishes, and ONE payment is signed for
+   * the finished video; a failed job is never charged. If the gateway does not
+   * accept poll signatures for the job, it is polled with a payment per poll
+   * instead, which is likewise only charged on completion.
+   *
+   * @param prompt - text description of the video.
+   * @param options - `model` (default `xai/grok-imagine-video`), `budgetMs`
+   *   (total wait, default 15 min); any other keys are sent verbatim, so use
+   *   the gateway's snake_case names (`duration_seconds`, `image_url`,
+   *   `aspect_ratio`, `resolution`, …).
+   */
+  async video(prompt, options = {}) {
+    const { model, budgetMs, ...rest } = options;
+    const body = { ...rest, model: model || DEFAULT_VIDEO_MODEL, prompt };
+    const data = await this.requestWithPaymentRaw(
+      "/v1/videos/generations",
+      body,
+      { pollBudgetMs: budgetMs ?? DEFAULT_VIDEO_BUDGET_MS, submitTimeoutMs: Math.max(this.timeout, MEDIA_SUBMIT_TIMEOUT_MS) }
+    );
+    return data;
+  }
+  /**
+   * Generate a music track on Solana. Paid at the POST; a slow track is then
+   * polled with a wallet signature, never another payment.
+   *
+   * @param prompt - music style, mood, or description.
+   * @param options - `model` (default `minimax/music-2.5+`), `instrumental`
+   *   (default true), `lyrics` (requires `instrumental: false`), `budgetMs`
+   *   (total wait, default 5 min); other keys are sent verbatim.
+   */
+  async music(prompt, options = {}) {
+    const { model, instrumental: instrumentalOption, lyrics: rawLyrics, budgetMs, ...rest } = options;
+    const instrumental = instrumentalOption ?? true;
+    const lyrics = rawLyrics?.trim();
+    if (instrumental && lyrics) throw new Error("Cannot specify lyrics when instrumental is true");
+    const body = { ...rest, model: model || DEFAULT_MUSIC_MODEL, prompt, instrumental };
+    if (lyrics) body.lyrics = lyrics;
+    const data = await this.requestWithPaymentRaw(
+      "/v1/audio/generations",
+      body,
+      { pollBudgetMs: budgetMs ?? DEFAULT_MUSIC_BUDGET_MS, submitTimeoutMs: Math.max(this.timeout, MEDIA_SUBMIT_TIMEOUT_MS) }
+    );
+    return data;
+  }
   /** Standalone search (Solana payment). */
   async search(query, options) {
     const body = { query, max_results: options?.maxResults || 10 };
@@ -12474,106 +12601,221 @@ var SolanaLLMClient = class {
     }
   }
   /**
-   * 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.
-   */
-  /**
-   * Follow a 202 `{ id, poll_url }` to completion, on Solana **image** routes.
-   *
-   * Two things differ from Base and both come from the same constraint — a
-   * Solana payment is a transaction pinned to a recent blockhash, valid for
-   * ~150 blocks (~60s), and a long render outlives it:
-   *
-   * 1. **The POST already settled.** Base settles on the completed poll; Solana
-   *    cannot, because by then the signed transaction has expired. So sol
-   *    settles optimistically at submit, and this loop only fetches the result.
-   *    The cost is recorded by the caller at POST, never here — recording it on
-   *    completion would lose the charge whenever a paid job then fails.
-   *    Solana VIDEO is the exception: it settles on the completed poll and a
-   *    failed job is not charged. Do not route video through this loop as-is —
-   *    it would book spend for jobs that were never charged.
-   * 2. **Every poll re-signs.** One authorization cannot be replayed across a
-   *    long render. The gateway binds the job to the payer address rather than
-   *    to the signature, so a fresh signature from the same wallet is accepted
-   *    and is never charged again.
+   * Follow a 202 `{ id, poll_url }` to completion on a Solana media route
+   * (image, music, video).
+   *
+   * **Polls prove ownership, they do not pay.** A Solana payment is a
+   * transaction pinned to a recent blockhash (~60s), so paying every poll of a
+   * multi-minute job meant signing a fresh transaction every few seconds. Each
+   * poll here instead carries the `x-poll-*` headers: the submitting wallet's
+   * ed25519 signature over `blockrun-poll:v1:<kind>:<job id>:<unix seconds>`
+   * (see `poll-ownership.ts`). That proof never charges.
+   *
+   * **Who pays when:**
+   * - image / music: the POST already settled (sol settles at submit because the
+   *   signed transaction would be dead by completion). The caller recorded the
+   *   cost at POST; this loop only fetches the result and never signs a payment.
+   *   A batch-billed image job still answers its proof poll with 402: that job
+   *   falls back to the per-poll payment below.
+   * - video: settles on completion, and a failed job is never charged. A
+   *   finished, unpaid job answers the proof poll with 402 `{status:"completed"}`
+   *   and a normal x402 challenge; ONE payment is signed from that challenge and
+   *   the same poll is re-sent with it. The cost is recorded here, on delivery.
+   *   A paid poll the gateway answers 402 (settlement in progress on another
+   *   poll, outcome unknown, stale blockhash) is re-polled after its
+   *   Retry-After — the gateway's per-job settlement claim makes a later fresh
+   *   payment safe — up to `MAX_PAID_POLL_REFUSALS` times.
+   *
+   * **Fallback, once per job:** if the gateway refuses the proof with its "no
+   * such job" answer (video 400, image/music 404) or answers it with a plain
+   * payment challenge (a gateway or job that predates poll proofs), the rest of
+   * this job is polled the old way — an x-payment signed per poll, which the
+   * gateway verifies against the job's payer and does not charge until a video
+   * completes. Logged to stderr; never switches back.
    */
-  async followSolanaJob(submitBody, budgetMs, intervalMs = 2e3) {
+  async followSolanaJob(submitBody, budgetMs, kind, intervalMs = kind === "video" ? VIDEO_POLL_INTERVAL_MS : 2e3) {
     const id = submitBody.id;
     const pollPath = submitBody.poll_url;
     if (!id || !pollPath) return submitBody;
-    const pollUrl = pollPath.startsWith("http") ? pollPath : `${this.apiUrl}${pollPath.startsWith("/") ? "" : "/"}${pollPath}`;
+    const pollUrl = this.resolvePollUrl(pollPath);
+    const jobId = pollJobIdFromUrl(pollUrl);
     const deadline = Date.now() + budgetMs;
     let lastStatus = submitBody.status || "queued";
+    let ownershipPolls = true;
+    let waitMs = intervalMs;
+    let paidRefusalsLeft = MAX_PAID_POLL_REFUSALS;
+    let videoCostUsd;
+    let settleAttempted = false;
+    const fallBack = (why) => {
+      ownershipPolls = false;
+      waitMs = 0;
+      console.warn(
+        `[@blockrun/llm] ${kind} job ${id}: ${why}; falling back to x-payment polling for this job`
+      );
+    };
+    const deliver = (data, response) => {
+      if (kind === "video") {
+        if (videoCostUsd !== void 0) this.recordSettlement(videoCostUsd);
+        const txHash = response.headers.get("x-payment-receipt");
+        if (txHash) data.txHash = txHash;
+      }
+      return data;
+    };
+    const failIfFailed = (data, status2) => {
+      if (lastStatus === "failed") {
+        throw new APIError(
+          `Upstream job failed: ${data.error || "unknown"}`,
+          status2,
+          sanitizeErrorResponse(data)
+        );
+      }
+    };
     while (Date.now() < deadline) {
-      await new Promise((r) => setTimeout(r, intervalMs));
-      const challenge = await this.fetchWithTimeout(pollUrl, {
-        method: "GET",
-        headers: { "User-Agent": USER_AGENT }
-      });
-      if (challenge.status === 200) {
-        const done = await challenge.json();
-        return done;
+      if (waitMs > 0) await sleep3(Math.min(waitMs, Math.max(0, deadline - Date.now())));
+      waitMs = intervalMs;
+      let challenge;
+      if (ownershipPolls) {
+        const proof = signPollOwnership(await solanaKeyToBytes(this.privateKey), kind, jobId);
+        const polled = await this.fetchWithTimeout(pollUrl, {
+          method: "GET",
+          headers: { "User-Agent": USER_AGENT, ...proof }
+        });
+        const data2 = await readJsonOrEmpty(polled);
+        if (polled.status === 402) {
+          if (kind === "video" && data2.status === "completed") {
+            lastStatus = "completed";
+            settleAttempted = true;
+            challenge = new Response(JSON.stringify(data2), { status: 402, headers: polled.headers });
+          } else {
+            fallBack(
+              kind === "image" ? "the gateway asks for a payment on this poll (a batch-billed job, or a gateway without poll proofs)" : "the gateway answered the poll proof with a payment challenge (a gateway without poll proofs)"
+            );
+            continue;
+          }
+        } else if (polled.status === (kind === "video" ? 400 : 404)) {
+          fallBack(`the gateway refused the poll proof (HTTP ${polled.status})`);
+          continue;
+        } else {
+          lastStatus = data2.status || lastStatus;
+          failIfFailed(data2, polled.status);
+          if (polled.status === 200 && lastStatus === "completed") return deliver(data2, polled);
+          if (!isPendingPollStatus(polled.status)) {
+            throw new APIError(`Poll failed: ${polled.status}`, polled.status, sanitizeErrorResponse(data2));
+          }
+          waitMs = retryAfterMs(polled) ?? intervalMs;
+          continue;
+        }
       }
-      if (challenge.status !== 402) {
-        let errorBody;
-        try {
-          errorBody = await challenge.json();
-        } catch {
-          errorBody = { error: "Poll failed" };
+      if (!challenge) {
+        const unpaid = await this.fetchWithTimeout(pollUrl, {
+          method: "GET",
+          headers: { "User-Agent": USER_AGENT }
+        });
+        if (unpaid.status === 200) {
+          return deliver(await unpaid.json(), unpaid);
+        }
+        if (unpaid.status !== 402) {
+          let errorBody;
+          try {
+            errorBody = await unpaid.json();
+          } catch {
+            errorBody = { error: "Poll failed" };
+          }
+          throw new APIError(`Poll failed: ${unpaid.status}`, unpaid.status, sanitizeErrorResponse(errorBody));
         }
-        throw new APIError(`Poll failed: ${challenge.status}`, challenge.status, sanitizeErrorResponse(errorBody));
+        challenge = unpaid;
       }
-      const { paymentPayload } = await this.signPaymentFrom402(
+      const { paymentPayload, costUsd } = await this.signPaymentFrom402(
         pollUrl,
         challenge,
         true,
         // always a fresh blockhash; the last one is stale by now
         pollUrl
       );
-      const paid = await this.fetchWithTimeout(pollUrl, {
-        method: "GET",
-        headers: { "User-Agent": USER_AGENT, "PAYMENT-SIGNATURE": paymentPayload }
-      });
-      let data = {};
+      if (kind === "video") videoCostUsd = costUsd;
+      let paid;
       try {
-        data = await paid.json();
-      } catch {
+        paid = await this.fetchWithTimeout(pollUrl, {
+          method: "GET",
+          headers: { "User-Agent": USER_AGENT, "PAYMENT-SIGNATURE": paymentPayload }
+        });
+      } catch (error) {
+        if (kind === "video" && lastStatus === "completed") settleAttempted = true;
+        if (--paidRefusalsLeft <= 0) {
+          throw withDisposition(
+            new PaymentError(
+              `Paid poll failed in transit (${error instanceof Error ? error.message : String(error)}). The payment may have settled: resume the job by polling ${pollUrl} with the same wallet before submitting again.`
+            ),
+            "paid-or-in-doubt"
+          );
+        }
+        continue;
       }
+      const data = await readJsonOrEmpty(paid);
       lastStatus = data.status || lastStatus;
-      if (lastStatus === "failed") {
-        throw new APIError(
-          `Upstream job failed: ${data.error || "unknown"}`,
-          paid.status,
-          sanitizeErrorResponse(data)
-        );
-      }
-      if (paid.status === 200 && lastStatus === "completed") {
-        return data;
+      failIfFailed(data, paid.status);
+      if (paid.status === 200 && lastStatus === "completed") return deliver(data, paid);
+      if (paid.status === 402 && kind === "video") {
+        if (data.error === "Payment verification failed" && !await isSafeStaleBlockhashResponse(new Response(JSON.stringify(data), { status: 402 }))) {
+          throw new PaymentError(
+            `Payment for the finished video was rejected. Check your Solana USDC balance, then resume the job by polling ${pollUrl} with the same wallet.`
+          );
+        }
+        settleAttempted = true;
+        if (--paidRefusalsLeft <= 0) {
+          throw withDisposition(
+            new PaymentError(
+              `Payment for the finished video did not settle after ${MAX_PAID_POLL_REFUSALS} attempts (last: ${data.error || "HTTP 402"}). It may still settle: resume the job by polling ${pollUrl} with the same wallet before submitting again.`
+            ),
+            "paid-or-in-doubt"
+          );
+        }
+        waitMs = retryAfterMs(paid) ?? intervalMs;
+        continue;
       }
-      if (paid.status !== 200 && paid.status !== 202 && paid.status !== 504) {
+      if (!isPendingPollStatus(paid.status) && paid.status !== 200) {
         throw new APIError(`Poll failed: ${paid.status}`, paid.status, sanitizeErrorResponse(data));
       }
+      waitMs = retryAfterMs(paid) ?? intervalMs;
     }
+    const billing = kind === "video" ? settleAttempted ? "A payment for the finished video was sent and may still settle." : "Nothing was charged: a video is charged only when a completed poll is paid." : "The submit was already paid.";
     throw new APIError(
-      `Job did not complete within ${Math.round(budgetMs / 1e3)}s (last status: ${lastStatus}). No payment was taken.`,
+      `Job did not complete within ${Math.round(budgetMs / 1e3)}s (last status: ${lastStatus}). ${billing} Resume by polling the same poll_url with the same wallet before submitting again.`,
       504,
-      { id, last_status: lastStatus }
+      { id, last_status: lastStatus, poll_url: pollUrl }
     );
   }
+  /**
+   * Absolute URL for a job's `poll_url`. The gateway returns `/api/v1/...`;
+   * {@link buildUrl} drops the `/api` that `apiUrl` already ends with. An
+   * absolute poll_url must be on the gateway's own origin: the poll carries a
+   * wallet signature (and, for a finished video, a payment).
+   */
+  resolvePollUrl(pollPath) {
+    if (!/^https?:\/\//i.test(pollPath)) return this.buildUrl(pollPath);
+    if (new URL(pollPath).origin !== new URL(this.apiUrl).origin) {
+      throw new APIError(`poll_url is not on the gateway origin: ${pollPath}`, 502, { poll_url: pollPath });
+    }
+    return pollPath;
+  }
+  /**
+   * 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) {
     return this.signExactPayment(
       url,
@@ -12663,17 +12905,18 @@ var SolanaLLMClient = class {
     this.recordSettlement(costUsd);
     return this.readPaidJson(retryResponse);
   }
-  async requestWithPaymentRaw(endpoint, body) {
+  async requestWithPaymentRaw(endpoint, body, media = {}) {
     const url = `${this.apiUrl}${endpoint}`;
+    const pollBudgetMs = media.pollBudgetMs ?? this.timeout;
     for (let staleRetries = 0; ; ) {
       const response = await this.fetchWithTimeout(url, {
         method: "POST",
         headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT },
         body: JSON.stringify(body)
-      });
+      }, media.submitTimeoutMs);
       if (response.status === 402) {
         try {
-          return await this.handlePaymentAndRetryRaw(url, body, response, staleRetries > 0);
+          return await this.handlePaymentAndRetryRaw(url, body, response, staleRetries > 0, media);
         } catch (error) {
           if (!(error instanceof SafeStaleBlockhashError) || staleRetries >= STALE_BLOCKHASH_RETRY_BACKOFFS_MS.length) throw error;
           await waitForStaleRetry(staleRetries++);
@@ -12689,26 +12932,38 @@ 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);
+      if (this.apiAuth && /^\/v1\/(images|videos|audio)\//.test(endpoint)) {
+        return this.apiAuth.poll(
+          response,
+          pollBudgetMs,
+          endpoint.startsWith("/v1/videos/") ? VIDEO_POLL_INTERVAL_MS : 2e3
+        );
+      }
       return response.json();
     }
   }
-  async handlePaymentAndRetryRaw(url, body, response, forceFreshBlockhash = false) {
+  async handlePaymentAndRetryRaw(url, body, response, forceFreshBlockhash = false, media = {}) {
     const { paymentPayload, costUsd } = await this.signPaymentFrom402(url, response, forceFreshBlockhash);
-    const retryResponse = await this.fetchWithTimeout(url, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "User-Agent": USER_AGENT,
-        "PAYMENT-SIGNATURE": paymentPayload
-      },
-      body: JSON.stringify(body)
-    });
+    let retryResponse;
+    try {
+      retryResponse = await this.fetchWithTimeout(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "User-Agent": USER_AGENT,
+          "PAYMENT-SIGNATURE": paymentPayload
+        },
+        body: JSON.stringify(body)
+      }, media.submitTimeoutMs);
+    } catch (error) {
+      throw withDisposition(error, "paid-or-in-doubt");
+    }
     await this.assertPaid(retryResponse);
     if (retryResponse.status === 202) {
-      this.recordSettlement(costUsd);
+      const kind = pollKindFor(url);
+      if (kind !== "video") this.recordSettlement(costUsd);
       const submitted = await retryResponse.json();
-      return this.followSolanaJob(submitted, this.timeout);
+      return this.followSolanaJob(submitted, media.pollBudgetMs ?? this.timeout, kind);
     }
     this.recordSettlement(costUsd);
     return retryResponse.json();
@@ -12785,9 +13040,10 @@ var SolanaLLMClient = class {
       } catch {
         errorBody = { error: "Request failed" };
       }
+      const unverified = response.status === 503 && errorBody?.code === "PAYMENT_VERIFICATION_UNAVAILABLE";
       throw withDisposition(
         new APIError(`API error after payment: ${response.status}`, response.status, sanitizeErrorResponse(errorBody)),
-        "paid-or-in-doubt"
+        unverified ? "unpaid" : "paid-or-in-doubt"
       );
     }
   }
@@ -12796,9 +13052,9 @@ var SolanaLLMClient = class {
     this.sessionCalls += 1;
     this.sessionTotalUsd += costUsd;
   }
-  async fetchWithTimeout(url, options) {
+  async fetchWithTimeout(url, options, timeoutMs = this.timeout) {
     const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
     try {
       return await (this.apiAuth ? this.apiAuth.fetch.bind(this.apiAuth) : fetch)(url, { ...options, signal: controller.signal });
     } finally {
@@ -13259,8 +13515,12 @@ var AnthropicClient = class {
         baseURL: this._apiUrl,
         apiKey: "blockrun",
         fetch: this._x402Fetch.bind(this),
-        // Account POSTs may already be billed when an upstream error arrives.
-        ...this.apiAuth ? { maxRetries: 0 } : {}
+        // Never let the Anthropic SDK retry. It retries 408/409/429/5xx and
+        // connection errors by calling this fetch again, which in wallet mode
+        // runs the whole x402 flow and signs a NEW payment each time (three
+        // payments for one call at the default maxRetries of 2); in account
+        // mode the POST itself may already be billed.
+        maxRetries: 0
       });
       return this._client;
     })();

package/package.json

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