@blockrun/llm 0.2.1 → 1.0.0

package/README.md

@@ -2,7 +2,11 @@
 
 Pay-per-request access to GPT-4o, Claude 4, Gemini 2.5, and more via x402 micropayments on Base and Solana.
 
-**Networks:** Base (Chain ID: 8453) and Solana Mainnet
+**Networks:**
+- **Base Mainnet:** Chain ID 8453 - Production with real USDC
+- **Base Sepolia (Testnet):** Chain ID 84532 - Developer testing with testnet USDC
+- **Solana Mainnet** - Production with real USDC
+
 **Payment:** USDC
 **Protocol:** x402 v2 (CDP Facilitator)
 
@@ -55,12 +59,10 @@ For Solana, set `BLOCKRUN_SOLANA_KEY` environment variable with your base58-enco
 | Model | Input Price | Output Price |
 |-------|-------------|--------------|
 | `openai/gpt-5.2` | $1.75/M | $14.00/M |
-| `openai/gpt-5.1` | $1.25/M | $10.00/M |
-| `openai/gpt-5` | $1.25/M | $10.00/M |
 | `openai/gpt-5-mini` | $0.25/M | $2.00/M |
 | `openai/gpt-5-nano` | $0.05/M | $0.40/M |
 | `openai/gpt-5.2-pro` | $21.00/M | $168.00/M |
-| `openai/gpt-5-pro` | $15.00/M | $120.00/M |
+| `openai/gpt-5.2-codex` | $1.75/M | $14.00/M |
 
 ### OpenAI GPT-4 Family
 | Model | Input Price | Output Price |
@@ -83,7 +85,10 @@ For Solana, set `BLOCKRUN_SOLANA_KEY` environment variable with your base58-enco
 ### Anthropic Claude
 | Model | Input Price | Output Price |
 |-------|-------------|--------------|
+| `anthropic/claude-opus-4.6` | $5.00/M | $25.00/M |
+| `anthropic/claude-opus-4.5` | $5.00/M | $25.00/M |
 | `anthropic/claude-opus-4` | $15.00/M | $75.00/M |
+| `anthropic/claude-sonnet-4.6` | $3.00/M | $15.00/M |
 | `anthropic/claude-sonnet-4` | $3.00/M | $15.00/M |
 | `anthropic/claude-haiku-4.5` | $1.00/M | $5.00/M |
 
@@ -92,7 +97,52 @@ For Solana, set `BLOCKRUN_SOLANA_KEY` environment variable with your base58-enco
 |-------|-------------|--------------|
 | `google/gemini-3-pro-preview` | $2.00/M | $12.00/M |
 | `google/gemini-2.5-pro` | $1.25/M | $10.00/M |
-| `google/gemini-2.5-flash` | $0.15/M | $0.60/M |
+| `google/gemini-2.5-flash` | $0.30/M | $2.50/M |
+
+### DeepSeek
+| Model | Input Price | Output Price |
+|-------|-------------|--------------|
+| `deepseek/deepseek-chat` | $0.28/M | $0.42/M |
+| `deepseek/deepseek-reasoner` | $0.28/M | $0.42/M |
+
+### xAI Grok
+| Model | Input Price | Output Price | Context | Notes |
+|-------|-------------|--------------|---------|-------|
+| `xai/grok-3` | $3.00/M | $15.00/M | 131K | Flagship |
+| `xai/grok-3-mini` | $0.30/M | $0.50/M | 131K | Fast & affordable |
+| `xai/grok-4-1-fast-reasoning` | $0.20/M | $0.50/M | **2M** | Latest, chain-of-thought |
+| `xai/grok-4-1-fast-non-reasoning` | $0.20/M | $0.50/M | **2M** | Latest, direct response |
+| `xai/grok-4-fast-reasoning` | $0.20/M | $0.50/M | **2M** | Step-by-step reasoning |
+| `xai/grok-4-fast-non-reasoning` | $0.20/M | $0.50/M | **2M** | Quick responses |
+| `xai/grok-code-fast-1` | $0.20/M | $1.50/M | 256K | Code generation |
+| `xai/grok-4-0709` | $0.20/M | $1.50/M | 256K | Premium quality |
+| `xai/grok-2-vision` | $2.00/M | $10.00/M | 32K | Vision capabilities |
+
+### Moonshot Kimi
+| Model | Input Price | Output Price |
+|-------|-------------|--------------|
+| `moonshot/kimi-k2.5` | $0.60/M | $3.00/M |
+
+### NVIDIA (Free & Hosted)
+| Model | Input Price | Output Price | Notes |
+|-------|-------------|--------------|-------|
+| `nvidia/gpt-oss-120b` | **FREE** | **FREE** | OpenAI open-weight 120B (Apache 2.0) |
+| `nvidia/kimi-k2.5` | $0.60/M | $3.00/M | Moonshot 1T MoE with vision |
+
+### E2E Verified Models
+
+All models below have been tested end-to-end via the TypeScript SDK (Feb 2026):
+
+| Provider | Model | Status |
+|----------|-------|--------|
+| OpenAI | `openai/gpt-4o-mini` | Passed |
+| OpenAI | `openai/gpt-5.2-codex` | Passed |
+| Anthropic | `anthropic/claude-opus-4.6` | Passed |
+| Anthropic | `anthropic/claude-sonnet-4` | Passed |
+| Google | `google/gemini-2.5-flash` | Passed |
+| DeepSeek | `deepseek/deepseek-chat` | Passed |
+| xAI | `xai/grok-3` | Passed |
+| Moonshot | `moonshot/kimi-k2.5` | Passed |
 
 ### Image Generation
 | Model | Price |
