TypeScript SDK

npm install @blockrun/llm @solana/web3.js @solana/spl-token

import { LLMClient } from '@blockrun/llm';

const client = new LLMClient({
  privateKey: process.env.BASE_CHAIN_WALLET_KEY as `0x${string}`
});

// Recommended: let the bundled router pick the cheapest capable model
const routed = await client.smartChat('Hello!');
console.log(routed.response, routed.model);

// Or pin a model yourself
const response = await client.chat('openai/gpt-5.5', 'Hello!');
console.log(response);

import { LLMClient } from '@blockrun/llm';

const client = new LLMClient({
  privateKey: '0x...',               // Optional if BASE_CHAIN_WALLET_KEY is set
  apiUrl: 'https://blockrun.ai/api', // Optional: API endpoint
  timeout: 600000                    // Optional: timeout in ms (default 600s)
});

import { setupAgentWallet } from '@blockrun/llm';

// Resolves BLOCKRUN_WALLET_KEY / BASE_CHAIN_WALLET_KEY → ~/.blockrun/.session,
// creates and saves a new key if none exists, and returns a ready LLMClient.
const client = setupAgentWallet();
console.log(client.getWalletAddress());   // fund this address with USDC on Base

const response = await client.chat('openai/gpt-5.5', 'Explain quantum computing', {
  system: 'You are a physics teacher.',  // Optional
  maxTokens: 500,                         // Optional (default 1024)
  temperature: 0.7,                       // Optional
  topP: 0.9,                              // Optional
  responseFormat: { type: 'json_object' }, // Optional: JSON mode
  stop: ['\n\n'],                         // Optional: up to 4 stop sequences
  fallbackModels: ['openai/gpt-5.4'],     // Optional: tried on timeout / 429 / 5xx
  search: true,                           // Optional: Live Search (search-enabled models)
});

import { LLMClient, type ChatMessage } from '@blockrun/llm';

const messages: ChatMessage[] = [
  { role: 'system', content: 'You are helpful.' },
  { role: 'user', content: 'What is 2+2?' }
];

const result = await client.chatCompletion('openai/gpt-5.5', messages, {
  maxTokens: 100,
  temperature: 0.7,
  topP: 0.9,
  // tools, toolChoice, responseFormat, stop, search, fallbackModels also accepted
});

console.log(result.choices[0].message.content);
console.log(`Tokens used: ${result.usage?.total_tokens}`);

const models = await client.listModels();
for (const model of models) {
  console.log(`${model.id}: $${model.inputPrice}/M`);
}

const address = client.getWalletAddress();
console.log(`Paying from: ${address}`);

const balance = await client.getBalance();          // USDC on Base
const spent = client.getSpending();                 // this session: { totalUsd, calls, ... }

const { url } = await client.onramp(client.getWalletAddress());

import { LLMClient } from '@blockrun/llm';

const client = new LLMClient({
  privateKey: process.env.BASE_CHAIN_WALLET_KEY as `0x${string}`
});

// Let the router pick the best model automatically
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(result.routing.savings);    // 0.88 (84% savings vs the premium baseline)

// 1. smartChat() — one-line routed chat
const result = await client.smartChat('What is 2+2?');

// 2. smartChatCompletion() — full agent/tool conversations, routed;
//    the decision is attached as response.routing
const agent = await client.smartChatCompletion(messages, { tools, toolChoice: 'auto' });

// 3. blockrun/auto | blockrun/eco | blockrun/premium — model aliases accepted by
//    chat(), chatCompletion() and chatCompletionStream() on Base and Solana
const reply = await client.chatCompletion('blockrun/auto', messages);

// Inspect a decision without making (or paying for) a model call
const decision = await client.route('Prove the Riemann hypothesis');

// Guaranteed $0: call a free model directly
const free = await client.chat('nvidia/nemotron-3.5-lightning', 'Explain recursion');

// Smart-routed $0-first
const result = await client.smartChat('What is 2+2?', {
  routingProfile: 'eco'
});
console.log(result.model);  // "nvidia/nemotron-3.5-lightning" (a live $0 model; the free lineup rotates as NVIDIA retires SKUs)
console.log(result.routing.savings);  // 1 (100%)

// Premium mode for critical tasks
const result3 = await client.smartChat('Review this contract for legal issues...', {
  routingProfile: 'premium'
});
console.log(result3.model);  // "anthropic/claude-opus-4.7"

