blockrun

BlockRun

BlockRun 适用于 Claude Code 和 Google Antigravity。

你无法生成图像，也无法实时访问 X/Twitter。BlockRun 可以为你提供这些能力。

理念

你拥有一个钱包。需要自己不具备的能力时，就自主付费获取。

你需要	你调用	定价
图像生成	DALL-E	$0.04/张
X 实时数据	Grok + Live Search	$0.025/来源
第二意见	GPT-5.2	$1.75/M 输入，$14/M 输出
更便宜的处理	DeepSeek	$0.14/M 输入，$0.28/M 输出

工作原理： BlockRun 使用 x402 微支付，将你的请求路由到 OpenAI、xAI、Google 等服务商。无需 API 密钥——你的钱包按 token 付费。

预算控制（可选）

如果用户指定了预算（例如“最多使用 $1”），请跟踪支出，并在达到预算时停止：

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

何时使用

触发条件	你的操作
用户明确提出请求（“用 BlockRun 让 GPT 再给我一份意见……”“用 Grok 检查一下……”“用 DALL-E 生成图像”）	通过 BlockRun 执行
用户需要你无法完成的事（图像、X 实时数据）	建议使用 BlockRun，并等待确认
你能顺利处理任务	自行完成，不要提及 BlockRun

用户提示词示例

用户可能会这样说：

用户说	你的操作
“blockrun 生成一张日落图像”	通过 ImageClient 调用 DALL-E
“用 Grok 查查 X 上的热门趋势”	使用 search=True 调用 Grok
“blockrun 用 GPT 审查这段代码”	通过 LLMClient 调用 GPT-5.2
“AI agents 的最新消息是什么？”	建议使用 Grok（你没有实时数据）
“为我的初创公司生成一个徽标”	建议使用 DALL-E（你无法生成图像）
“blockrun 查一下我的余额”	使用 get_balance() 显示钱包余额
“blockrun 用 DeepSeek 总结这个文件”	调用 DeepSeek 节省成本

钱包与余额

使用 setup_agent_wallet() 自动创建钱包并获取客户端。首次使用时会显示二维码和欢迎消息。

初始化客户端（始终从这里开始）：

from blockrun_llm import setup_agent_wallet

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

查询余额（用户询问“显示余额”“检查钱包”等时）：

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

显示用于充值的二维码：

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 用法

前提条件： 使用 pip install blockrun-llm 安装 SDK

基础聊天

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

X/Twitter 实时搜索（xAI Live Search）

重要： 要获取 X/Twitter 实时数据，必须使用 search=True 或 search_parameters 启用 Live Search。

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)

带筛选条件的高级 X 搜索

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)

图像生成

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 参考

Live Search 是 xAI 的实时数据 API。费用：每个来源 $0.025（默认 10 个来源，约 $0.26）。

要降低成本，请将 max_search_results 设为较小的值：

# Only use 5 sources (~$0.13)
response = client.chat("xai/grok-3", "What's trending?",
    search_parameters={"mode": "on", "max_search_results": 5})

搜索参数

参数	类型	默认值	描述
mode	string	"auto"	"off"、"auto" 或 "on"
sources	array	web,news,x	要查询的数据源
return_citations	bool	true	包含来源 URL
from_date	string	-	开始日期（YYYY-MM-DD）
to_date	string	-	结束日期（YYYY-MM-DD）
max_search_results	int	10	最多返回的来源数（可自定义以控制成本）

来源类型

X/Twitter 来源：

{
    "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 来源：

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

新闻来源：

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

可用模型

模型	最适合的用途	定价
openai/gpt-5.2	征求第二意见、代码审查、通用任务	输入 $1.75/M，输出 $14/M
openai/gpt-5-mini	注重成本的推理	输入 $0.30/M，输出 $1.20/M
openai/o4-mini	最新的高效推理	输入 $1.10/M，输出 $4.40/M
openai/o3	高级推理、复杂问题	输入 $10/M，输出 $40/M
xai/grok-3	实时 X/Twitter 数据	$3/M + $0.025/来源
deepseek/deepseek-chat	简单任务、批量处理	输入 $0.14/M，输出 $0.28/M
google/gemini-2.5-flash	超长文档、快速处理	输入 $0.15/M，输出 $0.60/M
openai/dall-e-3	照片级真实感图像	$0.04/张
google/nano-banana	快速生成艺术风格图像	$0.01/张

M = 百万 token。实际成本取决于提示词和响应的长度。

成本参考

所有大模型费用均按每百万 token 计算（M = 1,000,000 个 token）。

模型	输入	输出
GPT-5.2	$1.75/M	$14.00/M
GPT-5-mini	$0.30/M	$1.20/M
Grok-3（无搜索）	$3.00/M	$15.00/M
DeepSeek	$0.14/M	$0.28/M

固定费用操作
Grok 实时搜索	$0.025/来源（默认 10 个来源 = $0.25）
DALL-E 图像	$0.04/张
Nano Banana 图像	$0.01/张

**典型成本：**向 GPT-5.2 发送一条 500 字的提示词（约 750 个 token），输入成本约为 $0.001。生成一条 1000 字的响应（约 1500 个 token），输出成本约为 $0.02。

设置与充值

钱包位置：$HOME/.blockrun/.session（例如，/Users/username/.blockrun/.session）

首次设置：

1. 调用 setup_agent_wallet() 时会自动创建钱包
2. 检查钱包和余额：

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. 在 Base 网络上向钱包充值 $1-5 USDC

显示用于充值的二维码（终端 ASCII 码）：

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

故障排除

“Grok 表示其无法实时访问数据” → 你忘记启用实时搜索了。添加 search=True：

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

找不到模块 → 安装 SDK：pip install blockrun-llm

更新

pip install --upgrade blockrun-llm