BlockRun LLM SDK

Supported Chains

Installation

pip install blockrun-llm

Quick Start

from blockrun_llm import LLMClient
client = LLMClient() # Uses BLOCKRUN_WALLET_KEY (never sent to server)
response = client.chat("openai/gpt-5.2", "Hello!")

Smart Routing (ClawRouter)

from blockrun_llm import LLMClient
client = LLMClient()
# Auto-routes to cheapest capable model
result = client.smart_chat("What is 2+2?")
print(result.response) # '4'
print(result.model) # 'nvidia/kimi-k2.5' (cheap, fast)
print(f"Saved {result.routing.savings * 100:.0f}%") # 'Saved 94%'
# Complex reasoning task -> routes to reasoning model
result = client.smart_chat("Prove the Riemann hypothesis step by step")
print(result.model) # 'xai/grok-4-1-fast-reasoning'

Routing Profiles

# Use premium models for complex tasks
result = client.smart_chat(
 "Write production-grade async Python code",
 routing_profile="premium"
)
print(result.model) # 'anthropic/claude-opus-4.5'

How It Works

How It Works

Available Models

OpenAI GPT-5 Family

OpenAI GPT-4 Family

OpenAI O-Series (Reasoning)

Testnet Models (Base Sepolia)

Anthropic Claude

Google Gemini

DeepSeek

xAI Grok

Moonshot Kimi

NVIDIA (Free & Hosted)

E2E Verified Models

Image Generation

Usage Examples

Simple Chat

from blockrun_llm import LLMClient
client = LLMClient() # Uses BLOCKRUN_WALLET_KEY (never sent to server)
response = client.chat("openai/gpt-5.2", "Explain quantum computing")
print(response)
# With system prompt
response = client.chat(
 "anthropic/claude-sonnet-4",
 "Write a haiku",
 system="You are a creative poet."
)

Real-time X/Twitter Search (xAI Live Search)

from blockrun_llm import LLMClient
client = LLMClient()
# Simple: Enable live search with search=True (default 10 sources, ~0ドル.26)
response = client.chat(
 "xai/grok-3",
 "What are the latest posts from @blockrunai?",
 search=True
)
print(response)
# Custom: Limit sources to reduce cost (5 sources, ~0ドル.13)
response = client.chat(
 "xai/grok-3",
 "What's trending on X?",
 search_parameters={"mode": "on", "max_search_results": 5}
)
# Custom timeout (if 5 min isn't enough)
client = LLMClient(search_timeout=600.0) # 10 minutes

Check Spending

from blockrun_llm import LLMClient
client = LLMClient()
response = client.chat("openai/gpt-5.2", "Explain quantum computing")
print(response)
# Check how much was spent
spending = client.get_spending()
print(f"Spent ${spending['total_usd']:.4f} across {spending['calls']} calls")

Full Chat Completion

from blockrun_llm import LLMClient
client = LLMClient() # Uses BLOCKRUN_WALLET_KEY (never sent to server)
messages = [
 {"role": "system", "content": "You are a helpful assistant."},
 {"role": "user", "content": "How do I read a file in Python?"}
]
result = client.chat_completion("openai/gpt-5.2", messages)
print(result.choices[0].message.content)

Async Usage

import asyncio
from blockrun_llm import AsyncLLMClient
async def main():
 async with AsyncLLMClient() as client:
 # Simple chat
 response = await client.chat("openai/gpt-5.2", "Hello!")
 print(response)
 # Multiple requests concurrently
 tasks = [
 client.chat("openai/gpt-5.2", "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?"),
 ]
 responses = await asyncio.gather(*tasks)
 for r in responses:
 print(r)
asyncio.run(main())

List Available Models

from blockrun_llm import LLMClient
client = LLMClient()
models = client.list_models()
for model in models:
 print(f"{model['id']}: ${model['inputPrice']}/M input, ${model['outputPrice']}/M output")

Testnet Usage

from blockrun_llm import testnet_client
# Create testnet client (uses Base Sepolia)
client = testnet_client() # Uses BLOCKRUN_WALLET_KEY
# Chat with testnet model
response = client.chat("openai/gpt-oss-20b", "Hello!")
print(response)
# Check testnet USDC balance
balance = client.get_balance()
print(f"Testnet USDC: ${balance:.4f}")

Testnet Setup

Available Testnet Models

Manual Testnet Configuration

from blockrun_llm import LLMClient
# Or configure manually
client = LLMClient(api_url="https://testnet.blockrun.ai/api")
response = client.chat("openai/gpt-oss-20b", "Hello!")

XRPL Chain (RLUSD Payments)

from blockrun_llm import xrpl_client
# Create XRPL client (pays with RLUSD)
client = xrpl_client() # Uses BLOCKRUN_WALLET_KEY
# Chat with any model
response = client.chat("openai/gpt-4o", "Hello!")
print(response)
# Check RLUSD balance
balance = client.get_balance()
print(f"RLUSD: ${balance:.4f}")

Async XRPL Usage

import asyncio
from blockrun_llm import async_xrpl_client
async def main():
 async with async_xrpl_client() as client:
 response = await client.chat("openai/gpt-4o", "Hello!")
 print(response)
asyncio.run(main())

Manual XRPL Configuration

from blockrun_llm import LLMClient
# Or configure manually
client = LLMClient(api_url="https://xrpl.blockrun.ai/api")
response = client.chat("openai/gpt-4o", "Hello!")

Environment Variables

Setting Up Your Wallet

# .env file
BLOCKRUN_WALLET_KEY=0x...your_private_key_here

Error Handling

from blockrun_llm import LLMClient, APIError, PaymentError
client = LLMClient()
try:
 response = client.chat("openai/gpt-5.2", "Hello!")
except PaymentError as e:
 print(f"Payment failed: {e}")
 # Check your USDC balance
except APIError as e:
 print(f"API error ({e.status_code}): {e}")

Testing

Running Unit Tests

pytest tests/unit # Run unit tests only
pytest tests/unit --cov # Run with coverage report
pytest tests/unit -v # Verbose output

Running Integration Tests

export BLOCKRUN_WALLET_KEY=0x...
pytest tests/integration # Run integration tests only
pytest # Run all tests

Security

Private Key Safety

Best Practices

address = client.get_wallet_address()
print(f"View transactions: https://basescan.org/address/{address}")

pip install --upgrade blockrun-llm # Get security patches

Links

License