@blockrun/llm 3.22.0 → 3.23.0

package/dist/index.d.ts

@@ -230,6 +230,13 @@ interface Settlement {
     network?: string;
     /** Present and false only when the gateway reported a failed settlement. */
     success?: false;
+    /**
+     * `"free-fallback"` when the gateway served a paid request from a free
+     * fallback model and skipped settlement (`X-Settlement-Skipped`): nothing
+     * moved on chain, so `costUsd` is 0 and nothing was added to `getSpending()`.
+     * `quotedUsd` still states what was signed.
+     */
+    skipped?: "free-fallback";
 }
 interface FunctionCall {
     name: string;
@@ -1479,6 +1486,13 @@ declare class LLMClient {
     private signFrom402;
     /** Send the signed payment and read the answer. The payment may settle from here on. */
     private sendPaid;
+    /**
+     * Book a served, paid chat call and attach its cost. A response the gateway
+     * served from a free fallback with settlement skipped
+     * (`X-Settlement-Skipped: free-fallback`) moved nothing on chain, so it is
+     * not added to `getSpending()` or the cost log, and reports `costUsd: 0`.
+     */
+    private bookPaid;
     /**
      * Sign a payment header and return the PAYMENT-SIGNATURE value.
      * Extracted to share logic between streaming and non-streaming flows.
@@ -1641,7 +1655,7 @@ declare class LLMClient {
     /**
      * Query Predexon prediction market data (GET endpoints).
      *
-     * Access real-time data from Polymarket, Kalshi, dFlow, and Binance Futures.
+     * Access real-time data from Polymarket, Kalshi, Limitless, Opinion, Predict.Fun, Binance Futures, UMA and sports markets.
      * Powered by Predexon. Billed per request.
      *
      * @param path - Endpoint path, e.g. "polymarket/events", "kalshi/markets/12345"
@@ -1839,7 +1853,8 @@ declare class ImageClient {
      * combined with multiple source images.
      *
      * Edit-capable models: `openai/gpt-image-1`, `openai/gpt-image-2`,
-     * `google/nano-banana`, `google/nano-banana-pro`.
+     * `openai/gpt-image-2.5-sunburst`, `google/nano-banana`, `google/nano-banana-2`,
+     * `google/nano-banana-pro`. `mask` is OpenAI-only.
      *
      * @param prompt - Text description of the desired edit
      * @param image - A base64 `data:image/...` URI, or an array of 2–4 such URIs to fuse
@@ -3129,6 +3144,427 @@ declare class BatchCloseDeferredError extends BlockrunError {
         detail: string;
     });
 }
+/**
+ * The outcome of one batch attempt.
+ *
+ * - `paid`: served, and paid with batch.
+ * - `fallback`: pay `exact`. One after a 429 wait carries the fresh 402 it
+ *   fetched, which the `exact` payment must be signed against.
+ * - `served`: the fresh, unpaid challenge sent after a wait was answered with
+ *   a 2xx. That response is the call's result; nothing was paid, and nothing
+ *   must be.
+ * - `failed`: that fresh challenge got neither a 402 nor a 2xx (or no answer,
+ *   or a 402 that cannot be read). Raise `error`, which carries the `"unpaid"`
+ *   retry disposition: the 429 waited out proved nothing was charged, so
+ *   nothing was paid for the call. Never pay `exact` against the stale
+ *   challenge instead.
+ */
+type BatchAttempt = {
+    kind: "paid";
+    response: Response;
+    chargedUsd: number;
+} | {
+    kind: "fallback";
+    reason: string;
+    paymentRequired?: PaymentRequired;
+} | {
+    kind: "served";
+    response: Response;
+} | {
+    kind: "failed";
+    error: unknown;
+};
+/**
+ * The answer to a fresh, unpaid challenge request (see
+ * {@link SolanaBatchPayer.pay}): a 402 to pay, or a 2xx that served the
+ * request without a payment. Anything else is thrown.
+ */
+type Rechallenge = {
+    kind: "challenge";
+    paymentRequired: PaymentRequired;
+} | {
+    kind: "served";
+    response: Response;
+};
+interface SolanaBatchPayerInit {
+    options: SolanaBatchOptions;
+    secretKey: () => Promise<Uint8Array>;
+    address: () => Promise<string>;
+    rpcUrl: string;
+    /** 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.
+     */
+    configureClient?: (client: X402ClientLike) => void;
+}
+/**
+ * The slice of `@x402/core`'s x402Client handed to
+ * {@link SolanaBatchPayerInit.configureClient}: its payment-creation hooks.
+ * Structural, so this package's types never require the optional
+ * `@x402/core` peer to be installed.
+ */
+interface X402ClientLike {
+    onBeforePaymentCreation(hook: (context: X402HookContext) => Promise<unknown> | unknown): unknown;
+    onAfterPaymentCreation(hook: (context: X402HookContext) => Promise<unknown> | unknown): unknown;
+    onPaymentCreationFailure(hook: (context: X402HookContext) => Promise<unknown> | unknown): unknown;
+}
+/** What a payment-creation hook receives: at least the requirement being paid. */
+interface X402HookContext {
+    selectedRequirements: PaymentRequirement & {
+        scheme: string;
+        network: string;
+        amount?: string;
+    };
+    [key: string]: unknown;
+}
+/**
+ * One wallet's batch-settlement payer. Owned by a SolanaLLMClient.
+ *
+ * At most one batch request is in flight per wallet: the server-signed scheme
+ * allows a single pending authorization per channel. Concurrent calls do not
+ * queue behind it, they pay with `exact`, so batch never makes a parallel
+ * workload slower than it is today. The exception is a 429 cooldown: then
+ * every call for the wallet waits it out (within its own `rateLimit` budget)
+ * rather than send the gateway another channel open it would refuse.
+ */
+declare class SolanaBatchPayer {
+    private readonly init;
+    private state?;
+    private readonly maxAttempts;
+    private readonly maxWaitMs;
+    private readonly inDoubtMaxWaitMs;
+    private readonly counters;
+    constructor(init: SolanaBatchPayerInit);
+    /** A copy of this client's batch counters. */
+    stats(): SolanaBatchStats;
+    private storeFile;
+    /**
+     * This wallet's shared batch state, or why this client cannot use batch:
+     * another client in this process holds the wallet with a different trust
+     * configuration, or another live process owns its channel file.
+     */
+    private wallet;
+    private build;
+    /** Run a scheme call so its RPC requests carry this client's `rpcHeaders`. */
+    private withRpcHeaders;
+    /**
+     * Drop everything this wallet knows about one channel, on disk and in
+     * memory, leaving its other channels' records alone. The scheme is rebuilt
+     * on the next call, without the closed channel in its memory.
+     */
+    private forget;
+    /**
+     * Stop trusting the record of the channel a payload paid into: the next
+     * payment re-reads that channel from the chain first. The scheme has
+     * already restored (or, for an open, dropped) its record; the book still
+     * knows the channel and the cumulative it last confirmed.
+     */
+    private distrust;
+    /**
+     * The channel's total deposit if a deposit payload landed: the confirmed
+     * deposit plus this one (for an open, nothing plus this one). Undefined for
+     * a payment without a deposit, or a channel the SDK has no record of.
+     */
+    private depositExpectation;
+    /**
+     * Re-read every distrusted channel from the chain, at `finalized`
+     * commitment, and rewrite its record: the on-chain deposit, and the highest
+     * of the cumulative the SDK can vouch for, the cumulative the stored record
+     * already confirmed, and the on-chain settled amount. A closing or closed
+     * channel is dropped. The scheme is rebuilt to load the repaired record.
+     *
+     * The stored cumulative is never moved backwards. A deposit's intent can
+     * outlive the receipt that reconciled it (the process died, or the journal
+     * could not be cleared, after the scheme saved the new state), so its
+     * cumulative may predate vouchers the scheme has since confirmed; and
+     * vouchers are redeemed on-chain asynchronously, so `settled` can lag too.
+     * Rewriting the record with either would leave every later voucher
+     * unreconcilable.
+     *
+     * A deposit in doubt is settled by the chain alone:
+     * - landed: the finalized channel holds at least the deposit it would
+     *   bring (and at least what the record already claimed);
+     * - never landed: the finalized chain is {@link LANDING_MARGIN_BLOCKS}
+     *   past the target's anchor height, and a read at least that recent still
+     *   does not show it. An open's record is then dropped; a top-up's channel
+     *   is rewritten with the deposit it really has.
+     * Until one of those holds, it is pending. This settles only the deposit:
+     * whether the gateway charged the payment that carried it is never read
+     * from the chain.
+     *
+     * @throws ResyncError when the chain cannot be read, or a deposit may still
+     *   land: the caller pays exact and the re-read is tried again next call.
+     *   Nothing opens or tops up a channel while any re-read is pending.
+     */
+    private resync;
+    /**
+     * A distrusted channel's account at `finalized` commitment, checked to be
+     * this wallet's channel for the record's operator and mint.
+     *
+     * @throws ResyncError (`channel_unreadable`) for any other payment channel.
+     */
+    private readOwnChannel;
+    /**
+     * Make one event observable three ways: a stderr line (every time, never
+     * deduplicated), this client's counters, and the caller's `onEvent`.
+     */
+    private report;
+    /** Report a fallback and tell the caller to pay exact. */
+    private fallback;
+    /**
+     * Pay one 402 with batch-settlement, or say why the caller should use exact.
+     *
+     * `send` replays the original request with the payment headers. Every send
+     * goes through {@link sendOnce}, the one place an answer is classified as
+     * charged, not charged, or in doubt:
+     *
+     * - charged: the 2xx is returned (`paid`);
+     * - not charged (the gateway's explicit answer to a first send): a 429
+     *   whose receipt proves nothing was broadcast is backed off
+     *   (`Retry-After`, else 1s, 2s, 4s with jitter) and paid again with a new
+     *   payment built from a fresh 402 (`rechallenge`: the original's
+     *   `recentBlockhash` / `recentSlot` can be stale by then), within
+     *   `rateLimit.maxAttempts` / `maxWaitMs`, then with exact; any other is
+     *   paid with exact (`fallback`). A fresh challenge served with a 2xx is
+     *   the call's result (`served`, nothing paid); one that fails otherwise
+     *   is the call's error (`failed`, `"unpaid"`), never an exact payment
+     *   against the stale challenge;
+     * - in doubt: ends only with a definitive success receipt from a replay
+     *   of the identical payment ({@link resolveInDoubt}: the one replay a
+     *   receipt-less 429 is allowed, or the replays of a payment carrying a
+     *   payment identifier while the gateway says one can succeed, within
+     *   `inDoubt.maxWaitMs`), or a thrown {@link BatchPaymentUnresolvedError}.
+     *   No new authorization, no new deposit, no exact payment and no fallback
+     *   model is ever paid for a call in doubt.
+     *
+     * The wallet stays in cooldown after a 429, so its other calls wait
+     * instead of sending opens of their own. After a deposit the facilitator
+     * refused before broadcasting it (a 402 with a failed `batch_*` admission
+     * receipt), its calls do not wait: they pay exact at once
+     * (`admission_refused`) until the refusal cooldown ends.
+     *
+     * @param closesAtStart - {@link closeFence}, taken before the call's first
+     *   (unpaid) request. If a close completed since, the call pays exact
+     *   (`closed_during_call`): it started before the close, so it must not
+     *   open a channel the caller believes is closed.
+     */
+    pay(paymentRequired: PaymentRequired, send: (headers: Record<string, string>) => Promise<Response>, rechallenge: () => Promise<Rechallenge>, closesAtStart?: number): Promise<BatchAttempt>;
+    /**
+     * The close fence for a call about to send its first request: how many
+     * closes this wallet has completed so far, to hand to {@link pay}.
+     * `close()` refuses while a call is inside `pay()`, but a call still
+     * waiting for its 402 is not there yet; the fence covers that window.
+     * Undefined when the wallet cannot be named (no fence then; `pay()`
+     * reports why batch is unavailable).
+     */
+    closeFence(): Promise<number | undefined>;
+    /** {@link pay}, for a wallet this client may use. */
+    private payWith;
+    /**
+     * Put the wallet in a 429 cooldown for `delay` ms (`Retry-After`, or the
+     * default backoff), and return how long this call would have to wait.
+     *
+     * The shared cooldown is capped at `rateLimit.maxWaitMs`, so one header,
+     * however long, never keeps the wallet's calls off batch for longer than
+     * the retry budget. This call still weighs the full delay: one it cannot
+     * wait out within its budget is not waited at all, and the caller pays
+     * exact (or raises a payment in doubt) at once.
+     */
+    private coolDown;
+    /**
+     * Try to end a payment in doubt with the gateway's own word.
+     *
+     * The one source of evidence this SDK accepts is a definitive success
+     * receipt on a byte-identical replay of the payment. Any other answer to a
+     * replay (a 402 or `duplicate_settlement`, which mean the original reached
+     * the gateway; a 409; another 429; a 5xx; a timeout) leaves it in doubt.
+     *
+     * - A payment carrying a payment identifier is replayed for as long as
+     *   the gateway says a later replay can succeed ({@link replayInDoubt}).
+     * - Any other payment gets a replay only after a 429 without a receipt:
+     *   one, after its backoff (the owner's bounded safety attempt), within
+     *   `rateLimit`. Every other in-doubt outcome is never replayed.
+     *
+     * Chain state is not evidence here: it can settle a deposit (see
+     * `resync`), never whether the gateway charged.
+     *
+     * @returns the charged replay, or the doubt to raise.
+     */
+    private resolveInDoubt;
+    /**
+     * Replay a payment in doubt that carries a payment identifier until the
+     * gateway's answer settles it.
+     *
+     * A gateway that declares `payment-identifier` stores each paid response
+     * under its identifier and answers a byte-identical replay of a completed
+     * request with it, the original receipt included; while the original is
+     * still running, it answers 409 with a `Retry-After`. So the identical
+     * payment (the same `PAYMENT-SIGNATURE` header and the same body) is
+     * replayed for as long as the last answer says a later one can succeed
+     * ({@link replayMayResolve}), after {@link inDoubtWait} each time, as long
+     * as the wait fits in `inDoubt.maxWaitMs`, counted from the first doubt:
+     * every wait (as long as it really took) and every replay's round trip. A
+     * replay already sent is not cut short. These replays do not count
+     * against `rateLimit`; a 429 among them still puts the wallet in cooldown.
+     *
+     * Every answer that does not settle it is held back from the scheme
+     * ({@link InDoubt.held}) and handed over only once no replay follows, so
+     * the scheme rolls the payment back once, or takes the receipt that answer
+     * carries. That is the last answer, unless an earlier one carried a
+     * success receipt and the later ones do not: a success receipt is the
+     * gateway's word that it charged, and handing the scheme a receipt-less
+     * refusal of a replay instead would roll a real charge back and desync the
+     * channel's cumulative.
+     *
+     * @returns the charged replay, or the doubt to raise.
+     */
+    private replayInDoubt;
+    /**
+     * Raise a payment in doubt: release the scheme's hold on it (the channel
+     * goes back to its confirmed state), put a deposit's channel in doubt so
+     * it is re-read from the chain before anything pays into it again, report
+     * the `unresolved` event, and throw {@link BatchPaymentUnresolvedError}.
+     */
+    private raiseUnresolved;
+    /** Build a new batch payment for a 402: the payload, its headers and its kind. */
+    private buildPayment;
+    /**
+     * Write a deposit's intent to the wallet's journal before it is sent
+     * (with the file store: the file and its directory fsynced).
+     *
+     * @throws when it cannot be recorded; the deposit must then not be sent.
+     */
+    private journalDeposit;
+    /**
+     * Remove a deposit's intent once it is reconciled. A failure is logged,
+     * not thrown: the intent then outlives its deposit, and after a restart
+     * the chain re-read settles it again.
+     */
+    private forgetIntent;
+    /**
+     * THE choke point: send a batch payment once and classify the answer.
+     *
+     * The only caller of `send` for a batch payment, and the only place its
+     * outcome is decided (see {@link SendOutcome}). Every exception once the
+     * send has started is `in_doubt`, whatever its type or `cause.code`: the
+     * request may have reached the gateway. "Not charged" is only ever minted
+     * here, and only for a first send.
+     *
+     * @param retry - count this send in `retries` (it follows this call's own 429).
+     * @param replay - this is a replay of a payment in doubt: only a 2xx with
+     *   a success receipt counts, everything else stays in doubt.
+     */
+    private sendOnce;
+    /** {@link sendOnce}'s classifier, for an HTTP answer. */
+    private classify;
+    /**
+     * {@link classify}, past a receipt-less 429. With `hold`, the answer is not
+     * handed to the scheme: its receipt is only read.
+     */
+    private classifyAnswer;
+    /**
+     * Build the payment payload, re-reading any distrusted channel from the
+     * chain first. A stored record the book refuses to hand over (a deposit a
+     * dead process never heard back about), or one a top-up's read found
+     * unusable ({@link prepareTopUp}), is re-read and the payload rebuilt
+     * once.
+     */
+    private createPayload;
+    /**
+     * When this payment will top up the wallet's channel, read how much of its
+     * deposit is already settled on-chain (at `finalized` commitment, so never
+     * more than will stay settled), so `maxDeposit` caps the escrow still at
+     * stake rather than every deposit the channel ever took.
+     *
+     * Only a top-up costs this read (a channel's balance decides it, from the
+     * stored record). If the read fails, nothing settled is assumed, which is
+     * the stricter, lifetime cap. If the chain shows a larger deposit than the
+     * record, the record is behind (a deposit it never heard about landed):
+     * sizing a top-up from it could exceed `maxDeposit`, so this call pays
+     * exact and the channel is re-read before the next payment. If
+     * `@x402/svm`'s channel layout is not the one this SDK decodes, or the
+     * account at the channel's address cannot be read as a channel, the call
+     * pays exact (`channel_unreadable`), record kept. If
+     * the finalized channel is closing or closed, or is not this wallet's for
+     * the record's operator and mint, no top-up is sized from the record: it
+     * is re-read at once (`channel_unusable`), see {@link createPayload}.
+     */
+    private prepareTopUp;
+    /**
+     * Hand the gateway's answer to the scheme, which verifies the operator's
+     * voucher and advances (or rolls back) the channel's local state.
+     *
+     * A malformed receipt must not lose a response the caller has been served,
+     * so a scheme error is logged rather than thrown.
+     */
+    private settle;
+    /**
+     * Close the channel the gateway's current challenge names and return its
+     * unused escrow to the wallet.
+     *
+     * The scheme keeps a closed channel in its records, and would go on paying
+     * into it, so a successful close forgets that channel. The next batch call
+     * finds no open channel on-chain and opens a new one. Any other channel
+     * (say, one opened with an operator key that is being rotated out) keeps
+     * its record, so it can still be closed without an on-chain scan. A
+     * client-signed channel an earlier SDK version opened is closed too, once
+     * the trusted server-signed one has no record (see {@link refundTarget}).
+     *
+     * @param url - any batch-enabled route on the gateway the channel was opened with.
+     * @throws BatchCloseDeferredError while a batch call for the wallet is in
+     *   flight, or while any of its deposits is in doubt (until a finalized
+     *   chain read settles it). Nothing is refunded or forgotten then.
+     */
+    close(url: string): Promise<unknown>;
+    /**
+     * Re-read every distrusted channel before a close. A deposit still in
+     * doubt defers the close: refunding (or forgetting) a channel a deposit
+     * may yet land on could strand that deposit, and after a restart nothing
+     * would remember it. A record re-read that only failed for another reason
+     * (an RPC error on a channel with no deposit in doubt) does not.
+     */
+    private settleDoubtsForClose;
+    /**
+     * The channel a close targets: the one the gateway's refund challenge
+     * names, by the scheme's storage key for its trusted server-signed accept
+     * (network, asset, receiver, fee payer, withdraw delay, receiver
+     * authorizer, operator). Probed with an unpaid GET, as `@x402/svm`'s own
+     * refund probes; that accept is then handed to the refund, so upstream
+     * does not probe again and pick another accept.
+     *
+     * A legacy client-signed channel (opened by an earlier SDK version, which
+     * could pay a client-signed accept; this one never opens one) must stay
+     * refundable. When the trusted server-signed accept has no stored record,
+     * or there is none, a client-signed accept in the challenge whose storage
+     * key names a stored client-signed record is the target instead, and the
+     * refund runs through `@x402/svm`'s client-signed path (a refund voucher
+     * signed by the payer at its confirmed cumulative). The signer modes match:
+     * a server-signed record is never refunded under a client-signed accept.
+     */
+    private refundTarget;
+    /**
+     * Get the stored channel `key` ready to refund.
+     *
+     * `@x402/svm` refunds a server-signed channel only from the scheme's memory,
+     * or after an on-chain scan that many RPCs refuse; it never reads the
+     * stored record. So the target channel is loaded into a freshly built
+     * scheme, and only that one: upstream's refund falls back to the first
+     * channel in memory for the same receiver and asset, whatever its operator.
+     * A record in doubt (a deposit this process never confirmed, or a pending
+     * deposit left by a process that died) is re-read from the chain before it
+     * is loaded. If a re-read cannot settle a record, the refund is still
+     * attempted and may find the channel by its scan.
+     */
+    private prepareClose;
+}
 
 interface SolanaLLMClientOptions extends ApiKeyOptions {
     /** bs58-encoded Solana secret key (64 bytes). Optional if SOLANA_WALLET_KEY env var is set. */
@@ -3789,10 +4225,10 @@ declare class ChatCompletions {
     /**
      * Create a chat completion (OpenAI-compatible).
      */
-    create(params: OpenAIChatCompletionParams): Promise<OpenAIChatCompletionResponse>;
     create(params: OpenAIChatCompletionParams & {
         stream: true;
     }): Promise<AsyncIterable<OpenAIChatCompletionChunk>>;
+    create(params: OpenAIChatCompletionParams): Promise<OpenAIChatCompletionResponse>;
     private createStream;
     private transformResponse;
 }
@@ -3971,4 +4407,4 @@ declare function readSettlement(response: Response, quotedUsd: number, scheme: S
     settlement: Settlement;
 };
 
-export { APIError, API_KEY_URL, ARC_CHAIN_ID, AnthropicClient, type AnyTool, type ApiKeyOptions, type AudioModel, type AudioTrack, BASE_CHAIN_ID, BLOCKRUN_SOL_OPERATOR, type BarResolution, BatchCloseDeferredError, type BatchPayloadKind, BatchPaymentUnresolvedError, type BatchUnresolvedReason, type BlockRunAnthropicOptions, BlockrunClient, type BlockrunClientOptions, BlockrunError, type CallInitiatedResponse, type CallModel, type CallOptions, type CallStatusResponse, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, DEFAULT_BATCH_IN_DOUBT, DEFAULT_BATCH_RATE_LIMIT, EVM_NETWORKS, type EvmNetwork, 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, NETWORK_ALIASES, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PHONE_PRICES, PORTAL_URL, PORTRAIT_ENROLLMENT_PRICE_USD, PaymentError, type PaymentLinks, type PhoneBuyOptions, type PhoneBuyResponse, PhoneClient, type PhoneClientOptions, type PhoneListResponse, type PhoneLookupResponse, type PhoneNumberRecord, type PhoneReleaseResponse, type PhoneRenewResponse, type PollOptions, PortraitClient, type PortraitClientOptions, type PortraitEnrollOptions, type PortraitEnrollResponse, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, RPC_PRICE_USD, type ResponseFormat, RetiredEndpointError, type RetryDisposition, type RoutingDecision, type RoutingProfile, type RoutingTaskType, type RoutingTier, type RoutingTierConfig, type RpcBatchRequest, RpcClient, type RpcClientOptions, type RpcError, type RpcNetwork, type RpcResponse, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SUPPORTED_NETWORKS, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type Settlement, type SmartChatCompletionOptions, type SmartChatCompletionResponse, type SmartChatOptions, type SmartChatResponse, type SolanaBatchEvent, type SolanaBatchOptions, type SolanaBatchStats, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type SoundEffectOptions, type SpeechAudio, SpeechClient, type SpeechClientOptions, type SpeechGenerateOptions, type SpeechModel, type SpeechResponse, type SpeechVoice, type Spending, type SpendingReport, type StockMarket, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_ARC, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, type UrlCitation, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoiceInfo, type VoicePreset, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type WebSearchTool, type XSearchSource, type XSearchTool, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, evmNetwork, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatSolanaWalletMigrationNotice, formatWalletCreatedMessage, formatWalletMigrationNotice, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, importSolanaWallet, importWallet, listDiscoveredSolanaWallets, listDiscoveredWallets, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, readSettlement, retryDisposition, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentClient, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, toWireSearchParameters, toWireTools, validateMaxTokens, validateModel, validateTemperature, validateTopP };
+export { APIError, API_KEY_URL, ARC_CHAIN_ID, AnthropicClient, type AnyTool, type ApiKeyOptions, type AudioModel, type AudioTrack, BASE_CHAIN_ID, BLOCKRUN_SOL_OPERATOR, type BarResolution, type BatchAttempt, BatchCloseDeferredError, type BatchPayloadKind, BatchPaymentUnresolvedError, type BatchUnresolvedReason, type BlockRunAnthropicOptions, BlockrunClient, type BlockrunClientOptions, BlockrunError, type CallInitiatedResponse, type CallModel, type CallOptions, type CallStatusResponse, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, DEFAULT_BATCH_IN_DOUBT, DEFAULT_BATCH_RATE_LIMIT, EVM_NETWORKS, type EvmNetwork, 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, NETWORK_ALIASES, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PHONE_PRICES, PORTAL_URL, PORTRAIT_ENROLLMENT_PRICE_USD, PaymentError, type PaymentLinks, type PhoneBuyOptions, type PhoneBuyResponse, PhoneClient, type PhoneClientOptions, type PhoneListResponse, type PhoneLookupResponse, type PhoneNumberRecord, type PhoneReleaseResponse, type PhoneRenewResponse, type PollOptions, PortraitClient, type PortraitClientOptions, type PortraitEnrollOptions, type PortraitEnrollResponse, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, RPC_PRICE_USD, type Rechallenge, type ResponseFormat, RetiredEndpointError, type RetryDisposition, type RoutingDecision, type RoutingProfile, type RoutingTaskType, type RoutingTier, type RoutingTierConfig, type RpcBatchRequest, RpcClient, type RpcClientOptions, type RpcError, type RpcNetwork, type RpcResponse, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SUPPORTED_NETWORKS, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type Settlement, type SmartChatCompletionOptions, type SmartChatCompletionResponse, type SmartChatOptions, type SmartChatResponse, type SolanaBatchEvent, type SolanaBatchOptions, SolanaBatchPayer, type SolanaBatchPayerInit, type SolanaBatchStats, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type SoundEffectOptions, type SpeechAudio, SpeechClient, type SpeechClientOptions, type SpeechGenerateOptions, type SpeechModel, type SpeechResponse, type SpeechVoice, type Spending, type SpendingReport, type StockMarket, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_ARC, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, type UrlCitation, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoiceInfo, type VoicePreset, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type WebSearchTool, type X402ClientLike, type X402HookContext, type XSearchSource, type XSearchTool, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, evmNetwork, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatSolanaWalletMigrationNotice, formatWalletCreatedMessage, formatWalletMigrationNotice, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, importSolanaWallet, importWallet, listDiscoveredSolanaWallets, listDiscoveredWallets, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, readSettlement, retryDisposition, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentClient, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, toWireSearchParameters, toWireTools, validateMaxTokens, validateModel, validateTemperature, validateTopP };

package/dist/index.js

@@ -423,7 +423,15 @@ function readSettlement(response, quotedUsd, scheme) {
   };
   return { costUsd, settlement };
 }
+function settlementSkipped(response) {
+  return response.headers.get("X-Settlement-Skipped") === "free-fallback";
+}
 function withCost(body, response, bookedUsd, scheme) {
+  if (settlementSkipped(response)) {
+    body.costUsd = 0;
+    body.settlement = { ...readSettlement(response, bookedUsd, scheme).settlement, skipped: "free-fallback" };
+    return body;
+  }
   body.costUsd = bookedUsd;
   body.settlement = readSettlement(response, bookedUsd, scheme).settlement;
   return body;
@@ -4694,7 +4702,7 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.22.0";
+var SDK_VERSION = "3.23.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
@@ -5260,11 +5268,7 @@ var LLMClient = class _LLMClient {
           }
           throw new APIError(`API error after payment: ${retryResp2.status}`, retryResp2.status, sanitizeErrorResponse(errorBody));
         }
-        const costUsd2 = parseFloat(details.amount) / 1e6;
-        this.sessionCalls += 1;
-        this.sessionTotalUsd += costUsd2;
-        this.recordCost(url, costUsd2, { body, network: details.network });
-        return withCost(await this.parseChatResponse(retryResp2), retryResp2, costUsd2, "exact");
+        return this.bookPaid(url, body, details, retryResp2);
       }
     }
     if (retryResponse.status === 402) {
@@ -5283,11 +5287,22 @@ var LLMClient = class _LLMClient {
         sanitizeErrorResponse(errorBody)
       );
     }
