From 4dcd96e48454db6f094bf89dca90cd32a00b2cc6 Mon Sep 17 00:00:00 2001 From: 1bcMax Date: Thu, 15 Jan 2026 02:44:28 -0800 Subject: [PATCH] Add BlockRun: Agent Wallet for LLM Micropayments Adds a skill that gives AI agents a crypto wallet (USDC on Base) to autonomously pay for capabilities they lack: - Image generation (DALL-E, Nano Banana) - Real-time X/Twitter data (Grok Live Search) - Second opinions (GPT-5, DeepSeek, Gemini) - 30+ models from 5 providers Key features: - No API keys needed - wallet pays per token - Auto-wallet creation on first use - Works with Claude Code and Antigravity - Budget tracking and spending controls More info: https://github.com/BlockRunAI/blockrun-agent-wallet --- skills/blockrun/SKILL.md | 292 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 292 insertions(+) create mode 100644 skills/blockrun/SKILL.md diff --git a/skills/blockrun/SKILL.md b/skills/blockrun/SKILL.md new file mode 100644 index 00000000..334b74a9 --- /dev/null +++ b/skills/blockrun/SKILL.md @@ -0,0 +1,292 @@ +--- +name: blockrun +description: 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") +allowed-tools: Read, Bash(python:*), Bash(python3:*), Bash(pip:*), Bash(source:*) +--- + +# 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: + +```python +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):** +```python +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.):** +```python +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:** +```python +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 +```python +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`. + +```python +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 + +```python +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 +```python +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: +```python +# 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:** +```python +{ + "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:** +```python +{ + "type": "web", + "country": "US", # ISO alpha-2 code + "allowed_websites": ["example.com"], # Max 5 + "safe_search": True +} +``` + +**News Source:** +```python +{ + "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:** +1. Wallet auto-creates when `setup_agent_wallet()` is called +2. Check wallet and balance: +```python +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") +``` +3. Fund wallet with $1-5 USDC on Base network + +**Show QR code for funding (ASCII for terminal):** +```python +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`: +```python +response = client.chat("xai/grok-3", "What's trending?", search=True) +``` + +**Module not found** +→ Install the SDK: `pip install blockrun-llm` + +## Updates + +```bash +pip install --upgrade blockrun-llm +```