@blockrun/llm 1.15.0 → 2.1.0

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;
@@ -242,6 +261,13 @@ interface ChatOptions {
     search?: boolean;
     /** Full Live Search configuration (for search-enabled models) */
     searchParameters?: SearchParameters;
+    /**
+     * Models to try in order if the primary returns a transient error
+     * (timeout, network, 5xx). 4xx and PaymentError still propagate
+     * immediately. `smartChat` populates this from the routing tier's
+     * fallback chain automatically.
+     */
+    fallbackModels?: string[];
 }
 interface ChatCompletionOptions {
     /** Max tokens to generate */
@@ -258,6 +284,12 @@ interface ChatCompletionOptions {
     tools?: Tool[];
     /** Tool selection strategy */
     toolChoice?: ToolChoice;
+    /**
+     * Models to try in order if the primary returns a transient error
+     * (timeout, network, 5xx). 4xx and PaymentError still propagate
+     * immediately.
+     */
+    fallbackModels?: string[];
 }
 type RoutingProfile = "free" | "eco" | "auto" | "premium";
 type RoutingTier = "SIMPLE" | "MEDIUM" | "COMPLEX" | "REASONING";
@@ -270,6 +302,12 @@ interface RoutingDecision {
     costEstimate: number;
     baselineCost: number;
     savings: number;
+    /**
+     * Remaining tier models with known pricing, in fallback order. `chat()`
+     * walks this list when the primary model hits a transient error
+     * (timeout, network, 5xx). Excludes the primary itself.
+     */
+    fallbacks?: string[];
 }
 interface SmartChatOptions extends ChatOptions {
     /** Routing profile: free (zero cost), eco (budget), auto (balanced), premium (best quality) */
@@ -689,29 +727,11 @@ declare class APIError extends BlockrunError {
  * BlockRun LLM Gateway Client.
  *
  * Provides access to multiple LLM providers (OpenAI, Anthropic, Google, etc.)
- * with automatic x402 micropayments on Base chain.
- *
- * Networks:
- * - Mainnet: https://blockrun.ai/api (Base, Chain ID 8453)
- * - Testnet: https://testnet.blockrun.ai/api (Base Sepolia, Chain ID 84532)
- *
- * @example Testnet usage
- * ```ts
- * // Use testnet convenience function
- * import { testnetClient } from '@blockrun/llm';
- * const client = testnetClient({ privateKey: '0x...' });
- * const response = await client.chat('openai/gpt-oss-20b', 'Hello!');
- *
- * // Or configure manually
- * const client = new LLMClient({
- *   privateKey: '0x...',
- *   apiUrl: 'https://testnet.blockrun.ai/api'
- * });
- * ```
+ * with automatic x402 micropayments on Base chain (Mainnet, Chain ID 8453).
+ * API base: https://blockrun.ai/api
  */
 declare class LLMClient {
     static readonly DEFAULT_API_URL = "https://blockrun.ai/api";
-    static readonly TESTNET_API_URL = "https://testnet.blockrun.ai/api";
     private account;
     private privateKey;
     private apiUrl;
@@ -779,17 +799,48 @@ declare class LLMClient {
     private getModelPricing;
     /**
      * Fetch model pricing from API.
+     *
+     * For flat-billed models (e.g. ZAI GLM-5 family at $0.001/call) the
+     * router still expects per-token rates, so we synthesise an equivalent
+     * per-token price assuming ~1500 total tokens per call. Without this,
+     * flat models would resolve to inputPrice=outputPrice=0 and the router
+     * would treat them as free, biasing routing decisions and reporting
+     * inflated savings %.
      */
     private fetchModelPricing;
     /**
      * Full chat completion interface (OpenAI-compatible).
      *
-     * @param model - Model ID
+     * When `fallbackModels` is set, transient failures (timeouts, network
+     * errors, 5xx) on the primary model trigger a retry against the next
+     * model in the list before raising. 4xx errors and PaymentError
+     * propagate immediately — those aren't "swap upstream and retry"
+     * situations. Each fallback hop logs one stderr line.
+     *
+     * @param model - Primary model ID
      * @param messages - Array of messages with role and content
      * @param options - Optional completion parameters
      * @returns ChatResponse object with choices and usage
      */
     chatCompletion(model: string, messages: ChatMessage[], options?: ChatCompletionOptions): Promise<ChatResponse>;
+    /**
+     * Write a canonical cost_log entry after a settled x402 payment.
+     * Best-effort: failures here must never break a successful API call.
+     * Mirrors what Franklin's AgentClient writes via src/agent/llm.ts so
+     * 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.
      */
@@ -836,29 +887,37 @@ declare class LLMClient {
      */
     private fetchWithTimeout;
     /**
-     * List available LLM models with pricing.
+     * List available models with pricing.
+     *
+     * Returns the full `/v1/models` unified catalog (chat + image + music).
+     * The shape preserves backwards compatibility — image/music rows have
+     * `inputPrice = outputPrice = 0` since those fields don't apply, and
+     * their per-call price surfaces via `flatPrice`.
      */
     listModels(): Promise<Model[]>;
     /**
      * List available image generation models with pricing.
+     *
+     * The dedicated `/v1/images/models` endpoint was deprecated server-side;
+     * image models live in the unified `/v1/models` catalog under
+     * `categories: ["image", ...]`. This method filters that catalog so
+     * existing callers keep working.
      */
     listImageModels(): Promise<ImageModel[]>;
     /**
-     * List all available models (both LLM and image) with pricing.
+     * List all available models (chat, image, music, etc.) with pricing.
      *
-     * @returns Array of all models with 'type' field ('llm' or 'image')
-     *
-     * @example
-     * const models = await client.listAllModels();
-     * for (const model of models) {
-     *   if (model.type === 'llm') {
-     *     console.log(`LLM: ${model.id} - $${model.inputPrice}/M input`);
-     *   } else {
-     *     console.log(`Image: ${model.id} - $${model.pricePerImage}/image`);
-     *   }
-     * }
+     * @returns Array of all models with `type` field set from category
+     * (`llm` for chat, `image` / `music` for media). Backwards-compat:
+     * chat models always report `type: "llm"`.
      */
     listAllModels(): Promise<(Model | ImageModel)[]>;
+    /**
+     * Internal: fetch the raw `/v1/models` catalog without normalising shape.
+     * Used by listImageModels / listAllModels so each can pick category-
+     * specific fields.
+     */
+    private fetchRawModels;
     /**
      * Edit an image using img2img.
      *
@@ -876,6 +935,17 @@ declare class LLMClient {
      * @returns SearchResult with summary and citations
      */
     search(query: string, options?: SearchOptions): Promise<SearchResult>;
+    /**
+     * Generic Exa endpoint proxy (POST). Useful when you need an Exa API
+     * surface that the typed wrappers below don't expose.
+     *
+     * @param path - Exa endpoint segment: "search" | "find-similar" | "contents" | "answer"
+     * @param body - Request body (see Exa API docs)
+     *
+     * @example
+     * const results = await client.exa("search", { query: "latest AI research", numResults: 5 });
+     */
+    exa(path: string, body: Record<string, unknown>): Promise<Record<string, unknown>>;
     /**
      * Neural web search via Exa. Returns semantically relevant URLs and metadata.
      * Understands meaning, not just keywords. $0.01/call.
@@ -907,9 +977,7 @@ declare class LLMClient {
      */
     exaFindSimilar(url: string, options?: ExaFindSimilarOptions): Promise<ExaSearchResponse>;
     /**
-     * Get USDC balance on Base network.
-     *
-     * Automatically detects mainnet vs testnet based on API URL.
+     * Get USDC balance on Base mainnet.
      *
      * @returns USDC balance as a float (6 decimal places normalized)
      *
@@ -1120,38 +1188,7 @@ declare class LLMClient {
      * Get the wallet address being used for payments.
      */
     getWalletAddress(): string;
-    /**
-     * Check if client is configured for testnet.
-     */
-    isTestnet(): boolean;
 }
-/**
- * Create a testnet LLM client for development and testing.
- *
- * This is a convenience function that creates an LLMClient configured
- * for the BlockRun testnet (Base Sepolia).
- *
- * @param options - Client options (privateKey required unless BASE_CHAIN_WALLET_KEY env var is set)
- * @returns LLMClient configured for testnet
- *
- * @example
- * ```ts
- * import { testnetClient } from '@blockrun/llm';
- *
- * const client = testnetClient({ privateKey: '0x...' });
- * const response = await client.chat('openai/gpt-oss-20b', 'Hello!');
- * ```
- *
- * Testnet Setup:
- * 1. Get testnet ETH from https://www.alchemy.com/faucets/base-sepolia
- * 2. Get testnet USDC from https://faucet.circle.com/
- * 3. Use your wallet with testnet funds
- *
- * Available Testnet Models:
- * - openai/gpt-oss-20b
- * - openai/gpt-oss-120b
- */
-declare function testnetClient(options?: Omit<LLMClientOptions, 'apiUrl'>): LLMClient;
 
 /**
  * BlockRun Image Client - Generate images via x402 micropayments.
@@ -1216,6 +1253,11 @@ declare class ImageClient {
     edit(prompt: string, image: string, options?: ImageEditOptions): Promise<ImageResponse>;
     /**
      * List available image generation models with pricing.
+     *
+     * The dedicated `/v1/images/models` endpoint was deprecated server-side;
+     * image models live in the unified `/v1/models` catalog under
+     * `categories: ["image", ...]`. This method filters that catalog so
+     * existing callers keep working.
      */
     listImageModels(): Promise<ImageModel[]>;
     /**
@@ -1850,18 +1892,29 @@ declare function status(): Promise<{
     balance: number;
 }>;
 
+/** Canonical on-wire schema for cost_log.jsonl entries. */
 interface CostEntry {
-    timestamp: string;
-    model: string;
-    inputTokens: number;
-    outputTokens: number;
-    costUsd: number;
+    /** Unix epoch seconds (float, millisecond precision). */
+    ts: number;
+    /** API endpoint path, e.g. "/v1/chat/completions". */
+    endpoint: string;
+    /** Settled USDC amount (USD, 6-decimal precision). */
+    cost_usd: number;
+    /** Model id when known, e.g. "zai/glm-5-turbo". Optional for non-LLM endpoints. */
+    model?: string;
+    /** Payer wallet address (EVM 0x... or Solana base58). */
+    wallet?: string;
+    /** Network identifier — "eip155:8453" for Base mainnet, "solana-mainnet", etc. */
+    network?: string;
+    /** Caller kind for analytics — "LLMClient", "ImageClient", "AgentClient", ... */
+    client_kind?: string;
 }
 declare function logCost(entry: CostEntry): void;
 declare function getCostSummary(): {
     totalUsd: number;
     calls: number;
     byModel: Record<string, number>;
+    byEndpoint: Record<string, number>;
 };
 
 /**
@@ -2077,4 +2130,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, testnetClient, 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, 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;
@@ -242,6 +261,13 @@ interface ChatOptions {
     search?: boolean;
     /** Full Live Search configuration (for search-enabled models) */
     searchParameters?: SearchParameters;
+    /**
+     * Models to try in order if the primary returns a transient error
+     * (timeout, network, 5xx). 4xx and PaymentError still propagate
+     * immediately. `smartChat` populates this from the routing tier's
+     * fallback chain automatically.
+     */
+    fallbackModels?: string[];
 }
 interface ChatCompletionOptions {
     /** Max tokens to generate */
@@ -258,6 +284,12 @@ interface ChatCompletionOptions {
     tools?: Tool[];
     /** Tool selection strategy */
     toolChoice?: ToolChoice;
+    /**
+     * Models to try in order if the primary returns a transient error
+     * (timeout, network, 5xx). 4xx and PaymentError still propagate
+     * immediately.
+     */
+    fallbackModels?: string[];
 }
 type RoutingProfile = "free" | "eco" | "auto" | "premium";
 type RoutingTier = "SIMPLE" | "MEDIUM" | "COMPLEX" | "REASONING";
@@ -270,6 +302,12 @@ interface RoutingDecision {
     costEstimate: number;
     baselineCost: number;
     savings: number;
+    /**
+     * Remaining tier models with known pricing, in fallback order. `chat()`
+     * walks this list when the primary model hits a transient error
+     * (timeout, network, 5xx). Excludes the primary itself.
+     */
+    fallbacks?: string[];
 }
 interface SmartChatOptions extends ChatOptions {
     /** Routing profile: free (zero cost), eco (budget), auto (balanced), premium (best quality) */
@@ -689,29 +727,11 @@ declare class APIError extends BlockrunError {
  * BlockRun LLM Gateway Client.
  *
  * Provides access to multiple LLM providers (OpenAI, Anthropic, Google, etc.)
- * with automatic x402 micropayments on Base chain.
- *
- * Networks:
- * - Mainnet: https://blockrun.ai/api (Base, Chain ID 8453)
- * - Testnet: https://testnet.blockrun.ai/api (Base Sepolia, Chain ID 84532)
- *
- * @example Testnet usage
- * ```ts
- * // Use testnet convenience function
- * import { testnetClient } from '@blockrun/llm';
- * const client = testnetClient({ privateKey: '0x...' });
- * const response = await client.chat('openai/gpt-oss-20b', 'Hello!');
- *
- * // Or configure manually
- * const client = new LLMClient({
- *   privateKey: '0x...',
- *   apiUrl: 'https://testnet.blockrun.ai/api'
- * });
- * ```
+ * with automatic x402 micropayments on Base chain (Mainnet, Chain ID 8453).
+ * API base: https://blockrun.ai/api
  */
 declare class LLMClient {
     static readonly DEFAULT_API_URL = "https://blockrun.ai/api";
-    static readonly TESTNET_API_URL = "https://testnet.blockrun.ai/api";
     private account;
     private privateKey;
     private apiUrl;
@@ -779,17 +799,48 @@ declare class LLMClient {
     private getModelPricing;
     /**
      * Fetch model pricing from API.
+     *
+     * For flat-billed models (e.g. ZAI GLM-5 family at $0.001/call) the
+     * router still expects per-token rates, so we synthesise an equivalent
+     * per-token price assuming ~1500 total tokens per call. Without this,
+     * flat models would resolve to inputPrice=outputPrice=0 and the router
+     * would treat them as free, biasing routing decisions and reporting
+     * inflated savings %.
      */
     private fetchModelPricing;
     /**
      * Full chat completion interface (OpenAI-compatible).
      *
-     * @param model - Model ID
+     * When `fallbackModels` is set, transient failures (timeouts, network
+     * errors, 5xx) on the primary model trigger a retry against the next
+     * model in the list before raising. 4xx errors and PaymentError
+     * propagate immediately — those aren't "swap upstream and retry"
+     * situations. Each fallback hop logs one stderr line.
+     *
+     * @param model - Primary model ID
      * @param messages - Array of messages with role and content
      * @param options - Optional completion parameters
      * @returns ChatResponse object with choices and usage
      */
     chatCompletion(model: string, messages: ChatMessage[], options?: ChatCompletionOptions): Promise<ChatResponse>;
+    /**
+     * Write a canonical cost_log entry after a settled x402 payment.
+     * Best-effort: failures here must never break a successful API call.
+     * Mirrors what Franklin's AgentClient writes via src/agent/llm.ts so
+     * 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.
      */
@@ -836,29 +887,37 @@ declare class LLMClient {
      */
     private fetchWithTimeout;
     /**
-     * List available LLM models with pricing.
+     * List available models with pricing.
+     *
+     * Returns the full `/v1/models` unified catalog (chat + image + music).
+     * The shape preserves backwards compatibility — image/music rows have
+     * `inputPrice = outputPrice = 0` since those fields don't apply, and
+     * their per-call price surfaces via `flatPrice`.
      */
     listModels(): Promise<Model[]>;
     /**
      * List available image generation models with pricing.
+     *
+     * The dedicated `/v1/images/models` endpoint was deprecated server-side;
+     * image models live in the unified `/v1/models` catalog under
+     * `categories: ["image", ...]`. This method filters that catalog so
+     * existing callers keep working.
      */
     listImageModels(): Promise<ImageModel[]>;
     /**
-     * List all available models (both LLM and image) with pricing.
+     * List all available models (chat, image, music, etc.) with pricing.
      *
-     * @returns Array of all models with 'type' field ('llm' or 'image')
-     *
-     * @example
-     * const models = await client.listAllModels();
-     * for (const model of models) {
-     *   if (model.type === 'llm') {
-     *     console.log(`LLM: ${model.id} - $${model.inputPrice}/M input`);
-     *   } else {
-     *     console.log(`Image: ${model.id} - $${model.pricePerImage}/image`);
-     *   }
-     * }
+     * @returns Array of all models with `type` field set from category
+     * (`llm` for chat, `image` / `music` for media). Backwards-compat:
+     * chat models always report `type: "llm"`.
      */
     listAllModels(): Promise<(Model | ImageModel)[]>;
+    /**
+     * Internal: fetch the raw `/v1/models` catalog without normalising shape.
+     * Used by listImageModels / listAllModels so each can pick category-
+     * specific fields.
+     */
+    private fetchRawModels;
     /**
      * Edit an image using img2img.
      *
@@ -876,6 +935,17 @@ declare class LLMClient {
      * @returns SearchResult with summary and citations
      */
     search(query: string, options?: SearchOptions): Promise<SearchResult>;
+    /**
+     * Generic Exa endpoint proxy (POST). Useful when you need an Exa API
+     * surface that the typed wrappers below don't expose.
+     *
+     * @param path - Exa endpoint segment: "search" | "find-similar" | "contents" | "answer"
+     * @param body - Request body (see Exa API docs)
+     *
+     * @example
+     * const results = await client.exa("search", { query: "latest AI research", numResults: 5 });
+     */
+    exa(path: string, body: Record<string, unknown>): Promise<Record<string, unknown>>;
     /**
      * Neural web search via Exa. Returns semantically relevant URLs and metadata.
      * Understands meaning, not just keywords. $0.01/call.
@@ -907,9 +977,7 @@ declare class LLMClient {
      */
     exaFindSimilar(url: string, options?: ExaFindSimilarOptions): Promise<ExaSearchResponse>;
     /**
-     * Get USDC balance on Base network.
-     *
-     * Automatically detects mainnet vs testnet based on API URL.
+     * Get USDC balance on Base mainnet.
      *
      * @returns USDC balance as a float (6 decimal places normalized)
      *
@@ -1120,38 +1188,7 @@ declare class LLMClient {
      * Get the wallet address being used for payments.
      */
     getWalletAddress(): string;
-    /**
-     * Check if client is configured for testnet.
-     */
-    isTestnet(): boolean;
 }
-/**
- * Create a testnet LLM client for development and testing.
- *
- * This is a convenience function that creates an LLMClient configured
- * for the BlockRun testnet (Base Sepolia).
- *
- * @param options - Client options (privateKey required unless BASE_CHAIN_WALLET_KEY env var is set)
- * @returns LLMClient configured for testnet
- *
- * @example
- * ```ts
- * import { testnetClient } from '@blockrun/llm';
- *
- * const client = testnetClient({ privateKey: '0x...' });
- * const response = await client.chat('openai/gpt-oss-20b', 'Hello!');
- * ```
- *
- * Testnet Setup:
- * 1. Get testnet ETH from https://www.alchemy.com/faucets/base-sepolia
- * 2. Get testnet USDC from https://faucet.circle.com/
- * 3. Use your wallet with testnet funds
- *
- * Available Testnet Models:
- * - openai/gpt-oss-20b
- * - openai/gpt-oss-120b
- */
-declare function testnetClient(options?: Omit<LLMClientOptions, 'apiUrl'>): LLMClient;
 
 /**
  * BlockRun Image Client - Generate images via x402 micropayments.
@@ -1216,6 +1253,11 @@ declare class ImageClient {
     edit(prompt: string, image: string, options?: ImageEditOptions): Promise<ImageResponse>;
     /**
      * List available image generation models with pricing.
+     *
+     * The dedicated `/v1/images/models` endpoint was deprecated server-side;
+     * image models live in the unified `/v1/models` catalog under
+     * `categories: ["image", ...]`. This method filters that catalog so
+     * existing callers keep working.
      */
     listImageModels(): Promise<ImageModel[]>;
     /**
@@ -1850,18 +1892,29 @@ declare function status(): Promise<{
     balance: number;
 }>;
 
+/** Canonical on-wire schema for cost_log.jsonl entries. */
 interface CostEntry {
-    timestamp: string;
-    model: string;
-    inputTokens: number;
-    outputTokens: number;
-    costUsd: number;
+    /** Unix epoch seconds (float, millisecond precision). */
+    ts: number;
+    /** API endpoint path, e.g. "/v1/chat/completions". */
+    endpoint: string;
+    /** Settled USDC amount (USD, 6-decimal precision). */
+    cost_usd: number;
+    /** Model id when known, e.g. "zai/glm-5-turbo". Optional for non-LLM endpoints. */
+    model?: string;
+    /** Payer wallet address (EVM 0x... or Solana base58). */
+    wallet?: string;
+    /** Network identifier — "eip155:8453" for Base mainnet, "solana-mainnet", etc. */
+    network?: string;
+    /** Caller kind for analytics — "LLMClient", "ImageClient", "AgentClient", ... */
+    client_kind?: string;
 }
 declare function logCost(entry: CostEntry): void;
 declare function getCostSummary(): {
     totalUsd: number;
     calls: number;
     byModel: Record<string, number>;
+    byEndpoint: Record<string, number>;
 };
 
 /**
@@ -2077,4 +2130,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, testnetClient, 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, 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 };