@blockrun/llm 1.5.0 → 1.6.1

package/README.md

@@ -550,6 +550,46 @@ All current endpoints are GET. The `pmQuery()` method is available for future PO
 
 Works on both `LLMClient` (Base) and `SolanaLLMClient`.
 
+## Exa Web Search (Powered by Exa)
+
+Access [Exa](https://exa.ai)'s neural web search via x402. No API keys needed — pay-per-request via Solana USDC. Available on `SolanaLLMClient` only.
+
+| Method | Description | Price |
+|---|---|---|
+| `exaSearch(query, options?)` | Neural/keyword web search | $0.01/request |
+| `exaFindSimilar(url, options?)` | Find semantically similar pages | $0.01/request |
+| `exaContents(urls, options?)` | Extract full text from URLs | $0.002/URL |
+| `exaAnswer(query, options?)` | AI answer grounded in web search | $0.01/request |
+| `exa(path, body)` | Generic proxy for any Exa endpoint | varies |
+
+```typescript
+import { SolanaLLMClient } from '@blockrun/llm';
+
+const client = new SolanaLLMClient();
+
+// Neural web search ($0.01/request)
+const results = await client.exaSearch("latest AI safety research", { numResults: 5 });
+const news = await client.exaSearch("bitcoin ETF news", { category: "news", numResults: 10 });
+
+// Find similar pages ($0.01/request)
+const similar = await client.exaFindSimilar("https://openai.com/research/gpt-4", { numResults: 5 });
+
+// Extract content from URLs ($0.002/URL)
+const content = await client.exaContents(["https://arxiv.org/abs/2303.08774"]);
+const rich = await client.exaContents(
+  ["https://example.com/page1", "https://example.com/page2"],
+  { text: true, highlights: true }
+);
+
+// AI-generated answer from live web ($0.01/request)
+const answer = await client.exaAnswer("What is the current state of AI safety research?");
+
+// Generic proxy for any Exa endpoint
+const custom = await client.exa("search", { query: "transformer architecture", numResults: 5 });
+```
+
+`SolanaLLMClient` only — Exa endpoints are on `sol.blockrun.ai`.
+
 ## Configuration
 
 ```typescript

package/dist/index.cjs

@@ -440,7 +440,7 @@ var DEFAULT_MAX_TOKENS = 1024;
 var DEFAULT_TIMEOUT = 6e4;
 var SDK_VERSION = "1.5.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
-var LLMClient = class {
+var LLMClient = class _LLMClient {
   static DEFAULT_API_URL = DEFAULT_API_URL;
   static TESTNET_API_URL = TESTNET_API_URL;
   account;
@@ -451,6 +451,11 @@ var LLMClient = class {
   sessionCalls = 0;
   modelPricingCache = null;
   modelPricingPromise = null;
+  // Pre-auth cache: avoids the 402 round-trip on repeat requests to the same model.
+  // Key = "endpoint:model", value = cached payment header + timestamp.
+  // TTL: 1 hour (mirrors ClawRouter's payment-preauth.ts approach).
+  preAuthCache = /* @__PURE__ */ new Map();
+  static PRE_AUTH_TTL_MS = 36e5;
   /**
    * Initialize the BlockRun LLM client.
    *
@@ -762,6 +767,131 @@ var LLMClient = class {
     this.sessionTotalUsd += costUsd;
     return retryResponse.json();
   }
+  /**
+   * Sign a payment header and return the PAYMENT-SIGNATURE value.
+   * Extracted to share logic between streaming and non-streaming flows.
+   */
+  async signPayment(paymentHeader) {
+    const paymentRequired = parsePaymentRequired(paymentHeader);
+    const details = extractPaymentDetails(paymentRequired);
+    const extensions = paymentRequired.extensions;
+    const paymentPayload = await createPaymentPayload(
+      this.privateKey,
+      this.account.address,
+      details.recipient,
+      details.amount,
+      details.network || "eip155:8453",
+      {
+        resourceUrl: validateResourceUrl(
+          details.resource?.url || `${this.apiUrl}/v1/chat/completions`,
+          this.apiUrl
+        ),
+        resourceDescription: details.resource?.description || "BlockRun AI API call",
+        maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
+        extra: details.extra,
+        extensions
+      }
+    );
+    const costUsd = parseFloat(details.amount) / 1e6;
+    return { paymentPayload, costUsd };
+  }
+  /**
+   * Streaming chat completion with automatic x402 payment.
+   *
+   * Uses a pre-auth cache so repeat calls to the same model skip the 402
+   * round-trip (~200ms savings). Falls back to the normal 402 flow on cache
+   * miss or if the pre-signed payment is rejected.
+   *
+   * @returns Raw fetch Response with a streaming SSE body.
+   */
+  async chatCompletionStream(model, messages, options) {
+    const url = `${this.apiUrl}/v1/chat/completions`;
+    const body = {
+      model,
+      messages,
+      max_tokens: options?.maxTokens ?? DEFAULT_MAX_TOKENS,
+      stream: true
+    };
+    if (options?.temperature !== void 0) body.temperature = options.temperature;
+    if (options?.topP !== void 0) body.top_p = options.topP;
+    if (options?.tools !== void 0) body.tools = options.tools;
+    if (options?.toolChoice !== void 0) body.tool_choice = options.toolChoice;
+    const cacheKey2 = `/v1/chat/completions:${model}`;
+    const cached = this.preAuthCache.get(cacheKey2);
+    const now = Date.now();
+    if (cached && now - cached.cachedAt < _LLMClient.PRE_AUTH_TTL_MS) {
+      try {
+        const { paymentPayload: paymentPayload2, costUsd: costUsd2 } = await this.signPayment(cached.paymentHeader);
+        const preAuthResp = await this.fetchWithTimeout(url, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "User-Agent": USER_AGENT,
+            "PAYMENT-SIGNATURE": paymentPayload2
+          },
+          body: JSON.stringify(body)
+        });
+        if (preAuthResp.status !== 402 && preAuthResp.ok) {
+          this.sessionCalls += 1;
+          this.sessionTotalUsd += costUsd2;
+          return preAuthResp;
+        }
+        this.preAuthCache.delete(cacheKey2);
+      } catch {
+        this.preAuthCache.delete(cacheKey2);
+      }
+    }
+    const firstResp = await this.fetchWithTimeout(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT },
+      body: JSON.stringify(body)
+    });
+    if (firstResp.status !== 402) {
+      if (!firstResp.ok) {
+        let errorBody;
+        try {
+          errorBody = await firstResp.json();
+        } catch {
+          errorBody = { error: "Request failed" };
+        }
+        throw new APIError(`API error: ${firstResp.status}`, firstResp.status, sanitizeErrorResponse(errorBody));
+      }
+      return firstResp;
+    }
+    let paymentHeader = firstResp.headers.get("payment-required");
+    if (!paymentHeader) {
+      try {
+        const rb = await firstResp.json();
+        if (rb.x402 || rb.accepts) paymentHeader = btoa(JSON.stringify(rb));
+      } catch {
+      }
+    }
+    if (!paymentHeader) throw new PaymentError("402 response but no payment requirements found");
+    this.preAuthCache.set(cacheKey2, { paymentHeader, cachedAt: now });
+    const { paymentPayload, costUsd } = await this.signPayment(paymentHeader);
+    const streamResp = await this.fetchWithTimeout(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "User-Agent": USER_AGENT,
+        "PAYMENT-SIGNATURE": paymentPayload
+      },
+      body: JSON.stringify(body)
+    });
+    if (streamResp.status === 402) throw new PaymentError("Payment was rejected. Check your wallet balance.");
+    if (!streamResp.ok) {
+      let errorBody;
+      try {
+        errorBody = await streamResp.json();
+      } catch {
+        errorBody = { error: "Request failed" };
+      }
+      throw new APIError(`API error after payment: ${streamResp.status}`, streamResp.status, sanitizeErrorResponse(errorBody));
+    }
+    this.sessionCalls += 1;
+    this.sessionTotalUsd += costUsd;
+    return streamResp;
+  }
   /**
    * Make a request with automatic x402 payment handling, returning raw JSON.
    * Used for non-ChatResponse endpoints (X/Twitter, search, image edit, etc.).
@@ -1091,12 +1221,12 @@ var LLMClient = class {
     return (data.data || []).map((m) => ({
       id: m.id,
       name: m.name || m.id,
-      provider: m.owned_by || "",
+      provider: m.provider || m.owned_by || "",
       description: m.description || "",
-      inputPrice: m.pricing?.input ?? m.pricing?.flat ?? 0,
-      outputPrice: m.pricing?.output ?? 0,
-      contextWindow: m.context_window || 0,
-      maxOutput: m.max_output || 0,
+      inputPrice: m.inputPrice ?? m.input_price ?? m.pricing?.input ?? 0,
+      outputPrice: m.outputPrice ?? m.output_price ?? m.pricing?.output ?? 0,
+      contextWindow: m.contextWindow ?? m.context_window ?? 0,
+      maxOutput: m.maxOutput ?? m.max_output ?? 0,
       categories: m.categories || [],
       available: true
     }));
@@ -1184,6 +1314,58 @@ var LLMClient = class {
     const data = await this.requestWithPaymentRaw("/v1/search", body);
     return data;
   }
+  /**
+   * Neural web search via Exa. Returns semantically relevant URLs and metadata.
+   * Understands meaning, not just keywords. $0.01/call.
+   *
+   * @param query - Natural language search query
+   * @param options - Optional filters (numResults, category, date range, domains)
+   */
+  async exaSearch(query, options) {
+    const body = { query };
+    if (options?.numResults !== void 0) body.numResults = options.numResults;
+    if (options?.category !== void 0) body.category = options.category;
+    if (options?.startPublishedDate !== void 0) body.startPublishedDate = options.startPublishedDate;
+    if (options?.endPublishedDate !== void 0) body.endPublishedDate = options.endPublishedDate;
+    if (options?.includeDomains !== void 0) body.includeDomains = options.includeDomains;
+    if (options?.excludeDomains !== void 0) body.excludeDomains = options.excludeDomains;
+    const data = await this.requestWithPaymentRaw("/v1/exa/search", body);
+    return data.data;
+  }
+  /**
+   * Ask a question and get a cited, synthesized answer grounded in real web sources.
+   * No hallucinations — every claim is backed by a citation. $0.01/call.
+   *
+   * @param query - The question to answer
+   */
+  async exaAnswer(query) {
+    const data = await this.requestWithPaymentRaw("/v1/exa/answer", { query });
+    return data.data;
+  }
+  /**
+   * Fetch full Markdown text content from a list of URLs. $0.002 per URL.
+   * Returns clean text ready to feed into an LLM context window.
+   *
+   * @param urls - Array of URLs to fetch (up to 100)
+   */
+  async exaContents(urls) {
+    const data = await this.requestWithPaymentRaw("/v1/exa/contents", { urls });
+    return data.data;
+  }
+  /**
+   * Find pages semantically similar to a given URL. $0.01/call.
+   * Useful for discovering competitors, alternatives, and related resources.
+   *
+   * @param url - Reference URL
+   * @param options - Optional filters (numResults, excludeSourceDomain)
+   */
+  async exaFindSimilar(url, options) {
+    const body = { url };
+    if (options?.numResults !== void 0) body.numResults = options.numResults;
+    if (options?.excludeSourceDomain !== void 0) body.excludeSourceDomain = options.excludeSourceDomain;
+    const data = await this.requestWithPaymentRaw("/v1/exa/find-similar", body);
+    return data.data;
+  }
   /**
    * Get USDC balance on Base network.
    *
@@ -2197,6 +2379,55 @@ var SolanaLLMClient = class {
   async pmQuery(path5, query) {
     return this.requestWithPaymentRaw(`/v1/pm/${path5}`, query);
   }
+  // ── Exa Web Search (Powered by Exa) ──────────────────────────────────────
+  /**
+   * Generic Exa endpoint proxy (POST, Solana payment). Powered by Exa.
+   *
+   * @param path - Exa endpoint: "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 });
+   */
+  async exa(path5, body) {
+    return this.requestWithPaymentRaw(`/v1/exa/${path5}`, body);
+  }
+  /**
+   * Neural and keyword web search via Exa (Solana payment, $0.01/request).
+   *
+   * @example
+   * const results = await client.exaSearch("latest AI papers", { numResults: 5 });
+   */
+  async exaSearch(query, options) {
+    return this.requestWithPaymentRaw("/v1/exa/search", { query, ...options });
+  }
+  /**
+   * Find pages semantically similar to a given URL via Exa (Solana payment, $0.01/request).
+   *
+   * @example
+   * const results = await client.exaFindSimilar("https://openai.com/research/gpt-4", { numResults: 5 });
+   */
+  async exaFindSimilar(url, options) {
+    return this.requestWithPaymentRaw("/v1/exa/find-similar", { url, ...options });
+  }
+  /**
+   * Extract full text content from URLs via Exa (Solana payment, $0.002/URL).
+   *
+   * @example
+   * const data = await client.exaContents(["https://arxiv.org/abs/2303.08774"]);
+   */
+  async exaContents(urls, options) {
+    return this.requestWithPaymentRaw("/v1/exa/contents", { urls, ...options });
+  }
+  /**
+   * AI-generated answer grounded in live web search via Exa (Solana payment, $0.01/request).
+   *
+   * @example
+   * const answer = await client.exaAnswer("What is the current state of AI safety research?");
+   */
+  async exaAnswer(query, options) {
+    return this.requestWithPaymentRaw("/v1/exa/answer", { query, ...options });
+  }
   /** Get session spending. */
   getSpending() {
     return { totalUsd: this.sessionTotalUsd, calls: this.sessionCalls };
@@ -2578,7 +2809,7 @@ function readableFilename(endpoint, body) {
     ep = "image";
   }
   let label = body.query || body.username || body.handle || body.model || (typeof body.prompt === "string" ? body.prompt.slice(0, 40) : "") || "";
-  label = String(label).replace(/[^a-zA-Z0-9_\-]/g, "_").slice(0, 40).replace(/^_+|_+$/g, "");
+  label = String(label).replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 40).replace(/^_+|_+$/g, "");
   return label ? `${ep}_${ts}_${label}.json` : `${ep}_${ts}.json`;
 }
 function saveReadable(endpoint, body, response, costUsd) {
@@ -2842,46 +3073,18 @@ var ChatCompletions = class {
     return this.transformResponse(response);
   }
   async createStream(params) {
-    const url = `${this.apiUrl}/v1/chat/completions`;
-    const body = {
-      model: params.model,
-      messages: params.messages,
-      max_tokens: params.max_tokens || 1024,
-      temperature: params.temperature,
-      top_p: params.top_p,
-      stream: true
-    };
-    if (params.tools) {
-      body.tools = params.tools;
-    }
-    if (params.tool_choice) {
-      body.tool_choice = params.tool_choice;
-    }
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-    try {
-      const response = await fetch(url, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify(body),
-        signal: controller.signal
-      });
-      if (response.status === 402) {
-        const paymentHeader = response.headers.get("payment-required");
-        if (!paymentHeader) {
-          throw new Error("402 response but no payment requirements found");
-        }
-        throw new Error(
-          "Streaming with automatic payment requires direct wallet access. Please use non-streaming mode or contact support for streaming setup."
-        );
-      }
-      if (!response.ok) {
-        throw new Error(`API error: ${response.status}`);
+    const response = await this.client.chatCompletionStream(
+      params.model,
+      params.messages,
+      {
+        maxTokens: params.max_tokens,
+        temperature: params.temperature,
+        topP: params.top_p,
+        tools: params.tools,
+        toolChoice: params.tool_choice
       }
-      return new StreamingResponse(response, params.model);
-    } finally {
-      clearTimeout(timeoutId);
-    }
+    );
+    return new StreamingResponse(response, params.model);
   }
   transformResponse(response) {
     return {

package/dist/index.d.cts

@@ -296,6 +296,68 @@ interface SearchOptions {
     /** End date filter (YYYY-MM-DD) */
     toDate?: string;
 }
+interface ExaSearchOptions {
+    /** Number of results to return (default: 10, max: 100) */
+    numResults?: number;
+    /** Restrict to a content category */
+    category?: "github" | "news" | "research paper" | "linkedin profile" | "personal site" | "tweet" | "financial report" | "pdf" | "company";
+    /** Only include pages published after this date (ISO 8601) */
+    startPublishedDate?: string;
+    /** Only include pages published before this date (ISO 8601) */
+    endPublishedDate?: string;
+    /** Only search within these domains */
+    includeDomains?: string[];
+    /** Exclude these domains from results */
+    excludeDomains?: string[];
+}
+interface ExaSearchItem {
+    id: string;
+    url: string;
+    title: string;
+    publishedDate?: string;
+    author?: string;
+    score?: number;
+}
+interface ExaSearchResponse {
+    requestId: string;
+    resolvedSearchType: string;
+    results: ExaSearchItem[];
+    searchTime: number;
+    costDollars: {
+        total: number;
+    };
+}
+interface ExaAnswerCitation {
+    id: string;
+    title: string;
+    url: string;
+    publishedDate?: string;
+    favicon?: string;
+}
+interface ExaAnswerResponse {
+    requestId: string;
+    answer: string;
+    citations: ExaAnswerCitation[];
+}
+interface ExaContentItem {
+    id: string;
+    url: string;
+    title: string;
+    text: string;
+    author?: string | null;
+}
+interface ExaContentsResponse {
+    results: ExaContentItem[];
+    costDollars: {
+        total: number;
+    };
+}
+interface ExaFindSimilarOptions {
+    /** Number of results to return (default: 10, max: 100) */
+    numResults?: number;
+    /** Exclude pages from the same domain as the reference URL */
+    excludeSourceDomain?: boolean;
+}
 interface XUser {
     id: string;
     userName: string;
@@ -483,6 +545,8 @@ declare class LLMClient {
     private sessionCalls;
     private modelPricingCache;
     private modelPricingPromise;
+    private preAuthCache;
+    private static readonly PRE_AUTH_TTL_MS;
     /**
      * Initialize the BlockRun LLM client.
      *
@@ -559,6 +623,21 @@ declare class LLMClient {
      * Handle 402 response: parse requirements, sign payment, retry.
      */
     private handlePaymentAndRetry;
+    /**
+     * Sign a payment header and return the PAYMENT-SIGNATURE value.
+     * Extracted to share logic between streaming and non-streaming flows.
+     */
+    private signPayment;
+    /**
+     * Streaming chat completion with automatic x402 payment.
+     *
+     * Uses a pre-auth cache so repeat calls to the same model skip the 402
+     * round-trip (~200ms savings). Falls back to the normal 402 flow on cache
+     * miss or if the pre-signed payment is rejected.
+     *
+     * @returns Raw fetch Response with a streaming SSE body.
+     */
+    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.).
@@ -622,6 +701,36 @@ declare class LLMClient {
      * @returns SearchResult with summary and citations
      */
     search(query: string, options?: SearchOptions): Promise<SearchResult>;
+    /**
+     * Neural web search via Exa. Returns semantically relevant URLs and metadata.
+     * Understands meaning, not just keywords. $0.01/call.
+     *
+     * @param query - Natural language search query
+     * @param options - Optional filters (numResults, category, date range, domains)
+     */
+    exaSearch(query: string, options?: ExaSearchOptions): Promise<ExaSearchResponse>;
+    /**
+     * Ask a question and get a cited, synthesized answer grounded in real web sources.
+     * No hallucinations — every claim is backed by a citation. $0.01/call.
+     *
+     * @param query - The question to answer
+     */
+    exaAnswer(query: string): Promise<ExaAnswerResponse>;
+    /**
+     * Fetch full Markdown text content from a list of URLs. $0.002 per URL.
+     * Returns clean text ready to feed into an LLM context window.
+     *
+     * @param urls - Array of URLs to fetch (up to 100)
+     */
+    exaContents(urls: string[]): Promise<ExaContentsResponse>;
+    /**
+     * Find pages semantically similar to a given URL. $0.01/call.
+     * Useful for discovering competitors, alternatives, and related resources.
+     *
+     * @param url - Reference URL
+     * @param options - Optional filters (numResults, excludeSourceDomain)
+     */
+    exaFindSimilar(url: string, options?: ExaFindSimilarOptions): Promise<ExaSearchResponse>;
     /**
      * Get USDC balance on Base network.
      *
@@ -1204,6 +1313,44 @@ declare class SolanaLLMClient {
     xCompareAuthors(handle1: string, handle2: string): Promise<XCompareAuthorsResponse>;
     pm(path: string, params?: Record<string, string>): Promise<Record<string, unknown>>;
     pmQuery(path: string, query: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Generic Exa endpoint proxy (POST, Solana payment). Powered by Exa.
+     *
+     * @param path - Exa endpoint: "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 and keyword web search via Exa (Solana payment, $0.01/request).
+     *
+     * @example
+     * const results = await client.exaSearch("latest AI papers", { numResults: 5 });
+     */
+    exaSearch(query: string, options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Find pages semantically similar to a given URL via Exa (Solana payment, $0.01/request).
+     *
+     * @example
+     * const results = await client.exaFindSimilar("https://openai.com/research/gpt-4", { numResults: 5 });
+     */
+    exaFindSimilar(url: string, options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Extract full text content from URLs via Exa (Solana payment, $0.002/URL).
+     *
+     * @example
+     * const data = await client.exaContents(["https://arxiv.org/abs/2303.08774"]);
+     */
+    exaContents(urls: string[], options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * AI-generated answer grounded in live web search via Exa (Solana payment, $0.01/request).
+     *
+     * @example
+     * const answer = await client.exaAnswer("What is the current state of AI safety research?");
+     */
+    exaAnswer(query: string, options?: Record<string, unknown>): Promise<Record<string, unknown>>;
     /** Get session spending. */
     getSpending(): Spending;
     /** True if using sol.blockrun.ai. */

package/dist/index.d.ts

@@ -296,6 +296,68 @@ interface SearchOptions {
     /** End date filter (YYYY-MM-DD) */
     toDate?: string;
 }
+interface ExaSearchOptions {
+    /** Number of results to return (default: 10, max: 100) */
+    numResults?: number;
+    /** Restrict to a content category */
+    category?: "github" | "news" | "research paper" | "linkedin profile" | "personal site" | "tweet" | "financial report" | "pdf" | "company";
+    /** Only include pages published after this date (ISO 8601) */
+    startPublishedDate?: string;
+    /** Only include pages published before this date (ISO 8601) */
+    endPublishedDate?: string;
+    /** Only search within these domains */
+    includeDomains?: string[];
+    /** Exclude these domains from results */
+    excludeDomains?: string[];
+}
+interface ExaSearchItem {
+    id: string;
+    url: string;
+    title: string;
+    publishedDate?: string;
+    author?: string;
+    score?: number;
+}
+interface ExaSearchResponse {
+    requestId: string;
+    resolvedSearchType: string;
+    results: ExaSearchItem[];
+    searchTime: number;
+    costDollars: {
+        total: number;
+    };
+}
+interface ExaAnswerCitation {
+    id: string;
+    title: string;
+    url: string;
+    publishedDate?: string;
+    favicon?: string;
+}
+interface ExaAnswerResponse {
+    requestId: string;
+    answer: string;
+    citations: ExaAnswerCitation[];
+}
+interface ExaContentItem {
+    id: string;
+    url: string;
+    title: string;
+    text: string;
+    author?: string | null;
+}
+interface ExaContentsResponse {
+    results: ExaContentItem[];
+    costDollars: {
+        total: number;
+    };
+}
+interface ExaFindSimilarOptions {
+    /** Number of results to return (default: 10, max: 100) */
+    numResults?: number;
+    /** Exclude pages from the same domain as the reference URL */
+    excludeSourceDomain?: boolean;
+}
 interface XUser {
     id: string;
     userName: string;
@@ -483,6 +545,8 @@ declare class LLMClient {
     private sessionCalls;
     private modelPricingCache;
     private modelPricingPromise;
+    private preAuthCache;
+    private static readonly PRE_AUTH_TTL_MS;
     /**
      * Initialize the BlockRun LLM client.
      *
@@ -559,6 +623,21 @@ declare class LLMClient {
      * Handle 402 response: parse requirements, sign payment, retry.
      */
     private handlePaymentAndRetry;
+    /**
+     * Sign a payment header and return the PAYMENT-SIGNATURE value.
+     * Extracted to share logic between streaming and non-streaming flows.
+     */
+    private signPayment;
+    /**
+     * Streaming chat completion with automatic x402 payment.
+     *
+     * Uses a pre-auth cache so repeat calls to the same model skip the 402
+     * round-trip (~200ms savings). Falls back to the normal 402 flow on cache
+     * miss or if the pre-signed payment is rejected.
+     *
+     * @returns Raw fetch Response with a streaming SSE body.
+     */
+    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.).
@@ -622,6 +701,36 @@ declare class LLMClient {
      * @returns SearchResult with summary and citations
      */
     search(query: string, options?: SearchOptions): Promise<SearchResult>;
+    /**
+     * Neural web search via Exa. Returns semantically relevant URLs and metadata.
+     * Understands meaning, not just keywords. $0.01/call.
+     *
+     * @param query - Natural language search query
+     * @param options - Optional filters (numResults, category, date range, domains)
+     */
+    exaSearch(query: string, options?: ExaSearchOptions): Promise<ExaSearchResponse>;
+    /**
+     * Ask a question and get a cited, synthesized answer grounded in real web sources.
+     * No hallucinations — every claim is backed by a citation. $0.01/call.
+     *
+     * @param query - The question to answer
+     */
+    exaAnswer(query: string): Promise<ExaAnswerResponse>;
+    /**
+     * Fetch full Markdown text content from a list of URLs. $0.002 per URL.
+     * Returns clean text ready to feed into an LLM context window.
+     *
+     * @param urls - Array of URLs to fetch (up to 100)
+     */
+    exaContents(urls: string[]): Promise<ExaContentsResponse>;
+    /**
+     * Find pages semantically similar to a given URL. $0.01/call.
+     * Useful for discovering competitors, alternatives, and related resources.
+     *
+     * @param url - Reference URL
+     * @param options - Optional filters (numResults, excludeSourceDomain)
+     */
+    exaFindSimilar(url: string, options?: ExaFindSimilarOptions): Promise<ExaSearchResponse>;
     /**
      * Get USDC balance on Base network.
      *
@@ -1204,6 +1313,44 @@ declare class SolanaLLMClient {
     xCompareAuthors(handle1: string, handle2: string): Promise<XCompareAuthorsResponse>;
     pm(path: string, params?: Record<string, string>): Promise<Record<string, unknown>>;
     pmQuery(path: string, query: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Generic Exa endpoint proxy (POST, Solana payment). Powered by Exa.
+     *
+     * @param path - Exa endpoint: "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 and keyword web search via Exa (Solana payment, $0.01/request).
+     *
+     * @example
+     * const results = await client.exaSearch("latest AI papers", { numResults: 5 });
+     */
+    exaSearch(query: string, options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Find pages semantically similar to a given URL via Exa (Solana payment, $0.01/request).
+     *
+     * @example
+     * const results = await client.exaFindSimilar("https://openai.com/research/gpt-4", { numResults: 5 });
+     */
+    exaFindSimilar(url: string, options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Extract full text content from URLs via Exa (Solana payment, $0.002/URL).
+     *
+     * @example
+     * const data = await client.exaContents(["https://arxiv.org/abs/2303.08774"]);
+     */
+    exaContents(urls: string[], options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * AI-generated answer grounded in live web search via Exa (Solana payment, $0.01/request).
+     *
+     * @example
+     * const answer = await client.exaAnswer("What is the current state of AI safety research?");
+     */
+    exaAnswer(query: string, options?: Record<string, unknown>): Promise<Record<string, unknown>>;
     /** Get session spending. */
     getSpending(): Spending;
     /** True if using sol.blockrun.ai. */

package/dist/index.js

@@ -355,7 +355,7 @@ var DEFAULT_MAX_TOKENS = 1024;
 var DEFAULT_TIMEOUT = 6e4;
 var SDK_VERSION = "1.5.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
-var LLMClient = class {
+var LLMClient = class _LLMClient {
   static DEFAULT_API_URL = DEFAULT_API_URL;
   static TESTNET_API_URL = TESTNET_API_URL;
   account;
@@ -366,6 +366,11 @@ var LLMClient = class {
   sessionCalls = 0;
   modelPricingCache = null;
   modelPricingPromise = null;
+  // Pre-auth cache: avoids the 402 round-trip on repeat requests to the same model.
+  // Key = "endpoint:model", value = cached payment header + timestamp.
+  // TTL: 1 hour (mirrors ClawRouter's payment-preauth.ts approach).
+  preAuthCache = /* @__PURE__ */ new Map();
+  static PRE_AUTH_TTL_MS = 36e5;
   /**
    * Initialize the BlockRun LLM client.
    *
@@ -677,6 +682,131 @@ var LLMClient = class {
     this.sessionTotalUsd += costUsd;
     return retryResponse.json();
   }
+  /**
+   * Sign a payment header and return the PAYMENT-SIGNATURE value.
+   * Extracted to share logic between streaming and non-streaming flows.
+   */
+  async signPayment(paymentHeader) {
+    const paymentRequired = parsePaymentRequired(paymentHeader);
+    const details = extractPaymentDetails(paymentRequired);
+    const extensions = paymentRequired.extensions;
+    const paymentPayload = await createPaymentPayload(
+      this.privateKey,
+      this.account.address,
+      details.recipient,
+      details.amount,
+      details.network || "eip155:8453",
+      {
+        resourceUrl: validateResourceUrl(
+          details.resource?.url || `${this.apiUrl}/v1/chat/completions`,
+          this.apiUrl
+        ),
+        resourceDescription: details.resource?.description || "BlockRun AI API call",
+        maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
+        extra: details.extra,
+        extensions
+      }
+    );
+    const costUsd = parseFloat(details.amount) / 1e6;
+    return { paymentPayload, costUsd };
+  }
+  /**
+   * Streaming chat completion with automatic x402 payment.
+   *
+   * Uses a pre-auth cache so repeat calls to the same model skip the 402
+   * round-trip (~200ms savings). Falls back to the normal 402 flow on cache
+   * miss or if the pre-signed payment is rejected.
+   *
+   * @returns Raw fetch Response with a streaming SSE body.
+   */
+  async chatCompletionStream(model, messages, options) {
+    const url = `${this.apiUrl}/v1/chat/completions`;
+    const body = {
+      model,
+      messages,
+      max_tokens: options?.maxTokens ?? DEFAULT_MAX_TOKENS,
+      stream: true
+    };
+    if (options?.temperature !== void 0) body.temperature = options.temperature;
+    if (options?.topP !== void 0) body.top_p = options.topP;
+    if (options?.tools !== void 0) body.tools = options.tools;
+    if (options?.toolChoice !== void 0) body.tool_choice = options.toolChoice;
+    const cacheKey2 = `/v1/chat/completions:${model}`;
+    const cached = this.preAuthCache.get(cacheKey2);
+    const now = Date.now();
+    if (cached && now - cached.cachedAt < _LLMClient.PRE_AUTH_TTL_MS) {
+      try {
+        const { paymentPayload: paymentPayload2, costUsd: costUsd2 } = await this.signPayment(cached.paymentHeader);
+        const preAuthResp = await this.fetchWithTimeout(url, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "User-Agent": USER_AGENT,
+            "PAYMENT-SIGNATURE": paymentPayload2
+          },
+          body: JSON.stringify(body)
+        });
+        if (preAuthResp.status !== 402 && preAuthResp.ok) {
+          this.sessionCalls += 1;
+          this.sessionTotalUsd += costUsd2;
+          return preAuthResp;
+        }
+        this.preAuthCache.delete(cacheKey2);
+      } catch {
+        this.preAuthCache.delete(cacheKey2);
+      }
+    }
+    const firstResp = await this.fetchWithTimeout(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT },
+      body: JSON.stringify(body)
+    });
+    if (firstResp.status !== 402) {
+      if (!firstResp.ok) {
+        let errorBody;
+        try {
+          errorBody = await firstResp.json();
+        } catch {
+          errorBody = { error: "Request failed" };
+        }
+        throw new APIError(`API error: ${firstResp.status}`, firstResp.status, sanitizeErrorResponse(errorBody));
+      }
+      return firstResp;
+    }
+    let paymentHeader = firstResp.headers.get("payment-required");
+    if (!paymentHeader) {
+      try {
+        const rb = await firstResp.json();
+        if (rb.x402 || rb.accepts) paymentHeader = btoa(JSON.stringify(rb));
+      } catch {
+      }
+    }
+    if (!paymentHeader) throw new PaymentError("402 response but no payment requirements found");
+    this.preAuthCache.set(cacheKey2, { paymentHeader, cachedAt: now });
+    const { paymentPayload, costUsd } = await this.signPayment(paymentHeader);
+    const streamResp = await this.fetchWithTimeout(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "User-Agent": USER_AGENT,
+        "PAYMENT-SIGNATURE": paymentPayload
+      },
+      body: JSON.stringify(body)
+    });
+    if (streamResp.status === 402) throw new PaymentError("Payment was rejected. Check your wallet balance.");
+    if (!streamResp.ok) {
+      let errorBody;
+      try {
+        errorBody = await streamResp.json();
+      } catch {
+        errorBody = { error: "Request failed" };
+      }
+      throw new APIError(`API error after payment: ${streamResp.status}`, streamResp.status, sanitizeErrorResponse(errorBody));
+    }
+    this.sessionCalls += 1;
+    this.sessionTotalUsd += costUsd;
+    return streamResp;
+  }
   /**
    * Make a request with automatic x402 payment handling, returning raw JSON.
    * Used for non-ChatResponse endpoints (X/Twitter, search, image edit, etc.).
@@ -1006,12 +1136,12 @@ var LLMClient = class {
     return (data.data || []).map((m) => ({
       id: m.id,
       name: m.name || m.id,
-      provider: m.owned_by || "",
+      provider: m.provider || m.owned_by || "",
       description: m.description || "",
-      inputPrice: m.pricing?.input ?? m.pricing?.flat ?? 0,
-      outputPrice: m.pricing?.output ?? 0,
-      contextWindow: m.context_window || 0,
-      maxOutput: m.max_output || 0,
+      inputPrice: m.inputPrice ?? m.input_price ?? m.pricing?.input ?? 0,
+      outputPrice: m.outputPrice ?? m.output_price ?? m.pricing?.output ?? 0,
+      contextWindow: m.contextWindow ?? m.context_window ?? 0,
+      maxOutput: m.maxOutput ?? m.max_output ?? 0,
       categories: m.categories || [],
       available: true
     }));
@@ -1099,6 +1229,58 @@ var LLMClient = class {
     const data = await this.requestWithPaymentRaw("/v1/search", body);
     return data;
   }
+  /**
+   * Neural web search via Exa. Returns semantically relevant URLs and metadata.
+   * Understands meaning, not just keywords. $0.01/call.
+   *
+   * @param query - Natural language search query
+   * @param options - Optional filters (numResults, category, date range, domains)
+   */
+  async exaSearch(query, options) {
+    const body = { query };
+    if (options?.numResults !== void 0) body.numResults = options.numResults;
+    if (options?.category !== void 0) body.category = options.category;
+    if (options?.startPublishedDate !== void 0) body.startPublishedDate = options.startPublishedDate;
+    if (options?.endPublishedDate !== void 0) body.endPublishedDate = options.endPublishedDate;
+    if (options?.includeDomains !== void 0) body.includeDomains = options.includeDomains;
+    if (options?.excludeDomains !== void 0) body.excludeDomains = options.excludeDomains;
+    const data = await this.requestWithPaymentRaw("/v1/exa/search", body);
+    return data.data;
+  }
+  /**
+   * Ask a question and get a cited, synthesized answer grounded in real web sources.
+   * No hallucinations — every claim is backed by a citation. $0.01/call.
+   *
+   * @param query - The question to answer
+   */
+  async exaAnswer(query) {
+    const data = await this.requestWithPaymentRaw("/v1/exa/answer", { query });
+    return data.data;
+  }
+  /**
+   * Fetch full Markdown text content from a list of URLs. $0.002 per URL.
+   * Returns clean text ready to feed into an LLM context window.
+   *
+   * @param urls - Array of URLs to fetch (up to 100)
+   */
+  async exaContents(urls) {
+    const data = await this.requestWithPaymentRaw("/v1/exa/contents", { urls });
+    return data.data;
+  }
+  /**
+   * Find pages semantically similar to a given URL. $0.01/call.
+   * Useful for discovering competitors, alternatives, and related resources.
+   *
+   * @param url - Reference URL
+   * @param options - Optional filters (numResults, excludeSourceDomain)
+   */
+  async exaFindSimilar(url, options) {
+    const body = { url };
+    if (options?.numResults !== void 0) body.numResults = options.numResults;
+    if (options?.excludeSourceDomain !== void 0) body.excludeSourceDomain = options.excludeSourceDomain;
+    const data = await this.requestWithPaymentRaw("/v1/exa/find-similar", body);
+    return data.data;
+  }
   /**
    * Get USDC balance on Base network.
    *
@@ -2112,6 +2294,55 @@ var SolanaLLMClient = class {
   async pmQuery(path5, query) {
     return this.requestWithPaymentRaw(`/v1/pm/${path5}`, query);
   }
+  // ── Exa Web Search (Powered by Exa) ──────────────────────────────────────
+  /**
+   * Generic Exa endpoint proxy (POST, Solana payment). Powered by Exa.
+   *
+   * @param path - Exa endpoint: "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 });
+   */
+  async exa(path5, body) {
+    return this.requestWithPaymentRaw(`/v1/exa/${path5}`, body);
+  }
+  /**
+   * Neural and keyword web search via Exa (Solana payment, $0.01/request).
+   *
+   * @example
+   * const results = await client.exaSearch("latest AI papers", { numResults: 5 });
+   */
+  async exaSearch(query, options) {
+    return this.requestWithPaymentRaw("/v1/exa/search", { query, ...options });
+  }
+  /**
+   * Find pages semantically similar to a given URL via Exa (Solana payment, $0.01/request).
+   *
+   * @example
+   * const results = await client.exaFindSimilar("https://openai.com/research/gpt-4", { numResults: 5 });
+   */
+  async exaFindSimilar(url, options) {
+    return this.requestWithPaymentRaw("/v1/exa/find-similar", { url, ...options });
+  }
+  /**
+   * Extract full text content from URLs via Exa (Solana payment, $0.002/URL).
+   *
+   * @example
+   * const data = await client.exaContents(["https://arxiv.org/abs/2303.08774"]);
+   */
+  async exaContents(urls, options) {
+    return this.requestWithPaymentRaw("/v1/exa/contents", { urls, ...options });
+  }
+  /**
+   * AI-generated answer grounded in live web search via Exa (Solana payment, $0.01/request).
+   *
+   * @example
+   * const answer = await client.exaAnswer("What is the current state of AI safety research?");
+   */
+  async exaAnswer(query, options) {
+    return this.requestWithPaymentRaw("/v1/exa/answer", { query, ...options });
+  }
   /** Get session spending. */
   getSpending() {
     return { totalUsd: this.sessionTotalUsd, calls: this.sessionCalls };
@@ -2493,7 +2724,7 @@ function readableFilename(endpoint, body) {
     ep = "image";
   }
   let label = body.query || body.username || body.handle || body.model || (typeof body.prompt === "string" ? body.prompt.slice(0, 40) : "") || "";
-  label = String(label).replace(/[^a-zA-Z0-9_\-]/g, "_").slice(0, 40).replace(/^_+|_+$/g, "");
+  label = String(label).replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 40).replace(/^_+|_+$/g, "");
   return label ? `${ep}_${ts}_${label}.json` : `${ep}_${ts}.json`;
 }
 function saveReadable(endpoint, body, response, costUsd) {
@@ -2757,46 +2988,18 @@ var ChatCompletions = class {
     return this.transformResponse(response);
   }
   async createStream(params) {
-    const url = `${this.apiUrl}/v1/chat/completions`;
-    const body = {
-      model: params.model,
-      messages: params.messages,
-      max_tokens: params.max_tokens || 1024,
-      temperature: params.temperature,
-      top_p: params.top_p,
-      stream: true
-    };
-    if (params.tools) {
-      body.tools = params.tools;
-    }
-    if (params.tool_choice) {
-      body.tool_choice = params.tool_choice;
-    }
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-    try {
-      const response = await fetch(url, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify(body),
-        signal: controller.signal
-      });
-      if (response.status === 402) {
-        const paymentHeader = response.headers.get("payment-required");
-        if (!paymentHeader) {
-          throw new Error("402 response but no payment requirements found");
-        }
-        throw new Error(
-          "Streaming with automatic payment requires direct wallet access. Please use non-streaming mode or contact support for streaming setup."
-        );
-      }
-      if (!response.ok) {
-        throw new Error(`API error: ${response.status}`);
+    const response = await this.client.chatCompletionStream(
+      params.model,
+      params.messages,
+      {
+        maxTokens: params.max_tokens,
+        temperature: params.temperature,
+        topP: params.top_p,
+        tools: params.tools,
+        toolChoice: params.tool_choice
       }
-      return new StreamingResponse(response, params.model);
-    } finally {
-      clearTimeout(timeoutId);
-    }
+    );
+    return new StreamingResponse(response, params.model);
   }
   transformResponse(response) {
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/llm",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "type": "module",
   "description": "BlockRun LLM Gateway SDK - Pay-per-request AI via x402 on Base and Solana",
   "main": "dist/index.cjs",