Agent Developers

Build AI agents that pay for their own intelligence.

This guide is for agent developers. The primary paths are Franklin (our autonomous agent), the SDKs, and the BlockRun MCP — all on one wallet, 78 models via x402 micropayments. Already using a framework (ElizaOS, AgentKit, GOAT, LangChain)? See Community integrations.

Fastest path: Franklin

Want an agent that already spends autonomously? Franklin is one install (npm install -g @blockrun/franklin) and runs free out of the box — fund a wallet to unlock everything.

Why BlockRun for Agents?

Traditional	With BlockRun
Manage API keys for each provider	One wallet for all models
Prepaid credits or subscriptions	Pay-per-request
Credential rotation headaches	Just fund and go
Complex billing reconciliation	On-chain transparency

Quick Start

Install the SDK for your language:

Then set up a wallet and make your first call:

Set up the wallet

from blockrun_llm import setup_agent_wallet

client = setup_agent_wallet()  # Creates ~/.blockrun/.session if none exists, prints a funding QR
print(f"Wallet address: {client.get_wallet_address()}")

Fund this address with USDC on Base network. (Solana: pip install "blockrun-llm[solana]" and setup_agent_solana_wallet().)

Use any model

# OpenAI
response = client.chat("openai/gpt-5.4", "Analyze this market data...")

# Anthropic
response = client.chat("anthropic/claude-sonnet-4.6", "Review this code...")

# DeepSeek (~20x cheaper)
response = client.chat("deepseek/deepseek-chat", "Summarize these documents...")

Framework Integrations

Framework	Status	Guide
ElizaOS	Released	Full plugin
AgentKit	Compatible	SDK integration
GOAT SDK	In Review	Planned plugin
LangChain	Available	LiteLLM adapter or custom LLM class

Architecture

┌─────────────────────────────────────────────────┐
│              Your Agent Framework               │
│         (ElizaOS, AgentKit, LangChain)          │
├─────────────────────────────────────────────────┤
│               BlockRun SDK                       │
│         (Handles x402 payments)                 │
├─────────────────────────────────────────────────┤
│               BlockRun API                       │
│         (Routes to providers)                   │
├─────────────────────────────────────────────────┤
│            AI Providers                          │
│   OpenAI • Anthropic • Google • DeepSeek • ...  │
└─────────────────────────────────────────────────┘

Common Patterns

Multi-Model Decision Making

Get multiple perspectives on important decisions:

def get_consensus(question: str) -> str:
    models = [
        "openai/gpt-5.4",
        "anthropic/claude-sonnet-4.6",
        "deepseek/deepseek-chat"
    ]

    opinions = []
    for model in models:
        response = client.chat(model, question)
        opinions.append(f"{model}: {response}")

    # Synthesize
    return client.chat(
        "openai/gpt-5.4",
        f"Synthesize these opinions:\n{chr(10).join(opinions)}"
    )

Cost-Optimized Routing

Use cheap models for routine tasks, premium for important ones:

def smart_route(task: str, importance: str) -> str:
    if importance == "high":
        model = "openai/gpt-5.4"  # $2.50/M
    elif importance == "medium":
        model = "anthropic/claude-haiku-4.5"  # $1.00/M
    else:
        model = "deepseek/deepseek-chat"  # $0.14/M

    return client.chat(model, task)

Or let the SDK's built-in router classify each request locally and pick the cheapest capable model, with a fallback chain walked on 429/5xx:

result = client.smart_chat(task)                      # routing_profile: "auto" | "eco" | "premium" | "free"
print(result.model, result.routing.tier, result.routing.savings)

# Same thing from any chat call — one string change
client.chat("blockrun/auto", task)

Spend Limits

Cap what an agent session can sign for. A quote above the ceiling is refused before payment, so nothing settles:

from blockrun_llm import LLMClient, SpendLimitError

client = LLMClient(max_cost_per_call=0.50, max_session_cost=10.00)  # or BLOCKRUN_MAX_* env vars

try:
    response = client.chat("openai/o1", expensive_prompt)
except SpendLimitError:
    # Fallback to cheaper model
    response = client.chat("deepseek/deepseek-chat", expensive_prompt)

Async Operations

For high-throughput agents:

import asyncio
from blockrun_llm import AsyncLLMClient

async def process_batch(items: list) -> list:
    async with AsyncLLMClient() as client:
        tasks = [
            client.chat("deepseek/deepseek-chat", f"Process: {item}")
            for item in items
        ]
        return await asyncio.gather(*tasks)

results = asyncio.run(process_batch(my_items))

Available Models

Speed-Optimized

google/gemini-3-flash-preview — Fastest with thinking mode
google/gemini-3.1-flash-lite — Ultra-fast and cheapest
anthropic/claude-haiku-4.5 — Fast, good quality

Cost-Optimized

google/gemini-2.5-flash-lite — Best value ($0.10/$0.40 per 1M)
deepseek/deepseek-chat — Great value ($0.14/$0.28 per 1M)
nvidia/nemotron-3.5-lightning — Free (open-weight)

Quality-Optimized

openai/gpt-5.4 — Best all-around
anthropic/claude-opus-5 — Best for nuanced tasks

Reasoning

openai/o3 — Advanced reasoning
openai/o1 — Complex logic
deepseek/deepseek-reasoner — Cheaper reasoning

Full list: Models Reference

Pricing

Pay only for what you use, at the per-token price in the live catalog (client.list_models() or GET https://blockrun.ai/api/v1/models).

Example costs per 1M tokens:

Model	Input	Output
`deepseek/deepseek-chat`	$0.14	$0.28
`openai/gpt-5.4`	$2.50	$15.00
`anthropic/claude-opus-5`	$5.00	$25.00

Full pricing: Intelligence Pricing

Wallet Management

Environment Variable

export BLOCKRUN_WALLET_KEY=0x...

Programmatic

from blockrun_llm import LLMClient, setup_agent_wallet

# Create new (or load the existing ~/.blockrun/.session)
client = setup_agent_wallet()

# Use existing key
client = LLMClient(private_key="0x...")   # LLMClient() alone raises ValueError if no wallet is configured

# Check balance
balance = client.get_balance()
print(f"${balance} USDC")

# Get address to fund
print(client.get_wallet_address())

Security

Private key stored locally (~/.blockrun/.session, mode 0600; Solana: ~/.blockrun/.solana-session)
Only signatures sent to API
All payments verifiable on Basescan
A failed paid request is never retried with a second payment — the SDK refuses to advance its fallback chain once a signature has gone out

Never commit BLOCKRUN_WALLET_KEY to git or share your private key. Use a dedicated agent wallet funded with only what the session needs.

Error Handling

from blockrun_llm import (
    LLMClient,
    PaymentError,
    SpendLimitError,
    APIError,
)

try:
    response = client.chat(model, prompt)
except SpendLimitError:
    print("Over the agent's spend limit — nothing was charged")
except PaymentError:
    print("Need to fund wallet")
except APIError as e:
    if e.status_code == 429:
        print("Too many requests, backing off")
    else:
        print(f"API error {e.status_code}: {e}")   # e.g. unknown model id

Best Practices

Start with cheap models — Test with DeepSeek before using GPT-4o
Set session budgets — Prevent runaway spending
Use async for batch operations — Better throughput
Monitor balance — Set up alerts when low
Log model usage — Track costs per task type

What's next?

ElizaOS Integration

Drop the BlockRun plugin into an ElizaOS agent.

SDK reference

Full Python, TypeScript, and Go SDK APIs, config, and error handling.

Set up your wallet

Fund on Base or Solana, manage budgets, and understand settlement.