const result = await client.smartChat('Prove that √2 is irrational');

// Access full routing decision
const { routing } = result;
console.log(`Model: ${routing.model}`);             // the selected model id
console.log(`Tier: ${routing.tier}`);               // "REASONING"
console.log(`Method: ${routing.method}`);           // "portfolio"
console.log(`Task: ${routing.taskType}`);           // "reasoning_math"
console.log(`Candidates: ${routing.candidates}`);   // ranked, capability-eligible models
console.log(`Fallbacks: ${routing.fallbacks}`);     // the chain walked on transient errors
console.log(`Confidence: ${routing.confidence}`);   // 0–1
console.log(`Reasoning: ${routing.reasoning}`);     // "Detected: math proof..."
console.log(`Cost: $${routing.costEstimate.toFixed(4)}`);
console.log(`Baseline: $${routing.baselineCost.toFixed(4)}`);
console.log(`Savings: ${(routing.savings * 100).toFixed(0)}%`);
console.log(`Router: ${routing.routerVersion}`);    // "v3-portfolio"

import type {
  RoutingProfile,              // "eco" | "auto" | "premium"
  RoutingTier,                 // "SIMPLE" | "MEDIUM" | "COMPLEX" | "REASONING"
  RoutingTaskType,             // "chat" | "code_edit" | "tool_agent" | "reasoning" | ...
  RoutingTierConfig,           // primary + fallbacks for one tier
  RoutingDecision,             // Full routing details
  SmartChatOptions,            // ChatOptions + routingProfile + maxOutputTokens
  SmartChatResponse,           // Response + model + routing
  SmartChatCompletionOptions,  // ChatCompletionOptions + routingProfile + maxOutputTokens
  SmartChatCompletionResponse, // Full ChatResponse + routing
} from '@blockrun/llm';

const result = await client.smartChat('Write a haiku about coding', {
  system: 'You are a poet.',
  routingProfile: 'auto'
});

import { SolanaLLMClient, solanaClient } from '@blockrun/llm';

// SOLANA_WALLET_KEY env var — bs58, CLI JSON array, or hex
const client = new SolanaLLMClient();

// Or pass the key and RPC explicitly
const client2 = new SolanaLLMClient({
  privateKey: 'your-bs58-solana-key',
  apiUrl: 'https://sol.blockrun.ai/api',        // default
  rpcUrl: 'https://your-helius-or-tatum-rpc',   // default: BlockRun's own free proxy
  rpcHeaders: { 'x-api-key': '...' },           // optional header-auth
});

const response = await client.chat('openai/gpt-4o', 'gm Solana');
const routed = await client.smartChat('What is 2+2?');   // routing parity with Base
const address = await client.getWalletAddress();          // async on Solana

import { LLMClient, type ChatMessage } from '@blockrun/llm';

const client = new LLMClient();
const messages: ChatMessage[] = [{ role: 'user', content: 'Explain quantum computing simply' }];

const response = await client.chatCompletionStream('google/gemini-2.5-flash', messages);

const reader = response.body!.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  for (const line of decoder.decode(value, { stream: true }).split('\n')) {
    if (!line.startsWith('data: ') || line === 'data: [DONE]') continue;
    const data = JSON.parse(line.slice(6));
    process.stdout.write(data.choices?.[0]?.delta?.content ?? '');
  }
}

import {
  ImageClient, VideoClient, MusicClient, SpeechClient, VoiceClient,
  PhoneClient, PortraitClient, SearchClient, PriceClient, SurfClient, RpcClient,
} from '@blockrun/llm';

// Image — generate + edit/fuse
const img = new ImageClient();
const out = await img.generate('A sunset over mountains', { model: 'google/nano-banana', size: '1024x1024' });
const fused = await img.edit('Place the logo on the shirt', [subjectDataUri, logoDataUri]);  // default model openai/gpt-image-2

// Video — async submit→poll handled internally
const vid = new VideoClient();
const clip = await vid.generate('a red apple spinning', { model: 'bytedance/seedance-2.0', durationSeconds: 5, resolution: '720p' });

// Speech + sound effects
const tts = new SpeechClient();
const audio = await tts.generate('Hello!', { voice: 'sarah', responseFormat: 'mp3' });
const sfx = await tts.soundEffect('rain on a tin roof', { durationSeconds: 5 });

