BlockRun

BlockRun works with Claude Code and Google Antigravity.

You can't generate images. You have no real-time X/Twitter access. BlockRun gives you these capabilities.

Philosophy

You have a wallet. When you need a capability you lack, you pay for it autonomously.

You Need You Call Pricing

Image generation DALL-E $0.04/image

Real-time X data Grok + Live Search $0.025/source

Second opinion GPT-5.2 $1.75/M input, $14/M output

Cheaper processing DeepSeek $0.14/M input, $0.28/M output

How it works: BlockRun uses x402 micropayments to route your requests to OpenAI, xAI, Google, and other providers. No API keys needed - your wallet pays per token.

Budget Control (Optional)

If the user specifies a budget (e.g., "use at most $1"), track spending and stop when budget is reached:

from blockrun_llm import setup_agent_wallet

client = setup_agent_wallet() budget = 1.0 # User's budget

Before each call, check if within budget

spending = client.get_spending() if spending['total_usd'] >= budget: print(f"Budget reached: ${spending['total_usd']:.4f} spent") # Stop making calls else: response = client.chat("openai/gpt-5.2", "Hello!")

At the end, report spending

spending = client.get_spending() print(f"💰 Total spent: ${spending['total_usd']:.4f} across {spending['calls']} calls")

When to Use

Trigger Your Action

User explicitly requests ("blockrun second opinion with GPT on...", "use grok to check...", "generate image with dall-e") Execute via BlockRun

User needs something you can't do (images, live X data) Suggest BlockRun, wait for confirmation

You can handle the task fine Do it yourself, don't mention BlockRun

Example User Prompts

Users will say things like:

User Says What You Do

"blockrun generate an image of a sunset" Call DALL-E via ImageClient

"use grok to check what's trending on X" Call Grok with search=True

"blockrun GPT review this code" Call GPT-5.2 via LLMClient

"what's the latest news about AI agents?" Suggest Grok (you lack real-time data)

