@blockrun/llm 3.23.0 → 3.23.2

package/README.md

@@ -1600,9 +1600,9 @@ await status();
 
 `getOrCreateWallet()` resolves the Base wallet in a fixed order:
 `BLOCKRUN_WALLET_KEY` or `BASE_CHAIN_WALLET_KEY`, then `~/.blockrun/.session`,
-then the legacy `~/.blockrun/wallet.key`. `LLMClient` itself reads only
-`BASE_CHAIN_WALLET_KEY` (or an explicit `privateKey`). For a single run of the
-helpers without changing anything, use `export BLOCKRUN_WALLET_KEY=<private-key>`.
+then the legacy `~/.blockrun/wallet.key`. `LLMClient` reads an explicit
+`privateKey`, then `BASE_CHAIN_WALLET_KEY`, then `BLOCKRUN_WALLET_KEY`. For a
+single run without changing anything, use `export BLOCKRUN_WALLET_KEY=<private-key>`.
 
 ### Wallet discovery and migration
 
@@ -1686,7 +1686,7 @@ const configured = new LLMClient({
 | `BLOCKRUN_API_KEY` | Account key (`brk_...`): account billing, no wallet needed. Create one at [user.blockrun.ai/dashboard/keys](https://user.blockrun.ai/dashboard/keys) |
 | `BLOCKRUN_API_BASE_URL` | Account API endpoint (default `https://api.blockrun.ai`) |
 | `BASE_CHAIN_WALLET_KEY` | EVM wallet private key for `LLMClient` (Base / Arc) and every EVM client |
-| `BLOCKRUN_WALLET_KEY` | EVM wallet key honoured by the service clients, `BlockrunClient`, `setupAgentWallet()` and `AnthropicClient` (checked before `BASE_CHAIN_WALLET_KEY`); **not** read by `LLMClient` |
+| `BLOCKRUN_WALLET_KEY` | EVM wallet key read by every EVM client. The service clients, `BlockrunClient`, `setupAgentWallet()` and `AnthropicClient` check it before `BASE_CHAIN_WALLET_KEY`; `LLMClient` checks it after, so a process holding both keeps paying from the same wallet |
 | `SOLANA_WALLET_KEY` | Solana secret key, bs58-encoded, for `SolanaLLMClient` |
 | `SOLANA_RPC_URL` | Solana RPC for payments and balance (also `rpcUrl`) |
 | `SOLANA_RPC_API_KEY` / `SOLANA_RPC_HEADERS` | Header auth for that RPC (also `rpcHeaders`) |

package/dist/index.cjs

@@ -4833,7 +4833,7 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.23.0";
+var SDK_VERSION = "3.23.2";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
@@ -4908,16 +4908,16 @@ var LLMClient = class _LLMClient {
   /**
    * Initialize the BlockRun LLM client.
    *
-   * @param options - Client configuration options (optional if BASE_CHAIN_WALLET_KEY env var is set)
+   * @param options - Client configuration options (optional if BLOCKRUN_API_KEY, BASE_CHAIN_WALLET_KEY or BLOCKRUN_WALLET_KEY is set)
    */
   constructor(options = {}) {
     this.apiAuth = resolveApiKeyAuth(options);
     if (!this.apiAuth) {
-      const envKey = typeof process !== "undefined" && process.env ? process.env.BASE_CHAIN_WALLET_KEY : void 0;
+      const envKey = typeof process !== "undefined" && process.env ? process.env.BASE_CHAIN_WALLET_KEY || process.env.BLOCKRUN_WALLET_KEY : void 0;
       const privateKey = options.privateKey || envKey;
       if (!privateKey) {
         throw new Error(
-          "Private key required. Pass privateKey in options or set BASE_CHAIN_WALLET_KEY environment variable."
+          "Private key required. Pass privateKey in options or set BASE_CHAIN_WALLET_KEY (or BLOCKRUN_WALLET_KEY) environment variable."
         );
       }
       validatePrivateKey(privateKey);
@@ -5606,7 +5606,7 @@ var LLMClient = class _LLMClient {
   }
   /**
    * Make a request with automatic x402 payment handling, returning raw JSON.
-   * Used for non-ChatResponse endpoints (X/Twitter, search, image edit, etc.).
+   * Used for non-ChatResponse endpoints (search, image edit, etc.).
    */
   async requestWithPaymentRaw(endpoint, body) {
     const url = `${this.apiUrl}${endpoint}`;
@@ -6014,7 +6014,8 @@ var LLMClient = class _LLMClient {
     return data;
   }
   /**
-   * Standalone search (web, X/Twitter, news).
+   * Standalone search over web and news. For X/Twitter, use chat on an
+   * `xai/*` model with an `x_search` tool.
    *
    * @param query - Search query
    * @param options - Optional search parameters
@@ -8508,6 +8509,7 @@ var import_accounts12 = require("viem/accounts");
 var DEFAULT_API_URL11 = "https://blockrun.ai/api";
 var DEFAULT_TIMEOUT11 = 6e4;
 var SURF_PREFIX = "/v1/surf";
+var warnedRetired = false;
 var SurfClient = class {
   _account;
   get account() {
@@ -8525,6 +8527,12 @@ var SurfClient = class {
   apiUrl;
   timeout;
   constructor(options = {}) {
+    if (!warnedRetired) {
+      warnedRetired = true;
+      console.warn(
+        "[blockrun] SurfClient is deprecated: the gateway retired /v1/surf/* (410 endpoint_retired). Use PriceClient, LLMClient.defi*, LLMClient.pm() or LLMClient.dex* instead."
+      );
+    }
     this.apiAuth = resolveApiKeyAuth(options);
     if (!this.apiAuth) {
       const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
@@ -10861,6 +10869,38 @@ function capOutstandingEscrow(scheme, wallet) {
     return original.call(this, requirements, requestAmount, needed, context, widened, existingDeposit);
   };
 }
+var payScope = new import_async_hooks.AsyncLocalStorage();
+function registerHookDispatchers(client) {
+  client.onBeforePaymentCreation(async (context) => {
+    for (const hook of payScope.getStore()?.hooks.before ?? []) {
+      const result = await hook(context);
+      if (result && typeof result === "object" && result.abort) return result;
+    }
+    return void 0;
+  });
+  client.onAfterPaymentCreation(async (context) => {
+    const scope = payScope.getStore();
+    for (const hook of scope?.hooks.after ?? []) {
+      try {
+        await hook(context);
+      } catch (error) {
+        if (scope && !scope.afterError) scope.afterError = { error };
+      }
+    }
+  });
+  client.onPaymentCreationFailure(async (context) => {
+    await runFailureHooks(payScope.getStore(), context);
+    return void 0;
+  });
+}
+async function runFailureHooks(scope, context) {
+  for (const hook of scope?.hooks.failure ?? []) {
+    try {
+      await hook(context);
+    } catch {
+    }
+  }
+}
 var RPC_SCOPE_STORE = /* @__PURE__ */ Symbol.for("@blockrun/llm/batch-rpc-scope/v1");
 var RPC_HEADER_HOOK = /* @__PURE__ */ Symbol.for("@blockrun/llm/batch-rpc-headers/v1");
 var sharedGlobal = globalThis;
@@ -10912,6 +10952,11 @@ function intentTarget(intent) {
 var SolanaBatchPayer = class {
   constructor(init) {
     this.init = init;
+    init.configureClient?.({
+      onBeforePaymentCreation: (hook) => void this.hooks.before.push(hook),
+      onAfterPaymentCreation: (hook) => void this.hooks.after.push(hook),
+      onPaymentCreationFailure: (hook) => void this.hooks.failure.push(hook)
+    });
     const { operators, rateLimit, inDoubt } = init.options;
     if (!Array.isArray(operators) || operators.length === 0 || operators.some((o) => typeof o !== "string" || !o)) {
       throw new Error("batch.operators must list at least one base58 operator public key");
@@ -10944,6 +10989,7 @@ var SolanaBatchPayer = class {
     unresolved: 0,
     unresolvedByReason: {}
   };
+  hooks = { before: [], after: [], failure: [] };
   /** A copy of this client's batch counters. */
   stats() {
     return {
@@ -11046,7 +11092,7 @@ var SolanaBatchPayer = class {
       capOutstandingEscrow(scheme, wallet);
       const client = new core.x402Client().register("solana:*", scheme).registerPolicy(scheme.paymentPolicy);
       client.setSpendControls({ maxAmountPerPayment: false });
-      this.init.configureClient?.(client);
+      registerHookDispatchers(client);
       const raw = new core.x402HTTPClient(client);
       const http = {
         getPaymentSettleResponse: (getHeader) => raw.getPaymentSettleResponse(getHeader),
@@ -11340,7 +11386,10 @@ var SolanaBatchPayer = class {
     }
     wallet.active += 1;
     try {
-      return await this.payWith(wallet, paymentRequired, send, rechallenge, closesAtStart ?? wallet.closes);
+      return await payScope.run(
+        { hooks: this.hooks },
+        () => this.payWith(wallet, paymentRequired, send, rechallenge, closesAtStart ?? wallet.closes)
+      );
     } finally {
       wallet.active -= 1;
     }
@@ -11752,6 +11801,18 @@ var SolanaBatchPayer = class {
   /** Build a new batch payment for a 402: the payload, its headers and its kind. */
   async buildPayment(wallet, paymentRequired) {
     const { http, payload } = await this.createPayload(wallet, paymentRequired);
+    const scope = payScope.getStore();
+    if (scope?.afterError) {
+      const { error } = scope.afterError;
+      scope.afterError = void 0;
+      await this.settle(http, payload, () => null, 0);
+      await runFailureHooks(scope, {
+        paymentRequired,
+        selectedRequirements: payload.accepted,
+        error
+      });
+      throw error;
+    }
     const headers = http.encodePaymentSignatureHeader(payload);
     const channelId = payloadChannelId(payload);
     const known = channelId ? wallet.book.find(channelId) : void 0;

package/dist/index.d.cts

@@ -499,7 +499,7 @@ interface PaymentRequired {
     extensions?: Record<string, unknown>;
 }
 interface LLMClientOptions extends ApiKeyOptions {
-    /** EVM wallet private key (hex string starting with 0x). Optional if BASE_CHAIN_WALLET_KEY env var is set. */
+    /** EVM wallet private key (hex string starting with 0x). Optional if BASE_CHAIN_WALLET_KEY (or BLOCKRUN_WALLET_KEY) is set. */
     privateKey?: `0x${string}` | string;
     /** API endpoint URL (default: https://blockrun.ai/api) */
     apiUrl?: string;
@@ -975,7 +975,10 @@ interface VideoGenerateOptions {
     returnLastFrame?: boolean;
 }
 interface SearchOptions {
-    /** Source types to search (e.g. ["web", "x", "news"]) */
+    /**
+     * Source types to search: `"web"` and/or `"news"` (default `["web"]`). `"x"` is
+     * rejected by the gateway; X search runs in chat on `xai/*` models (`x_search`).
+     */
     sources?: string[];
     /** Maximum number of results (default: 10) */
     maxResults?: number;
@@ -1119,6 +1122,7 @@ interface PriceClientOptions extends ApiKeyOptions {
     /** If false, construction succeeds without a wallet (free endpoints only). */
     requireWallet?: boolean;
 }
+/** @deprecated Surf is retired; see {@link SurfClient}. */
 interface SurfClientOptions extends ApiKeyOptions {
     privateKey?: `0x${string}` | string;
     apiUrl?: string;
@@ -1351,7 +1355,7 @@ declare class LLMClient {
     /**
      * Initialize the BlockRun LLM client.
      *
-     * @param options - Client configuration options (optional if BASE_CHAIN_WALLET_KEY env var is set)
+     * @param options - Client configuration options (optional if BLOCKRUN_API_KEY, BASE_CHAIN_WALLET_KEY or BLOCKRUN_WALLET_KEY is set)
      */
     constructor(options?: LLMClientOptions);
     /**
@@ -1510,7 +1514,7 @@ declare class LLMClient {
     chatCompletionStream(model: string, messages: ChatMessage[], options?: ChatCompletionOptions): Promise<Response>;
     /**
      * Make a request with automatic x402 payment handling, returning raw JSON.
-     * Used for non-ChatResponse endpoints (X/Twitter, search, image edit, etc.).
+     * Used for non-ChatResponse endpoints (search, image edit, etc.).
      */
     private requestWithPaymentRaw;
     /**
@@ -1574,7 +1578,8 @@ declare class LLMClient {
      */
     imageEdit(prompt: string, image: string | string[], options?: ImageEditOptions): Promise<ImageResponse>;
     /**
-     * Standalone search (web, X/Twitter, news).
+     * Standalone search over web and news. For X/Twitter, use chat on an
+     * `xai/*` model with an `x_search` tool.
      *
      * @param query - Search query
      * @param options - Optional search parameters
@@ -2328,6 +2333,7 @@ declare class PriceClient {
 
 type QueryValue$1 = string | number | boolean | null | undefined;
 type QueryParams$1 = Record<string, QueryValue$1 | QueryValue$1[]>;
+/** @deprecated Surf is retired (`410 endpoint_retired`); see the module docs for replacements. */
 declare class SurfClient {
     private _account?;
     private get account();
@@ -3194,14 +3200,20 @@ interface SolanaBatchPayerInit {
     /** Headers the exact path sends to `rpcUrl` (`rpcHeaders`, `SOLANA_RPC_HEADERS`, `SOLANA_RPC_API_KEY`). */
     rpcHeaders?: Record<string, string>;
     /**
-     * Called once with the batch scheme's `x402Client`, after the scheme and its
-     * policy are registered and before anything is signed. An embedder that
-     * enforces its own spend rules registers its payment-creation hooks here, so
-     * they see every batch payment this payer signs (each one's
-     * `selectedRequirements.amount` is the per-call ceiling, not the channel
-     * deposit) exactly as they see the embedder's own `exact` payments. A
-     * before-hook that throws refuses the payment: nothing is signed or sent,
-     * and `pay()` reports a fallback.
+     * Called once, when the payer is constructed, with a registrar for x402
+     * payment-creation hooks. An embedder that enforces its own spend rules
+     * registers its hooks here, so they see every batch payment THIS payer signs
+     * (each one's `selectedRequirements.amount` is the per-call ceiling, not the
+     * channel deposit) exactly as they see the embedder's own `exact` payments.
+     *
+     * The hooks are this payer's own: payers that share a wallet (and so its
+     * channel and scheme client) never run each other's hooks. A before-hook
+     * that throws refuses the payment: nothing is signed or sent, and `pay()`
+     * reports a fallback. An after-hook that throws does the same: the payment
+     * was signed but is rolled back unsent, so the channel is not left pending,
+     * and the failure hooks are told. Failure hooks are notifications only: a
+     * payload one returns as `recovered` is ignored, since a batch payment is
+     * never replaced by a payment built outside the batch scheme.
      */
     configureClient?: (client: X402ClientLike) => void;
 }
@@ -3242,6 +3254,7 @@ declare class SolanaBatchPayer {
     private readonly maxWaitMs;
     private readonly inDoubtMaxWaitMs;
     private readonly counters;
+    private readonly hooks;
     constructor(init: SolanaBatchPayerInit);
     /** A copy of this client's batch counters. */
     stats(): SolanaBatchStats;

package/dist/index.d.ts

@@ -499,7 +499,7 @@ interface PaymentRequired {
     extensions?: Record<string, unknown>;
 }
 interface LLMClientOptions extends ApiKeyOptions {
-    /** EVM wallet private key (hex string starting with 0x). Optional if BASE_CHAIN_WALLET_KEY env var is set. */
+    /** EVM wallet private key (hex string starting with 0x). Optional if BASE_CHAIN_WALLET_KEY (or BLOCKRUN_WALLET_KEY) is set. */
     privateKey?: `0x${string}` | string;
     /** API endpoint URL (default: https://blockrun.ai/api) */
     apiUrl?: string;
@@ -975,7 +975,10 @@ interface VideoGenerateOptions {
     returnLastFrame?: boolean;
 }
 interface SearchOptions {
-    /** Source types to search (e.g. ["web", "x", "news"]) */
+    /**
+     * Source types to search: `"web"` and/or `"news"` (default `["web"]`). `"x"` is
+     * rejected by the gateway; X search runs in chat on `xai/*` models (`x_search`).
+     */
     sources?: string[];
     /** Maximum number of results (default: 10) */
     maxResults?: number;
@@ -1119,6 +1122,7 @@ interface PriceClientOptions extends ApiKeyOptions {
     /** If false, construction succeeds without a wallet (free endpoints only). */
     requireWallet?: boolean;
 }
+/** @deprecated Surf is retired; see {@link SurfClient}. */
 interface SurfClientOptions extends ApiKeyOptions {
     privateKey?: `0x${string}` | string;
     apiUrl?: string;
@@ -1351,7 +1355,7 @@ declare class LLMClient {
     /**
      * Initialize the BlockRun LLM client.
      *
-     * @param options - Client configuration options (optional if BASE_CHAIN_WALLET_KEY env var is set)
+     * @param options - Client configuration options (optional if BLOCKRUN_API_KEY, BASE_CHAIN_WALLET_KEY or BLOCKRUN_WALLET_KEY is set)
      */
     constructor(options?: LLMClientOptions);
     /**
@@ -1510,7 +1514,7 @@ declare class LLMClient {
     chatCompletionStream(model: string, messages: ChatMessage[], options?: ChatCompletionOptions): Promise<Response>;
     /**
      * Make a request with automatic x402 payment handling, returning raw JSON.
-     * Used for non-ChatResponse endpoints (X/Twitter, search, image edit, etc.).
+     * Used for non-ChatResponse endpoints (search, image edit, etc.).
      */
     private requestWithPaymentRaw;
     /**
@@ -1574,7 +1578,8 @@ declare class LLMClient {
      */
     imageEdit(prompt: string, image: string | string[], options?: ImageEditOptions): Promise<ImageResponse>;
     /**
-     * Standalone search (web, X/Twitter, news).
+     * Standalone search over web and news. For X/Twitter, use chat on an
+     * `xai/*` model with an `x_search` tool.
      *
      * @param query - Search query
      * @param options - Optional search parameters
@@ -2328,6 +2333,7 @@ declare class PriceClient {
 
 type QueryValue$1 = string | number | boolean | null | undefined;
 type QueryParams$1 = Record<string, QueryValue$1 | QueryValue$1[]>;
+/** @deprecated Surf is retired (`410 endpoint_retired`); see the module docs for replacements. */
 declare class SurfClient {
     private _account?;
     private get account();
@@ -3194,14 +3200,20 @@ interface SolanaBatchPayerInit {
     /** Headers the exact path sends to `rpcUrl` (`rpcHeaders`, `SOLANA_RPC_HEADERS`, `SOLANA_RPC_API_KEY`). */
     rpcHeaders?: Record<string, string>;
     /**
-     * Called once with the batch scheme's `x402Client`, after the scheme and its
-     * policy are registered and before anything is signed. An embedder that
-     * enforces its own spend rules registers its payment-creation hooks here, so
-     * they see every batch payment this payer signs (each one's
-     * `selectedRequirements.amount` is the per-call ceiling, not the channel
-     * deposit) exactly as they see the embedder's own `exact` payments. A
-     * before-hook that throws refuses the payment: nothing is signed or sent,
-     * and `pay()` reports a fallback.
+     * Called once, when the payer is constructed, with a registrar for x402
+     * payment-creation hooks. An embedder that enforces its own spend rules
+     * registers its hooks here, so they see every batch payment THIS payer signs
+     * (each one's `selectedRequirements.amount` is the per-call ceiling, not the
+     * channel deposit) exactly as they see the embedder's own `exact` payments.
+     *
+     * The hooks are this payer's own: payers that share a wallet (and so its
+     * channel and scheme client) never run each other's hooks. A before-hook
+     * that throws refuses the payment: nothing is signed or sent, and `pay()`
+     * reports a fallback. An after-hook that throws does the same: the payment
+     * was signed but is rolled back unsent, so the channel is not left pending,
+     * and the failure hooks are told. Failure hooks are notifications only: a
+     * payload one returns as `recovered` is ignored, since a batch payment is
+     * never replaced by a payment built outside the batch scheme.
      */
     configureClient?: (client: X402ClientLike) => void;
 }
@@ -3242,6 +3254,7 @@ declare class SolanaBatchPayer {
     private readonly maxWaitMs;
     private readonly inDoubtMaxWaitMs;
     private readonly counters;
+    private readonly hooks;
     constructor(init: SolanaBatchPayerInit);
     /** A copy of this client's batch counters. */
     stats(): SolanaBatchStats;

package/dist/index.js

@@ -4702,7 +4702,7 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.23.0";
+var SDK_VERSION = "3.23.2";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
@@ -4777,16 +4777,16 @@ var LLMClient = class _LLMClient {
   /**
    * Initialize the BlockRun LLM client.
    *
-   * @param options - Client configuration options (optional if BASE_CHAIN_WALLET_KEY env var is set)
+   * @param options - Client configuration options (optional if BLOCKRUN_API_KEY, BASE_CHAIN_WALLET_KEY or BLOCKRUN_WALLET_KEY is set)
    */
   constructor(options = {}) {
     this.apiAuth = resolveApiKeyAuth(options);
     if (!this.apiAuth) {
-      const envKey = typeof process !== "undefined" && process.env ? process.env.BASE_CHAIN_WALLET_KEY : void 0;
+      const envKey = typeof process !== "undefined" && process.env ? process.env.BASE_CHAIN_WALLET_KEY || process.env.BLOCKRUN_WALLET_KEY : void 0;
       const privateKey = options.privateKey || envKey;
       if (!privateKey) {
         throw new Error(
-          "Private key required. Pass privateKey in options or set BASE_CHAIN_WALLET_KEY environment variable."
+          "Private key required. Pass privateKey in options or set BASE_CHAIN_WALLET_KEY (or BLOCKRUN_WALLET_KEY) environment variable."
         );
       }
       validatePrivateKey(privateKey);
@@ -5475,7 +5475,7 @@ var LLMClient = class _LLMClient {
   }
   /**
    * Make a request with automatic x402 payment handling, returning raw JSON.
-   * Used for non-ChatResponse endpoints (X/Twitter, search, image edit, etc.).
+   * Used for non-ChatResponse endpoints (search, image edit, etc.).
    */
   async requestWithPaymentRaw(endpoint, body) {
     const url = `${this.apiUrl}${endpoint}`;
@@ -5883,7 +5883,8 @@ var LLMClient = class _LLMClient {
     return data;
   }
   /**
-   * Standalone search (web, X/Twitter, news).
+   * Standalone search over web and news. For X/Twitter, use chat on an
+   * `xai/*` model with an `x_search` tool.
    *
    * @param query - Search query
    * @param options - Optional search parameters
@@ -8377,6 +8378,7 @@ import { privateKeyToAccount as privateKeyToAccount11 } from "viem/accounts";
 var DEFAULT_API_URL11 = "https://blockrun.ai/api";
 var DEFAULT_TIMEOUT11 = 6e4;
 var SURF_PREFIX = "/v1/surf";
+var warnedRetired = false;
 var SurfClient = class {
   _account;
   get account() {
@@ -8394,6 +8396,12 @@ var SurfClient = class {
   apiUrl;
   timeout;
   constructor(options = {}) {
+    if (!warnedRetired) {
+      warnedRetired = true;
+      console.warn(
+        "[blockrun] SurfClient is deprecated: the gateway retired /v1/surf/* (410 endpoint_retired). Use PriceClient, LLMClient.defi*, LLMClient.pm() or LLMClient.dex* instead."
+      );
+    }
     this.apiAuth = resolveApiKeyAuth(options);
     if (!this.apiAuth) {
       const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
@@ -10730,6 +10738,38 @@ function capOutstandingEscrow(scheme, wallet) {
     return original.call(this, requirements, requestAmount, needed, context, widened, existingDeposit);
   };
 }
+var payScope = new AsyncLocalStorage();
+function registerHookDispatchers(client) {
+  client.onBeforePaymentCreation(async (context) => {
+    for (const hook of payScope.getStore()?.hooks.before ?? []) {
+      const result = await hook(context);
+      if (result && typeof result === "object" && result.abort) return result;
+    }
+    return void 0;
+  });
+  client.onAfterPaymentCreation(async (context) => {
+    const scope = payScope.getStore();
+    for (const hook of scope?.hooks.after ?? []) {
+      try {
+        await hook(context);
+      } catch (error) {
+        if (scope && !scope.afterError) scope.afterError = { error };
+      }
+    }
+  });
+  client.onPaymentCreationFailure(async (context) => {
+    await runFailureHooks(payScope.getStore(), context);
+    return void 0;
+  });
+}
+async function runFailureHooks(scope, context) {
+  for (const hook of scope?.hooks.failure ?? []) {
+    try {
+      await hook(context);
+    } catch {
+    }
+  }
+}
 var RPC_SCOPE_STORE = /* @__PURE__ */ Symbol.for("@blockrun/llm/batch-rpc-scope/v1");
 var RPC_HEADER_HOOK = /* @__PURE__ */ Symbol.for("@blockrun/llm/batch-rpc-headers/v1");
 var sharedGlobal = globalThis;
@@ -10781,6 +10821,11 @@ function intentTarget(intent) {
 var SolanaBatchPayer = class {
   constructor(init) {
     this.init = init;
+    init.configureClient?.({
+      onBeforePaymentCreation: (hook) => void this.hooks.before.push(hook),
+      onAfterPaymentCreation: (hook) => void this.hooks.after.push(hook),
+      onPaymentCreationFailure: (hook) => void this.hooks.failure.push(hook)
+    });
     const { operators, rateLimit, inDoubt } = init.options;
     if (!Array.isArray(operators) || operators.length === 0 || operators.some((o) => typeof o !== "string" || !o)) {
       throw new Error("batch.operators must list at least one base58 operator public key");
@@ -10813,6 +10858,7 @@ var SolanaBatchPayer = class {
     unresolved: 0,
     unresolvedByReason: {}
   };
+  hooks = { before: [], after: [], failure: [] };
   /** A copy of this client's batch counters. */
   stats() {
     return {
@@ -10915,7 +10961,7 @@ var SolanaBatchPayer = class {
       capOutstandingEscrow(scheme, wallet);
       const client = new core.x402Client().register("solana:*", scheme).registerPolicy(scheme.paymentPolicy);
       client.setSpendControls({ maxAmountPerPayment: false });
-      this.init.configureClient?.(client);
+      registerHookDispatchers(client);
       const raw = new core.x402HTTPClient(client);
       const http = {
         getPaymentSettleResponse: (getHeader) => raw.getPaymentSettleResponse(getHeader),
@@ -11209,7 +11255,10 @@ var SolanaBatchPayer = class {
     }
     wallet.active += 1;
     try {
-      return await this.payWith(wallet, paymentRequired, send, rechallenge, closesAtStart ?? wallet.closes);
+      return await payScope.run(
+        { hooks: this.hooks },
+        () => this.payWith(wallet, paymentRequired, send, rechallenge, closesAtStart ?? wallet.closes)
+      );
     } finally {
       wallet.active -= 1;
     }
@@ -11621,6 +11670,18 @@ var SolanaBatchPayer = class {
   /** Build a new batch payment for a 402: the payload, its headers and its kind. */
   async buildPayment(wallet, paymentRequired) {
     const { http, payload } = await this.createPayload(wallet, paymentRequired);
+    const scope = payScope.getStore();
+    if (scope?.afterError) {
+      const { error } = scope.afterError;
+      scope.afterError = void 0;
+      await this.settle(http, payload, () => null, 0);
+      await runFailureHooks(scope, {
+        paymentRequired,
+        selectedRequirements: payload.accepted,
+        error
+      });
+      throw error;
+    }
     const headers = http.encodePaymentSignatureHeader(payload);
     const channelId = payloadChannelId(payload);
     const known = channelId ? wallet.book.find(channelId) : void 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/llm",
-  "version": "3.23.0",
+  "version": "3.23.2",
   "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",