// Search, prices, crypto data, RPC
const search = new SearchClient();
const news   = await search.search('agent payments', { sources: ['web', 'news'], maxResults: 10 });
const px     = new PriceClient();
const btc    = await px.price('crypto', 'BTC-USD');
const rpc    = new RpcClient();
const block  = await rpc.call('ethereum', 'eth_blockNumber');   // $0.003/call

import { BlockrunClient } from '@blockrun/llm';

const br = new BlockrunClient();   // BLOCKRUN_WALLET_KEY or BASE_CHAIN_WALLET_KEY

// get<T>(path, params?) — synchronous GET (price, ranking, list, news)
const btc = await br.get('/v1/crypto/price', { symbol: 'BTC' });

// post<T>(path, body?) — synchronous POST (on-chain SQL, search)
const rows = await br.get('/v1/defillama/protocols', {});

// poll<T>(path, body?, { budgetMs, intervalMs }) — submit + poll (image, video, music, voice)
const video = await br.poll('/v1/videos/generations', { model: 'xai/grok-imagine-video', prompt: 'a red apple spinning' });

// stream<T>(path, body?) — async iterator over SSE chunks (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 ?? '');
}

import { LLMClient } from '@blockrun/llm';

const client = new LLMClient();

// List Polymarket markets
const markets = await client.pm("polymarket/markets");

// List Polymarket events
const events = await client.pm("polymarket/events");

// Get Polymarket trades
const trades = await client.pm("polymarket/trades");

// Get candlestick data for a specific condition
const candles = await client.pm("polymarket/candlesticks/0xabc123...");

// Get wallet profile
const wallet = await client.pm("polymarket/wallet/0x1234...");

// Get wallet P&L
const pnl = await client.pm("polymarket/wallet/pnl/0x1234...");

// Get Polymarket leaderboard
const leaders = await client.pm("polymarket/leaderboard");

// List Kalshi markets
const kalshiMarkets = await client.pm("kalshi/markets");

// Get Kalshi trades
const kalshiTrades = await client.pm("kalshi/trades");

// Get Binance candles for a symbol
const btcCandles = await client.pm("binance/candles/BTCUSDT");
const ethCandles = await client.pm("binance/candles/ETHUSDT");

// Cross-venue search (matching-markets was sunset by Predexon 2026-07-20)
const results = await client.pm("markets/search", { q: "Fed rate" });

// Bulk wallet identity lookup ($0.0085)
const batch = await client.pmQuery("polymarket/wallet/identities", {
  addresses: ["0xabc...", "0xdef...", "0x123..."],  // up to 200
});

// Polymarket keyset pagination (Tier 1)
const page      = await client.pmPolymarketMarketsKeyset({ limit: "100" });
const nextPage  = await client.pmPolymarketEventsKeyset({
  pagination_key: (page.pagination as Record<string, string>).next_key,
});

// Wallet identity & on-chain clustering (Tier 2)
const ident   = await client.pmWalletIdentity("0xabc...");
const batch   = await client.pmWalletIdentities(["0xabc...", "0xdef..."]);  // up to 200
const cluster = await client.pmWalletCluster("0xabc...");

// Sports (currently upstream 500 — see note above)
const cats    = await client.pmSportsCategories();
const games   = await client.pmSportsMarkets({ category: "nba" });

// Retired: pmMarkets(), pmListings(), pmOutcome() throw RetiredEndpointError.
// Use pm("markets/search", { q }) instead.

import { SolanaLLMClient } from '@blockrun/llm';

const client = new SolanaLLMClient();
const markets = await client.pm("polymarket/markets");

import { LLMClient } from '@blockrun/llm';

const client = new LLMClient({
  privateKey: process.env.BASE_CHAIN_WALLET_KEY as `0x${string}`,
  apiUrl: 'https://testnet.blockrun.ai/api'
});

// Chat with a testnet model
const response = await client.chat('openai/gpt-oss-20b', 'Hello!');
console.log(response);

import { LLMClient, APIError, PaymentError, RetiredEndpointError, BlockrunError } from '@blockrun/llm';

const client = new LLMClient({ privateKey: '0x...' });