@@ -103,6 +153,56 @@ For Solana, set `BLOCKRUN_SOLANA_KEY` environment variable with your base58-enco
 | `google/nano-banana-pro` | $0.10-0.15/image |
 | `black-forest/flux-1.1-pro` | $0.04/image |
 
+### Testnet Models (Base Sepolia)
+| Model | Price |
+|-------|-------|
+| `openai/gpt-oss-20b` | $0.001/request |
+| `openai/gpt-oss-120b` | $0.002/request |
+
+*Testnet models use flat pricing (no token counting) for simplicity.*
+
+## Testnet Usage
+
+For development and testing without real USDC, use the testnet:
+
+```typescript
+import { testnetClient } from '@blockrun/llm';
+
+// Create testnet client (uses Base Sepolia)
+const client = testnetClient({ privateKey: '0x...' });
+
+// Chat with testnet model
+const response = await client.chat('openai/gpt-oss-20b', 'Hello!');
+console.log(response);
+
+// Check if client is on testnet
+console.log(client.isTestnet()); // true
+```
+
+### Testnet Setup
+
+1. Get testnet ETH from [Alchemy Base Sepolia Faucet](https://www.alchemy.com/faucets/base-sepolia)
+2. Get testnet USDC from [Circle USDC Faucet](https://faucet.circle.com/)
+3. Set your wallet key: `export BASE_CHAIN_WALLET_KEY=0x...`
+
+### Available Testnet Models
+
+- `openai/gpt-oss-20b` - $0.001/request (flat price)
+- `openai/gpt-oss-120b` - $0.002/request (flat price)
+
+### Manual Testnet Configuration
+
+```typescript
+import { LLMClient } from '@blockrun/llm';
+
+// Or configure manually
+const client = new LLMClient({
+  privateKey: '0x...',
+  apiUrl: 'https://testnet.blockrun.ai/api'
+});
+const response = await client.chat('openai/gpt-oss-20b', 'Hello!');
+```
+
 ## Usage Examples
 
 ### Simple Chat
@@ -121,6 +221,47 @@ const response2 = await client.chat('anthropic/claude-sonnet-4', 'Write a haiku'
 });
 ```
 
+### Smart Routing (ClawRouter)
+
+Save up to 78% on inference costs with intelligent model routing. ClawRouter uses a 14-dimension rule-based scoring algorithm to select the cheapest model that can handle your request (<1ms, 100% local).
+
+```typescript
+import { LLMClient } from '@blockrun/llm';
+
+const client = new LLMClient();
+
+// Auto-route to cheapest capable model
+const result = await client.smartChat('What is 2+2?');
+console.log(result.response);     // '4'
+console.log(result.model);        // 'google/gemini-2.5-flash'
+console.log(result.routing.tier); // 'SIMPLE'
+console.log(`Saved ${(result.routing.savings * 100).toFixed(0)}%`); // 'Saved 78%'
+
+// Routing profiles
+const free = await client.smartChat('Hello!', { routingProfile: 'free' });     // Zero cost
+const eco = await client.smartChat('Explain AI', { routingProfile: 'eco' });   // Budget optimized
+const auto = await client.smartChat('Code review', { routingProfile: 'auto' }); // Balanced (default)
+const premium = await client.smartChat('Write a legal brief', { routingProfile: 'premium' }); // Best quality
+```
+
+**Routing Profiles:**
+
+| Profile | Description | Best For |
+|---------|-------------|----------|
+| `free` | NVIDIA free models only | Testing, simple queries |
+| `eco` | Budget-optimized | Cost-sensitive workloads |
+| `auto` | Intelligent routing (default) | General use |
+| `premium` | Best quality models | Critical tasks |
+
+**Tiers:**
+
+| Tier | Example Tasks | Typical Models |
+|------|---------------|----------------|
+| SIMPLE | Greetings, math, lookups | Gemini Flash, GPT-4o-mini |
+| MEDIUM | Explanations, summaries | GPT-4o, Claude Sonnet |
+| COMPLEX | Analysis, code generation | GPT-5.2, Claude Opus |
+| REASONING | Multi-step logic, planning | o3, DeepSeek Reasoner |
+
 ### Full Chat Completion
 
 ```typescript
@@ -299,10 +440,17 @@ Full TypeScript support with exported types:
 ```typescript
 import {
   LLMClient,
+  testnetClient,
   type ChatMessage,
   type ChatResponse,
   type ChatOptions,
   type Model,
+  // Smart routing types
+  type SmartChatOptions,
+  type SmartChatResponse,
+  type RoutingDecision,
+  type RoutingProfile,
+  type RoutingTier,
   APIError,
   PaymentError,
 } from '@blockrun/llm';
@@ -311,9 +459,9 @@ import {
 ## Links
 
 - [Website](https://blockrun.ai)
-- [Documentation](https://docs.blockrun.ai)
-- [GitHub](https://github.com/blockrun/blockrun-llm-ts)
-- [Discord](https://discord.gg/blockrun)
+- [Documentation](https://github.com/BlockRunAI/awesome-blockrun/tree/main/docs)
+- [GitHub](https://github.com/blockrunai/blockrun-llm-ts)
+- [Telegram](https://t.me/+mroQv4-4hGgzOGUx)
 
 ## License
 

package/dist/index.cjs

@@ -51,7 +51,8 @@ __export(index_exports, {
   getPaymentLinks: () => getPaymentLinks,
   getWalletAddress: () => getWalletAddress,
   loadWallet: () => loadWallet,
-  saveWallet: () => saveWallet
+  saveWallet: () => saveWallet,
+  testnetClient: () => testnetClient
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -82,6 +83,9 @@ var APIError = class extends BlockrunError {
   }
 };
 
+// src/client.ts
+var import_clawrouter = require("@blockrun/clawrouter");
+
 // src/x402.ts
 var import_accounts = require("viem/accounts");
 var BASE_CHAIN_ID = 8453;
@@ -278,15 +282,22 @@ function validateResourceUrl(url, baseUrl) {
 
 // src/client.ts
 var DEFAULT_API_URL = "https://blockrun.ai/api";
+var TESTNET_API_URL = "https://testnet.blockrun.ai/api";
 var DEFAULT_MAX_TOKENS = 1024;
 var DEFAULT_TIMEOUT = 6e4;
+var SDK_VERSION = "0.3.0";
+var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 var LLMClient = class {
+  static DEFAULT_API_URL = DEFAULT_API_URL;
+  static TESTNET_API_URL = TESTNET_API_URL;
   account;
   privateKey;
   apiUrl;
   timeout;
   sessionTotalUsd = 0;
   sessionCalls = 0;
+  modelPricingCache = null;
+  modelPricingPromise = null;
   /**
    * Initialize the BlockRun LLM client.
    *
@@ -333,7 +344,92 @@ var LLMClient = class {
       search: options?.search,
       searchParameters: options?.searchParameters
     });
-    return result.choices[0].message.content;
+    return result.choices[0].message.content || "";
+  }
+  /**
+   * Smart chat with automatic model routing.
+   *
+   * Uses ClawRouter's 14-dimension rule-based scoring algorithm (<1ms, 100% local)
+   * to select the cheapest model that can handle your request.
+   *
+   * @param prompt - User message
+   * @param options - Optional chat and routing parameters
+   * @returns SmartChatResponse with response text, selected model, and routing metadata
+   *
+   * @example Simple usage (auto profile)
+   * ```ts
+   * const result = await client.smartChat('What is 2+2?');
+   * console.log(result.response); // '4'
+   * console.log(result.model); // 'google/gemini-2.5-flash'
+   * console.log(result.routing.savings); // 0.78 (78% savings)
+   * ```
+   *
+   * @example With routing profile
+   * ```ts
+   * // Free tier only (zero cost)
+   * const result = await client.smartChat('Hello!', { routingProfile: 'free' });
+   *
+   * // Eco mode (budget optimized)
+   * const result = await client.smartChat('Explain quantum computing', { routingProfile: 'eco' });
+   *
+   * // Premium mode (best quality)
+   * const result = await client.smartChat('Write a business plan', { routingProfile: 'premium' });
+   * ```
+   */
+  async smartChat(prompt, options) {
+    const modelPricing = await this.getModelPricing();
+    const maxOutputTokens = options?.maxOutputTokens || options?.maxTokens || 1024;
+    const decision = (0, import_clawrouter.route)(prompt, options?.system, maxOutputTokens, {
+      config: import_clawrouter.DEFAULT_ROUTING_CONFIG,
+      modelPricing,
+      routingProfile: options?.routingProfile
+    });
+    const response = await this.chat(decision.model, prompt, {
+      system: options?.system,
+      maxTokens: options?.maxTokens,
+      temperature: options?.temperature,
+      topP: options?.topP,
+      search: options?.search,
+      searchParameters: options?.searchParameters
+    });
+    return {
+      response,
+      model: decision.model,
+      routing: decision
+    };
+  }
+  /**
+   * Get model pricing map (cached).
+   * Fetches from API on first call, then returns cached result.
+   */
+  async getModelPricing() {
+    if (this.modelPricingCache) {
+      return this.modelPricingCache;
+    }
+    if (this.modelPricingPromise) {
+      return this.modelPricingPromise;
+    }
+    this.modelPricingPromise = this.fetchModelPricing();
+    try {
+      this.modelPricingCache = await this.modelPricingPromise;
+      return this.modelPricingCache;
+    } finally {
+      this.modelPricingPromise = null;
+    }
+  }
+  /**
+   * Fetch model pricing from API.
+   */
+  async fetchModelPricing() {
+    const models = await this.listModels();
+    const pricing = /* @__PURE__ */ new Map();
+    for (const model of models) {
+      pricing.set(model.id, {
+        inputPrice: model.inputPrice,
+        outputPrice: model.outputPrice
+      });
+    }
+    return pricing;
   }
   /**
    * Full chat completion interface (OpenAI-compatible).
@@ -360,6 +456,12 @@ var LLMClient = class {
     } else if (options?.search === true) {
       body.search_parameters = { mode: "on" };
     }
+    if (options?.tools !== void 0) {
+      body.tools = options.tools;
+    }
+    if (options?.toolChoice !== void 0) {
+      body.tool_choice = options.toolChoice;
+    }
     return this.requestWithPayment("/v1/chat/completions", body);
   }
   /**
@@ -369,7 +471,7 @@ var LLMClient = class {
     const url = `${this.apiUrl}${endpoint}`;
     const response = await this.fetchWithTimeout(url, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT },
       body: JSON.stringify(body)
     });
     if (response.status === 402) {
@@ -432,6 +534,7 @@ var LLMClient = class {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
+        "User-Agent": USER_AGENT,
         "PAYMENT-SIGNATURE": paymentPayload
       },
       body: JSON.stringify(body)
@@ -560,7 +663,19 @@ var LLMClient = class {
   getWalletAddress() {
     return this.account.address;
   }
+  /**
+   * Check if client is configured for testnet.
+   */
+  isTestnet() {
+    return this.apiUrl.includes("testnet.blockrun.ai");
+  }
 };
+function testnetClient(options = {}) {
+  return new LLMClient({
+    ...options,
+    apiUrl: TESTNET_API_URL
+  });
+}
 var client_default = LLMClient;
 
 // src/image.ts
@@ -962,7 +1077,9 @@ var ChatCompletions = class {
       {
         maxTokens: params.max_tokens,
         temperature: params.temperature,
-        topP: params.top_p
+        topP: params.top_p,
+        tools: params.tools,
+        toolChoice: params.tool_choice
       }
     );
     return this.transformResponse(response);
@@ -977,6 +1094,12 @@ var ChatCompletions = class {
       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 {
@@ -1013,7 +1136,8 @@ var ChatCompletions = class {
         index: choice.index ?? index,
         message: {
           role: "assistant",
-          content: choice.message.content
+          content: choice.message.content,
+          tool_calls: choice.message.tool_calls
         },
         finish_reason: choice.finish_reason || "stop"
       })),
@@ -1070,5 +1194,6 @@ var OpenAI = class {
   getPaymentLinks,
   getWalletAddress,
   loadWallet,
-  saveWallet
+  saveWallet,
+  testnetClient
 });

package/dist/index.d.cts

@@ -1,14 +1,42 @@
 /**
  * Type definitions for BlockRun LLM SDK
  */
+interface FunctionDefinition {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+    strict?: boolean;
+}
+interface Tool {
+    type: "function";
+    function: FunctionDefinition;
+}
+interface FunctionCall {
+    name: string;
+    arguments: string;
+}
+interface ToolCall {
+    id: string;
+    type: "function";
+    function: FunctionCall;
+}
+type ToolChoice = "none" | "auto" | "required" | {
+    type: "function";
+    function: {
+        name: string;
+    };
+};
 interface ChatMessage {
-    role: "system" | "user" | "assistant";
-    content: string;
+    role: "system" | "user" | "assistant" | "tool";
+    content?: string | null;
+    name?: string;
+    tool_call_id?: string;
+    tool_calls?: ToolCall[];
 }
 interface ChatChoice {
     index: number;
     message: ChatMessage;
-    finish_reason?: string;
+    finish_reason?: "stop" | "length" | "content_filter" | "tool_calls";
 }
 interface ChatUsage {
     prompt_tokens: number;
@@ -146,6 +174,36 @@ interface ChatCompletionOptions {
     search?: boolean;
     /** Full xAI Live Search configuration (for Grok models) */
     searchParameters?: SearchParameters;
+    /** Tool definitions for function calling */
+    tools?: Tool[];
+    /** Tool selection strategy */
+    toolChoice?: ToolChoice;
+}
+type RoutingProfile = "free" | "eco" | "auto" | "premium";
+type RoutingTier = "SIMPLE" | "MEDIUM" | "COMPLEX" | "REASONING";
+interface RoutingDecision {
+    model: string;
+    tier: RoutingTier;
+    confidence: number;
+    method: "rules" | "llm";
+    reasoning: string;
+    costEstimate: number;
+    baselineCost: number;
+    savings: number;
+}
+interface SmartChatOptions extends ChatOptions {
+    /** Routing profile: free (zero cost), eco (budget), auto (balanced), premium (best quality) */
+    routingProfile?: RoutingProfile;
+    /** Maximum output tokens (used for cost estimation) */
+    maxOutputTokens?: number;
+}
+interface SmartChatResponse {
+    /** The AI response text */
+    response: string;
+    /** Which model was selected by smart routing */
+    model: string;
+    /** Routing decision metadata */
+    routing: RoutingDecision;
 }
 declare class BlockrunError extends Error {
     constructor(message: string);
@@ -180,14 +238,36 @@ declare class APIError extends BlockrunError {
  *
  * Provides access to multiple LLM providers (OpenAI, Anthropic, Google, etc.)
  * with automatic x402 micropayments on Base chain.
+ *
+ * Networks:
+ * - Mainnet: https://blockrun.ai/api (Base, Chain ID 8453)
+ * - Testnet: https://testnet.blockrun.ai/api (Base Sepolia, Chain ID 84532)
+ *
+ * @example Testnet usage
+ * ```ts
+ * // Use testnet convenience function
+ * import { testnetClient } from '@blockrun/llm';
+ * const client = testnetClient({ privateKey: '0x...' });
+ * const response = await client.chat('openai/gpt-oss-20b', 'Hello!');
+ *
+ * // Or configure manually
+ * const client = new LLMClient({
+ *   privateKey: '0x...',
+ *   apiUrl: 'https://testnet.blockrun.ai/api'
+ * });
+ * ```
  */
 declare class LLMClient {
+    static readonly DEFAULT_API_URL = "https://blockrun.ai/api";
+    static readonly TESTNET_API_URL = "https://testnet.blockrun.ai/api";
     private account;
     private privateKey;
     private apiUrl;
     private timeout;
     private sessionTotalUsd;
     private sessionCalls;
+    private modelPricingCache;
+    private modelPricingPromise;
     /**
      * Initialize the BlockRun LLM client.
      *
@@ -207,6 +287,46 @@ declare class LLMClient {
      * console.log(response); // 'The capital of France is Paris.'
      */
     chat(model: string, prompt: string, options?: ChatOptions): Promise<string>;
+    /**
+     * Smart chat with automatic model routing.
+     *
+     * Uses ClawRouter's 14-dimension rule-based scoring algorithm (<1ms, 100% local)
+     * to select the cheapest model that can handle your request.
+     *
+     * @param prompt - User message
+     * @param options - Optional chat and routing parameters
+     * @returns SmartChatResponse with response text, selected model, and routing metadata
+     *
+     * @example Simple usage (auto profile)
+     * ```ts
+     * const result = await client.smartChat('What is 2+2?');
+     * console.log(result.response); // '4'
+     * console.log(result.model); // 'google/gemini-2.5-flash'
+     * console.log(result.routing.savings); // 0.78 (78% savings)
+     * ```
+     *
+     * @example With routing profile
+     * ```ts
+     * // Free tier only (zero cost)
+     * const result = await client.smartChat('Hello!', { routingProfile: 'free' });
+     *
+     * // Eco mode (budget optimized)
+     * const result = await client.smartChat('Explain quantum computing', { routingProfile: 'eco' });
+     *
+     * // Premium mode (best quality)
+     * const result = await client.smartChat('Write a business plan', { routingProfile: 'premium' });
+     * ```
+     */
+    smartChat(prompt: string, options?: SmartChatOptions): Promise<SmartChatResponse>;
+    /**
+     * Get model pricing map (cached).
+     * Fetches from API on first call, then returns cached result.
+     */
+    private getModelPricing;
+    /**
+     * Fetch model pricing from API.
+     */
+    private fetchModelPricing;
     /**
      * Full chat completion interface (OpenAI-compatible).
      *
@@ -266,7 +386,38 @@ declare class LLMClient {
      * Get the wallet address being used for payments.
      */
     getWalletAddress(): string;
+    /**
+     * Check if client is configured for testnet.
+     */
+    isTestnet(): boolean;
 }
+/**
+ * Create a testnet LLM client for development and testing.
+ *
+ * This is a convenience function that creates an LLMClient configured
+ * for the BlockRun testnet (Base Sepolia).
+ *
+ * @param options - Client options (privateKey required unless BASE_CHAIN_WALLET_KEY env var is set)
+ * @returns LLMClient configured for testnet
+ *
+ * @example
+ * ```ts
+ * import { testnetClient } from '@blockrun/llm';
+ *
+ * const client = testnetClient({ privateKey: '0x...' });
+ * const response = await client.chat('openai/gpt-oss-20b', 'Hello!');
+ * ```
+ *
+ * Testnet Setup:
+ * 1. Get testnet ETH from https://www.alchemy.com/faucets/base-sepolia
+ * 2. Get testnet USDC from https://faucet.circle.com/
+ * 3. Use your wallet with testnet funds
+ *
+ * Available Testnet Models:
+ * - openai/gpt-oss-20b
+ * - openai/gpt-oss-120b
+ */
+declare function testnetClient(options?: Omit<LLMClientOptions, 'apiUrl'>): LLMClient;
 
 /**
  * BlockRun Image Client - Generate images via x402 micropayments.
@@ -485,8 +636,11 @@ interface OpenAIClientOptions {
 interface OpenAIChatCompletionParams {
     model: string;
     messages: Array<{
-        role: "system" | "user" | "assistant";
-        content: string;
+        role: "system" | "user" | "assistant" | "tool";
+        content?: string | null;
+        name?: string;
+        tool_call_id?: string;
+        tool_calls?: ToolCall[];
     }>;
     max_tokens?: number;
     temperature?: number;
@@ -497,14 +651,17 @@ interface OpenAIChatCompletionParams {
     presence_penalty?: number;
     frequency_penalty?: number;
     user?: string;
+    tools?: Tool[];
+    tool_choice?: ToolChoice;
 }
 interface OpenAIChatCompletionChoice {
     index: number;
     message: {
         role: "assistant";
-        content: string;
+        content?: string | null;
+        tool_calls?: ToolCall[];
     };
-    finish_reason: string | null;
+    finish_reason: "stop" | "length" | "content_filter" | "tool_calls" | null;
 }
 interface OpenAIChatCompletionResponse {
     id: string;
@@ -584,4 +741,4 @@ declare class OpenAI {
     getWalletAddress(): string;
 }
 
-export { APIError, BASE_CHAIN_ID, BlockrunError, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatUsage, ImageClient, type ImageClientOptions, type ImageData, type ImageGenerateOptions, type ImageModel, type ImageResponse, LLMClient, type LLMClientOptions, type Model, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PaymentError, type PaymentLinks, type RssSearchSource, type SearchParameters, type SearchSource, type Spending, USDC_BASE, USDC_BASE_CONTRACT, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XSearchSource, createWallet, LLMClient as default, formatFundingMessageCompact, formatNeedsFundingMessage, formatWalletCreatedMessage, getEip681Uri, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadWallet, saveWallet };
+export { APIError, BASE_CHAIN_ID, BlockrunError, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatUsage, type FunctionCall, type FunctionDefinition, ImageClient, type ImageClientOptions, type ImageData, type ImageGenerateOptions, type ImageModel, type ImageResponse, LLMClient, type LLMClientOptions, type Model, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PaymentError, type PaymentLinks, type RoutingDecision, type RoutingProfile, type RoutingTier, type RssSearchSource, type SearchParameters, type SearchSource, type SmartChatOptions, type SmartChatResponse, type Spending, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XSearchSource, createWallet, LLMClient as default, formatFundingMessageCompact, formatNeedsFundingMessage, formatWalletCreatedMessage, getEip681Uri, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadWallet, saveWallet, testnetClient };

package/dist/index.d.ts

@@ -1,14 +1,42 @@
 /**
  * Type definitions for BlockRun LLM SDK
  */
+interface FunctionDefinition {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+    strict?: boolean;
+}
+interface Tool {
+    type: "function";
+    function: FunctionDefinition;
+}
+interface FunctionCall {
+    name: string;
+    arguments: string;
+}
+interface ToolCall {
+    id: string;
+    type: "function";
+    function: FunctionCall;
+}
+type ToolChoice = "none" | "auto" | "required" | {
+    type: "function";
+    function: {
+        name: string;
+    };
+};
 interface ChatMessage {
-    role: "system" | "user" | "assistant";
-    content: string;
+    role: "system" | "user" | "assistant" | "tool";
+    content?: string | null;
+    name?: string;
+    tool_call_id?: string;
+    tool_calls?: ToolCall[];
 }
 interface ChatChoice {
     index: number;
     message: ChatMessage;
-    finish_reason?: string;
+    finish_reason?: "stop" | "length" | "content_filter" | "tool_calls";
 }
 interface ChatUsage {
     prompt_tokens: number;
@@ -146,6 +174,36 @@ interface ChatCompletionOptions {
     search?: boolean;
     /** Full xAI Live Search configuration (for Grok models) */
     searchParameters?: SearchParameters;
+    /** Tool definitions for function calling */
+    tools?: Tool[];
+    /** Tool selection strategy */
+    toolChoice?: ToolChoice;
+}
+type RoutingProfile = "free" | "eco" | "auto" | "premium";
+type RoutingTier = "SIMPLE" | "MEDIUM" | "COMPLEX" | "REASONING";
+interface RoutingDecision {
+    model: string;
+    tier: RoutingTier;
+    confidence: number;
+    method: "rules" | "llm";
+    reasoning: string;
+    costEstimate: number;
+    baselineCost: number;
+    savings: number;
+}
+interface SmartChatOptions extends ChatOptions {
+    /** Routing profile: free (zero cost), eco (budget), auto (balanced), premium (best quality) */
+    routingProfile?: RoutingProfile;
+    /** Maximum output tokens (used for cost estimation) */
+    maxOutputTokens?: number;
+}
+interface SmartChatResponse {
+    /** The AI response text */
+    response: string;
+    /** Which model was selected by smart routing */
+    model: string;
+    /** Routing decision metadata */
+    routing: RoutingDecision;
 }
 declare class BlockrunError extends Error {
     constructor(message: string);
@@ -180,14 +238,36 @@ declare class APIError extends BlockrunError {
  *
  * Provides access to multiple LLM providers (OpenAI, Anthropic, Google, etc.)
  * with automatic x402 micropayments on Base chain.
+ *
+ * Networks:
+ * - Mainnet: https://blockrun.ai/api (Base, Chain ID 8453)
+ * - Testnet: https://testnet.blockrun.ai/api (Base Sepolia, Chain ID 84532)
+ *
+ * @example Testnet usage
+ * ```ts
+ * // Use testnet convenience function
+ * import { testnetClient } from '@blockrun/llm';
+ * const client = testnetClient({ privateKey: '0x...' });
+ * const response = await client.chat('openai/gpt-oss-20b', 'Hello!');
+ *
+ * // Or configure manually
+ * const client = new LLMClient({
+ *   privateKey: '0x...',
+ *   apiUrl: 'https://testnet.blockrun.ai/api'
+ * });
+ * ```
  */
 declare class LLMClient {
+    static readonly DEFAULT_API_URL = "https://blockrun.ai/api";
+    static readonly TESTNET_API_URL = "https://testnet.blockrun.ai/api";
     private account;
     private privateKey;
     private apiUrl;
     private timeout;
     private sessionTotalUsd;
     private sessionCalls;
+    private modelPricingCache;
+    private modelPricingPromise;
     /**
      * Initialize the BlockRun LLM client.
      *
@@ -207,6 +287,46 @@ declare class LLMClient {
      * console.log(response); // 'The capital of France is Paris.'
      */
     chat(model: string, prompt: string, options?: ChatOptions): Promise<string>;
+    /**
+     * Smart chat with automatic model routing.
+     *
+     * Uses ClawRouter's 14-dimension rule-based scoring algorithm (<1ms, 100% local)
+     * to select the cheapest model that can handle your request.
+     *
+     * @param prompt - User message
+     * @param options - Optional chat and routing parameters
+     * @returns SmartChatResponse with response text, selected model, and routing metadata
+     *
+     * @example Simple usage (auto profile)
+     * ```ts
+     * const result = await client.smartChat('What is 2+2?');
+     * console.log(result.response); // '4'
+     * console.log(result.model); // 'google/gemini-2.5-flash'
+     * console.log(result.routing.savings); // 0.78 (78% savings)
+     * ```
+     *
+     * @example With routing profile
+     * ```ts
+     * // Free tier only (zero cost)
+     * const result = await client.smartChat('Hello!', { routingProfile: 'free' });
+     *
+     * // Eco mode (budget optimized)
+     * const result = await client.smartChat('Explain quantum computing', { routingProfile: 'eco' });
+     *
+     * // Premium mode (best quality)
+     * const result = await client.smartChat('Write a business plan', { routingProfile: 'premium' });
+     * ```
+     */
+    smartChat(prompt: string, options?: SmartChatOptions): Promise<SmartChatResponse>;
+    /**
+     * Get model pricing map (cached).
+     * Fetches from API on first call, then returns cached result.
+     */
+    private getModelPricing;
+    /**
+     * Fetch model pricing from API.
+     */
+    private fetchModelPricing;
     /**
      * Full chat completion interface (OpenAI-compatible).
      *
@@ -266,7 +386,38 @@ declare class LLMClient {
      * Get the wallet address being used for payments.
      */
     getWalletAddress(): string;
+    /**
+     * Check if client is configured for testnet.
+     */
+    isTestnet(): boolean;
 }
+/**
+ * Create a testnet LLM client for development and testing.
+ *
+ * This is a convenience function that creates an LLMClient configured
+ * for the BlockRun testnet (Base Sepolia).
+ *
+ * @param options - Client options (privateKey required unless BASE_CHAIN_WALLET_KEY env var is set)
+ * @returns LLMClient configured for testnet
+ *
+ * @example
+ * ```ts
+ * import { testnetClient } from '@blockrun/llm';
+ *
+ * const client = testnetClient({ privateKey: '0x...' });
+ * const response = await client.chat('openai/gpt-oss-20b', 'Hello!');
+ * ```
+ *
+ * Testnet Setup:
+ * 1. Get testnet ETH from https://www.alchemy.com/faucets/base-sepolia
+ * 2. Get testnet USDC from https://faucet.circle.com/
+ * 3. Use your wallet with testnet funds
+ *
+ * Available Testnet Models:
+ * - openai/gpt-oss-20b
+ * - openai/gpt-oss-120b
+ */
+declare function testnetClient(options?: Omit<LLMClientOptions, 'apiUrl'>): LLMClient;
 
 /**
  * BlockRun Image Client - Generate images via x402 micropayments.
@@ -485,8 +636,11 @@ interface OpenAIClientOptions {
 interface OpenAIChatCompletionParams {
     model: string;
     messages: Array<{
-        role: "system" | "user" | "assistant";
-        content: string;
+        role: "system" | "user" | "assistant" | "tool";
+        content?: string | null;
+        name?: string;
+        tool_call_id?: string;
+        tool_calls?: ToolCall[];
     }>;
     max_tokens?: number;
     temperature?: number;
@@ -497,14 +651,17 @@ interface OpenAIChatCompletionParams {
     presence_penalty?: number;
     frequency_penalty?: number;
     user?: string;
+    tools?: Tool[];
+    tool_choice?: ToolChoice;
 }
 interface OpenAIChatCompletionChoice {
     index: number;
     message: {
         role: "assistant";
-        content: string;
+        content?: string | null;
+        tool_calls?: ToolCall[];
     };
-    finish_reason: string | null;
+    finish_reason: "stop" | "length" | "content_filter" | "tool_calls" | null;
 }
 interface OpenAIChatCompletionResponse {
     id: string;
@@ -584,4 +741,4 @@ declare class OpenAI {
     getWalletAddress(): string;
 }
 
-export { APIError, BASE_CHAIN_ID, BlockrunError, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatUsage, ImageClient, type ImageClientOptions, type ImageData, type ImageGenerateOptions, type ImageModel, type ImageResponse, LLMClient, type LLMClientOptions, type Model, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PaymentError, type PaymentLinks, type RssSearchSource, type SearchParameters, type SearchSource, type Spending, USDC_BASE, USDC_BASE_CONTRACT, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XSearchSource, createWallet, LLMClient as default, formatFundingMessageCompact, formatNeedsFundingMessage, formatWalletCreatedMessage, getEip681Uri, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadWallet, saveWallet };
+export { APIError, BASE_CHAIN_ID, BlockrunError, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatUsage, type FunctionCall, type FunctionDefinition, ImageClient, type ImageClientOptions, type ImageData, type ImageGenerateOptions, type ImageModel, type ImageResponse, LLMClient, type LLMClientOptions, type Model, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PaymentError, type PaymentLinks, type RoutingDecision, type RoutingProfile, type RoutingTier, type RssSearchSource, type SearchParameters, type SearchSource, type SmartChatOptions, type SmartChatResponse, type Spending, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XSearchSource, createWallet, LLMClient as default, formatFundingMessageCompact, formatNeedsFundingMessage, formatWalletCreatedMessage, getEip681Uri, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadWallet, saveWallet, testnetClient };

package/dist/index.js

@@ -27,6 +27,9 @@ var APIError = class extends BlockrunError {
   }
 };
 
+// src/client.ts
+import { route, DEFAULT_ROUTING_CONFIG } from "@blockrun/clawrouter";
+
 // src/x402.ts
 import { signTypedData } from "viem/accounts";
 var BASE_CHAIN_ID = 8453;
@@ -223,15 +226,22 @@ function validateResourceUrl(url, baseUrl) {
 
 // src/client.ts
 var DEFAULT_API_URL = "https://blockrun.ai/api";
+var TESTNET_API_URL = "https://testnet.blockrun.ai/api";
 var DEFAULT_MAX_TOKENS = 1024;
 var DEFAULT_TIMEOUT = 6e4;
+var SDK_VERSION = "0.3.0";
+var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 var LLMClient = class {
+  static DEFAULT_API_URL = DEFAULT_API_URL;
+  static TESTNET_API_URL = TESTNET_API_URL;
   account;
   privateKey;
   apiUrl;
   timeout;
   sessionTotalUsd = 0;
   sessionCalls = 0;
+  modelPricingCache = null;
+  modelPricingPromise = null;
   /**
    * Initialize the BlockRun LLM client.
    *
@@ -278,7 +288,92 @@ var LLMClient = class {
       search: options?.search,
       searchParameters: options?.searchParameters
     });
-    return result.choices[0].message.content;
+    return result.choices[0].message.content || "";
+  }
+  /**
+   * Smart chat with automatic model routing.
+   *
+   * Uses ClawRouter's 14-dimension rule-based scoring algorithm (<1ms, 100% local)
+   * to select the cheapest model that can handle your request.
+   *
+   * @param prompt - User message
+   * @param options - Optional chat and routing parameters
+   * @returns SmartChatResponse with response text, selected model, and routing metadata
+   *
+   * @example Simple usage (auto profile)
+   * ```ts
+   * const result = await client.smartChat('What is 2+2?');
+   * console.log(result.response); // '4'
+   * console.log(result.model); // 'google/gemini-2.5-flash'
+   * console.log(result.routing.savings); // 0.78 (78% savings)
+   * ```
+   *
+   * @example With routing profile
+   * ```ts
+   * // Free tier only (zero cost)
+   * const result = await client.smartChat('Hello!', { routingProfile: 'free' });
+   *
+   * // Eco mode (budget optimized)
+   * const result = await client.smartChat('Explain quantum computing', { routingProfile: 'eco' });
+   *
+   * // Premium mode (best quality)
+   * const result = await client.smartChat('Write a business plan', { routingProfile: 'premium' });
+   * ```
+   */
+  async smartChat(prompt, options) {
+    const modelPricing = await this.getModelPricing();
+    const maxOutputTokens = options?.maxOutputTokens || options?.maxTokens || 1024;
+    const decision = route(prompt, options?.system, maxOutputTokens, {
+      config: DEFAULT_ROUTING_CONFIG,
+      modelPricing,
+      routingProfile: options?.routingProfile
+    });
+    const response = await this.chat(decision.model, prompt, {
+      system: options?.system,
+      maxTokens: options?.maxTokens,
+      temperature: options?.temperature,
+      topP: options?.topP,
+      search: options?.search,
+      searchParameters: options?.searchParameters
+    });
+    return {
+      response,
+      model: decision.model,
+      routing: decision
+    };
+  }
+  /**
+   * Get model pricing map (cached).
+   * Fetches from API on first call, then returns cached result.
+   */
+  async getModelPricing() {
+    if (this.modelPricingCache) {
+      return this.modelPricingCache;
+    }
+    if (this.modelPricingPromise) {
+      return this.modelPricingPromise;
+    }
+    this.modelPricingPromise = this.fetchModelPricing();
+    try {
+      this.modelPricingCache = await this.modelPricingPromise;
+      return this.modelPricingCache;
+    } finally {
+      this.modelPricingPromise = null;
+    }
+  }
+  /**
+   * Fetch model pricing from API.
+   */
+  async fetchModelPricing() {
+    const models = await this.listModels();
+    const pricing = /* @__PURE__ */ new Map();
+    for (const model of models) {
+      pricing.set(model.id, {
+        inputPrice: model.inputPrice,
+        outputPrice: model.outputPrice
+      });
+    }
+    return pricing;
   }
   /**
    * Full chat completion interface (OpenAI-compatible).
@@ -305,6 +400,12 @@ var LLMClient = class {
     } else if (options?.search === true) {
       body.search_parameters = { mode: "on" };
     }
+    if (options?.tools !== void 0) {
+      body.tools = options.tools;
+    }
+    if (options?.toolChoice !== void 0) {
+      body.tool_choice = options.toolChoice;
+    }
     return this.requestWithPayment("/v1/chat/completions", body);
   }
   /**
@@ -314,7 +415,7 @@ var LLMClient = class {
     const url = `${this.apiUrl}${endpoint}`;
     const response = await this.fetchWithTimeout(url, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT },
       body: JSON.stringify(body)
     });
     if (response.status === 402) {
@@ -377,6 +478,7 @@ var LLMClient = class {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
+        "User-Agent": USER_AGENT,
         "PAYMENT-SIGNATURE": paymentPayload
       },
       body: JSON.stringify(body)
@@ -505,7 +607,19 @@ var LLMClient = class {
   getWalletAddress() {
     return this.account.address;
   }
+  /**
+   * Check if client is configured for testnet.
+   */
+  isTestnet() {
+    return this.apiUrl.includes("testnet.blockrun.ai");
+  }
 };
+function testnetClient(options = {}) {
+  return new LLMClient({
+    ...options,
+    apiUrl: TESTNET_API_URL
+  });
+}
 var client_default = LLMClient;
 
 // src/image.ts
@@ -907,7 +1021,9 @@ var ChatCompletions = class {
       {
         maxTokens: params.max_tokens,
         temperature: params.temperature,
-        topP: params.top_p
+        topP: params.top_p,
+        tools: params.tools,
+        toolChoice: params.tool_choice
       }
     );
     return this.transformResponse(response);
@@ -922,6 +1038,12 @@ var ChatCompletions = class {
       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 {
@@ -958,7 +1080,8 @@ var ChatCompletions = class {
         index: choice.index ?? index,
         message: {
           role: "assistant",
-          content: choice.message.content
+          content: choice.message.content,
+          tool_calls: choice.message.tool_calls
         },
         finish_reason: choice.finish_reason || "stop"
       })),
@@ -1015,5 +1138,6 @@ export {
   getPaymentLinks,
   getWalletAddress,
   loadWallet,
-  saveWallet
+  saveWallet,
+  testnetClient
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/llm",
-  "version": "0.2.1",
+  "version": "1.0.0",
   "type": "module",
   "description": "BlockRun LLM Gateway SDK - Pay-per-request AI via x402 on Base",
   "main": "dist/index.cjs",
@@ -48,6 +48,7 @@
     "url": "https://github.com/BlockRunAI/blockrun-llm-ts/issues"
   },
   "dependencies": {
+    "@blockrun/clawrouter": "^0.9.3",
     "viem": "^2.21.0"
   },
   "optionalDependencies": {