name: blockrun
user-invocable: true
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"). For Antigravity users, also use when credits are exhausted, stuck in refactoring loops, or need a second opinion on Gemini's code.
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.

How to Invoke

Users can trigger this skill in two ways:
- Slash command: /blockrun <request> (e.g., /blockrun use grok to analyze @elonmusk)
- Keyword in message: Include "blockrun" or model names (e.g., "blockrun grok find trending crypto", "use grok to check...")

Common triggers: blockrun, use grok, use gpt, dall-e, deepseek, generate image

CRITICAL: Balance Check Before API Calls

You MUST check wallet balance and get user confirmation BEFORE making any paid API call.

Step 1: Check Balance First

from blockrun_llm import setup_agent_wallet

client = setup_agent_wallet()
balance = client.get_balance()
address = client.get_wallet_address()

Step 2: Estimate Cost & Ask User

Before calling any model, show the user:

📊 Wallet Status
   Address: 0x413c...1DC3
   Balance: $0.39 USDC

💰 Estimated Cost
   Grok + Live Search (10 sources): ~$0.25

Proceed? (Balance after: ~$0.14)

Wait for user confirmation before making the API call.

Step 3: Handle Insufficient Balance

If balance is too low, show a friendly message:

⚠️ Insufficient balance for this operation.

Current: $0.05 USDC
Required: ~$0.25 (Grok + Live Search)

To fund your wallet, send USDC on Base to:
0x413c7846194698829F8605C631c06c91B7B71DC3

Would you like to:
1. Use fewer search sources (~$0.13 for 5 sources)
2. Try a cheaper model (DeepSeek ~$0.001)

Cost Reference for Confirmation

Output Guidelines

Keep it clean. The user wants results, not process.

• Hide retries - If an API call fails and you retry, don't show the error. Just retry silently and show the final result.
• No stack traces - If something fails, summarize the error in one sentence. Don't dump tracebacks.
• Concise results - For balance checks: just show wallet address and balance. For X/Twitter: summarize the findings, don't show raw API responses.
• Show cost at the end - After BlockRun operations, show what was spent: Cost: $0.28

Example good output:

@BlockRunAI Twitter Summary:
- Recent focus: Circle partnership, Grok integration, website redesign
- Top post: Circle announcement (1,637 views, 26 likes)
- Assessment: Active development, growing visibility

Cost: $0.28

Example bad output:

Error: Exit code 1
Traceback (most recent call last):
  File "<string>", line 31...
[retrying with different RPC]
[still failing, trying another]
...

Philosophy

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

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

Antigravity-Specific Triggers

Example User Prompts

Users will say things like:

Antigravity User Prompts

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

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

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).

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:

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")

1. 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

PaymentError: Payment was rejected
→ NEVER show raw stack traces. Always check balance first (see "CRITICAL: Balance Check" section above).
If you get this error, show a user-friendly message:

⚠️ Payment failed - insufficient balance.

Current balance: $0.05 USDC
Wallet: 0x413c7846194698829F8605C631c06c91B7B71DC3

Options:
1. Fund wallet with USDC on Base network
2. Use fewer search sources to reduce cost
3. Try a cheaper model (DeepSeek)

"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

Error Handling Pattern

Always wrap API calls with balance checking:

from blockrun_llm import setup_agent_wallet
from blockrun_llm.types import PaymentError

client = setup_agent_wallet()
balance = client.get_balance()
estimated_cost = 0.25  # Grok + Live Search

# Pre-flight check
if balance < estimated_cost:
    print(f"⚠️ Insufficient balance: ${balance:.2f} USDC")
    print(f"Required: ~${estimated_cost:.2f}")
    print(f"Wallet: {client.get_wallet_address()}")
    # Ask user what to do
else:
    # User confirmed, make the call
    try:
        response = client.chat("xai/grok-3", "Query", search=True)
        print(response)
        print(f"\nCost: ${client.get_spending()['total_usd']:.2f}")
    except PaymentError:
        print("⚠️ Payment failed. Balance may have changed.")

Updates

pip install --upgrade blockrun-llm