"generate a logo for my startup" Suggest DALL-E (you can't generate images)

"blockrun check my balance" Show wallet balance via get_balance()

"blockrun deepseek summarize this file" Call DeepSeek for cost savings

Wallet & Balance

Use setup_agent_wallet() to auto-create a wallet and get a client. This shows the QR code and welcome message on first use.

Initialize client (always start with this):

from blockrun_llm import setup_agent_wallet

client = setup_agent_wallet() # Auto-creates wallet, shows QR if new

Check balance (when user asks "show balance", "check wallet", etc.):

balance = client.get_balance() # On-chain USDC balance print(f"Balance: ${balance:.2f} USDC") print(f"Wallet: {client.get_wallet_address()}")

Show QR code for funding:

from blockrun_llm import generate_wallet_qr_ascii, get_wallet_address

ASCII QR for terminal display

print(generate_wallet_qr_ascii(get_wallet_address()))

SDK Usage

Prerequisite: Install the SDK with pip install blockrun-llm

Basic Chat

from blockrun_llm import setup_agent_wallet

client = setup_agent_wallet() # Auto-creates wallet if needed response = client.chat("openai/gpt-5.2", "What is 2+2?") print(response)

Check spending

spending = client.get_spending() print(f"Spent ${spending['total_usd']:.4f}")

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

IMPORTANT: For real-time X/Twitter data, you MUST enable Live Search with search=True or search_parameters .

from blockrun_llm import setup_agent_wallet

client = setup_agent_wallet()

Simple: Enable live search with search=True

response = client.chat( "xai/grok-3", "What are the latest posts from @blockrunai on X?", search=True # Enables real-time X/Twitter search ) print(response)

Advanced X Search with Filters

from blockrun_llm import setup_agent_wallet

client = setup_agent_wallet()

response = client.chat( "xai/grok-3", "Analyze @blockrunai's recent content and engagement", search_parameters={ "mode": "on", "sources": [ { "type": "x", "included_x_handles": ["blockrunai"], "post_favorite_count": 5 } ], "max_search_results": 20, "return_citations": True } ) print(response)

Image Generation

from blockrun_llm import ImageClient

client = ImageClient() result = client.generate("A cute cat wearing a space helmet") print(result.data[0].url)

xAI Live Search Reference

Live Search is xAI's real-time data API. Cost: $0.025 per source (default 10 sources = ~$0.26).

To reduce costs, set max_search_results to a lower value:

Only use 5 sources (~$0.13)

response = client.chat("xai/grok-3", "What's trending?", search_parameters={"mode": "on", "max_search_results": 5})

Search Parameters

Parameter Type Default Description

mode

string "auto" "off", "auto", or "on"

sources

array web,news,x Data sources to query

return_citations

bool true Include source URLs

from_date

string

Start date (YYYY-MM-DD)

to_date

string

End date (YYYY-MM-DD)

max_search_results

int 10 Max sources to return (customize to control cost)

Source Types

X/Twitter Source:

{ "type": "x", "included_x_handles": ["handle1", "handle2"], # Max 10 "excluded_x_handles": ["spam_account"], # Max 10 "post_favorite_count": 100, # Min likes threshold "post_view_count": 1000 # Min views threshold }

Web Source:

{ "type": "web", "country": "US", # ISO alpha-2 code "allowed_websites": ["example.com"], # Max 5 "safe_search": True }

News Source:

{ "type": "news", "country": "US", "excluded_websites": ["tabloid.com"] # Max 5 }

Available Models

Model Best For Pricing

openai/gpt-5.2

Second opinions, code review, general $1.75/M in, $14/M out

openai/gpt-5-mini

Cost-optimized reasoning $0.30/M in, $1.20/M out

openai/o4-mini

Latest efficient reasoning $1.10/M in, $4.40/M out

openai/o3

Advanced reasoning, complex problems $10/M in, $40/M out

xai/grok-3

Real-time X/Twitter data $3/M + $0.025/source

deepseek/deepseek-chat

Simple tasks, bulk processing $0.14/M in, $0.28/M out

google/gemini-2.5-flash

Very long documents, fast $0.15/M in, $0.60/M out

openai/dall-e-3

Photorealistic images $0.04/image

google/nano-banana

Fast, artistic images $0.01/image

M = million tokens. Actual cost depends on your prompt and response length.

Cost Reference

All LLM costs are per million tokens (M = 1,000,000 tokens).

Model Input Output

GPT-5.2 $1.75/M $14.00/M

GPT-5-mini $0.30/M $1.20/M

Grok-3 (no search) $3.00/M $15.00/M

DeepSeek $0.14/M $0.28/M

Fixed Cost Actions

Grok Live Search $0.025/source (default 10 = $0.25)

DALL-E image $0.04/image

Nano Banana image $0.01/image

Typical costs: A 500-word prompt (~750 tokens) to GPT-5.2 costs ~$0.001 input. A 1000-word response (~1500 tokens) costs ~$0.02 output.

Setup & Funding

Wallet location: $HOME/.blockrun/.session (e.g., /Users/username/.blockrun/.session )

First-time setup:

• Wallet auto-creates when setup_agent_wallet() is called

• Check wallet and balance:

from blockrun_llm import setup_agent_wallet client = setup_agent_wallet() print(f"Wallet: {client.get_wallet_address()}") print(f"Balance: ${client.get_balance():.2f} USDC")

• Fund wallet with $1-5 USDC on Base network

Show QR code for funding (ASCII for terminal):

from blockrun_llm import generate_wallet_qr_ascii, get_wallet_address print(generate_wallet_qr_ascii(get_wallet_address()))

Troubleshooting

"Grok says it has no real-time access" → You forgot to enable Live Search. Add search=True :

response = client.chat("xai/grok-3", "What's trending?", search=True)

Module not found → Install the SDK: pip install blockrun-llm

Updates

pip install --upgrade blockrun-llm