@blockrun/llm 2.0.0 → 2.1.1

package/dist/index.cjs

@@ -48,6 +48,7 @@ __export(index_exports, {
   USDC_BASE: () => USDC_BASE,
   USDC_BASE_CONTRACT: () => USDC_BASE_CONTRACT,
   USDC_SOLANA: () => USDC_SOLANA,
+  VideoClient: () => VideoClient,
   WALLET_DIR_PATH: () => WALLET_DIR_PATH,
   WALLET_FILE_PATH: () => WALLET_FILE_PATH,
   XClient: () => XClient,
@@ -619,9 +620,6 @@ var LLMClient = class _LLMClient {
    *
    * @example With routing profile
    * ```ts
-   * // Free tier only (zero cost)
-   * const result = await client.smartChat('Hello!', { routingProfile: 'free' });
-   *
    * // Eco mode (budget optimized)
    * const result = await client.smartChat('Explain quantum computing', { routingProfile: 'eco' });
    *
@@ -781,6 +779,28 @@ var LLMClient = class _LLMClient {
     } catch {
     }
   }
+  /**
+   * Parse the chat response JSON and attach `fallback` metadata when the
+   * gateway signalled a transparent free-fallback substitution. The
+   * gateway sets X-Fallback-Used / X-Fallback-Model / X-Settlement-Skipped
+   * on the response when it served a paid request from a free model
+   * (route.ts createPaymentResponseHeader path). Without surfacing these
+   * to the caller, the user gets a different model than requested with
+   * no visibility — silent quality drop and no clue why the on-chain
+   * balance didn't change.
+   */
+  async parseChatResponse(response) {
+    const body = await response.json();
+    const used = response.headers.get("X-Fallback-Used") === "true";
+    if (used) {
+      body.fallback = {
+        used: true,
+        model: response.headers.get("X-Fallback-Model") || void 0,
+        settlementSkipped: response.headers.get("X-Settlement-Skipped") === "free-fallback"
+      };
+    }
+    return body;
+  }
   /**
    * Make a request with automatic x402 payment handling.
    */
@@ -809,7 +829,7 @@ var LLMClient = class _LLMClient {
           }
           throw new APIError(`API error: ${retryResp.status}`, retryResp.status, sanitizeErrorResponse(errorBody));
         }
-        return retryResp.json();
+        return this.parseChatResponse(retryResp);
       }
     }
     if (response.status === 402) {
@@ -828,7 +848,7 @@ var LLMClient = class _LLMClient {
         sanitizeErrorResponse(errorBody)
       );
     }
-    return response.json();
+    return this.parseChatResponse(response);
   }
   /**
    * Handle 402 response: parse requirements, sign payment, retry.
@@ -903,7 +923,7 @@ var LLMClient = class _LLMClient {
         this.sessionCalls += 1;
         this.sessionTotalUsd += costUsd2;
         this.recordCost(url, costUsd2, { body, network: details.network });
-        return retryResp2.json();
+        return this.parseChatResponse(retryResp2);
       }
     }
     if (retryResponse.status === 402) {
@@ -926,7 +946,7 @@ var LLMClient = class _LLMClient {
     this.sessionCalls += 1;
     this.sessionTotalUsd += costUsd;
     this.recordCost(url, costUsd, { body, network: details.network });
-    return retryResponse.json();
+    return this.parseChatResponse(retryResponse);
   }
   /**
    * Sign a payment header and return the PAYMENT-SIGNATURE value.
@@ -2344,15 +2364,21 @@ var MusicClient = class {
   }
 };
 
-// src/search.ts
+// src/video.ts
 var import_accounts5 = require("viem/accounts");
 var DEFAULT_API_URL4 = "https://blockrun.ai/api";
-var DEFAULT_TIMEOUT4 = 6e4;
-var SearchClient = class {
+var DEFAULT_MODEL3 = "xai/grok-imagine-video";
+var DEFAULT_TIMEOUT4 = 12e4;
+var POLL_INTERVAL_MS2 = 5e3;
+var DEFAULT_GENERATE_BUDGET_MS = 3e5;
+var MAX_TIMEOUT_SECONDS = 600;
+var VideoClient = class {
   account;
   privateKey;
   apiUrl;
   timeout;
+  sessionTotalUsd = 0;
+  sessionCalls = 0;
   constructor(options = {}) {
     const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
     const privateKey = options.privateKey || envKey;
@@ -2369,6 +2395,193 @@ var SearchClient = class {
     this.apiUrl = apiUrl.replace(/\/$/, "");
     this.timeout = options.timeout || DEFAULT_TIMEOUT4;
   }
+  /**
+   * 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.
+   *
+   * @param prompt - Text description of the video
+   * @param options - Optional generation parameters
+   */
+  async generate(prompt, options) {
+    const body = {
+      model: options?.model || DEFAULT_MODEL3,
+      prompt
+    };
+    if (options?.imageUrl) body.image_url = options.imageUrl;
+    if (options?.durationSeconds !== void 0) body.duration_seconds = options.durationSeconds;
+    const budgetMs = options?.budgetMs ?? DEFAULT_GENERATE_BUDGET_MS;
+    return this.submitAndPoll(body, budgetMs);
+  }
+  // --------------------------------------------------------------------
+  // Internal: async submit + poll
+  // --------------------------------------------------------------------
+  async submitAndPoll(body, budgetMs) {
+    const submitUrl = `${this.apiUrl}/v1/videos/generations`;
+    const resp402 = await this.fetchWithTimeout(submitUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    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
+      }
+    );
+    const submitResp = await this.fetchWithTimeout(submitUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "PAYMENT-SIGNATURE": paymentPayload
+      },
+      body: JSON.stringify(body)
+    });
+    if (submitResp.status === 402) {
+      throw new PaymentError("Payment was rejected. Check your wallet balance.");
+    }
+    if (submitResp.status !== 200 && submitResp.status !== 202) {
+      await this.throwApiError(submitResp, "Submit failed");
+    }
+    const submitData = await submitResp.json();
+    if (!submitData.id || !submitData.poll_url) {
+      throw new APIError(
+        "Submit response missing id/poll_url",
+        submitResp.status,
+        { response: submitData }
+      );
+    }
+    const pollUrl = this.absolute(submitData.poll_url);
+    const deadline = Date.now() + budgetMs;
+    let lastStatus = submitData.status || "queued";
+    while (Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS2));
+      const pollResp = await this.fetchWithTimeout(pollUrl, {
+        method: "GET",
+        headers: { "PAYMENT-SIGNATURE": paymentPayload }
+      });
+      let pollData = {};
+      try {
+        pollData = await pollResp.json();
+      } catch {
+      }
+      lastStatus = pollData.status || lastStatus;
+      if (pollResp.status === 202 && (lastStatus === "queued" || lastStatus === "in_progress")) {
+        continue;
+      }
+      if (lastStatus === "failed") {
+        throw new APIError(
+          `Upstream generation failed: ${pollData.error || "unknown"}`,
+          pollResp.status,
+          sanitizeErrorResponse(pollData)
+        );
+      }
+      if (pollResp.status === 200 && lastStatus === "completed") {
+        const data = pollData;
+        const billedSeconds = typeof body.duration_seconds === "number" ? body.duration_seconds : 8;
+        this.sessionCalls++;
+        this.sessionTotalUsd += 0.05 * billedSeconds * 1.05;
+        const txHash = pollResp.headers.get("x-payment-receipt") || pollResp.headers.get("X-Payment-Receipt");
+        if (txHash) data.txHash = txHash;
+        return data;
+      }
+      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.`,
+      504,
+      { id: submitData.id, last_status: lastStatus }
+    );
+  }
+  absolute(url) {
+    if (url.startsWith("http://") || url.startsWith("https://")) return url;
+    const base = this.apiUrl.endsWith("/api") ? this.apiUrl.slice(0, -"/api".length) : this.apiUrl;
+    return `${base}${url}`;
+  }
+  async extractPaymentRequired(resp) {
+    const header = resp.headers.get("payment-required");
+    if (header) return parsePaymentRequired(header);
+    try {
+      const body = await resp.json();
+      if (body && (body.x402Version !== void 0 || body.accepts !== void 0)) {
+        return body;
+      }
+    } catch {
+    }
+    throw new PaymentError("402 response but no payment requirements found");
+  }
+  async throwApiError(resp, prefix) {
+    let errorBody;
+    try {
+      errorBody = await resp.json();
+    } catch {
+      errorBody = { error: "Request failed" };
+    }
+    throw new APIError(
+      `${prefix}: HTTP ${resp.status}`,
+      resp.status,
+      sanitizeErrorResponse(errorBody)
+    );
+  }
+  async fetchWithTimeout(url, options) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      return await fetch(url, { ...options, signal: controller.signal });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  getWalletAddress() {
+    return this.account.address;
+  }
+  getSpending() {
+    return { totalUsd: this.sessionTotalUsd, calls: this.sessionCalls };
+  }
+};
+
+// src/search.ts
+var import_accounts6 = require("viem/accounts");
+var DEFAULT_API_URL5 = "https://blockrun.ai/api";
+var DEFAULT_TIMEOUT5 = 6e4;
+var SearchClient = class {
+  account;
+  privateKey;
+  apiUrl;
+  timeout;
+  constructor(options = {}) {
+    const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
+    const privateKey = options.privateKey || envKey;
+    if (!privateKey) {
+      throw new Error(
+        "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
+      );
+    }
+    validatePrivateKey(privateKey);
+    this.privateKey = privateKey;
+    this.account = (0, import_accounts6.privateKeyToAccount)(privateKey);
+    const apiUrl = options.apiUrl || DEFAULT_API_URL5;
+    validateApiUrl(apiUrl);
+    this.apiUrl = apiUrl.replace(/\/$/, "");
+    this.timeout = options.timeout || DEFAULT_TIMEOUT5;
+  }
   async search(query, options) {
     if (!query || query.length > 1e3) {
       throw new Error("query must be 1-1000 characters");
@@ -2481,9 +2694,9 @@ var SearchClient = class {
 };
 
 // src/x-client.ts
-var import_accounts6 = require("viem/accounts");
-var DEFAULT_API_URL5 = "https://blockrun.ai/api";
-var DEFAULT_TIMEOUT5 = 6e4;
+var import_accounts7 = require("viem/accounts");
+var DEFAULT_API_URL6 = "https://blockrun.ai/api";
+var DEFAULT_TIMEOUT6 = 6e4;
 var XClient = class _XClient {
   account;
   privateKey;
@@ -2506,11 +2719,11 @@ var XClient = class _XClient {
     }
     validatePrivateKey(privateKey);
     this.privateKey = privateKey;
-    this.account = (0, import_accounts6.privateKeyToAccount)(privateKey);
-    const apiUrl = options.apiUrl || DEFAULT_API_URL5;
+    this.account = (0, import_accounts7.privateKeyToAccount)(privateKey);
+    const apiUrl = options.apiUrl || DEFAULT_API_URL6;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
-    this.timeout = options.timeout || DEFAULT_TIMEOUT5;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT6;
   }
   // ───────── User endpoints ─────────
   userLookup(usernames) {
@@ -2688,9 +2901,9 @@ var XClient = class _XClient {
 };
 
 // src/price.ts
-var import_accounts7 = require("viem/accounts");
-var DEFAULT_API_URL6 = "https://blockrun.ai/api";
-var DEFAULT_TIMEOUT6 = 3e4;
+var import_accounts8 = require("viem/accounts");
+var DEFAULT_API_URL7 = "https://blockrun.ai/api";
+var DEFAULT_TIMEOUT7 = 3e4;
 var PriceClient = class {
   account = null;
   privateKey = null;
@@ -2708,12 +2921,12 @@ var PriceClient = class {
     if (privateKey) {
       validatePrivateKey(privateKey);
       this.privateKey = privateKey;
-      this.account = (0, import_accounts7.privateKeyToAccount)(privateKey);
+      this.account = (0, import_accounts8.privateKeyToAccount)(privateKey);
     }
-    const apiUrl = options.apiUrl || DEFAULT_API_URL6;
+    const apiUrl = options.apiUrl || DEFAULT_API_URL7;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
-    this.timeout = options.timeout || DEFAULT_TIMEOUT6;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT7;
   }
   async price(category, symbol, options) {
     if (!symbol) throw new Error("symbol is required");
@@ -2892,7 +3105,7 @@ function buildUrl(base, query) {
 }
 
 // src/wallet.ts
-var import_accounts8 = require("viem/accounts");
+var import_accounts9 = require("viem/accounts");
 var fs2 = __toESM(require("fs"), 1);
 var path2 = __toESM(require("path"), 1);
 var os2 = __toESM(require("os"), 1);
@@ -2901,8 +3114,8 @@ var BASE_CHAIN_ID2 = "8453";
 var WALLET_DIR = path2.join(os2.homedir(), ".blockrun");
 var WALLET_FILE = path2.join(WALLET_DIR, ".session");
 function createWallet() {
-  const privateKey = (0, import_accounts8.generatePrivateKey)();
-  const account = (0, import_accounts8.privateKeyToAccount)(privateKey);
+  const privateKey = (0, import_accounts9.generatePrivateKey)();
+  const account = (0, import_accounts9.privateKeyToAccount)(privateKey);
   return {
     address: account.address,
     privateKey
@@ -2958,12 +3171,12 @@ function loadWallet() {
 function getOrCreateWallet() {
   const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
   if (envKey) {
-    const account = (0, import_accounts8.privateKeyToAccount)(envKey);
+    const account = (0, import_accounts9.privateKeyToAccount)(envKey);
     return { address: account.address, privateKey: envKey, isNew: false };
   }
   const fileKey = loadWallet();
   if (fileKey) {
-    const account = (0, import_accounts8.privateKeyToAccount)(fileKey);
+    const account = (0, import_accounts9.privateKeyToAccount)(fileKey);
     return { address: account.address, privateKey: fileKey, isNew: false };
   }
   const { address, privateKey } = createWallet();
@@ -2973,11 +3186,11 @@ function getOrCreateWallet() {
 function getWalletAddress() {
   const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
   if (envKey) {
-    return (0, import_accounts8.privateKeyToAccount)(envKey).address;
+    return (0, import_accounts9.privateKeyToAccount)(envKey).address;
   }
   const fileKey = loadWallet();
   if (fileKey) {
-    return (0, import_accounts8.privateKeyToAccount)(fileKey).address;
+    return (0, import_accounts9.privateKeyToAccount)(fileKey).address;
   }
   return null;
 }
@@ -3157,7 +3370,7 @@ async function getOrCreateSolanaWallet() {
 // src/solana-client.ts
 var SOLANA_API_URL = "https://sol.blockrun.ai/api";
 var DEFAULT_MAX_TOKENS2 = 1024;
-var DEFAULT_TIMEOUT7 = 6e4;
+var DEFAULT_TIMEOUT8 = 6e4;
 var SDK_VERSION2 = "0.3.0";
 var USER_AGENT2 = `blockrun-ts/${SDK_VERSION2}`;
 var SolanaLLMClient = class {
@@ -3182,7 +3395,7 @@ var SolanaLLMClient = class {
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
     this.rpcUrl = options.rpcUrl || "https://api.mainnet-beta.solana.com";
-    this.timeout = options.timeout || DEFAULT_TIMEOUT7;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT8;
   }
   /** Get Solana wallet address (public key in base58). */
   async getWalletAddress() {
@@ -4007,6 +4220,9 @@ var ChatCompletions = class {
     this.apiUrl = apiUrl;
     this.timeout = timeout;
   }
+  client;
+  apiUrl;
+  timeout;
   async create(params) {
     if (params.stream) {
       return this.createStream(params);
@@ -4086,7 +4302,7 @@ var OpenAI = class {
 };
 
 // src/anthropic-compat.ts
-var import_accounts9 = require("viem/accounts");
+var import_accounts10 = require("viem/accounts");
 var AnthropicClient = class {
   _client = null;
   _clientPromise = null;
@@ -4099,7 +4315,7 @@ var AnthropicClient = class {
     const key = options.privateKey ?? wallet.privateKey;
     validatePrivateKey(key);
     this._privateKey = key;
-    this._account = (0, import_accounts9.privateKeyToAccount)(this._privateKey);
+    this._account = (0, import_accounts10.privateKeyToAccount)(this._privateKey);
     const apiUrl = options.apiUrl ?? "https://blockrun.ai/api";
     validateApiUrl(apiUrl);
     this._apiUrl = apiUrl.replace(/\/$/, "");
@@ -4213,6 +4429,7 @@ var AnthropicClient = class {
   USDC_BASE,
   USDC_BASE_CONTRACT,
   USDC_SOLANA,
+  VideoClient,
   WALLET_DIR_PATH,
   WALLET_FILE_PATH,
   XClient,

package/dist/index.d.cts

@@ -58,6 +58,25 @@ interface ChatResponse {
     choices: ChatChoice[];
     usage?: ChatUsage;
     citations?: string[];
+    /**
+     * Populated when the gateway transparently substituted a different
+     * model for the one the caller asked for — typically because the
+     * requested model errored and the gateway routed to a free fallback
+     * to fulfil the request. When `used` is true:
+     *   - `model` is the model that actually answered (vs `ChatResponse.model`
+     *     which historically reflected the requested model id).
+     *   - `settlementSkipped` is `true` when the gateway also skipped the
+     *     on-chain settle — i.e. the user was not charged for this call
+     *     because a free fallback served it.
+     * Surfaced from the gateway's `X-Fallback-Used / X-Fallback-Model /
+     * X-Settlement-Skipped` response headers. Absent when the headers
+     * aren't present (most calls).
+     */
+    fallback?: {
+        used: true;
+        model?: string;
+        settlementSkipped?: boolean;
+    };
 }
 interface Model {
     id: string;
@@ -272,7 +291,7 @@ interface ChatCompletionOptions {
      */
     fallbackModels?: string[];
 }
-type RoutingProfile = "free" | "eco" | "auto" | "premium";
+type RoutingProfile = "eco" | "auto" | "premium";
 type RoutingTier = "SIMPLE" | "MEDIUM" | "COMPLEX" | "REASONING";
 interface RoutingDecision {
     model: string;
@@ -283,6 +302,10 @@ interface RoutingDecision {
     costEstimate: number;
     baselineCost: number;
     savings: number;
+    /** Routing profile applied by clawrouter (may include "agentic" on gateway responses). */
+    profile?: RoutingProfile | "agentic";
+    /** Score used when agentic routing is active. */
+    agenticScore?: number;
     /**
      * Remaining tier models with known pricing, in fallback order. `chat()`
      * walks this list when the primary model hits a transient error
@@ -291,7 +314,7 @@ interface RoutingDecision {
     fallbacks?: string[];
 }
 interface SmartChatOptions extends ChatOptions {
-    /** Routing profile: free (zero cost), eco (budget), auto (balanced), premium (best quality) */
+    /** Routing profile: eco (budget), auto (balanced), premium (best quality) */
     routingProfile?: RoutingProfile;
     /** Maximum output tokens (used for cost estimation) */
     maxOutputTokens?: number;
@@ -762,9 +785,6 @@ declare class LLMClient {
      *
      * @example With routing profile
      * ```ts
-     * // Free tier only (zero cost)
-     * const result = await client.smartChat('Hello!', { routingProfile: 'free' });
-     *
      * // Eco mode (budget optimized)
      * const result = await client.smartChat('Explain quantum computing', { routingProfile: 'eco' });
      *
@@ -811,6 +831,17 @@ declare class LLMClient {
      * cost_log.jsonl is a single source of truth regardless of caller.
      */
     private recordCost;
+    /**
+     * Parse the chat response JSON and attach `fallback` metadata when the
+     * gateway signalled a transparent free-fallback substitution. The
+     * gateway sets X-Fallback-Used / X-Fallback-Model / X-Settlement-Skipped
+     * on the response when it served a paid request from a free model
+     * (route.ts createPaymentResponseHeader path). Without surfacing these
+     * to the caller, the user gets a different model than requested with
+     * no visibility — silent quality drop and no clue why the on-chain
+     * balance didn't change.
+     */
+    private parseChatResponse;
     /**
      * Make a request with automatic x402 payment handling.
      */
@@ -1323,6 +1354,68 @@ declare class MusicClient {
     getSpending(): Spending;
 }
 
+/**
+ * BlockRun Video Client - Generate short AI videos via x402 micropayments.
+ *
+ * SECURITY NOTE - Private Key Handling:
+ * Your private key NEVER leaves your machine. Here's what happens:
+ * 1. Key stays local - only used to sign an EIP-712 typed data message
+ * 2. Only the SIGNATURE is sent in the PAYMENT-SIGNATURE header
+ * 3. BlockRun verifies the signature on-chain via Coinbase CDP facilitator
+ *
+ * Async flow (client-polled):
+ *   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.
+ * Settlement happens only on the first completed poll, so upstream failure or
+ * the caller giving up = zero charge.
+ *
+ * Usage:
+ *   import { VideoClient } from '@blockrun/llm';
+ *
+ *   const client = new VideoClient({ privateKey: '0x...' });
+ *   const result = await client.generate('a red apple slowly spinning on a wooden table');
+ *   console.log(result.data[0].url);            // permanent MP4 URL
+ *   console.log(result.data[0].duration_seconds);
+ */
+
+/**
+ * BlockRun Video Generation Client.
+ *
+ * Supports xAI Grok Imagine Video and ByteDance Seedance (1.5 Pro /
+ * 2.0 Fast / 2.0 Pro) with automatic x402 micropayments on Base.
+ */
+declare class VideoClient {
+    private account;
+    private privateKey;
+    private apiUrl;
+    private timeout;
+    private sessionTotalUsd;
+    private sessionCalls;
+    constructor(options?: VideoClientOptions);
+    /**
+     * 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.
+     *
+     * @param prompt - Text description of the video
+     * @param options - Optional generation parameters
+     */
+    generate(prompt: string, options?: VideoGenerateOptions & {
+        budgetMs?: number;
+    }): Promise<VideoResponse>;
+    private submitAndPoll;
+    private absolute;
+    private extractPaymentRequired;
+    private throwApiError;
+    private fetchWithTimeout;
+    getWalletAddress(): string;
+    getSpending(): Spending;
+}
+
 /**
  * BlockRun Search Client - Standalone Grok Live Search via x402 micropayments.
  *
@@ -2100,4 +2193,4 @@ declare function validateTemperature(temperature?: number): void;
  */
 declare function validateTopP(topP?: number): void;
 
-export { APIError, AnthropicClient, type AudioModel, type AudioTrack, BASE_CHAIN_ID, type BarResolution, type BlockRunAnthropicOptions, BlockrunError, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PaymentError, type PaymentLinks, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, type RoutingDecision, type RoutingProfile, type RoutingTier, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type Spending, type SpendingReport, type StockMarket, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XArticlesRisingResponse, type XAuthorAnalyticsResponse, XClient, type XClientOptions, type XCompareAuthorsResponse, type XFollower, type XFollowersResponse, type XFollowingsResponse, type XMentionsOptions, type XMentionsResponse, type XSearchOptions, type XSearchResponse, type XSearchSource, type XTrendingResponse, type XTweet, type XTweetLookupResponse, type XTweetRepliesOptions, type XTweetRepliesResponse, type XTweetThreadResponse, type XTweetsResponse, type XUser, type XUserInfoResponse, type XUserLookupResponse, type XUserTweetsOptions, type XVerifiedFollowersResponse, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatWalletCreatedMessage, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, validateMaxTokens, validateModel, validateTemperature, validateTopP };
+export { APIError, AnthropicClient, type AudioModel, type AudioTrack, BASE_CHAIN_ID, type BarResolution, type BlockRunAnthropicOptions, BlockrunError, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PaymentError, type PaymentLinks, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, type RoutingDecision, type RoutingProfile, type RoutingTier, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type Spending, type SpendingReport, type StockMarket, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XArticlesRisingResponse, type XAuthorAnalyticsResponse, XClient, type XClientOptions, type XCompareAuthorsResponse, type XFollower, type XFollowersResponse, type XFollowingsResponse, type XMentionsOptions, type XMentionsResponse, type XSearchOptions, type XSearchResponse, type XSearchSource, type XTrendingResponse, type XTweet, type XTweetLookupResponse, type XTweetRepliesOptions, type XTweetRepliesResponse, type XTweetThreadResponse, type XTweetsResponse, type XUser, type XUserInfoResponse, type XUserLookupResponse, type XUserTweetsOptions, type XVerifiedFollowersResponse, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatWalletCreatedMessage, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, validateMaxTokens, validateModel, validateTemperature, validateTopP };

package/dist/index.d.ts

@@ -58,6 +58,25 @@ interface ChatResponse {
     choices: ChatChoice[];
     usage?: ChatUsage;
     citations?: string[];
+    /**
+     * Populated when the gateway transparently substituted a different
+     * model for the one the caller asked for — typically because the
+     * requested model errored and the gateway routed to a free fallback
+     * to fulfil the request. When `used` is true:
+     *   - `model` is the model that actually answered (vs `ChatResponse.model`
+     *     which historically reflected the requested model id).
+     *   - `settlementSkipped` is `true` when the gateway also skipped the
+     *     on-chain settle — i.e. the user was not charged for this call
+     *     because a free fallback served it.
+     * Surfaced from the gateway's `X-Fallback-Used / X-Fallback-Model /
+     * X-Settlement-Skipped` response headers. Absent when the headers
+     * aren't present (most calls).
+     */
+    fallback?: {
+        used: true;
+        model?: string;
+        settlementSkipped?: boolean;
+    };
 }
 interface Model {
     id: string;
@@ -272,7 +291,7 @@ interface ChatCompletionOptions {
      */
     fallbackModels?: string[];
 }
-type RoutingProfile = "free" | "eco" | "auto" | "premium";
+type RoutingProfile = "eco" | "auto" | "premium";
 type RoutingTier = "SIMPLE" | "MEDIUM" | "COMPLEX" | "REASONING";
 interface RoutingDecision {
     model: string;
@@ -283,6 +302,10 @@ interface RoutingDecision {
     costEstimate: number;
     baselineCost: number;
     savings: number;
+    /** Routing profile applied by clawrouter (may include "agentic" on gateway responses). */
+    profile?: RoutingProfile | "agentic";
+    /** Score used when agentic routing is active. */
+    agenticScore?: number;
     /**
      * Remaining tier models with known pricing, in fallback order. `chat()`
      * walks this list when the primary model hits a transient error
@@ -291,7 +314,7 @@ interface RoutingDecision {
     fallbacks?: string[];
 }
 interface SmartChatOptions extends ChatOptions {
-    /** Routing profile: free (zero cost), eco (budget), auto (balanced), premium (best quality) */
+    /** Routing profile: eco (budget), auto (balanced), premium (best quality) */
     routingProfile?: RoutingProfile;
     /** Maximum output tokens (used for cost estimation) */
     maxOutputTokens?: number;
@@ -762,9 +785,6 @@ declare class LLMClient {
      *
      * @example With routing profile
      * ```ts
-     * // Free tier only (zero cost)
-     * const result = await client.smartChat('Hello!', { routingProfile: 'free' });
-     *
      * // Eco mode (budget optimized)
      * const result = await client.smartChat('Explain quantum computing', { routingProfile: 'eco' });
      *
@@ -811,6 +831,17 @@ declare class LLMClient {
      * cost_log.jsonl is a single source of truth regardless of caller.
      */
     private recordCost;
+    /**
+     * Parse the chat response JSON and attach `fallback` metadata when the
+     * gateway signalled a transparent free-fallback substitution. The
+     * gateway sets X-Fallback-Used / X-Fallback-Model / X-Settlement-Skipped
+     * on the response when it served a paid request from a free model
+     * (route.ts createPaymentResponseHeader path). Without surfacing these
+     * to the caller, the user gets a different model than requested with
+     * no visibility — silent quality drop and no clue why the on-chain
+     * balance didn't change.
+     */
+    private parseChatResponse;
     /**
      * Make a request with automatic x402 payment handling.
      */
@@ -1323,6 +1354,68 @@ declare class MusicClient {
     getSpending(): Spending;
 }
 
+/**
+ * BlockRun Video Client - Generate short AI videos via x402 micropayments.
+ *
+ * SECURITY NOTE - Private Key Handling:
+ * Your private key NEVER leaves your machine. Here's what happens:
+ * 1. Key stays local - only used to sign an EIP-712 typed data message
+ * 2. Only the SIGNATURE is sent in the PAYMENT-SIGNATURE header
+ * 3. BlockRun verifies the signature on-chain via Coinbase CDP facilitator
+ *
+ * Async flow (client-polled):
+ *   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.
+ * Settlement happens only on the first completed poll, so upstream failure or
+ * the caller giving up = zero charge.
+ *
+ * Usage:
+ *   import { VideoClient } from '@blockrun/llm';
+ *
+ *   const client = new VideoClient({ privateKey: '0x...' });
+ *   const result = await client.generate('a red apple slowly spinning on a wooden table');
+ *   console.log(result.data[0].url);            // permanent MP4 URL
+ *   console.log(result.data[0].duration_seconds);
+ */
+
+/**
+ * BlockRun Video Generation Client.
+ *
+ * Supports xAI Grok Imagine Video and ByteDance Seedance (1.5 Pro /
+ * 2.0 Fast / 2.0 Pro) with automatic x402 micropayments on Base.
+ */
+declare class VideoClient {
+    private account;
+    private privateKey;
+    private apiUrl;
+    private timeout;
+    private sessionTotalUsd;
+    private sessionCalls;
+    constructor(options?: VideoClientOptions);
+    /**
+     * 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.
+     *
+     * @param prompt - Text description of the video
+     * @param options - Optional generation parameters
+     */
+    generate(prompt: string, options?: VideoGenerateOptions & {
+        budgetMs?: number;
+    }): Promise<VideoResponse>;
+    private submitAndPoll;
+    private absolute;
+    private extractPaymentRequired;
+    private throwApiError;
+    private fetchWithTimeout;
+    getWalletAddress(): string;
+    getSpending(): Spending;
+}
+
 /**
  * BlockRun Search Client - Standalone Grok Live Search via x402 micropayments.
  *
@@ -2100,4 +2193,4 @@ declare function validateTemperature(temperature?: number): void;
  */
 declare function validateTopP(topP?: number): void;
 
-export { APIError, AnthropicClient, type AudioModel, type AudioTrack, BASE_CHAIN_ID, type BarResolution, type BlockRunAnthropicOptions, BlockrunError, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PaymentError, type PaymentLinks, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, type RoutingDecision, type RoutingProfile, type RoutingTier, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type Spending, type SpendingReport, type StockMarket, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XArticlesRisingResponse, type XAuthorAnalyticsResponse, XClient, type XClientOptions, type XCompareAuthorsResponse, type XFollower, type XFollowersResponse, type XFollowingsResponse, type XMentionsOptions, type XMentionsResponse, type XSearchOptions, type XSearchResponse, type XSearchSource, type XTrendingResponse, type XTweet, type XTweetLookupResponse, type XTweetRepliesOptions, type XTweetRepliesResponse, type XTweetThreadResponse, type XTweetsResponse, type XUser, type XUserInfoResponse, type XUserLookupResponse, type XUserTweetsOptions, type XVerifiedFollowersResponse, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatWalletCreatedMessage, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, validateMaxTokens, validateModel, validateTemperature, validateTopP };
+export { APIError, AnthropicClient, type AudioModel, type AudioTrack, BASE_CHAIN_ID, type BarResolution, type BlockRunAnthropicOptions, BlockrunError, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PaymentError, type PaymentLinks, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, type RoutingDecision, type RoutingProfile, type RoutingTier, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type Spending, type SpendingReport, type StockMarket, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XArticlesRisingResponse, type XAuthorAnalyticsResponse, XClient, type XClientOptions, type XCompareAuthorsResponse, type XFollower, type XFollowersResponse, type XFollowingsResponse, type XMentionsOptions, type XMentionsResponse, type XSearchOptions, type XSearchResponse, type XSearchSource, type XTrendingResponse, type XTweet, type XTweetLookupResponse, type XTweetRepliesOptions, type XTweetRepliesResponse, type XTweetThreadResponse, type XTweetsResponse, type XUser, type XUserInfoResponse, type XUserLookupResponse, type XUserTweetsOptions, type XVerifiedFollowersResponse, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatWalletCreatedMessage, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, validateMaxTokens, validateModel, validateTemperature, validateTopP };

package/dist/index.js

@@ -524,9 +524,6 @@ var LLMClient = class _LLMClient {
    *
    * @example With routing profile
    * ```ts
-   * // Free tier only (zero cost)
-   * const result = await client.smartChat('Hello!', { routingProfile: 'free' });
-   *
    * // Eco mode (budget optimized)
    * const result = await client.smartChat('Explain quantum computing', { routingProfile: 'eco' });
    *
@@ -686,6 +683,28 @@ var LLMClient = class _LLMClient {
     } catch {
     }
   }
+  /**
+   * Parse the chat response JSON and attach `fallback` metadata when the
+   * gateway signalled a transparent free-fallback substitution. The
+   * gateway sets X-Fallback-Used / X-Fallback-Model / X-Settlement-Skipped
+   * on the response when it served a paid request from a free model
+   * (route.ts createPaymentResponseHeader path). Without surfacing these
+   * to the caller, the user gets a different model than requested with
+   * no visibility — silent quality drop and no clue why the on-chain
+   * balance didn't change.
+   */
+  async parseChatResponse(response) {
+    const body = await response.json();
+    const used = response.headers.get("X-Fallback-Used") === "true";
+    if (used) {
+      body.fallback = {
+        used: true,
+        model: response.headers.get("X-Fallback-Model") || void 0,
+        settlementSkipped: response.headers.get("X-Settlement-Skipped") === "free-fallback"
+      };
+    }
+    return body;
+  }
   /**
    * Make a request with automatic x402 payment handling.
    */
@@ -714,7 +733,7 @@ var LLMClient = class _LLMClient {
           }
           throw new APIError(`API error: ${retryResp.status}`, retryResp.status, sanitizeErrorResponse(errorBody));
         }
-        return retryResp.json();
+        return this.parseChatResponse(retryResp);
       }
     }
     if (response.status === 402) {
@@ -733,7 +752,7 @@ var LLMClient = class _LLMClient {
         sanitizeErrorResponse(errorBody)
       );
     }
-    return response.json();
+    return this.parseChatResponse(response);
   }
   /**
    * Handle 402 response: parse requirements, sign payment, retry.
@@ -808,7 +827,7 @@ var LLMClient = class _LLMClient {
         this.sessionCalls += 1;
         this.sessionTotalUsd += costUsd2;
         this.recordCost(url, costUsd2, { body, network: details.network });
-        return retryResp2.json();
+        return this.parseChatResponse(retryResp2);
       }
     }
     if (retryResponse.status === 402) {
@@ -831,7 +850,7 @@ var LLMClient = class _LLMClient {
     this.sessionCalls += 1;
     this.sessionTotalUsd += costUsd;
     this.recordCost(url, costUsd, { body, network: details.network });
-    return retryResponse.json();
+    return this.parseChatResponse(retryResponse);
   }
   /**
    * Sign a payment header and return the PAYMENT-SIGNATURE value.
@@ -2249,15 +2268,21 @@ var MusicClient = class {
   }
 };
 
-// src/search.ts
+// src/video.ts
 import { privateKeyToAccount as privateKeyToAccount4 } from "viem/accounts";
 var DEFAULT_API_URL4 = "https://blockrun.ai/api";
-var DEFAULT_TIMEOUT4 = 6e4;
-var SearchClient = class {
+var DEFAULT_MODEL3 = "xai/grok-imagine-video";
+var DEFAULT_TIMEOUT4 = 12e4;
+var POLL_INTERVAL_MS2 = 5e3;
+var DEFAULT_GENERATE_BUDGET_MS = 3e5;
+var MAX_TIMEOUT_SECONDS = 600;
+var VideoClient = class {
   account;
   privateKey;
   apiUrl;
   timeout;
+  sessionTotalUsd = 0;
+  sessionCalls = 0;
   constructor(options = {}) {
     const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
     const privateKey = options.privateKey || envKey;
@@ -2274,6 +2299,193 @@ var SearchClient = class {
     this.apiUrl = apiUrl.replace(/\/$/, "");
     this.timeout = options.timeout || DEFAULT_TIMEOUT4;
   }
+  /**
+   * 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.
+   *
+   * @param prompt - Text description of the video
+   * @param options - Optional generation parameters
+   */
+  async generate(prompt, options) {
+    const body = {
+      model: options?.model || DEFAULT_MODEL3,
+      prompt
+    };
+    if (options?.imageUrl) body.image_url = options.imageUrl;
+    if (options?.durationSeconds !== void 0) body.duration_seconds = options.durationSeconds;
+    const budgetMs = options?.budgetMs ?? DEFAULT_GENERATE_BUDGET_MS;
+    return this.submitAndPoll(body, budgetMs);
+  }
+  // --------------------------------------------------------------------
+  // Internal: async submit + poll
+  // --------------------------------------------------------------------
+  async submitAndPoll(body, budgetMs) {
+    const submitUrl = `${this.apiUrl}/v1/videos/generations`;
+    const resp402 = await this.fetchWithTimeout(submitUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    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
+      }
+    );
+    const submitResp = await this.fetchWithTimeout(submitUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "PAYMENT-SIGNATURE": paymentPayload
+      },
+      body: JSON.stringify(body)
+    });
+    if (submitResp.status === 402) {
+      throw new PaymentError("Payment was rejected. Check your wallet balance.");
+    }
+    if (submitResp.status !== 200 && submitResp.status !== 202) {
+      await this.throwApiError(submitResp, "Submit failed");
+    }
+    const submitData = await submitResp.json();
+    if (!submitData.id || !submitData.poll_url) {
+      throw new APIError(
+        "Submit response missing id/poll_url",
+        submitResp.status,
+        { response: submitData }
+      );
+    }
+    const pollUrl = this.absolute(submitData.poll_url);
+    const deadline = Date.now() + budgetMs;
+    let lastStatus = submitData.status || "queued";
+    while (Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS2));
+      const pollResp = await this.fetchWithTimeout(pollUrl, {
+        method: "GET",
+        headers: { "PAYMENT-SIGNATURE": paymentPayload }
+      });
+      let pollData = {};
+      try {
+        pollData = await pollResp.json();
+      } catch {
+      }
+      lastStatus = pollData.status || lastStatus;
+      if (pollResp.status === 202 && (lastStatus === "queued" || lastStatus === "in_progress")) {
+        continue;
+      }
+      if (lastStatus === "failed") {
+        throw new APIError(
+          `Upstream generation failed: ${pollData.error || "unknown"}`,
+          pollResp.status,
+          sanitizeErrorResponse(pollData)
+        );
+      }
+      if (pollResp.status === 200 && lastStatus === "completed") {
+        const data = pollData;
+        const billedSeconds = typeof body.duration_seconds === "number" ? body.duration_seconds : 8;
+        this.sessionCalls++;
+        this.sessionTotalUsd += 0.05 * billedSeconds * 1.05;
+        const txHash = pollResp.headers.get("x-payment-receipt") || pollResp.headers.get("X-Payment-Receipt");
+        if (txHash) data.txHash = txHash;
+        return data;
+      }
+      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.`,
+      504,
+      { id: submitData.id, last_status: lastStatus }
+    );
+  }
+  absolute(url) {
+    if (url.startsWith("http://") || url.startsWith("https://")) return url;
+    const base = this.apiUrl.endsWith("/api") ? this.apiUrl.slice(0, -"/api".length) : this.apiUrl;
+    return `${base}${url}`;
+  }
+  async extractPaymentRequired(resp) {
+    const header = resp.headers.get("payment-required");
+    if (header) return parsePaymentRequired(header);
+    try {
+      const body = await resp.json();
+      if (body && (body.x402Version !== void 0 || body.accepts !== void 0)) {
+        return body;
+      }
+    } catch {
+    }
+    throw new PaymentError("402 response but no payment requirements found");
+  }
+  async throwApiError(resp, prefix) {
+    let errorBody;
+    try {
+      errorBody = await resp.json();
+    } catch {
+      errorBody = { error: "Request failed" };
+    }
+    throw new APIError(
+      `${prefix}: HTTP ${resp.status}`,
+      resp.status,
+      sanitizeErrorResponse(errorBody)
+    );
+  }
+  async fetchWithTimeout(url, options) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      return await fetch(url, { ...options, signal: controller.signal });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  getWalletAddress() {
+    return this.account.address;
+  }
+  getSpending() {
+    return { totalUsd: this.sessionTotalUsd, calls: this.sessionCalls };
+  }
+};
+
+// src/search.ts
+import { privateKeyToAccount as privateKeyToAccount5 } from "viem/accounts";
+var DEFAULT_API_URL5 = "https://blockrun.ai/api";
+var DEFAULT_TIMEOUT5 = 6e4;
+var SearchClient = class {
+  account;
+  privateKey;
+  apiUrl;
+  timeout;
+  constructor(options = {}) {
+    const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
+    const privateKey = options.privateKey || envKey;
+    if (!privateKey) {
+      throw new Error(
+        "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
+      );
+    }
+    validatePrivateKey(privateKey);
+    this.privateKey = privateKey;
+    this.account = privateKeyToAccount5(privateKey);
+    const apiUrl = options.apiUrl || DEFAULT_API_URL5;
+    validateApiUrl(apiUrl);
+    this.apiUrl = apiUrl.replace(/\/$/, "");
+    this.timeout = options.timeout || DEFAULT_TIMEOUT5;
+  }
   async search(query, options) {
     if (!query || query.length > 1e3) {
       throw new Error("query must be 1-1000 characters");
@@ -2386,9 +2598,9 @@ var SearchClient = class {
 };
 
 // src/x-client.ts
-import { privateKeyToAccount as privateKeyToAccount5 } from "viem/accounts";
-var DEFAULT_API_URL5 = "https://blockrun.ai/api";
-var DEFAULT_TIMEOUT5 = 6e4;
+import { privateKeyToAccount as privateKeyToAccount6 } from "viem/accounts";
+var DEFAULT_API_URL6 = "https://blockrun.ai/api";
+var DEFAULT_TIMEOUT6 = 6e4;
 var XClient = class _XClient {
   account;
   privateKey;
@@ -2411,11 +2623,11 @@ var XClient = class _XClient {
     }
     validatePrivateKey(privateKey);
     this.privateKey = privateKey;
-    this.account = privateKeyToAccount5(privateKey);
-    const apiUrl = options.apiUrl || DEFAULT_API_URL5;
+    this.account = privateKeyToAccount6(privateKey);
+    const apiUrl = options.apiUrl || DEFAULT_API_URL6;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
-    this.timeout = options.timeout || DEFAULT_TIMEOUT5;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT6;
   }
   // ───────── User endpoints ─────────
   userLookup(usernames) {
@@ -2593,9 +2805,9 @@ var XClient = class _XClient {
 };
 
 // src/price.ts
-import { privateKeyToAccount as privateKeyToAccount6 } from "viem/accounts";
-var DEFAULT_API_URL6 = "https://blockrun.ai/api";
-var DEFAULT_TIMEOUT6 = 3e4;
+import { privateKeyToAccount as privateKeyToAccount7 } from "viem/accounts";
+var DEFAULT_API_URL7 = "https://blockrun.ai/api";
+var DEFAULT_TIMEOUT7 = 3e4;
 var PriceClient = class {
   account = null;
   privateKey = null;
@@ -2613,12 +2825,12 @@ var PriceClient = class {
     if (privateKey) {
       validatePrivateKey(privateKey);
       this.privateKey = privateKey;
-      this.account = privateKeyToAccount6(privateKey);
+      this.account = privateKeyToAccount7(privateKey);
     }
-    const apiUrl = options.apiUrl || DEFAULT_API_URL6;
+    const apiUrl = options.apiUrl || DEFAULT_API_URL7;
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
-    this.timeout = options.timeout || DEFAULT_TIMEOUT6;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT7;
   }
   async price(category, symbol, options) {
     if (!symbol) throw new Error("symbol is required");
@@ -2797,7 +3009,7 @@ function buildUrl(base, query) {
 }
 
 // src/wallet.ts
-import { privateKeyToAccount as privateKeyToAccount7, generatePrivateKey } from "viem/accounts";
+import { privateKeyToAccount as privateKeyToAccount8, generatePrivateKey } from "viem/accounts";
 import * as fs2 from "fs";
 import * as path2 from "path";
 import * as os2 from "os";
@@ -2807,7 +3019,7 @@ var WALLET_DIR = path2.join(os2.homedir(), ".blockrun");
 var WALLET_FILE = path2.join(WALLET_DIR, ".session");
 function createWallet() {
   const privateKey = generatePrivateKey();
-  const account = privateKeyToAccount7(privateKey);
+  const account = privateKeyToAccount8(privateKey);
   return {
     address: account.address,
     privateKey
@@ -2863,12 +3075,12 @@ function loadWallet() {
 function getOrCreateWallet() {
   const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
   if (envKey) {
-    const account = privateKeyToAccount7(envKey);
+    const account = privateKeyToAccount8(envKey);
     return { address: account.address, privateKey: envKey, isNew: false };
   }
   const fileKey = loadWallet();
   if (fileKey) {
-    const account = privateKeyToAccount7(fileKey);
+    const account = privateKeyToAccount8(fileKey);
     return { address: account.address, privateKey: fileKey, isNew: false };
   }
   const { address, privateKey } = createWallet();
@@ -2878,11 +3090,11 @@ function getOrCreateWallet() {
 function getWalletAddress() {
   const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
   if (envKey) {
-    return privateKeyToAccount7(envKey).address;
+    return privateKeyToAccount8(envKey).address;
   }
   const fileKey = loadWallet();
   if (fileKey) {
-    return privateKeyToAccount7(fileKey).address;
+    return privateKeyToAccount8(fileKey).address;
   }
   return null;
 }
@@ -3062,7 +3274,7 @@ async function getOrCreateSolanaWallet() {
 // src/solana-client.ts
 var SOLANA_API_URL = "https://sol.blockrun.ai/api";
 var DEFAULT_MAX_TOKENS2 = 1024;
-var DEFAULT_TIMEOUT7 = 6e4;
+var DEFAULT_TIMEOUT8 = 6e4;
 var SDK_VERSION2 = "0.3.0";
 var USER_AGENT2 = `blockrun-ts/${SDK_VERSION2}`;
 var SolanaLLMClient = class {
@@ -3087,7 +3299,7 @@ var SolanaLLMClient = class {
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
     this.rpcUrl = options.rpcUrl || "https://api.mainnet-beta.solana.com";
-    this.timeout = options.timeout || DEFAULT_TIMEOUT7;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT8;
   }
   /** Get Solana wallet address (public key in base58). */
   async getWalletAddress() {
@@ -3912,6 +4124,9 @@ var ChatCompletions = class {
     this.apiUrl = apiUrl;
     this.timeout = timeout;
   }
+  client;
+  apiUrl;
+  timeout;
   async create(params) {
     if (params.stream) {
       return this.createStream(params);
@@ -3991,7 +4206,7 @@ var OpenAI = class {
 };
 
 // src/anthropic-compat.ts
-import { privateKeyToAccount as privateKeyToAccount8 } from "viem/accounts";
+import { privateKeyToAccount as privateKeyToAccount9 } from "viem/accounts";
 var AnthropicClient = class {
   _client = null;
   _clientPromise = null;
@@ -4004,7 +4219,7 @@ var AnthropicClient = class {
     const key = options.privateKey ?? wallet.privateKey;
     validatePrivateKey(key);
     this._privateKey = key;
-    this._account = privateKeyToAccount8(this._privateKey);
+    this._account = privateKeyToAccount9(this._privateKey);
     const apiUrl = options.apiUrl ?? "https://blockrun.ai/api";
     validateApiUrl(apiUrl);
     this._apiUrl = apiUrl.replace(/\/$/, "");
@@ -4117,6 +4332,7 @@ export {
   USDC_BASE,
   USDC_BASE_CONTRACT,
   USDC_SOLANA,
+  VideoClient,
   WALLET_DIR_PATH,
   WALLET_FILE_PATH,
   XClient,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/llm",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "type": "module",
   "description": "BlockRun SDK - Pay-per-request AI (LLM, Image, Video, Music) via x402 on Base and Solana",
   "main": "dist/index.cjs",
@@ -48,23 +48,23 @@
     "url": "https://github.com/BlockRunAI/blockrun-llm-ts/issues"
   },
   "dependencies": {
-    "@blockrun/clawrouter": "^0.12.71",
+    "@blockrun/clawrouter": "^0.12.190",
     "bs58": "^6.0.0",
-    "viem": "^2.21.0"
+    "viem": "^2.49.0"
   },
   "optionalDependencies": {
     "@anthropic-ai/sdk": "^0.39.0",
-    "@solana/spl-token": "^0.4.0",
-    "@solana/web3.js": "^1.98.0"
+    "@solana/spl-token": "^0.4.14",
+    "@solana/web3.js": "^1.98.4"
   },
   "devDependencies": {
-    "@eslint/js": "^9.0.0",
-    "@types/node": "^20.0.0",
-    "eslint": "^9.0.0",
-    "tsup": "^8.0.0",
-    "typescript": "^5.0.0",
-    "typescript-eslint": "^8.0.0",
-    "vitest": "^1.0.0"
+    "@eslint/js": "^9.39.4",
+    "@types/node": "^20.19.41",
+    "eslint": "^9.39.4",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.59.3",
+    "vitest": "^1.6.1"
   },
   "engines": {
     "node": ">=20"