@blockrun/llm 2.3.0 → 2.4.0

package/README.md

@@ -455,6 +455,50 @@ const results = await x.search('x402 micropayments', { queryType: 'Latest' });
 const tweets = await x.userTweets({ username: 'vitalikbuterin', includeReplies: false });
 ```
 
+### Surf Crypto Data
+
+`SurfClient` exposes the full `/v1/surf/*` catalog — 84+ pay-per-call
+endpoints across CEX/DEX market data, on-chain SQL, wallet intelligence,
+prediction markets (Polymarket + Kalshi), social analytics, news, VC fund
+data, and an OpenAI-compatible chat surface. Flat pricing per call:
+
+| Tier | Price/call | Examples |
+|------|-----------|----------|
+| 1 | $0.001 | `/market/price`, `/market/ranking`, `/news/feed`, prediction-market reads, social tweets |
+| 2 | $0.005 | `/exchange/depth`, `/exchange/klines`, `/wallet/detail`, `/search/*`, `/social/ranking` |
+| 3 | $0.020 | `/onchain/sql`, `/onchain/query`, `/onchain/schema`, `/chat/completions` |
+
+Because the catalog is broad and evolving, the client deliberately ships a
+generic `get` / `post` pair instead of 84 typed wrappers. Pass the path
+(with or without the `/v1/surf` prefix), query params, or a JSON body —
+type the response via a generic if you want.
+
+```ts
+import { SurfClient } from '@blockrun/llm';
+
+const surf = new SurfClient();
+
+// Tier 1 — token price ($0.001)
+const btc = await surf.get('/market/price', { symbol: 'BTC' });
+
+// Tier 2 — order book depth ($0.005)
+const book = await surf.get('/exchange/depth', {
+  exchange: 'binance',
+  symbol: 'BTC-USDT',
+});
+
+// Tier 3 — raw on-chain SQL against 80+ ClickHouse tables ($0.020)
+const rows = await surf.post('/onchain/sql', {
+  query: 'SELECT block_number FROM ethereum.blocks ORDER BY block_number DESC LIMIT 5',
+});
+
+// Typed response via generic
+type Price = { symbol: string; price: number; timestamp: string };
+const eth = await surf.get<Price>('/market/price', { symbol: 'ETH' });
+```
+
+Full endpoint inventory: <https://blockrun.ai/marketplace/surf>.
+
 Methods: `userLookup`, `userInfo`, `followers`, `following`, `followings`,
 `verifiedFollowers`, `userTweets`, `mentions`, `tweetLookup`, `tweetReplies`,
 `tweetThread`, `search`, `trending`, `articlesRising`.

package/dist/index.cjs

@@ -45,6 +45,7 @@ __export(index_exports, {
   SOLANA_WALLET_FILE_PATH: () => SOLANA_WALLET_FILE,
   SearchClient: () => SearchClient,
   SolanaLLMClient: () => SolanaLLMClient,
+  SurfClient: () => SurfClient,
   USDC_BASE: () => USDC_BASE,
   USDC_BASE_CONTRACT: () => USDC_BASE_CONTRACT,
   USDC_SOLANA: () => USDC_SOLANA,
@@ -3312,8 +3313,163 @@ function buildUrl(base, query) {
   return `${base}?${qs}`;
 }
 
-// src/wallet.ts
+// src/surf.ts
 var import_accounts10 = require("viem/accounts");
+var DEFAULT_API_URL9 = "https://blockrun.ai/api";
+var DEFAULT_TIMEOUT9 = 6e4;
+var SURF_PREFIX = "/v1/surf";
+var SurfClient = class {
+  account;
+  privateKey;
+  apiUrl;
+  timeout;
+  constructor(options = {}) {
+    const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
+    const privateKey = options.privateKey || envKey;
+    if (!privateKey) {
+      throw new Error(
+        "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
+      );
+    }
+    validatePrivateKey(privateKey);
+    this.privateKey = privateKey;
+    this.account = (0, import_accounts10.privateKeyToAccount)(privateKey);
+    const apiUrl = options.apiUrl || DEFAULT_API_URL9;
+    validateApiUrl(apiUrl);
+    this.apiUrl = apiUrl.replace(/\/$/, "");
+    this.timeout = options.timeout || DEFAULT_TIMEOUT9;
+  }
+  /**
+   * GET a Surf endpoint. `path` is everything after `/v1/surf` (a leading
+   * `/v1/surf` is tolerated and stripped). Query params are URL-encoded;
+   * arrays become repeated keys (`?a=1&a=2`).
+   */
+  async get(path5, params) {
+    const url = this.buildUrl(path5, params);
+    return this.requestWithPayment(url, "GET");
+  }
+  /**
+   * POST a Surf endpoint with a JSON body. Same path normalization as `get`.
+   */
+  async post(path5, body) {
+    const url = this.buildUrl(path5);
+    return this.requestWithPayment(url, "POST", body);
+  }
+  buildUrl(path5, params) {
+    let normalized = path5.startsWith("/") ? path5 : `/${path5}`;
+    if (!normalized.startsWith(SURF_PREFIX)) {
+      normalized = `${SURF_PREFIX}${normalized}`;
+    }
+    const base = `${this.apiUrl}${normalized}`;
+    if (!params) return base;
+    const qs = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+      if (value === void 0 || value === null) continue;
+      if (Array.isArray(value)) {
+        for (const v of value) {
+          if (v === void 0 || v === null) continue;
+          qs.append(key, String(v));
+        }
+      } else {
+        qs.append(key, String(value));
+      }
+    }
+    const query = qs.toString();
+    return query ? `${base}?${query}` : base;
+  }
+  async requestWithPayment(url, method, body) {
+    const init = { method };
+    if (method === "POST") {
+      init.headers = { "Content-Type": "application/json" };
+      init.body = JSON.stringify(body ?? {});
+    }
+    const response = await this.fetchWithTimeout(url, init);
+    if (response.status === 402) {
+      return this.handlePaymentAndRetry(url, method, body, response);
+    }
+    if (!response.ok) {
+      await this.throwApiError(response, `Surf request failed (${method} ${url})`);
+    }
+    return response.json();
+  }
+  async handlePaymentAndRetry(url, method, body, response) {
+    let paymentHeader = response.headers.get("payment-required");
+    if (!paymentHeader) {
+      try {
+        const respBody = await response.json();
+        if (respBody.x402Version !== void 0 || respBody.accepts !== void 0) {
+          paymentHeader = btoa(JSON.stringify(respBody));
+        }
+      } catch {
+      }
+    }
+    if (!paymentHeader) {
+      throw new PaymentError("402 response but no payment requirements found");
+    }
+    const paymentRequired = parsePaymentRequired(paymentHeader);
+    const details = extractPaymentDetails(paymentRequired);
+    const paymentPayload = await createPaymentPayload(
+      this.privateKey,
+      this.account.address,
+      details.recipient,
+      details.amount,
+      details.network || "eip155:8453",
+      {
+        resourceUrl: details.resource?.url || url,
+        resourceDescription: details.resource?.description || "BlockRun Surf",
+        maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
+        extra: details.extra
+      }
+    );
+    const retryInit = {
+      method,
+      headers: { "PAYMENT-SIGNATURE": paymentPayload }
+    };
+    if (method === "POST") {
+      retryInit.headers = {
+        ...retryInit.headers,
+        "Content-Type": "application/json"
+      };
+      retryInit.body = JSON.stringify(body ?? {});
+    }
+    const retry = await this.fetchWithTimeout(url, retryInit);
+    if (retry.status === 402) {
+      throw new PaymentError("Payment was rejected. Check your wallet balance.");
+    }
+    if (!retry.ok) {
+      await this.throwApiError(retry, `Surf request failed after payment (${method} ${url})`);
+    }
+    return retry.json();
+  }
+  async throwApiError(resp, prefix) {
+    let errorBody;
+    try {
+      errorBody = await resp.json();
+    } catch {
+      errorBody = { error: "Request failed" };
+    }
+    throw new APIError(
+      `${prefix}: HTTP ${resp.status}`,
+      resp.status,
+      sanitizeErrorResponse(errorBody)
+    );
+  }
+  async fetchWithTimeout(url, init) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      return await fetch(url, { ...init, signal: controller.signal });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  getWalletAddress() {
+    return this.account.address;
+  }
+};
+
+// src/wallet.ts
+var import_accounts11 = require("viem/accounts");
 var fs2 = __toESM(require("fs"), 1);
 var path2 = __toESM(require("path"), 1);
 var os2 = __toESM(require("os"), 1);
