FAQ

Frequently asked questions about BlockRun — payments, products, models, wallets, and troubleshooting.

General

What is BlockRun?

BlockRun is economic infrastructure for AI agents. It provides:

• Trading — Franklin's built-in trading tools: live signals, paper trading, Polymarket bets, and a trade-plan gate for real money
• Creation — generate images, video, music, and speech, paid per output
• Intelligence — Access to 71 chat/LLM models via x402 micropayments
• Routing — ClawRouter picks the cheapest capable model locally, in under 1ms

What makes BlockRun different?

Is BlockRun free?

• Trading (Franklin): Free and open source — you pay only for the market data and models the tools use
• Creation: Pay-per-use — images $0.015–0.15, video from $0.05/sec, music $0.15/track, text-to-speech $0.05–0.10 per 1k chars
• Intelligence: Provider cost with no platform margin on per-token chat (since 2026-08-07) — only a flat $0.001 transaction fee per request. Media generation and Live Search carry 5%.
• Free tier: 5 chat/reasoning/vision models with no per-token charge

Products

How does trading work?

Trading is built into the Franklin agent — there is no separate package to install (the earlier alpha-mcp server is retired). Franklin can:

• Analyze markets (TradingSignal: RSI, MACD, Bollinger Bands computed locally from live data; TradingMarket for crypto, FX, commodities, and equities)
• Paper-trade at live prices with a persistent portfolio and journal
• Research prediction-market odds and place real Polymarket bets
• Propose real-money TradePlans that nothing executes until you approve

It's free and open source. See Trading Overview.

What is nano-banana?

nano-banana is the image-generation capability — Nano Banana, GPT Image, CogView-4, or Grok Imagine via micropayments. See nano-banana. The original nano-banana-blockrun Claude Code skill repo is archived; use the blockrun_image tool in blockrun-mcp or the GPT-Image-2 / SeeDance skill instead.

What is ClawRouter?

ClawRouter is the open-source LLM router for autonomous agents — it classifies each request locally and routes it to the cheapest capable model in under 1ms, paying per request in USDC on Base or Solana. It ships as an OpenClaw plugin and as ports for Hermes, DeepSeek Harness, Codex and the OKX OnchainOS wallet. See ClawRouter and the Ecosystem.

What is Franklin?

Franklin is the AI agent with a wallet — it holds USDC and spends it autonomously across every model and paid API to get work done, with budgets and guardrails. See Franklin.

Can I use an API key instead of a wallet?

Enterprise access at user.blockrun.ai is coming soon: API keys (brk_live_…), wire/prepaid billing, and post-hoc billing at exact usage with no per-call minimum. Sign-in is not yet open — reach out on Telegram for early access. Everyone else pays per call from a wallet; no API key is ever required.

Payments

How do payments work?

BlockRun uses the x402 protocol:

1. Request a service
2. Receive HTTP 402 Payment Required with price
3. Your SDK signs a USDC authorization locally
4. Payment settles on-chain, you receive the service

What currency is accepted?

USDC — on Base (blockrun.ai) or Solana (sol.blockrun.ai), both live. nano.blockrun.ai also accepts gas-free, batched USDC via Circle Gateway on Polygon, Arbitrum, Optimism and Unichain.

What's the minimum to get started?

$1 is enough for testing. Recommended: $5-20 for regular usage.

How do I fund my wallet?

Send USDC to your wallet address on Base (or Solana):

• Coinbase — Direct withdrawal to Base or Solana
• Base Bridge — Bridge from Ethereum
• Uniswap — Swap on Base
• POST /v1/onramp/token — a free Coinbase Onramp link for a Base wallet (blockrun fund in the CLI)

What if a request fails?

You pay for the upstream round trip. If the call fails on our side — the provider is down, times out, or returns a JSON-RPC -32603 — it doesn't settle. If the provider rejects what you sent (unknown method, invalid params, a reverted call), it does: we made the call on your behalf. Requests we can reject locally, before contacting anyone, are always free.

Can I get a refund?

Payments are on-chain and final, like any blockchain transaction.

Trading

Is AI trading risky?

Yes. Franklin layers hard guardrails — paper trades are capped at $400 per position and $900 total exposure, every real-money trade needs an approved TradePlan (approvals expire after 15 minutes), Polymarket orders are capped at $25 by default, and --max-spend caps a session — but all trading carries risk. Only trade what you can afford to lose.

Can I override the risk limits?

The paper-trading caps and the trade-plan gate live in code, not in a prompt, and cannot be switched off — asking Franklin to skip them does nothing. The Polymarket per-order cap is adjustable with POLYMARKET_MAX_BET_USD, and your own PreSpend hooks can veto any money-moving tool. See Risk Management.

What can Franklin trade?

