@blockrun/llm

Installation

# Base and Solana support (optional Solana deps auto-installed)
npm install @blockrun/llm
# or
pnpm add @blockrun/llm
# or
yarn add @blockrun/llm

Quick Start (Base - Default)

import { LLMClient } from '@blockrun/llm';
const client = new LLMClient(); // Uses BASE_CHAIN_WALLET_KEY (never sent to server)
const response = await client.chat('openai/gpt-4o', 'Hello!');

Quick Start (Solana)

import { LLMClient } from '@blockrun/llm';
const client = new LLMClient({ network: 'solana' }); // Uses BLOCKRUN_SOLANA_KEY
const response = await client.chat('openai/gpt-4o', 'Hello!');

How It Works

Available Models

OpenAI GPT-5 Family

OpenAI GPT-4 Family

OpenAI O-Series (Reasoning)

Anthropic Claude

Google Gemini

DeepSeek

xAI Grok

Moonshot Kimi

NVIDIA (Free & Hosted)

E2E Verified Models

Image Generation

Testnet Models (Base Sepolia)

Testnet Usage

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

Available Testnet Models

Manual Testnet Configuration

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

import { LLMClient } from '@blockrun/llm';
const client = new LLMClient(); // Uses BASE_CHAIN_WALLET_KEY (never sent to server)
const response = await client.chat('openai/gpt-4o', 'Explain quantum computing');
console.log(response);
// With system prompt
const response2 = await client.chat('anthropic/claude-sonnet-4', 'Write a haiku', {
 system: 'You are a creative poet.',
});

Smart Routing (ClawRouter)

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

Full Chat Completion

import { LLMClient, type ChatMessage } from '@blockrun/llm';
const client = new LLMClient(); // Uses BASE_CHAIN_WALLET_KEY (never sent to server)
const messages: ChatMessage[] = [
 { role: 'system', content: 'You are a helpful assistant.' },
 { role: 'user', content: 'How do I read a file in Node.js?' },
];
const result = await client.chatCompletion('openai/gpt-4o', messages);
console.log(result.choices[0].message.content);

List Available Models

import { LLMClient } from '@blockrun/llm';
const client = new LLMClient(); // Uses BASE_CHAIN_WALLET_KEY (never sent to server)
const models = await client.listModels();
for (const model of models) {
 console.log(`${model.id}: $${model.inputPrice}/M input`);
}

Multiple Requests

import { LLMClient } from '@blockrun/llm';
const client = new LLMClient(); // Uses BASE_CHAIN_WALLET_KEY (never sent to server)
const [gpt, claude, gemini] = await Promise.all([
 client.chat('openai/gpt-4o', 'What is 2+2?'),
 client.chat('anthropic/claude-sonnet-4', 'What is 3+3?'),
 client.chat('google/gemini-2.5-flash', 'What is 4+4?'),
]);

Configuration

// Default: reads BASE_CHAIN_WALLET_KEY from environment
const client = new LLMClient();
// Or pass options explicitly
const client = new LLMClient({
 privateKey: '0x...', // Your wallet key (never sent to server)
 apiUrl: 'https://blockrun.ai/api', // Optional
 timeout: 60000, // Optional (ms)
});

Environment Variables

Error Handling

import { LLMClient, APIError, PaymentError } from '@blockrun/llm';
const client = new LLMClient();
try {
 const response = await client.chat('openai/gpt-4o', 'Hello!');
} catch (error) {
 if (error instanceof PaymentError) {
 console.error('Payment failed - check USDC balance');
 } else if (error instanceof APIError) {
 console.error(`API error: ${error.message}`);
 }
}

Testing

Running Unit Tests

npm test # Run tests in watch mode
npm test run # Run tests once
npm test -- --coverage # Run with coverage report

Running Integration Tests

export BASE_CHAIN_WALLET_KEY=0x...
npm test -- test/integration # Run integration tests only

Setting Up Your Wallet

Base (EVM)

# .env
BASE_CHAIN_WALLET_KEY=0x...

Solana

# .env
BLOCKRUN_SOLANA_KEY=...your_base58_secret_key

Security

Private Key Safety

Best Practices

const address = client.getWalletAddress();
console.log(`View transactions: https://basescan.org/address/${address}`);

npm update @blockrun/llm # Get security patches

TypeScript Support

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';

Links

License