@@ -3322,8 +3478,8 @@ var BASE_CHAIN_ID2 = "8453";
 var WALLET_DIR = path2.join(os2.homedir(), ".blockrun");
 var WALLET_FILE = path2.join(WALLET_DIR, ".session");
 function createWallet() {
-  const privateKey = (0, import_accounts10.generatePrivateKey)();
-  const account = (0, import_accounts10.privateKeyToAccount)(privateKey);
+  const privateKey = (0, import_accounts11.generatePrivateKey)();
+  const account = (0, import_accounts11.privateKeyToAccount)(privateKey);
   return {
     address: account.address,
     privateKey
@@ -3379,12 +3535,12 @@ function loadWallet() {
 function getOrCreateWallet() {
   const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
   if (envKey) {
-    const account = (0, import_accounts10.privateKeyToAccount)(envKey);
+    const account = (0, import_accounts11.privateKeyToAccount)(envKey);
     return { address: account.address, privateKey: envKey, isNew: false };
   }
   const fileKey = loadWallet();
   if (fileKey) {
-    const account = (0, import_accounts10.privateKeyToAccount)(fileKey);
+    const account = (0, import_accounts11.privateKeyToAccount)(fileKey);
     return { address: account.address, privateKey: fileKey, isNew: false };
   }
   const { address, privateKey } = createWallet();
@@ -3394,11 +3550,11 @@ function getOrCreateWallet() {
 function getWalletAddress() {
   const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
   if (envKey) {
-    return (0, import_accounts10.privateKeyToAccount)(envKey).address;
+    return (0, import_accounts11.privateKeyToAccount)(envKey).address;
   }
   const fileKey = loadWallet();
   if (fileKey) {
-    return (0, import_accounts10.privateKeyToAccount)(fileKey).address;
+    return (0, import_accounts11.privateKeyToAccount)(fileKey).address;
   }
   return null;
 }
@@ -3578,7 +3734,7 @@ async function getOrCreateSolanaWallet() {
 // src/solana-client.ts
 var SOLANA_API_URL = "https://sol.blockrun.ai/api";
 var DEFAULT_MAX_TOKENS2 = 1024;
-var DEFAULT_TIMEOUT9 = 6e4;
+var DEFAULT_TIMEOUT10 = 6e4;
 var SDK_VERSION2 = "0.3.0";
 var USER_AGENT2 = `blockrun-ts/${SDK_VERSION2}`;
 var SolanaLLMClient = class {
@@ -3603,7 +3759,7 @@ var SolanaLLMClient = class {
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
     this.rpcUrl = options.rpcUrl || "https://api.mainnet-beta.solana.com";
-    this.timeout = options.timeout || DEFAULT_TIMEOUT9;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT10;
   }
   /** Get Solana wallet address (public key in base58). */
   async getWalletAddress() {
@@ -4510,7 +4666,7 @@ var OpenAI = class {
 };
 
 // src/anthropic-compat.ts
-var import_accounts11 = require("viem/accounts");
+var import_accounts12 = require("viem/accounts");
 var AnthropicClient = class {
   _client = null;
   _clientPromise = null;
@@ -4523,7 +4679,7 @@ var AnthropicClient = class {
     const key = options.privateKey ?? wallet.privateKey;
     validatePrivateKey(key);
     this._privateKey = key;
-    this._account = (0, import_accounts11.privateKeyToAccount)(this._privateKey);
+    this._account = (0, import_accounts12.privateKeyToAccount)(this._privateKey);
     const apiUrl = options.apiUrl ?? "https://blockrun.ai/api";
     validateApiUrl(apiUrl);
     this._apiUrl = apiUrl.replace(/\/$/, "");
@@ -4634,6 +4790,7 @@ var AnthropicClient = class {
   SOLANA_WALLET_FILE_PATH,
   SearchClient,
   SolanaLLMClient,
+  SurfClient,
   USDC_BASE,
   USDC_BASE_CONTRACT,
   USDC_SOLANA,

package/dist/index.d.cts

@@ -785,6 +785,11 @@ interface PriceClientOptions {
     /** If false, construction succeeds without a wallet (free endpoints only). */
     requireWallet?: boolean;
 }
+interface SurfClientOptions {
+    privateKey?: `0x${string}` | string;
+    apiUrl?: string;
+    timeout?: number;
+}
 declare class BlockrunError extends Error {
     constructor(message: string);
 }
@@ -1713,6 +1718,74 @@ declare class PriceClient {
     private fetchWithTimeout;
 }
 
+/**
+ * BlockRun Surf Client — pay-per-call crypto data via x402 micropayments.
+ *
+ * Surf aggregates 84+ endpoints across CEX/DEX market data, on-chain SQL,
+ * wallet intelligence, prediction markets, social analytics, and news under
+ * a single OpenAPI surface mounted at `/api/v1/surf/*`.
+ *
+ * Pricing tiers (flat per-call, USDC on Base):
+ *   Tier 1 — $0.001/call (prices, rankings, lists, news, simple reads)
+ *   Tier 2 — $0.005/call (order books, candles, search, wallet details)
+ *   Tier 3 — $0.020/call (on-chain SQL, schema introspection, chat)
+ *
+ * Because the catalog is large and evolving, this client deliberately
+ * exposes a thin `get` / `post` pair instead of 84 typed wrappers. Pass the
+ * path (with or without the `/v1/surf` prefix) and either query params or a
+ * JSON body. The full endpoint inventory lives at
+ * https://blockrun.ai/marketplace/surf.
+ *
+ * Usage:
+ *   import { SurfClient } from "@blockrun/llm";
+ *
+ *   const surf = new SurfClient({ privateKey: "0x..." });
+ *
+ *   // Tier 1 — token price ($0.001)
+ *   const btc = await surf.get("/market/price", { symbol: "BTC" });
+ *
+ *   // Tier 2 — order book ($0.005)
+ *   const book = await surf.get("/exchange/depth", {
+ *     exchange: "binance",
+ *     symbol: "BTC-USDT",
+ *   });
+ *
+ *   // Tier 3 — raw on-chain SQL ($0.020)
+ *   const rows = await surf.post("/onchain/sql", {
+ *     query: "SELECT block_number FROM ethereum.blocks ORDER BY block_number DESC LIMIT 5",
+ *   });
+ *
+ *   // Typed responses via generic
+ *   type Price = { symbol: string; price: number; timestamp: string };
+ *   const typed = await surf.get<Price>("/market/price", { symbol: "ETH" });
+ */
+
+type QueryValue = string | number | boolean | null | undefined;
+type QueryParams = Record<string, QueryValue | QueryValue[]>;
+declare class SurfClient {
+    private account;
+    private privateKey;
+    private apiUrl;
+    private timeout;
+    constructor(options?: SurfClientOptions);
+    /**
+     * GET a Surf endpoint. `path` is everything after `/v1/surf` (a leading
+     * `/v1/surf` is tolerated and stripped). Query params are URL-encoded;
+     * arrays become repeated keys (`?a=1&a=2`).
+     */
+    get<T = unknown>(path: string, params?: QueryParams): Promise<T>;
+    /**
+     * POST a Surf endpoint with a JSON body. Same path normalization as `get`.
+     */
+    post<T = unknown>(path: string, body?: Record<string, unknown>): Promise<T>;
+    private buildUrl;
+    private requestWithPayment;
+    private handlePaymentAndRetry;
+    private throwApiError;
+    private fetchWithTimeout;
+    getWalletAddress(): string;
+}
+
 /**
  * x402 Payment Protocol v2 Implementation for BlockRun.
  *
@@ -2356,4 +2429,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 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, 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, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoicePreset, 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 };
+export { APIError, AnthropicClient, type AudioModel, type AudioTrack, BASE_CHAIN_ID, type BarResolution, type BlockRunAnthropicOptions, 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, 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, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoicePreset, 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

@@ -785,6 +785,11 @@ interface PriceClientOptions {
     /** If false, construction succeeds without a wallet (free endpoints only). */
     requireWallet?: boolean;
 }
+interface SurfClientOptions {
+    privateKey?: `0x${string}` | string;
+    apiUrl?: string;
+    timeout?: number;
+}
 declare class BlockrunError extends Error {
     constructor(message: string);
 }
@@ -1713,6 +1718,74 @@ declare class PriceClient {
     private fetchWithTimeout;
 }
 
+/**
+ * BlockRun Surf Client — pay-per-call crypto data via x402 micropayments.
+ *
+ * Surf aggregates 84+ endpoints across CEX/DEX market data, on-chain SQL,
+ * wallet intelligence, prediction markets, social analytics, and news under
+ * a single OpenAPI surface mounted at `/api/v1/surf/*`.
+ *
+ * Pricing tiers (flat per-call, USDC on Base):
+ *   Tier 1 — $0.001/call (prices, rankings, lists, news, simple reads)
+ *   Tier 2 — $0.005/call (order books, candles, search, wallet details)
+ *   Tier 3 — $0.020/call (on-chain SQL, schema introspection, chat)
+ *
+ * Because the catalog is large and evolving, this client deliberately
+ * exposes a thin `get` / `post` pair instead of 84 typed wrappers. Pass the
+ * path (with or without the `/v1/surf` prefix) and either query params or a
+ * JSON body. The full endpoint inventory lives at
+ * https://blockrun.ai/marketplace/surf.
+ *
+ * Usage:
+ *   import { SurfClient } from "@blockrun/llm";
+ *
+ *   const surf = new SurfClient({ privateKey: "0x..." });
+ *
+ *   // Tier 1 — token price ($0.001)
+ *   const btc = await surf.get("/market/price", { symbol: "BTC" });
+ *
+ *   // Tier 2 — order book ($0.005)
+ *   const book = await surf.get("/exchange/depth", {
+ *     exchange: "binance",
+ *     symbol: "BTC-USDT",
+ *   });
+ *
+ *   // Tier 3 — raw on-chain SQL ($0.020)
+ *   const rows = await surf.post("/onchain/sql", {
+ *     query: "SELECT block_number FROM ethereum.blocks ORDER BY block_number DESC LIMIT 5",
+ *   });
+ *
+ *   // Typed responses via generic
+ *   type Price = { symbol: string; price: number; timestamp: string };
+ *   const typed = await surf.get<Price>("/market/price", { symbol: "ETH" });
+ */
+
+type QueryValue = string | number | boolean | null | undefined;
+type QueryParams = Record<string, QueryValue | QueryValue[]>;
+declare class SurfClient {
+    private account;
+    private privateKey;
+    private apiUrl;
+    private timeout;
+    constructor(options?: SurfClientOptions);
+    /**
+     * GET a Surf endpoint. `path` is everything after `/v1/surf` (a leading
+     * `/v1/surf` is tolerated and stripped). Query params are URL-encoded;
+     * arrays become repeated keys (`?a=1&a=2`).
+     */
+    get<T = unknown>(path: string, params?: QueryParams): Promise<T>;
+    /**
+     * POST a Surf endpoint with a JSON body. Same path normalization as `get`.
+     */
+    post<T = unknown>(path: string, body?: Record<string, unknown>): Promise<T>;
+    private buildUrl;
+    private requestWithPayment;
+    private handlePaymentAndRetry;
+    private throwApiError;
+    private fetchWithTimeout;
+    getWalletAddress(): string;
+}
+
 /**
  * x402 Payment Protocol v2 Implementation for BlockRun.
  *
@@ -2356,4 +2429,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 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, 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, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoicePreset, 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 };
+export { APIError, AnthropicClient, type AudioModel, type AudioTrack, BASE_CHAIN_ID, type BarResolution, type BlockRunAnthropicOptions, 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, 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, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoicePreset, 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.js

@@ -3215,8 +3215,163 @@ function buildUrl(base, query) {
   return `${base}?${qs}`;
 }
 
+// src/surf.ts
+import { privateKeyToAccount as privateKeyToAccount9 } from "viem/accounts";
+var DEFAULT_API_URL9 = "https://blockrun.ai/api";
+var DEFAULT_TIMEOUT9 = 6e4;
+var SURF_PREFIX = "/v1/surf";
+var SurfClient = class {
+  account;
+  privateKey;
+  apiUrl;
+  timeout;
+  constructor(options = {}) {
+    const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
+    const privateKey = options.privateKey || envKey;
+    if (!privateKey) {
+      throw new Error(
+        "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
+      );
+    }
+    validatePrivateKey(privateKey);
+    this.privateKey = privateKey;
+    this.account = privateKeyToAccount9(privateKey);
+    const apiUrl = options.apiUrl || DEFAULT_API_URL9;
+    validateApiUrl(apiUrl);
+    this.apiUrl = apiUrl.replace(/\/$/, "");
+    this.timeout = options.timeout || DEFAULT_TIMEOUT9;
+  }
+  /**
+   * GET a Surf endpoint. `path` is everything after `/v1/surf` (a leading
+   * `/v1/surf` is tolerated and stripped). Query params are URL-encoded;
+   * arrays become repeated keys (`?a=1&a=2`).
+   */
+  async get(path5, params) {
+    const url = this.buildUrl(path5, params);
+    return this.requestWithPayment(url, "GET");
+  }
+  /**
+   * POST a Surf endpoint with a JSON body. Same path normalization as `get`.
+   */
+  async post(path5, body) {
+    const url = this.buildUrl(path5);
+    return this.requestWithPayment(url, "POST", body);
+  }
+  buildUrl(path5, params) {
+    let normalized = path5.startsWith("/") ? path5 : `/${path5}`;
+    if (!normalized.startsWith(SURF_PREFIX)) {
+      normalized = `${SURF_PREFIX}${normalized}`;
+    }
+    const base = `${this.apiUrl}${normalized}`;
+    if (!params) return base;
+    const qs = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+      if (value === void 0 || value === null) continue;
+      if (Array.isArray(value)) {
+        for (const v of value) {
+          if (v === void 0 || v === null) continue;
+          qs.append(key, String(v));
+        }
+      } else {
+        qs.append(key, String(value));
+      }
+    }
+    const query = qs.toString();
+    return query ? `${base}?${query}` : base;
+  }
+  async requestWithPayment(url, method, body) {
+    const init = { method };
+    if (method === "POST") {
+      init.headers = { "Content-Type": "application/json" };
+      init.body = JSON.stringify(body ?? {});
+    }
+    const response = await this.fetchWithTimeout(url, init);
+    if (response.status === 402) {
+      return this.handlePaymentAndRetry(url, method, body, response);
+    }
+    if (!response.ok) {
+      await this.throwApiError(response, `Surf request failed (${method} ${url})`);
+    }
+    return response.json();
+  }
+  async handlePaymentAndRetry(url, method, body, response) {
+    let paymentHeader = response.headers.get("payment-required");
+    if (!paymentHeader) {
+      try {
+        const respBody = await response.json();
+        if (respBody.x402Version !== void 0 || respBody.accepts !== void 0) {
+          paymentHeader = btoa(JSON.stringify(respBody));
+        }
+      } catch {
+      }
+    }
+    if (!paymentHeader) {
+      throw new PaymentError("402 response but no payment requirements found");
+    }
+    const paymentRequired = parsePaymentRequired(paymentHeader);
+    const details = extractPaymentDetails(paymentRequired);
+    const paymentPayload = await createPaymentPayload(
+      this.privateKey,
+      this.account.address,
+      details.recipient,
+      details.amount,
+      details.network || "eip155:8453",
+      {
+        resourceUrl: details.resource?.url || url,
+        resourceDescription: details.resource?.description || "BlockRun Surf",
+        maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
+        extra: details.extra
+      }
+    );
+    const retryInit = {
+      method,
+      headers: { "PAYMENT-SIGNATURE": paymentPayload }
+    };
+    if (method === "POST") {
+      retryInit.headers = {
+        ...retryInit.headers,
+        "Content-Type": "application/json"
+      };
+      retryInit.body = JSON.stringify(body ?? {});
+    }
+    const retry = await this.fetchWithTimeout(url, retryInit);
+    if (retry.status === 402) {
+      throw new PaymentError("Payment was rejected. Check your wallet balance.");
+    }
+    if (!retry.ok) {
+      await this.throwApiError(retry, `Surf request failed after payment (${method} ${url})`);
+    }
+    return retry.json();
+  }
+  async throwApiError(resp, prefix) {
+    let errorBody;
+    try {
+      errorBody = await resp.json();
+    } catch {
+      errorBody = { error: "Request failed" };
+    }
+    throw new APIError(
+      `${prefix}: HTTP ${resp.status}`,
+      resp.status,
+      sanitizeErrorResponse(errorBody)
+    );
+  }
+  async fetchWithTimeout(url, init) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      return await fetch(url, { ...init, signal: controller.signal });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  getWalletAddress() {
+    return this.account.address;
+  }
+};
+
 // src/wallet.ts
-import { privateKeyToAccount as privateKeyToAccount9, generatePrivateKey } from "viem/accounts";
+import { privateKeyToAccount as privateKeyToAccount10, generatePrivateKey } from "viem/accounts";
 import * as fs2 from "fs";
 import * as path2 from "path";
 import * as os2 from "os";
@@ -3226,7 +3381,7 @@ var WALLET_DIR = path2.join(os2.homedir(), ".blockrun");
 var WALLET_FILE = path2.join(WALLET_DIR, ".session");
 function createWallet() {
   const privateKey = generatePrivateKey();
-  const account = privateKeyToAccount9(privateKey);
+  const account = privateKeyToAccount10(privateKey);
   return {
     address: account.address,
     privateKey
@@ -3282,12 +3437,12 @@ function loadWallet() {
 function getOrCreateWallet() {
   const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
   if (envKey) {
-    const account = privateKeyToAccount9(envKey);
+    const account = privateKeyToAccount10(envKey);
     return { address: account.address, privateKey: envKey, isNew: false };
   }
   const fileKey = loadWallet();
   if (fileKey) {
-    const account = privateKeyToAccount9(fileKey);
+    const account = privateKeyToAccount10(fileKey);
     return { address: account.address, privateKey: fileKey, isNew: false };
   }
   const { address, privateKey } = createWallet();
@@ -3297,11 +3452,11 @@ function getOrCreateWallet() {
 function getWalletAddress() {
   const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
   if (envKey) {
-    return privateKeyToAccount9(envKey).address;
+    return privateKeyToAccount10(envKey).address;
   }
   const fileKey = loadWallet();
   if (fileKey) {
-    return privateKeyToAccount9(fileKey).address;
+    return privateKeyToAccount10(fileKey).address;
   }
   return null;
 }
@@ -3481,7 +3636,7 @@ async function getOrCreateSolanaWallet() {
 // src/solana-client.ts
 var SOLANA_API_URL = "https://sol.blockrun.ai/api";
 var DEFAULT_MAX_TOKENS2 = 1024;
-var DEFAULT_TIMEOUT9 = 6e4;
+var DEFAULT_TIMEOUT10 = 6e4;
 var SDK_VERSION2 = "0.3.0";
 var USER_AGENT2 = `blockrun-ts/${SDK_VERSION2}`;
 var SolanaLLMClient = class {
@@ -3506,7 +3661,7 @@ var SolanaLLMClient = class {
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
     this.rpcUrl = options.rpcUrl || "https://api.mainnet-beta.solana.com";
-    this.timeout = options.timeout || DEFAULT_TIMEOUT9;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT10;
   }
   /** Get Solana wallet address (public key in base58). */
   async getWalletAddress() {
@@ -4413,7 +4568,7 @@ var OpenAI = class {
 };
 
 // src/anthropic-compat.ts
-import { privateKeyToAccount as privateKeyToAccount10 } from "viem/accounts";
+import { privateKeyToAccount as privateKeyToAccount11 } from "viem/accounts";
 var AnthropicClient = class {
   _client = null;
   _clientPromise = null;
@@ -4426,7 +4581,7 @@ var AnthropicClient = class {
     const key = options.privateKey ?? wallet.privateKey;
     validatePrivateKey(key);
     this._privateKey = key;
-    this._account = privateKeyToAccount10(this._privateKey);
+    this._account = privateKeyToAccount11(this._privateKey);
     const apiUrl = options.apiUrl ?? "https://blockrun.ai/api";
     validateApiUrl(apiUrl);
     this._apiUrl = apiUrl.replace(/\/$/, "");
@@ -4536,6 +4691,7 @@ export {
   SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH,
   SearchClient,
   SolanaLLMClient,
+  SurfClient,
   USDC_BASE,
   USDC_BASE_CONTRACT,
   USDC_SOLANA,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/llm",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "type": "module",
   "description": "BlockRun SDK - Pay-per-request AI (LLM, Image, Video, Music, Voice) via x402 on Base and Solana",
   "main": "dist/index.cjs",