Paper positions at live prices across crypto, FX, commodities, and equities; real bets on Polymarket (Polygon, your own funds); and read-only DEX quotes on Solana (Jupiter) and Base (0x). Live DEX swap execution is currently paused while Franklin adds complete local transaction validation.

Does BlockRun charge trading fees?

No. Franklin's trading tools are free and open source. You pay only for the paid data they buy from the agent wallet (equity prices, prediction-market data, on-chain RPC, web search — signals and crypto/FX/commodity prices are free), for model calls, and for Polymarket network fees.

Is there a per-request fee?

Yes — a flat $0.001 transaction fee on every paid call, which covers on-chain settlement. That is the only thing added on top of provider cost for chat; there is no percentage margin on tokens.

Technical

Which AI models are available?

78 models including:

• OpenAI (GPT-5.5, GPT-5.4, GPT-5.4 Pro, GPT-5.2)
• Anthropic (Claude Opus 5, Opus 4.8, Sonnet 5, Sonnet 4.6, Haiku 4.5)
• Google (Gemini 3.1 Pro, Gemini 3.5 Flash)
• DeepSeek (V4 Flash Chat, V4 Pro, Reasoner)
• Z.AI (GLM-5.2 with 1M context, GLM-5.1, GLM-5, GLM-5 Turbo)
• Moonshot (Kimi K3 — 1M context, image + text input)
• MiniMax (MiniMax M3)
• Qwen (Qwen3.7 Max — 1M context, Alibaba flagship)
• xAI (Grok 4.5, Grok 4.3, Grok Build 0.1)
• Plus a free tier of 5 reasoning, coding, and vision models

Full list: Models

Is the API OpenAI-compatible?

Yes. Use the same format as OpenAI's Chat Completions API.

How do I use BlockRun with Claude Code?

claude mcp add blockrun -s user -- npx -y @blockrun/mcp@latest

Then call the blockrun_wallet tool with action:"setup" in Claude Code.

What frameworks are supported?

• Claude Code, Cursor and any MCP client (blockrun-mcp; blockrun-claude-plugin for media spend gating)
• OpenClaw (ClawRouter, XClawRouter, lobster.cash skill)
• OpenAI Codex (clawrouter-codex bridge, blockrun-codex-plugin)
• NousResearch Hermes (ClawRouter-Hermes)
• DeepSeek Harness (dsh-clawrouter)
• OpenCode (@blockrun/opencode)
• LiteLLM (blockrun-litellm)
• Continue (native provider)
• ElizaOS (plugin)
• AgentKit (SDK integration) and LangChain (custom LLM class) — planned
• GOAT SDK (in review)

Install commands for each are in the Ecosystem.

Can I get the provider's response verbatim?

Yes. blockrun-llm-vip (Python) and blockrun-llm-go-vip (Go) subclass the official Anthropic and OpenAI SDKs and only swap the transport, so thinking-block signatures, native content[], cache-token usage and streaming events come back exactly as the provider sent them — no model substitution.

Security

Is my private key safe?

Your private key never leaves your machine. Only cryptographic signatures are sent.

Where is my wallet stored?

~/.blockrun/.session (Base key) and ~/.blockrun/.solana-session (Solana key) by default — shared by the MCP, the CLI, ClawRouter and the SDKs, so one wallet covers every tool.

Can BlockRun steal my funds?

No. BlockRun can only claim the specific amount you authorize per request.

Can I use my main wallet?

We recommend a dedicated wallet with small amounts. Don't use your main holdings wallet.

Wallet Setup

How do I create a wallet?

Claude Code:

blockrun_wallet action:"setup"

Python:

from blockrun_llm import setup_agent_wallet
client = setup_agent_wallet()  # Creates a wallet if none exists
print(client.get_wallet_address())

How much USDC do I need?

Can I withdraw my funds?

Yes. Your wallet is a standard Ethereum (Base) or Solana wallet. Import the private key into any Web3 wallet to withdraw.

Troubleshooting

"MCP not found"

Restart Claude Code after installing:

pkill -f "claude"
claude

"Wallet not found"

Run setup:

blockrun_wallet action:"setup"

"Insufficient balance"

Check your balance and fund if needed:

blockrun balance

"Network error"

Check internet connection and retry. If persistent, check BlockRun status.

Support

How do I get help?

1. Check this FAQ
2. Read the documentation
3. See MCP Troubleshooting
4. Open an issue on GitHub

How do I report bugs?

Open an issue on the relevant GitHub repository:

• General / MCP: blockrun-mcp
• Routing: ClawRouter
• Franklin agent: Franklin
• CLI: blockrun-cli
• Trading: built into Franklin — see Trading
• Python SDK: blockrun-llm
• TypeScript SDK: blockrun-llm-ts
• Go SDK: blockrun-llm-go

Where can I follow updates?

• Twitter/X: @BlockRunAI
• GitHub: BlockRunAI

What's next?