@blockrun/llm 3.13.6 → 3.14.0

package/dist/index.d.ts

@@ -1,5 +1,13 @@
 import * as _anthropic_ai_sdk from '@anthropic-ai/sdk';
 
+/** Account billing is independent of the wallet payment chain. */
+interface ApiKeyOptions {
+    /** BlockRun account key. Defaults to BLOCKRUN_API_KEY unless a privateKey is explicit. */
+    apiKey?: string;
+}
+declare const API_KEY_URL = "https://api.blockrun.ai";
+declare const PORTAL_URL = "https://user.blockrun.ai";
+
 /**
  * Smart Router Types
  *
@@ -174,10 +182,6 @@ type RoutingConfig = {
     overrides: OverridesConfig;
 };
 
-/**
- * Type definitions for BlockRun LLM SDK
- */
-
 interface FunctionDefinition {
     name: string;
     description?: string;
@@ -300,7 +304,7 @@ interface ImageModel {
     available: boolean;
     type?: "llm" | "image";
 }
-interface ImageClientOptions {
+interface ImageClientOptions extends ApiKeyOptions {
     /** EVM wallet private key (hex string starting with 0x) */
     privateKey?: `0x${string}` | string;
     /** API endpoint URL (default: https://blockrun.ai/api) */
@@ -417,7 +421,7 @@ interface PaymentRequired {
     accepts: PaymentRequirement[];
     resource?: ResourceInfo;
 }
-interface LLMClientOptions {
+interface LLMClientOptions extends ApiKeyOptions {
     /** EVM wallet private key (hex string starting with 0x). Optional if BASE_CHAIN_WALLET_KEY env var is set. */
     privateKey?: `0x${string}` | string;
     /** API endpoint URL (default: https://blockrun.ai/api) */
@@ -576,7 +580,7 @@ interface AudioModel {
     available: boolean;
     type: "audio";
 }
-interface MusicClientOptions {
+interface MusicClientOptions extends ApiKeyOptions {
     /** EVM wallet private key (hex string starting with 0x) */
     privateKey?: `0x${string}` | string;
     /** API endpoint URL (default: https://blockrun.ai/api) */
@@ -606,7 +610,7 @@ interface SpeechResponse {
     data: SpeechAudio[];
     txHash?: string;
 }
-interface SpeechClientOptions {
+interface SpeechClientOptions extends ApiKeyOptions {
     /** EVM wallet private key (hex string starting with 0x) */
     privateKey?: `0x${string}` | string;
     /** API endpoint URL (default: https://blockrun.ai/api) */
@@ -648,7 +652,7 @@ interface VoiceInfo {
     preview_url?: string;
     [key: string]: unknown;
 }
-interface RpcClientOptions {
+interface RpcClientOptions extends ApiKeyOptions {
     /** EVM wallet private key (hex string starting with 0x) */
     privateKey?: `0x${string}` | string;
     /** API endpoint URL (default: https://blockrun.ai/api) */
@@ -691,7 +695,7 @@ interface RpcBatchRequest {
 type VoicePreset = "nat" | "josh" | "maya" | "june" | "paige" | "derek" | "florian";
 /** Bland.ai conversation model tier. */
 type CallModel = "base" | "enhanced" | "turbo";
-interface VoiceClientOptions {
+interface VoiceClientOptions extends ApiKeyOptions {
     /** EVM wallet private key (hex string starting with 0x) */
     privateKey?: `0x${string}` | string;
     /** API endpoint URL (default: https://blockrun.ai/api) */
@@ -785,7 +789,7 @@ interface VideoModel {
     available: boolean;
     type: "video";
 }
-interface VideoClientOptions {
+interface VideoClientOptions extends ApiKeyOptions {
     /** EVM wallet private key (hex string starting with 0x) */
     privateKey?: `0x${string}` | string;
     /** API endpoint URL (default: https://blockrun.ai/api) */
@@ -976,24 +980,24 @@ interface ListOptions extends PriceOptions {
     /** Page size, capped at 2000. Defaults to 100. */
     limit?: number;
 }
-interface SearchClientOptions {
+interface SearchClientOptions extends ApiKeyOptions {
     privateKey?: `0x${string}` | string;
     apiUrl?: string;
     timeout?: number;
 }
-interface PriceClientOptions {
+interface PriceClientOptions extends ApiKeyOptions {
     privateKey?: `0x${string}` | string;
     apiUrl?: string;
     timeout?: number;
     /** If false, construction succeeds without a wallet (free endpoints only). */
     requireWallet?: boolean;
 }
-interface SurfClientOptions {
+interface SurfClientOptions extends ApiKeyOptions {
     privateKey?: `0x${string}` | string;
     apiUrl?: string;
     timeout?: number;
 }
-interface PhoneClientOptions {
+interface PhoneClientOptions extends ApiKeyOptions {
     /** EVM wallet private key (hex string starting with 0x) */
     privateKey?: `0x${string}` | string;
     /** API endpoint URL (default: https://blockrun.ai/api) */
@@ -1062,7 +1066,7 @@ interface PhoneReleaseResponse {
     phone_number: string;
     txHash?: string;
 }
-interface PortraitClientOptions {
+interface PortraitClientOptions extends ApiKeyOptions {
     /** EVM wallet private key (hex string starting with 0x) */
     privateKey?: `0x${string}` | string;
     /** API endpoint URL (default: https://blockrun.ai/api) */
@@ -1119,7 +1123,7 @@ interface PortraitEnrollResponse {
     /** On-chain payment receipt (tx hash), surfaced from the response header. */
     txHash?: string;
 }
-interface BlockrunClientOptions {
+interface BlockrunClientOptions extends ApiKeyOptions {
     privateKey?: `0x${string}` | string;
     apiUrl?: string;
     /** Per-HTTP-call timeout in ms (default 60000). For long-running poll() jobs,
@@ -1150,26 +1154,12 @@ declare class PaymentError extends BlockrunError {
 }
 declare class APIError extends BlockrunError {
     statusCode: number;
+    /** Retry-After header returned by the account API. */
+    retryAfter?: string;
     response?: unknown;
     constructor(message: string, statusCode: number, response?: unknown);
 }
 
-/**
- * BlockRun LLM Client - Main SDK entry point.
- *
- * Usage:
- *   import { LLMClient } from '@blockrun/llm';
- *
- *   // Option 1: Use BASE_CHAIN_WALLET_KEY env var
- *   const client = new LLMClient();
- *
- *   // Option 2: Pass private key directly
- *   const client = new LLMClient({ privateKey: '0x...' });
- *
- *   const response = await client.chat('openai/gpt-5.2', 'Hello!');
- *   console.log(response);
- */
-
 /**
  * BlockRun LLM Gateway Client.
  *
@@ -1179,8 +1169,13 @@ declare class APIError extends BlockrunError {
  */
 declare class LLMClient {
     static readonly DEFAULT_API_URL = "https://blockrun.ai/api";
-    private account;
-    private privateKey;
+    private _account?;
+    private get account();
+    private apiAuth?;
+    /** Active billing mode. */
+    get authMode(): "api-key" | "wallet";
+    private _privateKey?;
+    private get privateKey();
     private apiUrl;
     private timeout;
     private sessionTotalUsd;
@@ -1610,23 +1605,6 @@ declare class LLMClient {
     getWalletAddress(): string;
 }
 
-/**
- * BlockRun Image Client - Generate images via x402 micropayments.
- *
- * SECURITY NOTE - Private Key Handling:
- * Your private key NEVER leaves your machine. Here's what happens:
- * 1. Key stays local - only used to sign an EIP-712 typed data message
- * 2. Only the SIGNATURE is sent in the PAYMENT-SIGNATURE header
- * 3. BlockRun verifies the signature on-chain via Coinbase CDP facilitator
- *
- * Usage:
- *   import { ImageClient } from '@blockrun/llm';
- *
- *   const client = new ImageClient({ privateKey: '0x...' });
- *   const result = await client.generate('A cute cat in space');
- *   console.log(result.data[0].url);
- */
-
 /**
  * BlockRun Image Generation Client.
  *
@@ -1634,8 +1612,13 @@ declare class LLMClient {
  * or CogView-4 (Zhipu AI) with automatic x402 micropayments on Base chain.
  */
 declare class ImageClient {
-    private account;
-    private privateKey;
+    private _account?;
+    private get account();
+    private apiAuth?;
+    /** Active billing mode. */
+    get authMode(): "api-key" | "wallet";
+    private _privateKey?;
+    private get privateKey();
     private apiUrl;
     private timeout;
     private sessionTotalUsd;
@@ -1729,23 +1712,6 @@ declare class ImageClient {
     getSpending(): Spending;
 }
 
-/**
- * BlockRun Music Client - Generate music tracks via x402 micropayments.
- *
- * SECURITY NOTE - Private Key Handling:
- * Your private key NEVER leaves your machine. Here's what happens:
- * 1. Key stays local - only used to sign an EIP-712 typed data message
- * 2. Only the SIGNATURE is sent in the PAYMENT-SIGNATURE header
- * 3. BlockRun verifies the signature on-chain via Coinbase CDP facilitator
- *
- * Usage:
- *   import { MusicClient } from '@blockrun/llm';
- *
- *   const client = new MusicClient({ privateKey: '0x...' });
- *   const result = await client.generate('upbeat synthwave with neon pads');
- *   console.log(result.data[0].url); // CDN URL — download within 24h
- */
-
 /**
  * BlockRun Music Generation Client.
  *
@@ -1756,8 +1722,13 @@ declare class ImageClient {
  * Note: Generated URLs expire in ~24h — download immediately if needed.
  */
 declare class MusicClient {
-    private account;
-    private privateKey;
+    private _account?;
+    private get account();
+    private apiAuth?;
+    /** Active billing mode. */
+    get authMode(): "api-key" | "wallet";
+    private _privateKey?;
+    private get privateKey();
     private apiUrl;
     private timeout;
     private sessionTotalUsd;
@@ -1790,40 +1761,6 @@ declare class MusicClient {
     getSpending(): Spending;
 }
 
-/**
- * BlockRun Speech Client - Text-to-speech and sound effects (ElevenLabs) via x402 micropayments.
- *
- * SECURITY NOTE - Private Key Handling:
- * Your private key NEVER leaves your machine. Here's what happens:
- * 1. Key stays local - only used to sign an EIP-712 typed data message
- * 2. Only the SIGNATURE is sent in the PAYMENT-SIGNATURE header
- * 3. BlockRun verifies the signature on-chain via Coinbase CDP facilitator
- *
- * Usage:
- *   import { SpeechClient } from '@blockrun/llm';
- *
- *   const client = new SpeechClient({ privateKey: '0x...' });
- *
- *   // Text-to-speech (price scales with character count)
- *   const result = await client.generate('Hello from BlockRun!', { voice: 'sarah' });
- *   console.log(result.data[0].url);
- *
- *   // Sound effects (flat $0.05/generation)
- *   const fx = await client.soundEffect('rain on a tin roof, distant thunder');
- *
- *   // List voices (free, rate-limited)
- *   const voices = await client.listVoices();
- *
- * Models & pricing:
- *   elevenlabs/flash-v2.5        $0.05/1k chars  ~75ms latency, 32 languages (default)
- *   elevenlabs/turbo-v2.5        $0.05/1k chars  ~250ms latency, 32 languages
- *   elevenlabs/multilingual-v2   $0.10/1k chars  long-form narration, 29 languages
- *   elevenlabs/v3                $0.10/1k chars  max expressiveness, 70+ languages
- *   elevenlabs/sound-effects     $0.05/generation (up to 22s)
- *
- * Price = (characters / 1000) x model rate, minimum $0.001/request.
- */
-
 /**
  * BlockRun Speech Client (BlockRun Voice).
  *
@@ -1834,8 +1771,13 @@ declare class MusicClient {
  * $0.05/generation.
  */
 declare class SpeechClient {
-    private account;
-    private privateKey;
+    private _account?;
+    private get account();
+    private apiAuth?;
+    /** Active billing mode. */
+    get authMode(): "api-key" | "wallet";
+    private _privateKey?;
+    private get privateKey();
     private apiUrl;
     private timeout;
     private sessionTotalUsd;
@@ -1888,33 +1830,6 @@ declare class SpeechClient {
     getSpending(): Spending;
 }
 
-/**
- * BlockRun Video Client - Generate short AI videos via x402 micropayments.
- *
- * SECURITY NOTE - Private Key Handling:
- * Your private key NEVER leaves your machine. Here's what happens:
- * 1. Key stays local - only used to sign an EIP-712 typed data message
- * 2. Only the SIGNATURE is sent in the PAYMENT-SIGNATURE header
- * 3. BlockRun verifies the signature on-chain via Coinbase CDP facilitator
- *
- * Async flow (client-polled):
- *   POST /v1/videos/generations         -> 402 -> sign -> 202 { id, poll_url }
- *   GET  /v1/videos/generations/{id}    -> loop until status=completed
- *
- * The client signs once and replays the same PAYMENT-SIGNATURE on every poll,
- * re-signing automatically if the 600s authorization window lapses mid-poll.
- * Settlement happens only on the first completed poll, so upstream failure or
- * the caller giving up = zero charge.
- *
- * Usage:
- *   import { VideoClient } from '@blockrun/llm';
- *
- *   const client = new VideoClient({ privateKey: '0x...' });
- *   const result = await client.generate('a red apple slowly spinning on a wooden table');
- *   console.log(result.data[0].url);            // permanent MP4 URL
- *   console.log(result.data[0].duration_seconds);
- */
-
 /**
  * BlockRun Video Generation Client.
  *
@@ -1922,8 +1837,13 @@ declare class SpeechClient {
  * 2.0 Fast / 2.0 Pro) with automatic x402 micropayments on Base.
  */
 declare class VideoClient {
-    private account;
-    private privateKey;
+    private _account?;
+    private get account();
+    private apiAuth?;
+    /** Active billing mode. */
+    get authMode(): "api-key" | "wallet";
+    private _privateKey?;
+    private get privateKey();
     private apiUrl;
     private timeout;
     private sessionTotalUsd;
@@ -1993,37 +1913,6 @@ declare class VideoClient {
     getSpending(): Spending;
 }
 
-/**
- * BlockRun Voice Call Client - AI-powered outbound phone calls via x402 micropayments.
- *
- * The AI agent calls a phone number (E.164) and conducts a real-time conversation
- * based on your 'task' instructions. STT, LLM, and TTS are handled upstream by
- * Bland.ai; BlockRun handles billing through x402.
- *
- * SECURITY NOTE - Private Key Handling:
- * Your private key NEVER leaves your machine. Here's what happens:
- * 1. Key stays local - only used to sign an EIP-712 typed data message
- * 2. Only the SIGNATURE is sent in the PAYMENT-SIGNATURE header
- * 3. BlockRun verifies the signature on-chain via Coinbase CDP facilitator
- *
- * Usage:
- *   import { VoiceClient } from '@blockrun/llm';
- *
- *   const client = new VoiceClient({ privateKey: '0x...' });
- *
- *   // Initiate a call (paid, $0.54)
- *   const result = await client.call({
- *     to: '+14155552671',
- *     task: 'You are a friendly assistant calling to confirm a 3pm dentist appointment.',
- *     max_duration: 5,
- *   });
- *   console.log(result.call_id);
- *
- *   // Poll status, transcript, recording (free)
- *   const status = await client.getStatus(result.call_id);
- *   console.log(status);
- */
-
 /**
  * BlockRun Voice Call Client.
  *
@@ -2034,8 +1923,13 @@ declare class VideoClient {
  * Status polling is free.
  */
 declare class VoiceClient {
-    private account;
-    private privateKey;
+    private _account?;
+    private get account();
+    private apiAuth?;
+    /** Active billing mode. */
+    get authMode(): "api-key" | "wallet";
+    private _privateKey?;
+    private get privateKey();
     private apiUrl;
     private timeout;
     private sessionTotalUsd;
@@ -2070,43 +1964,6 @@ declare class VoiceClient {
     getSpending(): Spending;
 }
 
-/**
- * BlockRun Phone Client — Twilio-backed phone lookup + number provisioning via x402.
- *
- * Endpoints (all under /v1/phone/...):
- *   POST /lookup            $0.01    Carrier + line-type lookup
- *   POST /lookup/fraud      $0.05    Carrier + SIM-swap / call-forwarding signals
- *   POST /numbers/buy       $5.00    Provision a US/CA number (30-day lease, bound to wallet)
- *   POST /numbers/renew     $5.00    Extend an existing number by 30 days
- *   POST /numbers/list      $0.001   List the wallet's active numbers
- *   POST /numbers/release   free     Release a provisioned number (still flows through x402
- *                                    so the backend can verify wallet identity)
- *
- * After buying a number you can use it as the `from` caller ID in VoiceClient.call().
- *
- * SECURITY NOTE — your private key never leaves your machine. Only EIP-712
- * signatures are sent in the PAYMENT-SIGNATURE header.
- *
- * @example
- *   import { PhoneClient } from '@blockrun/llm';
- *
- *   const client = new PhoneClient({ privateKey: '0x...' });
- *
- *   // Lookup a number
- *   const info = await client.lookup('+14155552671');
- *
- *   // Buy a number (US, optional area code)
- *   const bought = await client.buyNumber({ country: 'US', areaCode: '415' });
- *   console.log(bought.phone_number, bought.expires_at);
- *
- *   // List your active numbers
- *   console.log(await client.listNumbers());
- *
- *   // Renew / release
- *   await client.renewNumber(bought.phone_number);
- *   await client.releaseNumber(bought.phone_number);
- */
-
 /** Per-endpoint price in USD — mirrors the backend's `PHONE_PRICES`. */
 declare const PHONE_PRICES: Readonly<Record<string, number>>;
 /**
@@ -2116,8 +1973,13 @@ declare const PHONE_PRICES: Readonly<Record<string, number>>;
  * and provisioning of the caller-ID numbers required by VoiceClient.call().
  */
 declare class PhoneClient {
-    private account;
-    private privateKey;
+    private _account?;
+    private get account();
+    private apiAuth?;
+    /** Active billing mode. */
+    get authMode(): "api-key" | "wallet";
+    private _privateKey?;
+    private get privateKey();
     private apiUrl;
     private timeout;
     private sessionTotalUsd;
@@ -2170,33 +2032,6 @@ declare class PhoneClient {
     private fetchWithTimeout;
 }
 
-/**
- * BlockRun Portrait Client — enroll a Virtual Portrait via x402.
- *
- * Wraps `POST /v1/portrait/enroll` ($0.01 USDC promo, no KYC). You upload a face image
- * by URL and get back a Token360 asset id (`ta_xxxxxx`). Pass that id as
- * `realFaceAssetId` on a Seedance 2.0 video generation (VideoClient.generate)
- * to keep the same AI character across clips.
- *
- * SECURITY NOTE — your private key never leaves your machine. Only EIP-712
- * signatures are sent in the PAYMENT-SIGNATURE header.
- *
- * @example
- *   import { PortraitClient, VideoClient } from '@blockrun/llm';
- *
- *   const portraits = new PortraitClient({ privateKey: '0x...' });
- *   const { asset_id } = await portraits.enroll({
- *     name: 'Spokesperson',
- *     imageUrl: 'https://example.com/face.jpg',
- *   });
- *
- *   const video = new VideoClient({ privateKey: '0x...' });
- *   const clip = await video.generate('she waves and smiles', {
- *     model: 'bytedance/seedance-2.0-fast',
- *     realFaceAssetId: asset_id,
- *   });
- */
-
 /**
  * Flat enrollment price in USD — mirrors the backend's `ENROLLMENT_PRICE_USD`.
  * Currently $0.01 (promotional, parity with RealFace). The authoritative price
@@ -2211,8 +2046,13 @@ declare const PORTRAIT_ENROLLMENT_PRICE_USD = 0.01;
  * not supported on BlockRun — enrolled portraits are AI characters.
  */
 declare class PortraitClient {
-    private account;
-    private privateKey;
+    private _account?;
+    private get account();
+    private apiAuth?;
+    /** Active billing mode. */
+    get authMode(): "api-key" | "wallet";
+    private _privateKey?;
+    private get privateKey();
     private apiUrl;
     private timeout;
     private sessionTotalUsd;
@@ -2239,25 +2079,14 @@ declare class PortraitClient {
     private fetchWithTimeout;
 }
 
-/**
- * BlockRun Search Client - Standalone Grok Live Search via x402 micropayments.
- *
- * Backend endpoint: POST /api/v1/search
- * Pricing: $0.025/source + margin (default 10 sources ≈ $0.26).
- *
- * Usage:
- *   import { SearchClient } from "@blockrun/llm";
- *
- *   const client = new SearchClient({ privateKey: "0x..." });
- *   const result = await client.search("Latest news on x402 adoption", {
- *     sources: ["x", "web"],
- *   });
- *   console.log(result.summary);
- */
-
 declare class SearchClient {
-    private account;
-    private privateKey;
+    private _account?;
+    private get account();
+    private apiAuth?;
+    /** Active billing mode. */
+    get authMode(): "api-key" | "wallet";
+    private _privateKey?;
+    private get privateKey();
     private apiUrl;
     private timeout;
     constructor(options?: SearchClientOptions);
@@ -2268,25 +2097,9 @@ declare class SearchClient {
     getWalletAddress(): string;
 }
 
-/**
- * BlockRun Price Client - Pyth-backed market data via x402.
- *
- * Payment gating mirrors CategoryConfig.paid in the backend:
- *   crypto, fx, commodity      → FREE across price + history + list
- *   usstock, stocks/{market}   → PAID for price + history; list always free
- *
- * Usage:
- *   import { PriceClient } from "@blockrun/llm";
- *
- *   const p = new PriceClient({ privateKey: "0x..." });
- *   const btc = await p.price("crypto", "BTC-USD");
- *   const aapl = await p.price("stocks", "AAPL", { market: "us" });
- *   const bars = await p.history("stocks", "AAPL", { market: "us",
- *     from: 1700000000, to: 1710000000 });
- *   const symbols = await p.listSymbols("crypto", { query: "sol" });
- */
-
 declare class PriceClient {
+    private apiAuth?;
+    get authMode(): "api-key" | "wallet";
     private account;
     private privateKey;
     private apiUrl;
@@ -2301,53 +2114,16 @@ 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$1 = string | number | boolean | null | undefined;
 type QueryParams$1 = Record<string, QueryValue$1 | QueryValue$1[]>;
 declare class SurfClient {
-    private account;
-    private privateKey;
+    private _account?;
+    private get account();
+    private apiAuth?;
+    /** Active billing mode. */
+    get authMode(): "api-key" | "wallet";
+    private _privateKey?;
+    private get privateKey();
     private apiUrl;
     private timeout;
     constructor(options?: SurfClientOptions);
@@ -2369,52 +2145,6 @@ declare class SurfClient {
     getWalletAddress(): string;
 }
 
-/**
- * BlockRun RPC Client - Multi-chain JSON-RPC (Tatum gateway) via x402 micropayments.
- *
- * One endpoint, 40+ chains: Ethereum, Base, Solana, Polygon, BSC, Arbitrum,
- * Optimism, Avalanche, Bitcoin, Sui, and more. Standard JSON-RPC 2.0
- * passthrough — no API key, pay-per-call in USDC.
- *
- * SECURITY NOTE - Private Key Handling:
- * Your private key NEVER leaves your machine. Here's what happens:
- * 1. Key stays local - only used to sign an EIP-712 typed data message
- * 2. Only the SIGNATURE is sent in the PAYMENT-SIGNATURE header
- * 3. BlockRun verifies the signature on-chain via Coinbase CDP facilitator
- *
- * Usage:
- *   import { RpcClient } from '@blockrun/llm';
- *
- *   const client = new RpcClient({ privateKey: '0x...' });
- *
- *   // EVM chains speak eth_* JSON-RPC
- *   const block = await client.call('ethereum', 'eth_blockNumber');
- *   console.log(block.result); // e.g. "0x1499f7c"
- *
- *   const balance = await client.call('base', 'eth_getBalance', [
- *     '0x4200000000000000000000000000000000000006',
- *     'latest',
- *   ]);
- *
- *   // Non-EVM chains speak their native JSON-RPC
- *   const slot = await client.call('solana', 'getSlot');
- *
- *   // Batch: one payment, per-element pricing ($0.002 x N)
- *   const out = await client.batch('polygon', [
- *     { method: 'eth_blockNumber' },
- *     { method: 'eth_gasPrice' },
- *   ]);
- *
- * Pricing:
- *   Flat $0.002 per JSON-RPC call; a batch charges per element.
- *
- * Networks:
- *   40 curated chains (see SUPPORTED_NETWORKS) plus common aliases
- *   (eth, arb, op, matic, bnb, avax, sol, btc, xrp, dot, ...). Unknown but
- *   well-formed slugs fall through to a generic `{slug}-mainnet` gateway
- *   attempt, so new Tatum chains work without an SDK update.
- */
-
 /**
  * Flat price per JSON-RPC call (batch = N x this). Informational only —
  * the actual quote always comes from the 402 challenge.
@@ -2439,8 +2169,13 @@ declare const NETWORK_ALIASES: Record<string, string>;
  * Flat $0.002 per call; a JSON-RPC batch charges per element.
  */
 declare class RpcClient {
-    private account;
-    private privateKey;
+    private _account?;
+    private get account();
+    private apiAuth?;
+    /** Active billing mode. */
+    get authMode(): "api-key" | "wallet";
+    private _privateKey?;
+    private get privateKey();
     private apiUrl;
     private timeout;
     private sessionTotalUsd;
@@ -2488,55 +2223,6 @@ declare class RpcClient {
     getSpending(): Spending;
 }
 
-/**
- * BlockrunClient — the x402-paying HTTP primitive for the BlockRun gateway.
- *
- * This is the **primitive** that every BlockRun API surface composes on top of:
- * a wallet, an x402 401-sign-replay handler, and four call shapes (get, post,
- * poll, stream). Per-API classes (LLMClient, ImageClient, SurfClient, …) are
- * being collapsed into Claude Code skills that drive this client directly.
- *
- * Why one primitive instead of one client per API surface:
- *   - Every BlockRun endpoint pays the same way (USDC via x402 on Base/Solana)
- *   - ~30-40 % of each existing client class is identical boilerplate
- *   - New API surfaces should ship as a skill (markdown) + path, not as a
- *     new TypeScript class + npm release
- *
- * Four call shapes:
- *   client.get<T>(path, params?)                — sync GET, e.g. /v1/surf/market/price
- *   client.post<T>(path, body?)                 — sync POST, e.g. /v1/surf/onchain/sql
- *   client.poll<T>(path, body?, { budgetMs })   — submit + poll, e.g. /v1/videos/generations
- *   client.stream<T>(path, body?)               — SSE iterator, e.g. /v1/chat/completions
- *
- * Usage:
- *   import { BlockrunClient } from "@blockrun/llm";
- *
- *   const br = new BlockrunClient({ privateKey: "0x..." });
- *
- *   // Surf endpoint (Tier 1, $0.001)
- *   const btc = await br.get("/v1/surf/market/price", { symbol: "BTC" });
- *
- *   // Raw on-chain SQL (Tier 3, $0.020)
- *   const rows = await br.post("/v1/surf/onchain/sql", {
- *     query: "SELECT block_number FROM ethereum.blocks ORDER BY block_number DESC LIMIT 1",
- *   });
- *
- *   // Long-running video generation (submit + poll, paid on success)
- *   const video = await br.poll("/v1/videos/generations", {
- *     model: "xai/grok-imagine-video",
- *     prompt: "a red apple spinning",
- *   });
- *
- *   // Streaming chat
- *   for await (const chunk of br.stream("/v1/chat/completions", {
- *     model: "anthropic/claude-sonnet-4-6",
- *     messages: [{ role: "user", content: "Hi" }],
- *     stream: true,
- *   })) {
- *     process.stdout.write(chunk.choices?.[0]?.delta?.content ?? "");
- *   }
- */
-
 type QueryValue = string | number | boolean | null | undefined;
 type QueryParams = Record<string, QueryValue | QueryValue[]>;
 /**
@@ -2546,8 +2232,13 @@ type QueryParams = Record<string, QueryValue | QueryValue[]>;
  * poll, stream) cover every endpoint type the gateway exposes.
  */
 declare class BlockrunClient {
-    private account;
-    private privateKey;
+    private _account?;
+    private get account();
+    private apiAuth?;
+    /** Active billing mode. */
+    get authMode(): "api-key" | "wallet";
+    private _privateKey?;
+    private get privateKey();
     private apiUrl;
     private timeout;
     private sessionTotalUsd;
@@ -2914,22 +2605,7 @@ declare function formatFundingMessageCompact(address: string): string;
 declare const WALLET_FILE_PATH: string;
 declare const WALLET_DIR_PATH: string;
 
-/**
- * BlockRun Solana LLM Client.
- *
- * Usage:
- *   import { SolanaLLMClient } from '@blockrun/llm';
- *
- *   // SOLANA_WALLET_KEY env var (bs58-encoded Solana secret key)
- *   const client = new SolanaLLMClient();
- *
- *   // Or pass key directly
- *   const client = new SolanaLLMClient({ privateKey: 'your-bs58-key' });
- *
- *   const response = await client.chat('openai/gpt-5.2', 'gm Solana');
- */
-
-interface SolanaLLMClientOptions {
+interface SolanaLLMClientOptions extends ApiKeyOptions {
     /** bs58-encoded Solana secret key (64 bytes). Optional if SOLANA_WALLET_KEY env var is set. */
     privateKey?: string;
     /** API endpoint URL (default: https://sol.blockrun.ai/api) */
@@ -2954,7 +2630,10 @@ interface SolanaLLMClientOptions {
 }
 declare class SolanaLLMClient {
     static readonly SOLANA_API_URL = "https://sol.blockrun.ai/api";
-    private privateKey;
+    private apiAuth?;
+    get authMode(): "api-key" | "wallet";
+    private _privateKey?;
+    private get privateKey();
     private apiUrl;
     private rpcUrl;
     private rpcHeaders?;
@@ -3204,13 +2883,6 @@ declare function getCostLogSummary(): {
     byEndpoint: Record<string, number>;
 };
 
-/**
- * Agent wallet setup utilities.
- *
- * Convenience functions for agent runtimes (Claude Code skills, etc.)
- * that auto-create wallets and return configured clients.
- */
-
 declare function setupAgentWallet(options?: {
     silent?: boolean;
 }): LLMClient;
@@ -3221,6 +2893,14 @@ declare function status(): Promise<{
     address: string;
     balance: number;
 }>;
+/** Account API when configured; otherwise Solana for new wallets.
+ * Existing chain preferences and Base-only wallets remain on their chosen chain.
+ * The named setupAgentWallet/setupAgentSolanaWallet helpers retain their behavior.
+ */
+declare function setupAgentClient(options?: ApiKeyOptions & {
+    chain?: 'solana' | 'base';
+    silent?: boolean;
+}): Promise<LLMClient | SolanaLLMClient>;
 
 /** Canonical on-wire schema for cost_log.jsonl entries. */
 interface CostEntry {
@@ -3247,29 +2927,8 @@ declare function getCostSummary(): {
     byEndpoint: Record<string, number>;
 };
 
-/**
- * OpenAI-compatible API wrapper for BlockRun LLM SDK.
- *
- * Drop-in replacement for OpenAI SDK - just change the import and use walletKey instead of apiKey.
- *
- * @example
- * // Before (OpenAI)
- * import OpenAI from 'openai';
- * const client = new OpenAI({ apiKey: 'sk-...' });
- *
- * // After (BlockRun)
- * import { OpenAI } from '@blockrun/llm';
- * const client = new OpenAI({ walletKey: '0x...' });
- *
- * // Rest of your code stays exactly the same!
- * const response = await client.chat.completions.create({
- *   model: 'gpt-5.2',
- *   messages: [{ role: 'user', content: 'Hello!' }]
- * });
- */
-
-interface OpenAIClientOptions {
-    /** EVM wallet private key (replaces apiKey) */
+interface OpenAIClientOptions extends ApiKeyOptions {
+    /** EVM wallet private key for explicit wallet mode. */
     walletKey?: `0x${string}` | string;
     /** Alternative: use privateKey like LLMClient */
     privateKey?: `0x${string}` | string;
@@ -3381,6 +3040,7 @@ declare class Chat {
  */
 declare class OpenAI {
     chat: Chat;
+    get authMode(): "api-key" | "wallet";
     private client;
     constructor(options?: OpenAIClientOptions);
     /**
@@ -3389,7 +3049,7 @@ declare class OpenAI {
     getWalletAddress(): string;
 }
 
-interface BlockRunAnthropicOptions {
+interface BlockRunAnthropicOptions extends ApiKeyOptions {
     privateKey?: `0x${string}` | string;
     apiUrl?: string;
     timeout?: number;
@@ -3397,8 +3057,12 @@ interface BlockRunAnthropicOptions {
 declare class AnthropicClient {
     private _client;
     private _clientPromise;
-    private _privateKey;
-    private _account;
+    private apiAuth?;
+    get authMode(): "api-key" | "wallet";
+    private walletKey?;
+    private get _privateKey();
+    private walletAccount?;
+    private get _account();
     private _apiUrl;
     private _timeout;
     constructor(options?: BlockRunAnthropicOptions);
@@ -3479,4 +3143,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, BlockrunClient, type BlockrunClientOptions, BlockrunError, type CallInitiatedResponse, type CallModel, type CallOptions, type CallStatusResponse, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, NETWORK_ALIASES, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PHONE_PRICES, PORTRAIT_ENROLLMENT_PRICE_USD, PaymentError, type PaymentLinks, type PhoneBuyOptions, type PhoneBuyResponse, PhoneClient, type PhoneClientOptions, type PhoneListResponse, type PhoneLookupResponse, type PhoneNumberRecord, type PhoneReleaseResponse, type PhoneRenewResponse, type PollOptions, PortraitClient, type PortraitClientOptions, type PortraitEnrollOptions, type PortraitEnrollResponse, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, RPC_PRICE_USD, type ResponseFormat, RetiredEndpointError, type RoutingDecision, type RoutingProfile, type RoutingTaskType, type RoutingTier, type RoutingTierConfig, type RpcBatchRequest, RpcClient, type RpcClientOptions, type RpcError, type RpcNetwork, type RpcResponse, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SUPPORTED_NETWORKS, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type SmartChatCompletionOptions, type SmartChatCompletionResponse, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type SoundEffectOptions, type SpeechAudio, SpeechClient, type SpeechClientOptions, type SpeechGenerateOptions, type SpeechModel, type SpeechResponse, type SpeechVoice, type Spending, type SpendingReport, type StockMarket, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoiceInfo, type VoicePreset, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XSearchSource, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatSolanaWalletMigrationNotice, formatWalletCreatedMessage, formatWalletMigrationNotice, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, importSolanaWallet, importWallet, listDiscoveredSolanaWallets, listDiscoveredWallets, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, validateMaxTokens, validateModel, validateTemperature, validateTopP };
+export { APIError, API_KEY_URL, AnthropicClient, type ApiKeyOptions, type AudioModel, type AudioTrack, BASE_CHAIN_ID, type BarResolution, type BlockRunAnthropicOptions, BlockrunClient, type BlockrunClientOptions, BlockrunError, type CallInitiatedResponse, type CallModel, type CallOptions, type CallStatusResponse, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, NETWORK_ALIASES, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PHONE_PRICES, PORTAL_URL, PORTRAIT_ENROLLMENT_PRICE_USD, PaymentError, type PaymentLinks, type PhoneBuyOptions, type PhoneBuyResponse, PhoneClient, type PhoneClientOptions, type PhoneListResponse, type PhoneLookupResponse, type PhoneNumberRecord, type PhoneReleaseResponse, type PhoneRenewResponse, type PollOptions, PortraitClient, type PortraitClientOptions, type PortraitEnrollOptions, type PortraitEnrollResponse, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, RPC_PRICE_USD, type ResponseFormat, RetiredEndpointError, type RoutingDecision, type RoutingProfile, type RoutingTaskType, type RoutingTier, type RoutingTierConfig, type RpcBatchRequest, RpcClient, type RpcClientOptions, type RpcError, type RpcNetwork, type RpcResponse, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SUPPORTED_NETWORKS, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type SmartChatCompletionOptions, type SmartChatCompletionResponse, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type SoundEffectOptions, type SpeechAudio, SpeechClient, type SpeechClientOptions, type SpeechGenerateOptions, type SpeechModel, type SpeechResponse, type SpeechVoice, type Spending, type SpendingReport, type StockMarket, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoiceInfo, type VoicePreset, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XSearchSource, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatSolanaWalletMigrationNotice, formatWalletCreatedMessage, formatWalletMigrationNotice, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, importSolanaWallet, importWallet, listDiscoveredSolanaWallets, listDiscoveredWallets, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentClient, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, validateMaxTokens, validateModel, validateTemperature, validateTopP };