@blockrun/llm 3.2.3 → 3.5.0

package/README.md

@@ -165,15 +165,59 @@ const tweet = await client.chat('xai/grok-3-mini', 'What is trending on X?', { s
 **Supported endpoint:** `https://sol.blockrun.ai/api`
 **Payment:** Solana USDC (SPL, mainnet)
 
-## How It Works
+## How Payment Works
 
-1. You send a request to BlockRun's API
-2. The API returns a 402 Payment Required with the price
-3. The SDK automatically signs a USDC payment on Base
-4. The request is retried with the payment proof
-5. You receive the AI response
+No API keys, no subscription. You hold USDC in your own wallet, and **every request pays for itself** with an on-chain micropayment. Two phases:
 
-**Your private key never leaves your machine** - it's only used for local signing.
+### Phase 1 — Fund your wallet once
+
+You only do this when your balance runs low. Three ways to get USDC into your wallet:
+
+- **(a) Buy with a card (Base USDC).** Call the new `onramp()` method to mint a one-time Coinbase Onramp link, then open the returned `pay.coinbase.com` URL — pay by card/bank in 60+ fiat currencies and the USDC lands in your wallet. The call itself is **free**. Onramp is **Base-only** (buying USDC with a card always lands Base USDC), and the funding address must equal your signing wallet:
+
+  ```typescript
+  const { url } = await client.onramp(client.getWalletAddress());
+  console.log(`Fund your wallet: ${url}`);  // single-use, expires ~5 min — mint at click time
+  ```
+
+- **(b) Transfer existing USDC.** Send USDC you already hold to your wallet address (`client.getWalletAddress()`). On Base, send Base USDC; on Solana (`SolanaLLMClient`), send Solana SPL USDC.
+
+- **(c) Skip funding entirely.** Use the free NVIDIA models (e.g. `nvidia/deepseek-v4-flash`) — every call is **$0**, no balance required.
+
+$5 of USDC covers thousands of paid requests. Check your balance any time:
+
+```typescript
+const balance = await client.getBalance();        // USDC on Base
+console.log(`Balance: $${balance.toFixed(2)} USDC`);
+```
+
+### Phase 2 — Every request pays itself (automatic x402)
+
+You just call e.g. `client.chat(...)` — the payment is invisible:
+
+1. You send a request to BlockRun's API.
+2. The gateway returns **402 Payment Required** with the price.
+3. The SDK signs a USDC payment **locally** (EIP-712) — on **Base** for `LLMClient`, on **Solana** for `SolanaLLMClient` — using your wallet key.
+4. The request is retried automatically with the payment proof.
+5. The gateway settles on-chain and returns the AI response.
+
+One call, no separate pay step. Free NVIDIA models settle at **$0** (no payment signed).
+
+### Track spend and verify settlements
+
+```typescript
+import { getCostSummary } from '@blockrun/llm';
+
+const spent = client.getSpending();               // this session
+console.log(`Spent $${spent.totalUsd.toFixed(4)} across ${spent.calls} calls`);
+
+const summary = getCostSummary();                  // across sessions (~/.blockrun/data/costs.jsonl)
+console.log(`Lifetime: $${summary.totalUsd.toFixed(2)} over ${summary.calls} calls`);
+```
+
+Every paid request is a real on-chain USDC transfer — look up your wallet address on [Basescan](https://basescan.org) (or a Solana explorer) to verify each settlement independently.
+
+**Non-custodial by design: your private key never leaves your machine** — it is only used for local signing, and no funds are ever held by BlockRun.
 
 ## Smart Routing (ClawRouter)
 
@@ -298,6 +342,7 @@ Released 2026-04-23 — first fully retrained base since GPT-4.5. 1M context, 12
 ### Anthropic Claude
 | Model | Input Price | Output Price | Context | Notes |
 |-------|-------------|--------------|---------|-------|
+| `anthropic/claude-fable-5` | $10.00/M | $50.00/M | **1M** | Mythos-class flagship above Opus — always-on thinking, 128K output, fallback `claude-opus-4.8`. Alias: `claude-fable-5` |
 | `anthropic/claude-opus-4.8` | $5.00/M | $25.00/M | **1M** | Flagship — agentic coding + adaptive thinking, 128K output |
 | `anthropic/claude-opus-4.7` | $5.00/M | $25.00/M | **1M** | Agentic coding + adaptive thinking, 128K output |
 | `anthropic/claude-opus-4.6` | $5.00/M | $25.00/M | 200K | Hidden but still callable — kept as in-family hot-swap fallback |
@@ -1320,7 +1365,7 @@ const gptResponse = await client.messages.create({
 });
 ```
 
-The `AnthropicClient` wraps the official `@anthropic-ai/sdk` with a custom fetch that handles x402 payment automatically. Your private key never leaves your machine.
+The `AnthropicClient` wraps the official `@anthropic-ai/sdk` with a custom fetch that handles x402 payment automatically. Your private key never leaves your machine. The Mythos-class `claude-fable-5` alias is available here too (1M context, always-on thinking).
 
 ## Links
 

package/dist/index.cjs

@@ -544,7 +544,17 @@ function mapRawToImageModel(m) {
 }
 var DEFAULT_API_URL = "https://blockrun.ai/api";
 var DEFAULT_MAX_TOKENS = 1024;
-var DEFAULT_TIMEOUT = 6e4;
+function resolveDefaultTimeout() {
+  const envVal = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_CHAT_TIMEOUT : void 0;
+  if (envVal !== void 0) {
+    const seconds = Number(envVal);
+    if (Number.isFinite(seconds) && seconds > 0) {
+      return seconds * 1e3;
+    }
+  }
+  return 6e5;
+}
+var DEFAULT_TIMEOUT = resolveDefaultTimeout();
 var SDK_VERSION = "1.5.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 var LLMClient = class _LLMClient {
@@ -1581,6 +1591,40 @@ var LLMClient = class _LLMClient {
     const data = await this.requestWithPaymentRaw("/v1/exa/find-similar", body);
     return data.data;
   }
+  /**
+   * Mint a one-time Coinbase Onramp link to fund this wallet with USDC on Base.
+   *
+   * FREE — the x402 signature only authenticates the wallet (no payment is
+   * charged). Because the funding address must equal the signing wallet, this
+   * mints a `pay.coinbase.com` link prefilled for `address` so a card/bank can
+   * top it up (60+ fiat currencies → Base USDC). Base / USDC only.
+   *
+   * The returned URL is single-use and expires in ~5 minutes — mint it at click
+   * time and never cache it. The funding `address` must match the signing wallet.
+   *
+   * @param address - Destination Base wallet address (0x + 40 hex chars). Must
+   *                  equal the signing wallet that funds it.
+   * @returns `{ url }` — a one-time https://pay.coinbase.com/... link.
+   *
+   * @example
+   * const { url } = await client.onramp(client.getWalletAddress());
+   * console.log(`Fund your wallet: ${url}`);
+   */
+  async onramp(address) {
+    if (!/^0x[0-9a-fA-F]{40}$/.test(address)) {
+      throw new Error("address must be a 0x-prefixed 40-hex-character Base address");
+    }
+    const data = await this.requestWithPaymentRaw("/v1/onramp/token", {
+      address,
+      network: "base",
+      asset: "USDC"
+    });
+    const url = typeof data.url === "string" ? data.url : "";
+    if (!url.startsWith("https://pay.coinbase.com/")) {
+      throw new APIError("gateway returned no onramp url", 502, { message: "gateway returned no onramp url" });
+    }
+    return { url };
+  }
   /**
    * Get USDC balance on Base mainnet.
    *
@@ -2522,8 +2566,9 @@ var DEFAULT_API_URL5 = "https://blockrun.ai/api";
 var DEFAULT_MODEL4 = "xai/grok-imagine-video";
 var DEFAULT_TIMEOUT5 = 12e4;
 var POLL_INTERVAL_MS2 = 5e3;
-var DEFAULT_GENERATE_BUDGET_MS = 3e5;
+var DEFAULT_GENERATE_BUDGET_MS = 9e5;
 var MAX_TIMEOUT_SECONDS = 600;
+var MAX_POLL_RESIGNS = 2;
 var VideoClient = class {
   account;
   privateKey;
@@ -2551,8 +2596,9 @@ var VideoClient = class {
    * Generate a short video clip from a text prompt (or text + image).
    *
    * Submits an async job, then polls until the video is ready. Typical total
-   * wall-time is 60-180s. If upstream runs past the budget (default 5min),
-   * throws without charging.
+   * 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.
    *
    * @param prompt - Text description of the video
    * @param options - Optional generation parameters
@@ -2670,21 +2716,9 @@ var VideoClient = class {
     if (resp402.status !== 402) {
       await this.throwApiError(resp402, "Expected 402 on first POST");
     }
-    const paymentRequired = await this.extractPaymentRequired(resp402);
-    const details = extractPaymentDetails(paymentRequired);
-    const paymentPayload = await createPaymentPayload(
-      this.privateKey,
-      this.account.address,
-      details.recipient,
-      details.amount,
-      details.network || "eip155:8453",
-      {
-        resourceUrl: details.resource?.url || submitUrl,
-        resourceDescription: details.resource?.description || "BlockRun Video Generation",
-        // Ensure signed auth covers the entire polling window.
-        maxTimeoutSeconds: Math.max(details.maxTimeoutSeconds || 0, MAX_TIMEOUT_SECONDS),
-        extra: details.extra
-      }
+    let { payload: paymentPayload, details } = await this.signFromChallenge(
+      resp402,
+      submitUrl
     );
     const submitResp = await this.fetchWithTimeout(submitUrl, {
       method: "POST",
@@ -2711,6 +2745,7 @@ var VideoClient = class {
     const pollUrl = this.absolute(submitData.poll_url);
     const deadline = Date.now() + budgetMs;
     let lastStatus = submitData.status || "queued";
+    let resignsLeft = MAX_POLL_RESIGNS;
     while (Date.now() < deadline) {
       await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS2));
       const pollResp = await this.fetchWithTimeout(pollUrl, {
@@ -2741,15 +2776,55 @@ var VideoClient = class {
         if (txHash) data.txHash = txHash;
         return data;
       }
+      if (pollResp.status === 402) {
+        if (resignsLeft > 0) {
+          resignsLeft--;
+          const challenge = await this.fetchWithTimeout(pollUrl, { method: "GET" });
+          if (challenge.status === 402) {
+            ({ payload: paymentPayload, details } = await this.signFromChallenge(
+              challenge,
+              pollUrl
+            ));
+            continue;
+          }
+        }
+        throw new PaymentError(
+          "Payment verification failed mid-poll (not a signature-expiry). Check the wallet balance and that you poll from the wallet that submitted the job."
+        );
+      }
       if (pollResp.status !== 200 && pollResp.status !== 202 && pollResp.status !== 504) {
         await this.throwApiError(pollResp, "Poll failed");
       }
     }
     throw new APIError(
-      `Video generation did not complete within ${Math.round(budgetMs / 1e3)}s (last status: ${lastStatus}). No payment was taken.`,
+      `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.`,
       504,
-      { id: submitData.id, last_status: lastStatus }
+      { id: submitData.id, last_status: lastStatus, poll_url: pollUrl }
+    );
+  }
+  /**
+   * Parse an x402 challenge response and sign a payment payload for it.
+   * Used for the initial submit AND for mid-poll re-signing after the 600s
+   * authorization window lapses on long polls.
+   */
+  async signFromChallenge(resp402, fallbackUrl) {
+    const paymentRequired = await this.extractPaymentRequired(resp402);
+    const details = extractPaymentDetails(paymentRequired);
+    const payload = await createPaymentPayload(
+      this.privateKey,
+      this.account.address,
+      details.recipient,
+      details.amount,
+      details.network || "eip155:8453",
+      {
+        resourceUrl: details.resource?.url || fallbackUrl,
+        resourceDescription: details.resource?.description || "BlockRun Video Generation",
+        // Ensure signed auth covers as much of the polling window as allowed.
+        maxTimeoutSeconds: Math.max(details.maxTimeoutSeconds || 0, MAX_TIMEOUT_SECONDS),
+        extra: details.extra
+      }
     );
+    return { payload, details };
   }
   absolute(url) {
     if (url.startsWith("http://") || url.startsWith("https://")) return url;
@@ -5739,7 +5814,7 @@ var OpenAI = class {
   constructor(options = {}) {
     const privateKey = options.walletKey || options.privateKey;
     const apiUrl = options.baseURL || "https://blockrun.ai/api";
-    const timeout = options.timeout || 6e4;
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT;
     this.client = new LLMClient({
       privateKey,
       apiUrl,
@@ -5773,7 +5848,7 @@ var AnthropicClient = class {
     const apiUrl = options.apiUrl ?? "https://blockrun.ai/api";
     validateApiUrl(apiUrl);
     this._apiUrl = apiUrl.replace(/\/$/, "");
-    this._timeout = options.timeout ?? 6e4;
+    this._timeout = options.timeout ?? DEFAULT_TIMEOUT;
   }
   async _getClient() {
     if (this._client) return this._client;

package/dist/index.d.cts

@@ -245,7 +245,7 @@ interface LLMClientOptions {
     privateKey?: `0x${string}` | string;
     /** API endpoint URL (default: https://blockrun.ai/api) */
     apiUrl?: string;
-    /** Request timeout in milliseconds (default: 60000) */
+    /** Request timeout in milliseconds (default: 600000 / 600s; override via BLOCKRUN_CHAT_TIMEOUT env, in seconds) */
     timeout?: number;
 }
 /**
@@ -727,6 +727,10 @@ interface ExaFindSimilarOptions {
     /** Exclude pages from the same domain as the reference URL */
     excludeSourceDomain?: boolean;
 }
+interface OnrampResult {
+    /** One-time https://pay.coinbase.com/... URL prefilled for this wallet. */
+    url: string;
+}
 type PriceCategory = "crypto" | "fx" | "commodity" | "usstock" | "stocks";
 type StockMarket = "us" | "hk" | "jp" | "kr" | "gb" | "de" | "fr" | "nl" | "ie" | "lu" | "cn" | "ca";
 type BarResolution = "1" | "5" | "15" | "60" | "240" | "D" | "W" | "M";
@@ -806,7 +810,7 @@ interface PhoneClientOptions {
     privateKey?: `0x${string}` | string;
     /** API endpoint URL (default: https://blockrun.ai/api) */
     apiUrl?: string;
-    /** Request timeout in milliseconds (default: 60000) */
+    /** Request timeout in milliseconds (default: 600000 / 600s; override via BLOCKRUN_CHAT_TIMEOUT env, in seconds) */
     timeout?: number;
 }
 /**
@@ -875,7 +879,7 @@ interface PortraitClientOptions {
     privateKey?: `0x${string}` | string;
     /** API endpoint URL (default: https://blockrun.ai/api) */
     apiUrl?: string;
-    /** Request timeout in milliseconds (default: 60000) */
+    /** Request timeout in milliseconds (default: 600000 / 600s; override via BLOCKRUN_CHAT_TIMEOUT env, in seconds) */
     timeout?: number;
 }
 interface PortraitEnrollOptions {
@@ -1220,6 +1224,26 @@ declare class LLMClient {
      * @param options - Optional filters (numResults, excludeSourceDomain)
      */
     exaFindSimilar(url: string, options?: ExaFindSimilarOptions): Promise<ExaSearchResponse>;
+    /**
+     * Mint a one-time Coinbase Onramp link to fund this wallet with USDC on Base.
+     *
+     * FREE — the x402 signature only authenticates the wallet (no payment is
+     * charged). Because the funding address must equal the signing wallet, this
+     * mints a `pay.coinbase.com` link prefilled for `address` so a card/bank can
+     * top it up (60+ fiat currencies → Base USDC). Base / USDC only.
+     *
+     * The returned URL is single-use and expires in ~5 minutes — mint it at click
+     * time and never cache it. The funding `address` must match the signing wallet.
+     *
+     * @param address - Destination Base wallet address (0x + 40 hex chars). Must
+     *                  equal the signing wallet that funds it.
+     * @returns `{ url }` — a one-time https://pay.coinbase.com/... link.
+     *
+     * @example
+     * const { url } = await client.onramp(client.getWalletAddress());
+     * console.log(`Fund your wallet: ${url}`);
+     */
+    onramp(address: string): Promise<OnrampResult>;
     /**
      * Get USDC balance on Base mainnet.
      *
@@ -1658,7 +1682,8 @@ declare class SpeechClient {
  *   POST /v1/videos/generations         -> 402 -> sign -> 202 { id, poll_url }
  *   GET  /v1/videos/generations/{id}    -> loop until status=completed
  *
- * The client signs ONCE and replays the same PAYMENT-SIGNATURE on every poll.
+ * The client signs once and replays the same PAYMENT-SIGNATURE on every poll,
+ * re-signing automatically if the 600s authorization window lapses mid-poll.
  * Settlement happens only on the first completed poll, so upstream failure or
  * the caller giving up = zero charge.
  *
@@ -1689,8 +1714,9 @@ declare class VideoClient {
      * Generate a short video clip from a text prompt (or text + image).
      *
      * Submits an async job, then polls until the video is ready. Typical total
-     * wall-time is 60-180s. If upstream runs past the budget (default 5min),
-     * throws without charging.
+     * 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.
      *
      * @param prompt - Text description of the video
      * @param options - Optional generation parameters
@@ -1734,6 +1760,12 @@ declare class VideoClient {
         returnLastFrame?: boolean;
     } & Record<string, unknown>): Promise<VideoResponse>;
     private submitAndPoll;
+    /**
+     * Parse an x402 challenge response and sign a payment payload for it.
+     * Used for the initial submit AND for mid-poll re-signing after the 600s
+     * authorization window lapses on long polls.
+     */
+    private signFromChallenge;
     private absolute;
     private extractPaymentRequired;
     private throwApiError;

package/dist/index.d.ts

@@ -245,7 +245,7 @@ interface LLMClientOptions {
     privateKey?: `0x${string}` | string;
     /** API endpoint URL (default: https://blockrun.ai/api) */
     apiUrl?: string;
-    /** Request timeout in milliseconds (default: 60000) */
+    /** Request timeout in milliseconds (default: 600000 / 600s; override via BLOCKRUN_CHAT_TIMEOUT env, in seconds) */
     timeout?: number;
 }
 /**
@@ -727,6 +727,10 @@ interface ExaFindSimilarOptions {
     /** Exclude pages from the same domain as the reference URL */
     excludeSourceDomain?: boolean;
 }
+interface OnrampResult {
+    /** One-time https://pay.coinbase.com/... URL prefilled for this wallet. */
+    url: string;
+}
 type PriceCategory = "crypto" | "fx" | "commodity" | "usstock" | "stocks";
 type StockMarket = "us" | "hk" | "jp" | "kr" | "gb" | "de" | "fr" | "nl" | "ie" | "lu" | "cn" | "ca";
 type BarResolution = "1" | "5" | "15" | "60" | "240" | "D" | "W" | "M";
@@ -806,7 +810,7 @@ interface PhoneClientOptions {
     privateKey?: `0x${string}` | string;
     /** API endpoint URL (default: https://blockrun.ai/api) */
     apiUrl?: string;
-    /** Request timeout in milliseconds (default: 60000) */
+    /** Request timeout in milliseconds (default: 600000 / 600s; override via BLOCKRUN_CHAT_TIMEOUT env, in seconds) */
     timeout?: number;
 }
 /**
@@ -875,7 +879,7 @@ interface PortraitClientOptions {
     privateKey?: `0x${string}` | string;
     /** API endpoint URL (default: https://blockrun.ai/api) */
     apiUrl?: string;
-    /** Request timeout in milliseconds (default: 60000) */
+    /** Request timeout in milliseconds (default: 600000 / 600s; override via BLOCKRUN_CHAT_TIMEOUT env, in seconds) */
     timeout?: number;
 }
 interface PortraitEnrollOptions {
@@ -1220,6 +1224,26 @@ declare class LLMClient {
      * @param options - Optional filters (numResults, excludeSourceDomain)
      */
     exaFindSimilar(url: string, options?: ExaFindSimilarOptions): Promise<ExaSearchResponse>;
+    /**
+     * Mint a one-time Coinbase Onramp link to fund this wallet with USDC on Base.
+     *
+     * FREE — the x402 signature only authenticates the wallet (no payment is
+     * charged). Because the funding address must equal the signing wallet, this
+     * mints a `pay.coinbase.com` link prefilled for `address` so a card/bank can
+     * top it up (60+ fiat currencies → Base USDC). Base / USDC only.
+     *
+     * The returned URL is single-use and expires in ~5 minutes — mint it at click
+     * time and never cache it. The funding `address` must match the signing wallet.
+     *
+     * @param address - Destination Base wallet address (0x + 40 hex chars). Must
+     *                  equal the signing wallet that funds it.
+     * @returns `{ url }` — a one-time https://pay.coinbase.com/... link.
+     *
+     * @example
+     * const { url } = await client.onramp(client.getWalletAddress());
+     * console.log(`Fund your wallet: ${url}`);
+     */
+    onramp(address: string): Promise<OnrampResult>;
     /**
      * Get USDC balance on Base mainnet.
      *
@@ -1658,7 +1682,8 @@ declare class SpeechClient {
  *   POST /v1/videos/generations         -> 402 -> sign -> 202 { id, poll_url }
  *   GET  /v1/videos/generations/{id}    -> loop until status=completed
  *
- * The client signs ONCE and replays the same PAYMENT-SIGNATURE on every poll.
+ * The client signs once and replays the same PAYMENT-SIGNATURE on every poll,
+ * re-signing automatically if the 600s authorization window lapses mid-poll.
  * Settlement happens only on the first completed poll, so upstream failure or
  * the caller giving up = zero charge.
  *
@@ -1689,8 +1714,9 @@ declare class VideoClient {
      * Generate a short video clip from a text prompt (or text + image).
      *
      * Submits an async job, then polls until the video is ready. Typical total
-     * wall-time is 60-180s. If upstream runs past the budget (default 5min),
-     * throws without charging.
+     * 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.
      *
      * @param prompt - Text description of the video
      * @param options - Optional generation parameters
@@ -1734,6 +1760,12 @@ declare class VideoClient {
         returnLastFrame?: boolean;
     } & Record<string, unknown>): Promise<VideoResponse>;
     private submitAndPoll;
+    /**
+     * Parse an x402 challenge response and sign a payment payload for it.
+     * Used for the initial submit AND for mid-poll re-signing after the 600s
+     * authorization window lapses on long polls.
+     */
+    private signFromChallenge;
     private absolute;
     private extractPaymentRequired;
     private throwApiError;

package/dist/index.js

@@ -437,7 +437,17 @@ function mapRawToImageModel(m) {
 }
 var DEFAULT_API_URL = "https://blockrun.ai/api";
 var DEFAULT_MAX_TOKENS = 1024;
-var DEFAULT_TIMEOUT = 6e4;
+function resolveDefaultTimeout() {
+  const envVal = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_CHAT_TIMEOUT : void 0;
+  if (envVal !== void 0) {
+    const seconds = Number(envVal);
+    if (Number.isFinite(seconds) && seconds > 0) {
+      return seconds * 1e3;
+    }
+  }
+  return 6e5;
+}
+var DEFAULT_TIMEOUT = resolveDefaultTimeout();
 var SDK_VERSION = "1.5.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 var LLMClient = class _LLMClient {
@@ -1474,6 +1484,40 @@ var LLMClient = class _LLMClient {
     const data = await this.requestWithPaymentRaw("/v1/exa/find-similar", body);
     return data.data;
   }
+  /**
+   * Mint a one-time Coinbase Onramp link to fund this wallet with USDC on Base.
+   *
+   * FREE — the x402 signature only authenticates the wallet (no payment is
+   * charged). Because the funding address must equal the signing wallet, this
+   * mints a `pay.coinbase.com` link prefilled for `address` so a card/bank can
+   * top it up (60+ fiat currencies → Base USDC). Base / USDC only.
+   *
+   * The returned URL is single-use and expires in ~5 minutes — mint it at click
+   * time and never cache it. The funding `address` must match the signing wallet.
+   *
+   * @param address - Destination Base wallet address (0x + 40 hex chars). Must
+   *                  equal the signing wallet that funds it.
+   * @returns `{ url }` — a one-time https://pay.coinbase.com/... link.
+   *
+   * @example
+   * const { url } = await client.onramp(client.getWalletAddress());
+   * console.log(`Fund your wallet: ${url}`);
+   */
+  async onramp(address) {
+    if (!/^0x[0-9a-fA-F]{40}$/.test(address)) {
+      throw new Error("address must be a 0x-prefixed 40-hex-character Base address");
+    }
+    const data = await this.requestWithPaymentRaw("/v1/onramp/token", {
+      address,
+      network: "base",
+      asset: "USDC"
+    });
+    const url = typeof data.url === "string" ? data.url : "";
+    if (!url.startsWith("https://pay.coinbase.com/")) {
+      throw new APIError("gateway returned no onramp url", 502, { message: "gateway returned no onramp url" });
+    }
+    return { url };
+  }
   /**
    * Get USDC balance on Base mainnet.
    *
@@ -2415,8 +2459,9 @@ var DEFAULT_API_URL5 = "https://blockrun.ai/api";
 var DEFAULT_MODEL4 = "xai/grok-imagine-video";
 var DEFAULT_TIMEOUT5 = 12e4;
 var POLL_INTERVAL_MS2 = 5e3;
-var DEFAULT_GENERATE_BUDGET_MS = 3e5;
+var DEFAULT_GENERATE_BUDGET_MS = 9e5;
 var MAX_TIMEOUT_SECONDS = 600;
+var MAX_POLL_RESIGNS = 2;
 var VideoClient = class {
   account;
   privateKey;
@@ -2444,8 +2489,9 @@ var VideoClient = class {
    * Generate a short video clip from a text prompt (or text + image).
    *
    * Submits an async job, then polls until the video is ready. Typical total
-   * wall-time is 60-180s. If upstream runs past the budget (default 5min),
-   * throws without charging.
+   * 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.
    *
    * @param prompt - Text description of the video
    * @param options - Optional generation parameters
@@ -2563,21 +2609,9 @@ var VideoClient = class {
     if (resp402.status !== 402) {
       await this.throwApiError(resp402, "Expected 402 on first POST");
     }
-    const paymentRequired = await this.extractPaymentRequired(resp402);
-    const details = extractPaymentDetails(paymentRequired);
-    const paymentPayload = await createPaymentPayload(
-      this.privateKey,
-      this.account.address,
-      details.recipient,
-      details.amount,
-      details.network || "eip155:8453",
-      {
-        resourceUrl: details.resource?.url || submitUrl,
-        resourceDescription: details.resource?.description || "BlockRun Video Generation",
-        // Ensure signed auth covers the entire polling window.
-        maxTimeoutSeconds: Math.max(details.maxTimeoutSeconds || 0, MAX_TIMEOUT_SECONDS),
-        extra: details.extra
-      }
+    let { payload: paymentPayload, details } = await this.signFromChallenge(
+      resp402,
+      submitUrl
     );
     const submitResp = await this.fetchWithTimeout(submitUrl, {
       method: "POST",
@@ -2604,6 +2638,7 @@ var VideoClient = class {
     const pollUrl = this.absolute(submitData.poll_url);
     const deadline = Date.now() + budgetMs;
     let lastStatus = submitData.status || "queued";
+    let resignsLeft = MAX_POLL_RESIGNS;
     while (Date.now() < deadline) {
       await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS2));
       const pollResp = await this.fetchWithTimeout(pollUrl, {
@@ -2634,15 +2669,55 @@ var VideoClient = class {
         if (txHash) data.txHash = txHash;
         return data;
       }
+      if (pollResp.status === 402) {
+        if (resignsLeft > 0) {
+          resignsLeft--;
+          const challenge = await this.fetchWithTimeout(pollUrl, { method: "GET" });
+          if (challenge.status === 402) {
+            ({ payload: paymentPayload, details } = await this.signFromChallenge(
+              challenge,
+              pollUrl
+            ));
+            continue;
+          }
+        }
+        throw new PaymentError(
+          "Payment verification failed mid-poll (not a signature-expiry). Check the wallet balance and that you poll from the wallet that submitted the job."
+        );
+      }
       if (pollResp.status !== 200 && pollResp.status !== 202 && pollResp.status !== 504) {
         await this.throwApiError(pollResp, "Poll failed");
       }
     }
     throw new APIError(
-      `Video generation did not complete within ${Math.round(budgetMs / 1e3)}s (last status: ${lastStatus}). No payment was taken.`,
+      `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.`,
       504,
-      { id: submitData.id, last_status: lastStatus }
+      { id: submitData.id, last_status: lastStatus, poll_url: pollUrl }
+    );
+  }
+  /**
+   * Parse an x402 challenge response and sign a payment payload for it.
+   * Used for the initial submit AND for mid-poll re-signing after the 600s
+   * authorization window lapses on long polls.
+   */
+  async signFromChallenge(resp402, fallbackUrl) {
+    const paymentRequired = await this.extractPaymentRequired(resp402);
+    const details = extractPaymentDetails(paymentRequired);
+    const payload = await createPaymentPayload(
+      this.privateKey,
+      this.account.address,
+      details.recipient,
+      details.amount,
+      details.network || "eip155:8453",
+      {
+        resourceUrl: details.resource?.url || fallbackUrl,
+        resourceDescription: details.resource?.description || "BlockRun Video Generation",
+        // Ensure signed auth covers as much of the polling window as allowed.
+        maxTimeoutSeconds: Math.max(details.maxTimeoutSeconds || 0, MAX_TIMEOUT_SECONDS),
+        extra: details.extra
+      }
     );
+    return { payload, details };
   }
   absolute(url) {
     if (url.startsWith("http://") || url.startsWith("https://")) return url;
@@ -5632,7 +5707,7 @@ var OpenAI = class {
   constructor(options = {}) {
     const privateKey = options.walletKey || options.privateKey;
     const apiUrl = options.baseURL || "https://blockrun.ai/api";
-    const timeout = options.timeout || 6e4;
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT;
     this.client = new LLMClient({
       privateKey,
       apiUrl,
@@ -5666,7 +5741,7 @@ var AnthropicClient = class {
     const apiUrl = options.apiUrl ?? "https://blockrun.ai/api";
     validateApiUrl(apiUrl);
     this._apiUrl = apiUrl.replace(/\/$/, "");
-    this._timeout = options.timeout ?? 6e4;
+    this._timeout = options.timeout ?? DEFAULT_TIMEOUT;
   }
   async _getClient() {
     if (this._client) return this._client;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/llm",
-  "version": "3.2.3",
+  "version": "3.5.0",
   "type": "module",
   "description": "BlockRun SDK - Pay-per-request AI (LLM, Image, Video, Music, Voice) via x402 on Base and Solana",
   "main": "dist/index.cjs",