@blockrun/llm 3.16.0 → 3.17.0

package/README.md

@@ -4,7 +4,7 @@
 
 ### Cut your LLM bill by <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->%. One line of TypeScript.
 
-The smart-routing SDK for <!-- br:models.chatVisible -->78<!-- /br:models.chatVisible --> models — every request goes to the cheapest model that can handle it,
+The smart-routing SDK for <!-- br:models.chatVisible -->79<!-- /br:models.chatVisible --> models — every request goes to the cheapest model that can handle it,
 paid with an API key or per-request USDC on Solana or Base. No vendor lock-in.
 
 [![npm](https://img.shields.io/npm/v/@blockrun/llm.svg?style=flat-square)](https://www.npmjs.com/package/@blockrun/llm)
@@ -56,7 +56,7 @@ console.log(r.response);         // the proof
 |                    | OpenAI SDK     | OpenRouter        | LiteLLM          | **@blockrun/llm**                                                       |
 | ------------------ | -------------- | ----------------- | ---------------- | ----------------------------------------------------------------------- |
 | **Cost routing**   | ✗ one vendor   | Manual selection  | Manual selection | **Automatic — <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->% cheaper** |
-| **Models**         | GPT only       | 200+              | 100+ (BYO keys)  | **<!-- br:models.chatVisible -->78<!-- /br:models.chatVisible -->, one credential** |
+| **Models**         | GPT only       | 200+              | 100+ (BYO keys)  | **<!-- br:models.chatVisible -->79<!-- /br:models.chatVisible -->, one credential** |
 | **Free tier**      | ✗              | Rate-limited      | ✗                | **<!-- br:models.free -->6<!-- /br:models.free --> models, no signup**  |
 | **Auth**           | API key        | Account + API key | Your API keys    | **API key *or* wallet signature**                                       |
 | **Payment**        | Card + invoice | Credit card       | BYO keys         | **Account credit or USDC per-request**                                  |
@@ -1774,7 +1774,7 @@ The `AnthropicClient` wraps the official `@anthropic-ai/sdk` with a custom fetch
 ## Frequently Asked Questions
 
 ### What is @blockrun/llm?
-@blockrun/llm is a TypeScript SDK that cuts LLM costs by up to <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->% with built-in smart routing: every request is routed to the cheapest of <!-- br:models.chatVisible -->78<!-- /br:models.chatVisible --> models (OpenAI, Anthropic, Google, xAI, DeepSeek, Moonshot, and more) that can handle it, then paid per-request in USDC via the x402 protocol — with API key account billing or x402 wallet payments on Solana or Base.
+@blockrun/llm is a TypeScript SDK that cuts LLM costs by up to <!-- br:savings.autoVsBaselinePct -->84<!-- /br:savings.autoVsBaselinePct -->% with built-in smart routing: every request is routed to the cheapest of <!-- br:models.chatVisible -->79<!-- /br:models.chatVisible --> models (OpenAI, Anthropic, Google, xAI, DeepSeek, Moonshot, and more) that can handle it, then paid per-request in USDC via the x402 protocol — with API key account billing or x402 wallet payments on Solana or Base.
 
 ### How does payment work?
 When you make an API call, the SDK automatically handles x402 payment. It signs a USDC transaction locally using your wallet private key (which never leaves your machine), and includes the payment proof in the request header. Settlement is non-custodial and instant on Base or Solana.

package/dist/index.cjs

@@ -8715,6 +8715,15 @@ var BlockrunClient = class {
    * deadline exceeded). Settlement happens only when upstream returns 200 +
    * completed — upstream failure or caller giving up = no charge.
    *
+   * **EVM only, and enforced upstream.** Replaying one signature works because
+   * an EIP-3009 authorization stays valid for as long as it was signed for. A
+   * Solana payment is a transaction pinned to a recent blockhash and expires in
+   * ~150 blocks (~60s), so replaying one could not cover a long render. No
+   * guard is needed here: `signFrom402` already refuses a `solana:` network
+   * outright, so this loop is unreachable on Solana. Use `SolanaLLMClient`,
+   * whose poll loop signs afresh each time; the gateway binds a job to the
+   * payer address rather than to the signature, and still settles exactly once.
+   *
    * If the gateway returns 200 directly on submit (no async surface), this
    * short-circuits and returns the body. Most long-running endpoints (image,
    * video, music, voice) return 202 with a poll_url.
@@ -9949,6 +9958,18 @@ var SolanaLLMClient = class {
     }
   }
   /** Edit an image using img2img (Solana payment). */
+  /**
+   * Generate an image on Solana.
+   *
+   * Slow models answer 202 `{ id, poll_url }`; `requestWithPaymentRaw` follows
+   * that to completion, re-signing per poll, and settles once at the end. Fast
+   * models answer 200 inline and settle there.
+   */
+  async image(prompt, options = {}) {
+    const body = { prompt, ...options };
+    const data = await this.requestWithPaymentRaw("/v1/images/generations", body);
+    return data;
+  }
   async imageEdit(prompt, image, options) {
     const body = {
       model: options?.model || "openai/gpt-image-2",
@@ -10196,6 +10217,81 @@ var SolanaLLMClient = class {
    * @returns the header value to replay with, and what it will settle for.
    * @throws PaymentError when the 402 carries no usable Solana requirements.
    */
+  /**
+   * Follow a 202 `{ id, poll_url }` to completion, on Solana.
+   *
+   * The Base SDK signs one EIP-3009 authorization and replays it on every poll.
+   * That cannot work here: a Solana payment is a transaction pinned to a recent
+   * blockhash, valid for ~150 blocks (~60s), and a long render outlives it. So
+   * every poll takes a **fresh** 402 and signs again. The gateway binds the job
+   * to the payer address rather than to the signature, which is what makes that
+   * legal — and it settles exactly once, on the poll that returns `completed`,
+   * so signing per poll costs signatures, never money.
+   */
+  async followSolanaJob(submitBody, budgetMs, intervalMs = 2e3) {
+    const id = submitBody.id;
+    const pollPath = submitBody.poll_url;
+    if (!id || !pollPath) return submitBody;
+    const pollUrl = pollPath.startsWith("http") ? pollPath : `${this.apiUrl}${pollPath.startsWith("/") ? "" : "/"}${pollPath}`;
+    const deadline = Date.now() + budgetMs;
+    let lastStatus = submitBody.status || "queued";
+    while (Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, intervalMs));
+      const challenge = await this.fetchWithTimeout(pollUrl, {
+        method: "GET",
+        headers: { "User-Agent": USER_AGENT }
+      });
+      if (challenge.status === 200) {
+        const done = await challenge.json();
+        return done;
+      }
+      if (challenge.status !== 402) {
+        let errorBody;
+        try {
+          errorBody = await challenge.json();
+        } catch {
+          errorBody = { error: "Poll failed" };
+        }
+        throw new APIError(`Poll failed: ${challenge.status}`, challenge.status, sanitizeErrorResponse(errorBody));
+      }
+      const { paymentPayload, costUsd } = await this.signPaymentFrom402(
+        pollUrl,
+        challenge,
+        true,
+        // always a fresh blockhash; the last one is stale by now
+        pollUrl
+      );
+      const paid = await this.fetchWithTimeout(pollUrl, {
+        method: "GET",
+        headers: { "User-Agent": USER_AGENT, "PAYMENT-SIGNATURE": paymentPayload }
+      });
+      let data = {};
+      try {
+        data = await paid.json();
+      } catch {
+      }
+      lastStatus = data.status || lastStatus;
+      if (lastStatus === "failed") {
+        throw new APIError(
+          `Upstream job failed: ${data.error || "unknown"}`,
+          paid.status,
+          sanitizeErrorResponse(data)
+        );
+      }
+      if (paid.status === 200 && lastStatus === "completed") {
+        this.recordSettlement(costUsd);
+        return data;
+      }
+      if (paid.status !== 200 && paid.status !== 202 && paid.status !== 504) {
+        throw new APIError(`Poll failed: ${paid.status}`, paid.status, sanitizeErrorResponse(data));
+      }
+    }
+    throw new APIError(
+      `Job did not complete within ${Math.round(budgetMs / 1e3)}s (last status: ${lastStatus}). No payment was taken.`,
+      504,
+      { id, last_status: lastStatus }
+    );
+  }
   async signPaymentFrom402(url, response, forceFreshBlockhash, resourceFallback = url) {
     let paymentHeader = response.headers.get("payment-required");
     if (!paymentHeader) {
@@ -10306,6 +10402,10 @@ var SolanaLLMClient = class {
       body: JSON.stringify(body)
     });
     await this.assertPaid(retryResponse);
+    if (retryResponse.status === 202) {
+      const submitted = await retryResponse.json();
+      return this.followSolanaJob(submitted, this.timeout);
+    }
     this.recordSettlement(costUsd);
     return retryResponse.json();
   }

package/dist/index.d.cts

@@ -2264,6 +2264,15 @@ declare class BlockrunClient {
      * deadline exceeded). Settlement happens only when upstream returns 200 +
      * completed — upstream failure or caller giving up = no charge.
      *
+     * **EVM only, and enforced upstream.** Replaying one signature works because
+     * an EIP-3009 authorization stays valid for as long as it was signed for. A
+     * Solana payment is a transaction pinned to a recent blockhash and expires in
+     * ~150 blocks (~60s), so replaying one could not cover a long render. No
+     * guard is needed here: `signFrom402` already refuses a `solana:` network
+     * outright, so this loop is unreachable on Solana. Use `SolanaLLMClient`,
+     * whose poll loop signs afresh each time; the gateway binds a job to the
+     * payer address rather than to the signature, and still settles exactly once.
+     *
      * If the gateway returns 200 directly on submit (no async surface), this
      * short-circuits and returns the body. Most long-running endpoints (image,
      * video, music, voice) return 202 with a poll_url.
@@ -2768,6 +2777,18 @@ declare class SolanaLLMClient {
      */
     getBalance(): Promise<number>;
     /** Edit an image using img2img (Solana payment). */
+    /**
+     * Generate an image on Solana.
+     *
+     * Slow models answer 202 `{ id, poll_url }`; `requestWithPaymentRaw` follows
+     * that to completion, re-signing per poll, and settles once at the end. Fast
+     * models answer 200 inline and settle there.
+     */
+    image(prompt: string, options?: {
+        model?: string;
+        size?: string;
+        n?: number;
+    } & Record<string, unknown>): Promise<ImageResponse>;
     imageEdit(prompt: string, image: string | string[], options?: ImageEditOptions): Promise<ImageResponse>;
     /** Standalone search (Solana payment). */
     search(query: string, options?: SearchOptions): Promise<SearchResult>;
@@ -2897,6 +2918,18 @@ declare class SolanaLLMClient {
      * @returns the header value to replay with, and what it will settle for.
      * @throws PaymentError when the 402 carries no usable Solana requirements.
      */
+    /**
+     * Follow a 202 `{ id, poll_url }` to completion, on Solana.
+     *
+     * The Base SDK signs one EIP-3009 authorization and replays it on every poll.
+     * That cannot work here: a Solana payment is a transaction pinned to a recent
+     * blockhash, valid for ~150 blocks (~60s), and a long render outlives it. So
+     * every poll takes a **fresh** 402 and signs again. The gateway binds the job
+     * to the payer address rather than to the signature, which is what makes that
+     * legal — and it settles exactly once, on the poll that returns `completed`,
+     * so signing per poll costs signatures, never money.
+     */
+    private followSolanaJob;
     private signPaymentFrom402;
     private handlePaymentAndRetry;
     private requestWithPaymentRaw;

package/dist/index.d.ts

@@ -2264,6 +2264,15 @@ declare class BlockrunClient {
      * deadline exceeded). Settlement happens only when upstream returns 200 +
      * completed — upstream failure or caller giving up = no charge.
      *
+     * **EVM only, and enforced upstream.** Replaying one signature works because
+     * an EIP-3009 authorization stays valid for as long as it was signed for. A
+     * Solana payment is a transaction pinned to a recent blockhash and expires in
+     * ~150 blocks (~60s), so replaying one could not cover a long render. No
+     * guard is needed here: `signFrom402` already refuses a `solana:` network
+     * outright, so this loop is unreachable on Solana. Use `SolanaLLMClient`,
+     * whose poll loop signs afresh each time; the gateway binds a job to the
+     * payer address rather than to the signature, and still settles exactly once.
+     *
      * If the gateway returns 200 directly on submit (no async surface), this
      * short-circuits and returns the body. Most long-running endpoints (image,
      * video, music, voice) return 202 with a poll_url.
@@ -2768,6 +2777,18 @@ declare class SolanaLLMClient {
      */
     getBalance(): Promise<number>;
     /** Edit an image using img2img (Solana payment). */
+    /**
+     * Generate an image on Solana.
+     *
+     * Slow models answer 202 `{ id, poll_url }`; `requestWithPaymentRaw` follows
+     * that to completion, re-signing per poll, and settles once at the end. Fast
+     * models answer 200 inline and settle there.
+     */
+    image(prompt: string, options?: {
+        model?: string;
+        size?: string;
+        n?: number;
+    } & Record<string, unknown>): Promise<ImageResponse>;
     imageEdit(prompt: string, image: string | string[], options?: ImageEditOptions): Promise<ImageResponse>;
     /** Standalone search (Solana payment). */
     search(query: string, options?: SearchOptions): Promise<SearchResult>;
@@ -2897,6 +2918,18 @@ declare class SolanaLLMClient {
      * @returns the header value to replay with, and what it will settle for.
      * @throws PaymentError when the 402 carries no usable Solana requirements.
      */
+    /**
+     * Follow a 202 `{ id, poll_url }` to completion, on Solana.
+     *
+     * The Base SDK signs one EIP-3009 authorization and replays it on every poll.
+     * That cannot work here: a Solana payment is a transaction pinned to a recent
+     * blockhash, valid for ~150 blocks (~60s), and a long render outlives it. So
+     * every poll takes a **fresh** 402 and signs again. The gateway binds the job
+     * to the payer address rather than to the signature, which is what makes that
+     * legal — and it settles exactly once, on the poll that returns `completed`,
+     * so signing per poll costs signatures, never money.
+     */
+    private followSolanaJob;
     private signPaymentFrom402;
     private handlePaymentAndRetry;
     private requestWithPaymentRaw;

package/dist/index.js

@@ -8594,6 +8594,15 @@ var BlockrunClient = class {
    * deadline exceeded). Settlement happens only when upstream returns 200 +
    * completed — upstream failure or caller giving up = no charge.
    *
+   * **EVM only, and enforced upstream.** Replaying one signature works because
+   * an EIP-3009 authorization stays valid for as long as it was signed for. A
+   * Solana payment is a transaction pinned to a recent blockhash and expires in
+   * ~150 blocks (~60s), so replaying one could not cover a long render. No
+   * guard is needed here: `signFrom402` already refuses a `solana:` network
+   * outright, so this loop is unreachable on Solana. Use `SolanaLLMClient`,
+   * whose poll loop signs afresh each time; the gateway binds a job to the
+   * payer address rather than to the signature, and still settles exactly once.
+   *
    * If the gateway returns 200 directly on submit (no async surface), this
    * short-circuits and returns the body. Most long-running endpoints (image,
    * video, music, voice) return 202 with a poll_url.
@@ -9828,6 +9837,18 @@ var SolanaLLMClient = class {
     }
   }
   /** Edit an image using img2img (Solana payment). */
+  /**
+   * Generate an image on Solana.
+   *
+   * Slow models answer 202 `{ id, poll_url }`; `requestWithPaymentRaw` follows
+   * that to completion, re-signing per poll, and settles once at the end. Fast
+   * models answer 200 inline and settle there.
+   */
+  async image(prompt, options = {}) {
+    const body = { prompt, ...options };
+    const data = await this.requestWithPaymentRaw("/v1/images/generations", body);
+    return data;
+  }
   async imageEdit(prompt, image, options) {
     const body = {
       model: options?.model || "openai/gpt-image-2",
@@ -10075,6 +10096,81 @@ var SolanaLLMClient = class {
    * @returns the header value to replay with, and what it will settle for.
    * @throws PaymentError when the 402 carries no usable Solana requirements.
    */
+  /**
+   * Follow a 202 `{ id, poll_url }` to completion, on Solana.
+   *
+   * The Base SDK signs one EIP-3009 authorization and replays it on every poll.
+   * That cannot work here: a Solana payment is a transaction pinned to a recent
+   * blockhash, valid for ~150 blocks (~60s), and a long render outlives it. So
+   * every poll takes a **fresh** 402 and signs again. The gateway binds the job
+   * to the payer address rather than to the signature, which is what makes that
+   * legal — and it settles exactly once, on the poll that returns `completed`,
+   * so signing per poll costs signatures, never money.
+   */
+  async followSolanaJob(submitBody, budgetMs, intervalMs = 2e3) {
+    const id = submitBody.id;
+    const pollPath = submitBody.poll_url;
+    if (!id || !pollPath) return submitBody;
+    const pollUrl = pollPath.startsWith("http") ? pollPath : `${this.apiUrl}${pollPath.startsWith("/") ? "" : "/"}${pollPath}`;
+    const deadline = Date.now() + budgetMs;
+    let lastStatus = submitBody.status || "queued";
+    while (Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, intervalMs));
+      const challenge = await this.fetchWithTimeout(pollUrl, {
+        method: "GET",
+        headers: { "User-Agent": USER_AGENT }
+      });
+      if (challenge.status === 200) {
+        const done = await challenge.json();
+        return done;
+      }
+      if (challenge.status !== 402) {
+        let errorBody;
+        try {
+          errorBody = await challenge.json();
+        } catch {
+          errorBody = { error: "Poll failed" };
+        }
+        throw new APIError(`Poll failed: ${challenge.status}`, challenge.status, sanitizeErrorResponse(errorBody));
+      }
+      const { paymentPayload, costUsd } = await this.signPaymentFrom402(
+        pollUrl,
+        challenge,
+        true,
+        // always a fresh blockhash; the last one is stale by now
+        pollUrl
+      );
+      const paid = await this.fetchWithTimeout(pollUrl, {
+        method: "GET",
+        headers: { "User-Agent": USER_AGENT, "PAYMENT-SIGNATURE": paymentPayload }
+      });
+      let data = {};
+      try {
+        data = await paid.json();
+      } catch {
+      }
+      lastStatus = data.status || lastStatus;
+      if (lastStatus === "failed") {
+        throw new APIError(
+          `Upstream job failed: ${data.error || "unknown"}`,
+          paid.status,
+          sanitizeErrorResponse(data)
+        );
+      }
+      if (paid.status === 200 && lastStatus === "completed") {
+        this.recordSettlement(costUsd);
+        return data;
+      }
+      if (paid.status !== 200 && paid.status !== 202 && paid.status !== 504) {
+        throw new APIError(`Poll failed: ${paid.status}`, paid.status, sanitizeErrorResponse(data));
+      }
+    }
+    throw new APIError(
+      `Job did not complete within ${Math.round(budgetMs / 1e3)}s (last status: ${lastStatus}). No payment was taken.`,
+      504,
+      { id, last_status: lastStatus }
+    );
+  }
   async signPaymentFrom402(url, response, forceFreshBlockhash, resourceFallback = url) {
     let paymentHeader = response.headers.get("payment-required");
     if (!paymentHeader) {
@@ -10185,6 +10281,10 @@ var SolanaLLMClient = class {
       body: JSON.stringify(body)
     });
     await this.assertPaid(retryResponse);
+    if (retryResponse.status === 202) {
+      const submitted = await retryResponse.json();
+      return this.followSolanaJob(submitted, this.timeout);
+    }
     this.recordSettlement(costUsd);
     return retryResponse.json();
   }

package/package.json

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