+    return this.bookPaid(url, body, details, retryResponse);
+  }
+  /**
+   * Book a served, paid chat call and attach its cost. A response the gateway
+   * served from a free fallback with settlement skipped
+   * (`X-Settlement-Skipped: free-fallback`) moved nothing on chain, so it is
+   * not added to `getSpending()` or the cost log, and reports `costUsd: 0`.
+   */
+  async bookPaid(url, body, details, response) {
     const costUsd = parseFloat(details.amount) / 1e6;
-    this.sessionCalls += 1;
-    this.sessionTotalUsd += costUsd;
-    this.recordCost(url, costUsd, { body, network: details.network });
-    return withCost(await this.parseChatResponse(retryResponse), retryResponse, costUsd, "exact");
+    if (!settlementSkipped(response)) {
+      this.sessionCalls += 1;
+      this.sessionTotalUsd += costUsd;
+      this.recordCost(url, costUsd, { body, network: details.network });
+    }
+    return withCost(await this.parseChatResponse(response), response, costUsd, "exact");
   }
   /**
    * Sign a payment header and return the PAYMENT-SIGNATURE value.
@@ -6033,7 +6048,7 @@ var LLMClient = class _LLMClient {
   /**
    * Query Predexon prediction market data (GET endpoints).
    *
-   * Access real-time data from Polymarket, Kalshi, dFlow, and Binance Futures.
+   * Access real-time data from Polymarket, Kalshi, Limitless, Opinion, Predict.Fun, Binance Futures, UMA and sports markets.
    * Powered by Predexon. Billed per request.
    *
    * @param path - Endpoint path, e.g. "polymarket/events", "kalshi/markets/12345"
@@ -6360,7 +6375,8 @@ var ImageClient = class {
    * combined with multiple source images.
    *
    * Edit-capable models: `openai/gpt-image-1`, `openai/gpt-image-2`,
-   * `google/nano-banana`, `google/nano-banana-pro`.
+   * `openai/gpt-image-2.5-sunburst`, `google/nano-banana`, `google/nano-banana-2`,
+   * `google/nano-banana-pro`. `mask` is OpenAI-only.
    *
    * @param prompt - Text description of the desired edit
    * @param image - A base64 `data:image/...` URI, or an array of 2–4 such URIs to fuse
@@ -10899,6 +10915,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);
       const raw = new core.x402HTTPClient(client);
       const http = {
         getPaymentSettleResponse: (getHeader) => raw.getPaymentSettleResponse(getHeader),
@@ -13274,7 +13291,7 @@ var SolanaLLMClient = class {
       throw withDisposition(error, "paid-or-in-doubt");
     }
     await this.assertPaid(retryResponse);
-    this.recordSettlement(costUsd);
+    if (!settlementSkipped(retryResponse)) this.recordSettlement(costUsd);
     const paid = await this.readPaidJson(retryResponse);
     return withCost(paid, retryResponse, costUsd, "exact");
   }
@@ -14014,6 +14031,7 @@ export {
   SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH,
   SUPPORTED_NETWORKS,
   SearchClient,
+  SolanaBatchPayer,
   SolanaLLMClient,
   SpeechClient,
   SurfClient,

package/package.json

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