try {
  const response = await client.chat('openai/gpt-5.5', 'Hello!');
} catch (error) {
  if (error instanceof PaymentError) {
    console.error('Payment failed:', error.message);
    // Check your USDC balance (Base for LLMClient, Solana for SolanaLLMClient)
  } else if (error instanceof RetiredEndpointError) {
    console.error('Endpoint retired upstream:', error.message);
  } else if (error instanceof APIError) {
    console.error(`API error (${error.statusCode}):`, error.message);
    // error.response holds the parsed body when there is one
  } else if (error instanceof BlockrunError) {
    console.error('SDK error:', error.message);
  } else {
    throw error;
  }
}

interface ChatMessage {
  role: 'system' | 'user' | 'assistant' | 'tool';
  content?: string | null;
  name?: string;              // tool messages
  tool_call_id?: string;      // tool result messages
  tool_calls?: ToolCall[];    // assistant messages that call tools
  reasoning_content?: string; // returned by reasoning-capable models
}

interface ChatResponse {
  id: string;
  object: string;
  created: number;
  model: string;
  choices: ChatChoice[];
  usage?: ChatUsage;
}

interface ChatChoice {
  index: number;
  message: ChatMessage;
  finish_reason?: string;
}

interface ChatUsage {
  prompt_tokens: number;
  completion_tokens: number;
  total_tokens: number;
}

interface Model {
  id: string;
  name: string;
  description: string;
  provider: string;
  inputPrice: number;       // per 1M tokens; 0 when billingMode !== "paid"
  outputPrice: number;
  contextWindow: number;    // mapped from API's context_window
  maxOutput: number;        // mapped from API's max_output
  categories: string[];     // e.g., ["chat", "reasoning", "coding", "vision"]
  available: boolean;
  billingMode?: string;     // "paid" | "free" | "flat"
  flatPrice?: number;       // per-request price for flat-billed models
  hidden?: boolean;
}

import { LLMClient } from '@blockrun/llm';

const client = new LLMClient({ privateKey: '0x...' });

const [gpt, claude, gemini] = await Promise.all([
  client.chat('openai/gpt-5.5', 'What is 2+2?'),
  client.chat('anthropic/claude-sonnet-4.6', 'What is 3+3?'),
  client.chat('google/gemini-3-flash-preview', 'What is 4+4?')
]);

console.log('GPT:', gpt);
console.log('Claude:', claude);
console.log('Gemini:', gemini);

import express from 'express';
import { LLMClient } from '@blockrun/llm';

const app = express();
const client = new LLMClient({ privateKey: process.env.BASE_CHAIN_WALLET_KEY });

app.post('/chat', async (req, res) => {
  try {
    const { message } = req.body;
    const response = await client.chat('openai/gpt-5.5', message);
    res.json({ response });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

// app/api/chat/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { LLMClient } from '@blockrun/llm';

const client = new LLMClient({
  privateKey: process.env.BASE_CHAIN_WALLET_KEY as `0x${string}`
});

export async function POST(request: NextRequest) {
  const { message } = await request.json();
  const response = await client.chat('openai/gpt-5.5', message);
  return NextResponse.json({ response });
}

import { getCostSummary } from '@blockrun/llm';

// Every paid call is appended to ~/.blockrun/cost_log.jsonl
const summary = getCostSummary();
console.log(`Lifetime: $${summary.totalUsd.toFixed(2)} over ${summary.calls} calls`);
console.log(summary.byModel);

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

# Set your funded wallet key
export BASE_CHAIN_WALLET_KEY=0x...

# Run only integration tests
npm test -- test/integration

# Run all tests including integration
npm test run

# .env (add to .gitignore!)
BASE_CHAIN_WALLET_KEY=0x...your_private_key_here

// app.ts
import { LLMClient } from '@blockrun/llm';
import dotenv from 'dotenv';

dotenv.config();

if (!process.env.BASE_CHAIN_WALLET_KEY) {
  throw new Error('BASE_CHAIN_WALLET_KEY not set');
}

const client = new LLMClient({
  privateKey: process.env.BASE_CHAIN_WALLET_KEY as `0x${string}`
});

try {
  await client.chat('invalid-model', 'Hello');
} catch (error) {
  // Error messages only contain safe, user-facing information
  // No internal stack traces, file paths, or sensitive data
  console.error(error.message);
}

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

npm update @blockrun/llm