BlockRun

1---
2name: blockrun
3description: Use when user needs capabilities Claude lacks (image generation, real-time X/Twitter data) or explicitly requests external models ("blockrun", "use grok", "use gpt", "dall-e", "deepseek")
4allowed-tools: Read, Bash(python:*), Bash(python3:*), Bash(pip:*), Bash(source:*)
5---
6 
7# BlockRun
8 
9**BlockRun works with Claude Code and Google Antigravity.**
10 
11You can't generate images. You have no real-time X/Twitter access. BlockRun gives you these capabilities.
12 
13## Philosophy
14 
15You have a wallet. When you need a capability you lack, you pay for it autonomously.
16 
17| You Need | You Call | Pricing |
18|----------|----------|---------|
19| Image generation | DALL-E | $0.04/image |
20| Real-time X data | Grok + Live Search | $0.025/source |
21| Second opinion | GPT-5.2 | $1.75/M input, $14/M output |
22| Cheaper processing | DeepSeek | $0.14/M input, $0.28/M output |
23 
24**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.
25 
26## Budget Control (Optional)
27 
28If the user specifies a budget (e.g., "use at most $1"), track spending and stop when budget is reached:
29 
30```python
31from blockrun_llm import setup_agent_wallet
32 
33client = setup_agent_wallet()
34budget = 1.0  # User's budget
35 
36# Before each call, check if within budget
37spending = client.get_spending()
38if spending['total_usd'] >= budget:
39    print(f"Budget reached: ${spending['total_usd']:.4f} spent")
40    # Stop making calls
41else:
42    response = client.chat("openai/gpt-5.2", "Hello!")
43 
44# At the end, report spending
45spending = client.get_spending()
46print(f"💰 Total spent: ${spending['total_usd']:.4f} across {spending['calls']} calls")
47```
48 
49## When to Use
50 
51| Trigger | Your Action |
52|---------|-------------|
53| User explicitly requests ("blockrun second opinion with GPT on...", "use grok to check...", "generate image with dall-e") | Execute via BlockRun |
54| User needs something you can't do (images, live X data) | Suggest BlockRun, wait for confirmation |
55| You can handle the task fine | Do it yourself, don't mention BlockRun |
56 
57## Example User Prompts
58 
59Users will say things like:
60 
61| User Says | What You Do |
62|-----------|-------------|
63| "blockrun generate an image of a sunset" | Call DALL-E via ImageClient |
64| "use grok to check what's trending on X" | Call Grok with `search=True` |
65| "blockrun GPT review this code" | Call GPT-5.2 via LLMClient |
66| "what's the latest news about AI agents?" | Suggest Grok (you lack real-time data) |
67| "generate a logo for my startup" | Suggest DALL-E (you can't generate images) |
68| "blockrun check my balance" | Show wallet balance via `get_balance()` |
69| "blockrun deepseek summarize this file" | Call DeepSeek for cost savings |
70 
71## Wallet & Balance
72 
73Use `setup_agent_wallet()` to auto-create a wallet and get a client. This shows the QR code and welcome message on first use.
74 
75**Initialize client (always start with this):**
76```python
77from blockrun_llm import setup_agent_wallet
78 
79client = setup_agent_wallet()  # Auto-creates wallet, shows QR if new
80```
81 
82**Check balance (when user asks "show balance", "check wallet", etc.):**
83```python
84balance = client.get_balance()  # On-chain USDC balance
85print(f"Balance: ${balance:.2f} USDC")
86print(f"Wallet: {client.get_wallet_address()}")
87```
88 
89**Show QR code for funding:**
90```python
91from blockrun_llm import generate_wallet_qr_ascii, get_wallet_address
92 
93# ASCII QR for terminal display
94print(generate_wallet_qr_ascii(get_wallet_address()))
95```
96 
97## SDK Usage
98 
99**Prerequisite:** Install the SDK with `pip install blockrun-llm`
100 
101### Basic Chat
102```python
103from blockrun_llm import setup_agent_wallet
104 
105client = setup_agent_wallet()  # Auto-creates wallet if needed
106response = client.chat("openai/gpt-5.2", "What is 2+2?")
107print(response)
108 
109# Check spending
110spending = client.get_spending()
111print(f"Spent ${spending['total_usd']:.4f}")
112```
113 
114### Real-time X/Twitter Search (xAI Live Search)
115 
116**IMPORTANT:** For real-time X/Twitter data, you MUST enable Live Search with `search=True` or `search_parameters`.
117 
118```python
119from blockrun_llm import setup_agent_wallet
120 
121client = setup_agent_wallet()
122 
123# Simple: Enable live search with search=True
124response = client.chat(
125    "xai/grok-3",
126    "What are the latest posts from @blockrunai on X?",
127    search=True  # Enables real-time X/Twitter search
128)
129print(response)
130```
131 
132### Advanced X Search with Filters
133 
134```python
135from blockrun_llm import setup_agent_wallet
136 
137client = setup_agent_wallet()
138 
139response = client.chat(
140    "xai/grok-3",
141    "Analyze @blockrunai's recent content and engagement",
142    search_parameters={
143        "mode": "on",
144        "sources": [
145            {
146                "type": "x",
147                "included_x_handles": ["blockrunai"],
148                "post_favorite_count": 5
149            }
150        ],
151        "max_search_results": 20,
152        "return_citations": True
153    }
154)
155print(response)
156```
157 
158### Image Generation
159```python
160from blockrun_llm import ImageClient
161 
162client = ImageClient()
163result = client.generate("A cute cat wearing a space helmet")
164print(result.data[0].url)
165```
166 
167## xAI Live Search Reference
168 
169Live Search is xAI's real-time data API. Cost: **$0.025 per source** (default 10 sources = ~$0.26).
170 
171To reduce costs, set `max_search_results` to a lower value:
172```python
173# Only use 5 sources (~$0.13)
174response = client.chat("xai/grok-3", "What's trending?",
175    search_parameters={"mode": "on", "max_search_results": 5})
176```
177 
178### Search Parameters
179 
180| Parameter | Type | Default | Description |
181|-----------|------|---------|-------------|
182| `mode` | string | "auto" | "off", "auto", or "on" |
183| `sources` | array | web,news,x | Data sources to query |
184| `return_citations` | bool | true | Include source URLs |
185| `from_date` | string | - | Start date (YYYY-MM-DD) |
186| `to_date` | string | - | End date (YYYY-MM-DD) |
187| `max_search_results` | int | 10 | Max sources to return (customize to control cost) |
188 
189### Source Types
190 
191**X/Twitter Source:**
192```python
193{
194    "type": "x",
195    "included_x_handles": ["handle1", "handle2"],  # Max 10
196    "excluded_x_handles": ["spam_account"],        # Max 10
197    "post_favorite_count": 100,  # Min likes threshold
198    "post_view_count": 1000      # Min views threshold
199}
200```
201 
202**Web Source:**
203```python
204{
205    "type": "web",
206    "country": "US",  # ISO alpha-2 code
207    "allowed_websites": ["example.com"],  # Max 5
208    "safe_search": True
209}
210```
211 
212**News Source:**
213```python
214{
215    "type": "news",
216    "country": "US",
217    "excluded_websites": ["tabloid.com"]  # Max 5
218}
219```
220 
221## Available Models
222 
223| Model | Best For | Pricing |
224|-------|----------|---------|
225| `openai/gpt-5.2` | Second opinions, code review, general | $1.75/M in, $14/M out |
226| `openai/gpt-5-mini` | Cost-optimized reasoning | $0.30/M in, $1.20/M out |
227| `openai/o4-mini` | Latest efficient reasoning | $1.10/M in, $4.40/M out |
228| `openai/o3` | Advanced reasoning, complex problems | $10/M in, $40/M out |
229| `xai/grok-3` | Real-time X/Twitter data | $3/M + $0.025/source |
230| `deepseek/deepseek-chat` | Simple tasks, bulk processing | $0.14/M in, $0.28/M out |
231| `google/gemini-2.5-flash` | Very long documents, fast | $0.15/M in, $0.60/M out |
232| `openai/dall-e-3` | Photorealistic images | $0.04/image |
233| `google/nano-banana` | Fast, artistic images | $0.01/image |
234 
235*M = million tokens. Actual cost depends on your prompt and response length.*
236 
237## Cost Reference
238 
239All LLM costs are per million tokens (M = 1,000,000 tokens).
240 
241| Model | Input | Output |
242|-------|-------|--------|
243| GPT-5.2 | $1.75/M | $14.00/M |
244| GPT-5-mini | $0.30/M | $1.20/M |
245| Grok-3 (no search) | $3.00/M | $15.00/M |
246| DeepSeek | $0.14/M | $0.28/M |
247 
248| Fixed Cost Actions | |
249|-------|--------|
250| Grok Live Search | $0.025/source (default 10 = $0.25) |
251| DALL-E image | $0.04/image |
252| Nano Banana image | $0.01/image |
253 
254**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.
255 
256## Setup & Funding
257 
258**Wallet location:** `$HOME/.blockrun/.session` (e.g., `/Users/username/.blockrun/.session`)
259 
260**First-time setup:**
2611. Wallet auto-creates when `setup_agent_wallet()` is called
2622. Check wallet and balance:
263```python
264from blockrun_llm import setup_agent_wallet
265client = setup_agent_wallet()
266print(f"Wallet: {client.get_wallet_address()}")
267print(f"Balance: ${client.get_balance():.2f} USDC")
268```
2693. Fund wallet with $1-5 USDC on Base network
270 
271**Show QR code for funding (ASCII for terminal):**
272```python
273from blockrun_llm import generate_wallet_qr_ascii, get_wallet_address
274print(generate_wallet_qr_ascii(get_wallet_address()))
275```
276 
277## Troubleshooting
278 
279**"Grok says it has no real-time access"**
280→ You forgot to enable Live Search. Add `search=True`:
281```python
282response = client.chat("xai/grok-3", "What's trending?", search=True)
283```
284 
285**Module not found**
286→ Install the SDK: `pip install blockrun-llm`
287 
288## Updates
289 
290```bash
291pip install --upgrade blockrun-llm
292```
293