Summary
A wallet-based MCP server that routes requests to 55+ AI models, live market data, and web APIs through pay-per-use USDC micropayments on Base. Skip API key management for Exa neural search, Polymarket predictions, Twitter/X data, DEX prices via DexScreener, and model endpoints from OpenAI to DeepSeek. Each call costs fractions of a cent billed from a local wallet. Fund once with $5 USDC and query real-time crypto prices, generate images with DALL-E or Flux, search recent research papers, or pull Twitter mentions without subscriptions or rate limit negotiations. Useful when you want Claude to access live data sources without juggling multiple API accounts.
Install to Claude Code
verifiedclaude mcp add blockrun-mcp --env BLOCKRUN_WALLET_KEY=YOUR_BLOCKRUN_WALLET_KEY -- npx -y @blockrun/mcpRun in your terminal. Replace YOUR_* placeholders with real values; add --scope user to install for every project.
Review the command, arguments, and environment values before installing — MCP servers run with your local permissions.
belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →
Plug Mailtrap into your AI workflow and let it handle the email.
Connect Mailtrap MCP →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
Make coding agent sessions - Searchable, Shareable, Vendor-neutral & Scored.
Try For Free →
Your agent targets a perfect 10 Code Health score. Deterministic. Every commit.
Try For Free →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Tools
Verified live against the running server on Jun 11, 2026.
verified live18 tools
blockrun_walletCall this tool to manage the BlockRun payment wallet and control agent spending budgets. Call this FIRST if any other blockrun_* tool returns a payment/balance error. Call this to check your current USDC balance before expensive operations. Call this to set spending limits bef...6 params
Call this tool to manage the BlockRun payment wallet and control agent spending budgets. Call this FIRST if any other blockrun_* tool returns a payment/balance error. Call this to check your current USDC balance before expensive operations. Call this to set spending limits bef...
Parameters* required
actionstringWhat to doone of
status · setup · qr · chain · budget · delegatedefault: statusagent_idstringAgent identifier for delegate/revoke/report actions
agent_limitnumberBudget limit in USD for this agent (required for delegate action)
budget_actionstringBudget action (for action='budget')one of
set · check · clearbudget_amountnumberBudget limit in USD (for budget_action='set')
chainstringTarget chain for action='chain'. Omit to view the current active chain.one of
base · solanablockrun_chatGet a second opinion from another AI model, or use a specialized model for a specific task. Notable modes: - mode:"glm" → Zhipu GLM-5 / GLM-5-Turbo ($0.001/call, excellent for coding tasks, pays via USDC on BlockRun) - mode:"coding" → GLM-5 first, then code-specialized models...13 params
Get a second opinion from another AI model, or use a specialized model for a specific task. Notable modes: - mode:"glm" → Zhipu GLM-5 / GLM-5-Turbo ($0.001/call, excellent for coding tasks, pays via USDC on BlockRun) - mode:"coding" → GLM-5 first, then code-specialized models...
Parameters* required
agent_idstringAgent identifier. If a budget was delegated for this agent_id via blockrun_wallet action:'delegate', spending is tracked and enforced. The agent is hard-stopped when its budget is exhausted.
max_tokensnumberMax tokens in responsedefault: 1024
message*stringYour message to the AI
messagesarrayConversation history for multi-turn context. When provided, 'message' is appended as the final user turn. Use with explicit 'model' param (defaults to 'openai/gpt-5.5' if not specified). Note: if y...
modestringRouting mode: glm = Zhipu GLM-5/GLM-5-Turbo ($0.001/call, great for coding), coding = GLM-5 + code models, cheap = GLM-5 + budget, free = NVIDIA only (ignored if model specified)one of
fast · balanced · powerful · cheap · reasoning · freemodelstringSpecific model ID (e.g., 'zai/glm-5', 'openai/o3')
response_formatstringSet to 'json_object' to force valid JSON output (no markdown fences). Works across all providers.one of
text · json_objectroutingstringSet to "smart" to auto-select the optimal model via ClawRouter (14-dimension AI routing)one of
smartrouting_profilestringCost/quality profile for ClawRouter: "free" (zero cost NVIDIA), "eco" (budget), "auto" (balanced, default), "premium" (best quality) (only applies when routing: "smart")one of
free · eco · auto · premiumdefault: autostoparrayUp to 4 stop sequences; generation halts when any is produced
systemstringOptional system prompt
temperaturenumberCreativity 0-2default: 1
thinkingobjectAnthropic extended thinking. Only honored for anthropic/claude-* models — these go direct to the native /v1/messages endpoint and the response includes verbatim type:'thinking' blocks with their or...
blockrun_modelsList available AI models with pricing. Use to discover models and compare costs.2 params
List available AI models with pricing. Use to discover models and compare costs.
Parameters* required
categorystringFilter by categoryone of
all · chat · reasoning · image · embeddingdefault: allproviderstringFilter by provider (e.g., 'openai', 'anthropic')
blockrun_imageGenerate or edit images via BlockRun. Pays with USDC — no separate API keys needed. Actions: - generate (default): Create image from text prompt - edit: Transform an existing image using img2img Generation models (1024x1024 base price; larger sizes cost more on gpt-image-*): -...7 params
Generate or edit images via BlockRun. Pays with USDC — no separate API keys needed. Actions: - generate (default): Create image from text prompt - edit: Transform an existing image using img2img Generation models (1024x1024 base price; larger sizes cost more on gpt-image-*): -...
Parameters* required
actionstringgenerate: create from text; edit: transform existing imageone of
generate · editdefault: generateagent_idstringAgent identifier for budget tracking and enforcement.
imagestringSource image for edit action: base64-encoded image or URL
modelstringModel to use (default: openai/gpt-image-2 for both generate and edit). gpt-image-2 renders on-image text best; nano-banana-pro for 4K photorealism; cogview-4 / grok-imagine-image for cheap drafts.one of
zai/cogview-4 · google/nano-banana · google/nano-banana-pro · openai/gpt-image-1 · openai/gpt-image-2 · xai/grok-imagine-imageprompt*stringImage description or edit instructions
qualitystringone of
standard · hddefault: standardsizestringImage size. Common values: 1024x1024 (all models), 1536x1024 / 1024x1536 (gpt-image-*), 2048x2048 / 4096x4096 (nano-banana-pro)default: 1024x1024
blockrun_musicGenerate music tracks via BlockRun x402. Generates a full-length ~3 minute MP3 track. Takes 1-3 minutes to complete. Models: minimax/music-2.5+ ($0.1575), minimax/music-2.5 ($0.1575) Returns a time-limited CDN URL — download immediately if you need to keep the file.5 params
Generate music tracks via BlockRun x402. Generates a full-length ~3 minute MP3 track. Takes 1-3 minutes to complete. Models: minimax/music-2.5+ ($0.1575), minimax/music-2.5 ($0.1575) Returns a time-limited CDN URL — download immediately if you need to keep the file.
Parameters* required
agent_idstringAgent identifier for budget tracking and enforcement.
instrumentalbooleanGenerate without vocals (default: true)default: true
lyricsstringCustom lyrics. Cannot be used with instrumental: true
modelstringMusic model to useone of
minimax/music-2.5+ · minimax/music-2.5default: minimax/music-2.5+prompt*stringMusic style, mood, or description. E.g. 'upbeat synthwave with neon pads', 'chill lo-fi beats', 'epic orchestral film score'
blockrun_speechElevenLabs voice via BlockRun x402 — speak text aloud, generate sound effects, list voices. Actions: - speak (default): text-to-speech. E.g. "speak this with the sarah voice". Price = chars/1000 × rate (min $0.001), quoted before payment. - sound_effect: cinematic sound effect...9 params
ElevenLabs voice via BlockRun x402 — speak text aloud, generate sound effects, list voices. Actions: - speak (default): text-to-speech. E.g. "speak this with the sarah voice". Price = chars/1000 × rate (min $0.001), quoted before payment. - sound_effect: cinematic sound effect...
Parameters* required
actionstringspeak: text-to-speech (default). sound_effect: generate a sound effect. voices: list voices (free).one of
speak · sound_effect · voicesdefault: speakagent_idstringAgent identifier for budget tracking and enforcement.
duration_secondsnumberSound effect length in seconds (sound_effect only; default: auto)
inputstringspeak: text to synthesize. sound_effect: description of the sound, e.g. 'rain on a tin roof, distant thunder' (max 1000 chars).
modelstringSpeech model (speak only)one of
elevenlabs/flash-v2.5 · elevenlabs/turbo-v2.5 · elevenlabs/multilingual-v2 · elevenlabs/v3default: elevenlabs/flash-v2.5prompt_influencenumberHow literally to follow the prompt, 0-1 (sound_effect only)
response_formatstringAudio formatone of
mp3 · opus · pcm · wavdefault: mp3speednumberPlayback speed 0.7-1.2 (speak only)
voicestringVoice alias (sarah, george, laura, charlie, river, roger, callum, harry) or raw ElevenLabs voice_id. Default: sarah.
blockrun_videoGenerate short AI videos via BlockRun x402 (async, client-polled). Turns a text prompt (and optional seed image) into a short MP4 clip. The tool submits the job, then polls until the video is ready (typical total wall-time 60-180s; 5 min hard cap). Payment is settled only when...6 params
Generate short AI videos via BlockRun x402 (async, client-polled). Turns a text prompt (and optional seed image) into a short MP4 clip. The tool submits the job, then polls until the video is ready (typical total wall-time 60-180s; 5 min hard cap). Payment is settled only when...
Parameters* required
agent_idstringAgent identifier for budget tracking and enforcement.
duration_secondsintegerDuration to bill for (defaults to the model's default — 8s for xAI, 5s for Seedance; Seedance supports up to 10s).
image_urlstringOptional seed image URL for image-to-video generation
modelstringVideo model to useone of
azure/sora-2 · xai/grok-imagine-video · bytedance/seedance-1.5-pro · bytedance/seedance-2.0-fast · bytedance/seedance-2.0default: xai/grok-imagine-videoprompt*stringText description of the video to generate. E.g. 'a red apple slowly spinning on a wooden table', 'a hummingbird hovering near a red flower, ultra slow motion'
real_face_asset_idstringBytePlus RealFace asset id (from blockrun_realface enroll/list) to generate video of a specific real person. Seedance 2.0 / 2.0-fast only. Mutually exclusive with image_url.
blockrun_realfaceEnroll a real person's face as a BytePlus RealFace asset, then drive Seedance 2.0 video with it (blockrun_video real_face_asset_id). A RealFace asset (ta_xxxx) lets Seedance 2.0 / 2.0-fast generate video of a SPECIFIC real person — not a generic seed image. Enrollment is a mul...5 params
Enroll a real person's face as a BytePlus RealFace asset, then drive Seedance 2.0 video with it (blockrun_video real_face_asset_id). A RealFace asset (ta_xxxx) lets Seedance 2.0 / 2.0-fast generate video of a SPECIFIC real person — not a generic seed image. Enrollment is a mul...
Parameters* required
action*stringWhat to doone of
init · status · enroll · portrait · listagent_idstringAgent identifier for budget tracking and enforcement (enroll only).
group_idstringAsset-group id from init (required for status and enroll; pass to init to refresh an expired H5 link). Not used by portrait.
image_urlstringPublic HTTPS URL to a clear front-facing face image (JPG/PNG/WEBP, ≤10MB). Required for enroll and portrait.
namestringDisplay name for the person/character (required for init, enroll, and portrait).
blockrun_searchGrok Live Search — real-time web + X/Twitter + news with AI-summarized results and citations. $0.025 per returned source (max_results × $0.025; default max_results=10 → $0.25). Common shape: - body: { query: "...", sources: ["web","x","news"], max_results: 10, from_date: "YYYY...3 params
Grok Live Search — real-time web + X/Twitter + news with AI-summarized results and citations. $0.025 per returned source (max_results × $0.025; default max_results=10 → $0.25). Common shape: - body: { query: "...", sources: ["web","x","news"], max_results: 10, from_date: "YYYY...
Parameters* required
agent_idstringAgent identifier for budget tracking and enforcement.
bodyvalueRequest body. At minimum { query: '...' }. Sent as POST.
pathstringEndpoint sub-path under /v1/search/ (default empty = root /v1/search). Reserved for future surfaces.default:
blockrun_exaNeural web search via Exa — understands meaning, not just keywords. Great for research. Common paths (all POST, body shapes documented in the exa-research skill): - search — body: { query, numResults?, category?, includeDomains?, excludeDomains? } ($0.01/call) - answer — body:...3 params
Neural web search via Exa — understands meaning, not just keywords. Great for research. Common paths (all POST, body shapes documented in the exa-research skill): - search — body: { query, numResults?, category?, includeDomains?, excludeDomains? } ($0.01/call) - answer — body:...
Parameters* required
agent_idstringAgent identifier for budget tracking and enforcement.
bodyvalueJSON body for the call. Sent as POST. Required for all four endpoints.
path*stringEndpoint name under /v1/exa/, e.g. 'search', 'answer', 'contents', 'find-similar'
blockrun_marketsPrediction market + derivatives data via Predexon aggregator. Tier 1 = $0.001/call, Tier 2 = $0.005/call. CANONICAL CROSS-VENUE (Tier 1) — Predexon v2 unified data layer: - markets — list canonical market/question containers with cross-venue Predexon IDs - markets/listings — v...4 params
Prediction market + derivatives data via Predexon aggregator. Tier 1 = $0.001/call, Tier 2 = $0.005/call. CANONICAL CROSS-VENUE (Tier 1) — Predexon v2 unified data layer: - markets — list canonical market/question containers with cross-venue Predexon IDs - markets/listings — v...
Parameters* required
agent_idstringAgent identifier for budget tracking and enforcement.
bodyvalueJSON body for POST queries (triggers pmQuery — most endpoints are GET)
paramsobjectQuery parameters for GET requests (e.g. { limit: '20', active: 'true' })
path*stringEndpoint path, e.g. 'polymarket/events', 'kalshi/markets/KXBTC-25MAR14', 'polymarket/wallet/0xabc...', 'markets/search'
blockrun_priceRealtime quotes and OHLC history for crypto, FX, commodities and 12 global stock markets (Pyth-backed). - action="price" — realtime quote for a symbol - action="history" — OHLC bars between from/to (unix seconds) - action="list" — discovery: list available symbols (free) Prici...11 params
Realtime quotes and OHLC history for crypto, FX, commodities and 12 global stock markets (Pyth-backed). - action="price" — realtime quote for a symbol - action="history" — OHLC bars between from/to (unix seconds) - action="list" — discovery: list available symbols (free) Prici...
Parameters* required
action*stringWhich endpoint to hit: price, history, or list.one of
price · history · listagent_idstringAgent identifier for budget tracking and enforcement.
category*stringMarket category.one of
crypto · fx · commodity · usstock · stocksfromnumberHistory window start (unix seconds).
limitintegerMax items for list (default 100, max 2000).
marketstringStock market code — required when category='stocks'.one of
us · hk · jp · kr · gb · dequerystringFree-text filter for list.
resolutionstringBar resolution for history (default D).one of
1 · 5 · 15 · 60 · 240 · DsessionstringEquity session hint (pre/post/on); ignored for non-equity.one of
pre · post · onsymbolstringTicker (required for price+history). e.g. BTC-USD, AAPL, EUR-USD.
tonumberHistory window end (unix seconds).
blockrun_dexGet real-time DEX data from DexScreener. FREE - no payment required. Use for: - Token prices and liquidity across chains - Trading volume and price changes - Finding token pairs and contracts Examples: blockrun_dex({ query: "SOL" }) -> Search for SOL pairs blockrun_dex({ token...4 params
Get real-time DEX data from DexScreener. FREE - no payment required. Use for: - Token prices and liquidity across chains - Trading volume and price changes - Finding token pairs and contracts Examples: blockrun_dex({ query: "SOL" }) -> Search for SOL pairs blockrun_dex({ token...
Parameters* required
chainstringFilter by chain (ethereum, solana, base, etc.)
querystringSearch query (token name, symbol, or address)
symbolstringToken symbol to search
tokenstringToken address for direct lookup
blockrun_modalRun isolated code in a BlockRun-hosted Modal sandbox — disposable remote container, optional GPU. Use when you need: a clean ephemeral environment, GPU access (T4/L4/A10G/A100/A100-80GB/H100), or a safer place for untrusted code. Prefer local tools for normal repo work. Common...3 params
Run isolated code in a BlockRun-hosted Modal sandbox — disposable remote container, optional GPU. Use when you need: a clean ephemeral environment, GPU access (T4/L4/A10G/A100/A100-80GB/H100), or a safer place for untrusted code. Prefer local tools for normal repo work. Common...
Parameters* required
agent_idstringAgent identifier for budget tracking and enforcement.
bodyvalueJSON body. Sent as POST.
path*stringEndpoint under /v1/modal/, e.g. 'sandbox/create', 'sandbox/exec'
blockrun_phonePhone-number intelligence, US/CA number provisioning, and outbound AI voice calls. Common paths (path = everything after /v1/): - phone/lookup POST body: { phoneNumber } ($0.01) - phone/lookup/fraud POST body: { phoneNumber } — SIM-swap + call-forwarding signals ($0.05) - phon...3 params
Phone-number intelligence, US/CA number provisioning, and outbound AI voice calls. Common paths (path = everything after /v1/): - phone/lookup POST body: { phoneNumber } ($0.01) - phone/lookup/fraud POST body: { phoneNumber } — SIM-swap + call-forwarding signals ($0.05) - phon...
Parameters* required
agent_idstringAgent identifier for budget tracking and enforcement.
bodyvalueJSON body. Sent as POST. Omit for the free GET poll (voice/call/{call_id}).
path*stringEndpoint after /v1/. Use 'phone/...' for lookup + number ops, 'voice/call' for outbound AI calls, 'voice/call/{id}' (no body) to poll status.
blockrun_surfUnified crypto data via Surf (asksurf.ai) — 84 endpoints, one API. Coverage: CEX market data (16 exchanges), on-chain SQL across 13 chains, 100M+ labeled wallets, prediction markets (Polymarket + Kalshi), social mindshare / CT intelligence, news, unified search, and Surf-1.5 c...4 params
Unified crypto data via Surf (asksurf.ai) — 84 endpoints, one API. Coverage: CEX market data (16 exchanges), on-chain SQL across 13 chains, 100M+ labeled wallets, prediction markets (Polymarket + Kalshi), social mindshare / CT intelligence, news, unified search, and Surf-1.5 c...
Parameters* required
agent_idstringAgent identifier for budget tracking and enforcement.
bodyvalueJSON body for POST endpoints. Provide for: onchain/query, onchain/sql, chat/completions. When set, the call is sent as POST; otherwise GET with params.
paramsobjectQuery parameters for GET endpoints, e.g. { symbol: 'BTC' } or { address: '0x...', chain: 'ethereum' }
path*stringEndpoint path under /v1/surf/, e.g. 'market/price', 'prediction-market/polymarket/ranking', 'wallet/detail', 'onchain/sql', 'chat/completions'
blockrun_rpcRaw JSON-RPC against 40+ blockchains — one endpoint, no node, no API key. $0.002 per call (batch charges per element). Use when you need data the higher-level tools don't cover: contract reads (eth_call), balances, blocks, txs, logs, gas, or any chain-native RPC method. Networ...5 params
Raw JSON-RPC against 40+ blockchains — one endpoint, no node, no API key. $0.002 per call (batch charges per element). Use when you need data the higher-level tools don't cover: contract reads (eth_call), balances, blocks, txs, logs, gas, or any chain-native RPC method. Networ...
Parameters* required
agent_idstringAgent identifier for budget tracking and enforcement.
bodyvalueFull JSON-RPC 2.0 body or an array of them (batch). Overrides method/params when set.
methodstringJSON-RPC method, e.g. 'eth_blockNumber', 'eth_call', 'getSlot' (Solana), 'getblockchaininfo' (Bitcoin). Required unless 'body' is set.
network*stringChain key, e.g. 'ethereum', 'base', 'solana', 'bitcoin', 'arbitrum', 'polygon'. Unknown slugs pass through to the Tatum gateway.
paramsvalueJSON-RPC params array for the method, e.g. ['0xabc...', 'latest'].
blockrun_defiDeFi fundamentals via DefiLlama — protocol TVL, chain TVL, yield pools (APY), token prices. Pays per call in USDC, no API key. Paths (GET only): - protocols ($0.005) — all DeFi protocols ranked by TVL - protocol/{slug} ($0.005) — one protocol's TVL history + chain breakdown, e...2 params
DeFi fundamentals via DefiLlama — protocol TVL, chain TVL, yield pools (APY), token prices. Pays per call in USDC, no API key. Paths (GET only): - protocols ($0.005) — all DeFi protocols ranked by TVL - protocol/{slug} ($0.005) — one protocol's TVL history + chain breakdown, e...
Parameters* required
agent_idstringAgent identifier for budget tracking and enforcement.
path*stringEndpoint under /v1/defillama/, e.g. 'protocols', 'protocol/aave-v3', 'chains', 'yields', 'prices/coingecko:ethereum'
BlockRun MCP
Real-time data — and real trades — for Claude and any AI agent.
Agents can't sign up for accounts. Agents can't enter credit cards.
Agents can only sign transactions.
BlockRun MCP gives your agent 20 tools — markets, research, web search, images, video, on-chain data, and live Polymarket trading — paid per call in USDC. No accounts. No API keys. No dashboards.
Read the odds and place the bet, from one self-custody wallet.
claude mcp add blockrun -s user -- npx -y @blockrun/mcp@latest
Wallet auto-created on first run. Fund with $5 USDC. Ask Claude anything.
BlockRun MCP is an open-source Model Context Protocol server that gives Claude — and any MCP-compatible agent — 20 tools for real-time data and real actions: 71 LLMs, image & video generation, prediction-market data, live web/X search, on-chain queries across 40 chains, and the ability to place real, USDC-settled bets on Polymarket. Authentication is a wallet signature (no API keys); you pay per call in USDC via the x402 protocol (no credit cards, no subscriptions). One self-custody wallet on Base or Solana. MIT licensed.
🏆 First of its kind — the signal → trade loop in Claude Code
Read live Polymarket odds and place the bet, from one self-custody wallet, pay-per-call. Jump to Polymarket trading →
Why BlockRun MCP exists
Every other data integration was built for human developers — create an account, copy an API key into .env, add a credit card, repeat for every vendor.
Agents can't do any of that. BlockRun MCP is built for the agent-first world:
- One wallet, every source — 20 tools behind a single self-custody wallet. No per-vendor signups.
- No API keys — your wallet signature is authentication.
- No credit cards — pay per request in USDC via x402, fractions of a cent each.
- Starts free — the free tier (
blockrun_chat mode:"free",blockrun_dex, cryptoblockrun_price,blockrun_models) costs $0. - Reads and acts — most tools deliver data;
blockrun_polymarketplaces real, confirm-gated trades. - Self-custody — your key never leaves your machine (
~/.blockrun/.sessionby default,0600). BlockRun can't move your funds.
How it compares
| Raw provider APIs | Typical single-vendor MCP | BlockRun MCP | |
|---|---|---|---|
| Setup | Account + API key per vendor | Account/key for 1 vendor | Wallet auto-created, no signup |
| Payment | Credit card, monthly minimums | Credit card / vendor plan | USDC per-call via x402 |
| Data sources | One per integration | One vendor | 20 tools — LLMs, media, markets, chain |
| Place real bets | Build it yourself | Rare | Yes — Polymarket CLOB, confirm-gated |
| Pay-chain | — | — | Base + Solana |
| Agent budgets | Manual | — | Built-in per-agent delegation |
| Open source | Varies | Varies | Yes (MIT) |
✓ One wallet · ✓ Pay-per-call · ✓ Reads and trades · ✓ Multi-chain · ✓ Agent-ready · ✓ Open source
What changes
Before BlockRun, Claude can't answer:
- "What's the current Polymarket probability that Bitcoin hits $100k this year?"
- "Find me the top 5 papers on RAG published in the last 30 days."
- "What are people saying about @sama on X right now?"
- "What's the 24h volume on the PEPE/ETH pair on Uniswap?"
- "Polymarket has the Fed holding at 73% — put $2 on it." ← and now it can place the trade, not just read the odds.
After BlockRun, it can. Each query costs fractions of a cent, billed from a local USDC wallet. No subscriptions. No API dashboards. No key rotation.
Quick Start
1. Install
Claude Code (recommended)
claude mcp add blockrun -s user -- npx -y @blockrun/mcp@latest
-s user installs globally (available in every project). The -- separator ensures -y is passed to npx, not parsed by claude mcp add.
💡 Homebrew / nvm users: if the server doesn't connect, Claude Code likely can't find
node/npxon its launcher PATH. Pass your shell PATH through — works on CLI and desktop:claude mcp add blockrun -s user -e PATH="$PATH" -- npx -y @blockrun/mcp@latestSee Troubleshooting if it persists.
Other clients — Claude Desktop, Cursor, Windsurf
Claude Desktop — add to claude_desktop_config.json:
{
"mcpServers": {
"blockrun": { "command": "npx", "args": ["-y", "@blockrun/mcp"] }
}
}
Cursor — add to ~/.cursor/mcp.json (macOS/Linux) or %APPDATA%\Cursor\mcp.json (Windows):
{
"mcpServers": {
"blockrun": { "command": "npx", "args": ["-y", "@blockrun/mcp@latest"] }
}
}
Windsurf — same JSON, in:
- macOS:
~/.codeium/windsurf/mcp_config.json - Linux:
~/.config/.codeium/windsurf/mcp_config.json - Windows:
%APPDATA%\Codeium\windsurf\mcp_config.json
2. Choose a tool profile (optional)
Expose a trimmed tool set so the client loads fewer schemas into context. Pass --profile <name> (or set BLOCKRUN_MCP_PROFILE); omit for the full set.
| Profile | Tools |
|---|---|
full (default) | everything (20 tools) |
media | wallet models image video realface music speech |
trading | wallet price dex markets surf defi rpc polymarket_read polymarket |
research | wallet models chat search exa surf |
chat | wallet models chat |
claude mcp add blockrun-trading -s user -- npx -y @blockrun/mcp@latest --profile trading
# Codex CLI
codex mcp add blockrun-trading -- npx -y @blockrun/mcp@latest --profile trading
An unknown profile name falls back to full. modal and phone are full-profile only.
For a complete live signal → order-preview presentation, use
skills/signal-to-trade-demo/SKILL.md
with the Stanford runbook.
3. Fund your wallet
Run blockrun_wallet to see your address. The server pays on Base by default — send USDC on Base (Coinbase → USDC → Base network → paste address, or bridge via bridge.base.org).
$5 covers ~525 market queries · ~500 Exa searches · ~250 image generations · ~14 Seedance 1.5-pro clips.
Prefer Solana? See Fund your wallet — two tool calls, no restart.
4. Ask Claude anything
"What's Polymarket saying about the next Fed decision? If 'hold' is above 70%, put $2 on it."
Claude reads the odds with blockrun_markets and — with your confirmation — places the trade with blockrun_polymarket. One wallet. Gasless. Confirm-gated.
Demo
User: What's Polymarket saying about the Fed rate decision next month?
Claude: According to Polymarket, the market puts a 73% probability on the Fed holding rates steady, 24% on a 25bp cut, 3% on a hike. 24h volume: $2.1M. The "Hold" contract last traded at $0.73.
(via
blockrun_markets· cost: $0.0095)
User: Polymarket has Hawley at ~13% to announce a 2026 presidential run — put $1 on Yes.
Claude: Done — bought 7.63 shares of Yes at $0.131 ($1.00, market FOK). Real on-chain order, settled in pUSD from your gasless Polymarket deposit wallet; I'm tracking the position now.
(signal via
blockrun_markets, trade viablockrun_polymarket— one self-custody wallet, gasless · on-chain tx0x7ca8…)
Tools
| Tool | Data source | Cost |
|---|---|---|
blockrun_chat | 71 LLMs (GPT, Claude, Gemini, DeepSeek, Kimi K3, GLM, NVIDIA free tier, …) with mode tier routing | per token |
blockrun_image | Generate: openai/gpt-image-2, gpt-image-1, google/nano-banana(-2/-pro), xai/grok-imagine-image(-pro), zai/cogview-4, bytedance/seedream-5-pro. Edit: img2img, inpaint, fusion. | $0.015–0.15 |
blockrun_video | Sora 2 + xAI Grok Imagine Video + ByteDance Seedance 1.5/2.0-mini/2.0-fast/2.0/2.5 (720p + audio; 4K on 2.0, up to 30s on 2.5); RealFace asset → real-person video | $0.053–0.32/sec charged |
blockrun_realface | Enroll a real person (phone liveness) or AI character (Virtual Portrait) as a ta_xxxx asset for Seedance 2.0 / 2.0-fast / 2.0-mini video (not 2.5) | free; $0.01 to enroll |
blockrun_music | MiniMax music generation | per track |
blockrun_speech | ElevenLabs TTS (Flash/Turbo/Multilingual/v3, 8 voices) + ByteDance Seed Audio (prompt-directed) + cinematic sound effects; free voice listing | $0.05–0.10/1k chars |
blockrun_price | Pyth-backed realtime + OHLC — crypto / FX / commodity (free), 12 stock markets (paid) | free or $0.001/call |
blockrun_markets | Polymarket (markets, candles, trades, orderbooks, leaderboards, smart-wallet PnL/clusters, UMA oracle), Kalshi, Limitless, Opinion, Predict.Fun, dFlow, Binance Futures, cross-platform search | $0.0095/query |
blockrun_polymarket_read | Read-only Polymarket positions/open orders plus executable live order previews, separated for MCP clients that enforce tool safety annotations | free |
blockrun_polymarket | Trade on Polymarket (CLOB V2): place/cancel real bets, positions, redeem winnings — signed locally, settled in pUSD from a gasless deposit wallet. Confirm-gated, $25/order default cap. Details ↓ | free tool; bets are your funds |
blockrun_surf | Surf (asksurf.ai) — 83 endpoints: CEX data, on-chain SQL (13 chains, 80+ tables), 100M+ labeled wallets, Polymarket + Kalshi, social mindshare, news, Surf-1.5 chat with citations | $0.0095/call |
blockrun_exa | Neural web search (Exa) — research, competitors, papers, URL content | $0.01/query |
blockrun_search | Grok Live Search — web + X/Twitter + news with citations | $0.025 × max_results |
blockrun_dex | Live DEX prices via DexScreener | free |
blockrun_rpc | Raw JSON-RPC on 40 chains (Ethereum, Base, Solana, Bitcoin, Sui, NEAR, …) via Tatum | $0.002/call |
blockrun_defi | DefiLlama — protocol TVL, chain TVL, yield pools (APY), token prices | $0.001–0.005/call |
blockrun_modal | Isolated code execution in a BlockRun-hosted Modal sandbox — disposable container, optional GPU (T4 → H100) | $0.01 create; $0.001/op |
blockrun_phone | Outbound AI voice calls (Bland) + wallet-owned US/CA numbers (Twilio), carrier + fraud lookups | $0.54/call; $5/number |
blockrun_models | Live catalogue of every LLM/image/video/music model + pricing | free |
blockrun_wallet | Balance, spending, agent budgets, setup QR, chain switch | free |
Key use cases
- Prediction-market consensus → "Polymarket's odds for the next Fed decision?" —
blockrun_markets - Signal → trade (the full loop, self-custody) → "If 'hold' is under 30%, put $2 on Yes." —
blockrun_marketsreads,blockrun_polymarket action:"buy"places. Gasless, confirm-gated. - On-chain forensics → "This wallet — what's it labeled, what does it hold, when did it whale up?" —
blockrun_surf - Cited research → "5 most-cited papers on speculative decoding, last 90 days." —
blockrun_exa - Image generation with on-image text → "Poster announcing GPT-5.5, retro-futuristic, headline 'NOW LIVE'." —
blockrun_image - Give your agent a voice → "Speak this with the sarah voice." —
blockrun_speech - Voice phone-out → "Call +1-415-… and confirm Friday at 3pm." —
blockrun_phone - Multi-agent research, capped → "Spawn 3 agents on competing L1 narratives. Cap each at $0.50." —
blockrun_wallet delegate × 3 - Cross-chain SQL → "Top 10 tokens by DEX volume on Base, last 24h." —
blockrun_surfonchain/sql
📈 Polymarket trading
blockrun_polymarket lets an agent place real bets on Polymarket (CLOB V2, Polygon). It is non-custodial: every order and approval is EIP-712-signed locally by your BlockRun wallet key — the same self-custody key that pays x402 API fees on Base also authorizes bets on Polygon. Neither BlockRun nor Polymarket's relayer can move funds; they only forward payloads you signed.
Architecture — the official "deposit wallet" path (signature type POLY_1271): a smart-contract vault on Polygon, CREATE2-derived from your key (only your key can authorize it), holds betting funds in pUSD (Polymarket's 1:1 collateral wrapper). Deployment, approvals, and redemptions all run gasless through Polymarket's relayer — you never need POL.
📖 Full step-by-step guide: docs/polymarket-trading-setup.md
# 1. Provision your deposit wallet (idempotent, gasless)
blockrun_polymarket action:"setup"
# 2. Fund it from your Base USDC in one call (gasless; $0.01 fee, non-custodial)
blockrun_polymarket action:"fund" amount_usd:5 confirm:true
# 3. Sign the one-time gasless approval batch
blockrun_polymarket action:"setup" confirm:true
# 4. Find a market, preview safely, then place only after exact user approval
blockrun_polymarket_read action:"preview" side:"buy" token_id:"<id>" amount_usd:5 order_type:"FOK"
blockrun_polymarket action:"buy" token_id:"<id>" amount_usd:5 order_type:"FOK" confirm:true
# 5. Manage → positions · orders · cancel · sell · redeem · withdraw
Safety rails (server-side; an agent cannot bypass them): confirm:true required for every order/approval/redeem, POLYMARKET_MAX_BET_USD per-order cap (default $25), optional POLYMARKET_MAX_SESSION_USD session cap, and bets never draw from the x402 API budget.
Regions: Polymarket geoblocks order placement by IP (US/UK + many regions). Handled by default — the MCP routes CLOB traffic through BlockRun's hosted Finland egress (a fully unrestricted region under Polymarket's policy), so trading works out of the box; setup reports your status. Override POLYMARKET_CLOB_HOST to go direct or run your own egress, optionally reached via HTTPS_PROXY / POLYMARKET_CLOB_PROXY (a proxy alone doesn't change the Polymarket-facing egress). Complying with Polymarket's terms for your jurisdiction is your responsibility.
⚠️ Back up your signer key (
~/.blockrun/.sessionby default; aBLOCKRUN_WALLET_KEYenv var or an existing agentwallet.jsontakes precedence —setupprints the actual signer address). It is the only key to both the payment wallet and the Polymarket deposit wallet.
Fund your wallet
Run blockrun_wallet to see your address. The server pays on Base by default.
| Method | Steps |
|---|---|
| Coinbase | Send → USDC → Base network → paste address |
| Bridge from Ethereum | bridge.base.org |
$5 covers ~525 market queries, ~500 Exa searches, ~250 image generations, or ~14 Seedance 1.5-pro clips (5s @ 720p+audio, ~$0.35 each).
Pay on Solana
Two tool calls — no env vars, no file editing, no restart:
blockrun_wallet action:"chain" chain:"solana" # provisions + activates the Solana wallet
blockrun_wallet action:"setup" # shows the Solana address + funding QR
Then send USDC (SPL) on the Solana network — from Coinbase (pick "Solana"), Phantom, Solflare, or Backpack. Switch back with blockrun_wallet action:"chain" chain:"base". The server keeps both wallets; switching just changes which one pays.
Base-only — these fall back to Base regardless of active chain: blockrun_music, blockrun_speech, blockrun_video, blockrun_modal, blockrun_defi, paid blockrun_realface, paid stock blockrun_price, and native Anthropic (claude-*) passthrough. In Solana mode they return a "switch to Base" message instead of charging. blockrun_image pays on either chain.
For agents & LLMs
If you are an LLM invoking BlockRun MCP tools, read these first:
- CRITICAL: On any payment / balance / 402 error, call
blockrun_walletfirst to check status, thenaction:"setup"for funding. Don't retry the failing tool blindly — the wallet is empty. - CRITICAL:
blockrun_polymarketmoves REAL user funds (pUSD on Polygon), separate from the x402 API budget. Neverbuy/sell/redeemwithconfirm:trueunless the user explicitly approved that exact trade; withoutconfirmyou get a safe dry-run. Discover markets/token IDs withblockrun_marketsfirst. - CRITICAL:
blockrun_surf's 84-endpoint catalog is inskills/surf/SKILL.md;blockrun_markets' full endpoint list is in its tool description (worked examples inskills/prediction-markets/SKILL.md; live-demo workflow inskills/signal-to-trade-demo/SKILL.md). Browse those before guessing paths. - CRITICAL:
blockrun_musicandblockrun_videoare payment-on-completion async. Failures / client timeouts do NOT charge. Don't retry-loop — they may take 60–180s. - CRITICAL: Before spawning child agents, allocate per-agent budget:
blockrun_wallet action:"delegate" agent_id:"X" agent_limit:1.00, then passagent_id:"X"to every downstream call. The child is auto-blocked at zero. - Free tier first for drafts:
blockrun_chat mode:"free"(NVIDIA),blockrun_dex,blockrun_price(crypto/FX/commodity), andblockrun_modelsare $0.
Showcase
Posters generated through blockrun_image with openai/gpt-image-2 — each a single API call routed through BlockRun, paid in USDC on Base.
 |  |  |
| Cornell Blockchain Conference 2026 | Cornell Blockchain Conference 2026 | 100 Trillion Tokens milestone |
Prompts and a worked example are in skills/image-prompting/SKILL.md.
Why not just use the APIs directly?
| Direct APIs | BlockRun | |
|---|---|---|
| Exa | Sign up, $20/mo minimum | $0.01/call, no subscription |
| Polymarket | Undocumented, rate-limited | $0.0095/call, clean JSON — plus you can trade |
| Surf (asksurf.ai) | Account + monthly plan | $0.0095/call, no account, 83 endpoints |
| Multiple sources | 3 accounts, 3 API keys, 3 billing pages | 1 wallet |
One wallet. All sources. No dashboards.
Configuration
Environment variables & files
| Variable / File | Default | Effect |
|---|---|---|
~/.blockrun/.session | auto-created on first run | EVM private key (0x…). File exists → use Base. Also the Polymarket signer (unless BLOCKRUN_WALLET_KEY or an agent wallet.json takes precedence). |
BLOCKRUN_WALLET_KEY | unset | Env override of the EVM key — takes precedence over .session / wallet.json as the Base + Polymarket signer. |
~/.blockrun/.chain | unset | Explicit chain preference: base or solana. Written only by blockrun_wallet action:"chain" — i.e. only when you choose. |
~/.blockrun/.chain-auto | written on first run | Automatic pin: the chain you were already on when your second wallet was provisioned. Keeps a Base user on Base once a Solana session exists, and is outranked by SOLANA_WALLET_KEY. Cleared whenever you set a chain explicitly. |
~/.blockrun/.solana-session | not created | Solana private key. File exists → Solana unless .chain says base. |
SOLANA_WALLET_KEY | unset | Env override of .solana-session. Set → use Solana. |
BLOCKRUN_MCP_PROFILE | full | Tool profile (media / trading / research / chat). |
POLYMARKET_CLOB_HOST | BlockRun Finland relay | Geoblock egress for order placement — defaulted for you. Override to go direct (https://clob.polymarket.com) or your own egress. |
POLYMARKET_MAX_BET_USD | 25 | Hard per-order notional cap. |
POLYMARKET_MAX_SESSION_USD | unset | Optional cumulative per-process betting cap. |
POLYMARKET_SIG_TYPE | 3 | 3 = deposit wallet (POLY_1271, gasless); 0 = plain EOA mode. |
POLYMARKET_CLOB_PROXY | unset | HTTPS proxy for Polymarket CLOB traffic only. |
POLYMARKET_BOUNDED_APPROVALS | unset (unlimited) | Bound pUSD exchange allowances to this many dollars. |
BLOCKRUN_BUILDER_CODE | unset | Optional Polymarket builder attribution code carried on orders. |
Chain selection priority (src/utils/wallet.ts): .chain preference → SOLANA_WALLET_KEY → .chain-auto pin → .solana-session exists → otherwise Base.
The server runs a non-blocking npm registry check at startup and prints an Update available notice to stderr when a newer @blockrun/mcp exists — re-run the install command to upgrade.
Troubleshooting
Insufficient balance/ HTTP 402 after retry → Runblockrun_wallet action:"setup", send USDC on Base (or Solana).blockrundoesn't connect / "MCP server failed" /spawn npx ENOENT→ Almost always a PATH issue: Claude Code can't findnode/npxon its launcher PATH (common with Homebrew / nvm, on CLI and desktop). Fix by passing your shell PATH at install:
Then restart Claude Code. Or pin absolute paths (claude mcp remove blockrun -s user claude mcp add blockrun -s user -e PATH="$PATH" -- npx -y @blockrun/mcp@latestwhich npx).claude mcp listdoesn't showblockrun→ Checknode -v(≥20.19). Clear the npx cache:rm -rf ~/.npm/_npx. Re-run the install.fetch failed/ balance-check timeout → Base RPC transient outage. The tool falls through 3 public RPCs; retry after 30s. Persistent = local proxy / firewall blocking outbound RPC.Video/Music generation timed out→ Upstream queue congestion. No charge (payment-on-completion). Retry, or pick a faster model.- Polymarket: neg-risk ("winner") market buy fails, or
redeemreverts, though setup shows ready → Re-runaction:"setup" confirm:trueonce (grants the on-chain approvals a pre-upgrade deposit wallet may lack — including the collateral-adapter approvalsredeemneeds). See the setup guide.
FAQ
What is BlockRun MCP? An open-source MCP server that gives Claude and other agents 20 tools for real-time data and real actions (trading, media, on-chain), paid per call in USDC. No accounts, no API keys.
Do I need API keys or accounts? No. A wallet is auto-created locally on first run; you fund it with USDC. No signups, no dashboards, no key rotation.
How much does it cost?
Pay-per-call — fractions of a cent to a few cents. The free tier (blockrun_chat mode:"free", blockrun_dex, crypto blockrun_price, blockrun_models) is $0. $5 of USDC covers thousands of queries.
Is it safe / non-custodial?
Yes. Your private key never leaves your machine (~/.blockrun/.session by default, 0600). x402 payments and Polymarket orders are signed locally — BlockRun forwards signed payloads and cannot move your funds.
Which clients work? Claude Code, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.
Can it really place real bets?
Yes. blockrun_polymarket places real, USDC-settled orders on Polymarket's CLOB — confirm-gated and capped. Read the odds with blockrun_markets, place with blockrun_polymarket.
Base or Solana?
Both. Switch instantly with blockrun_wallet action:"chain". A few media/paid tools settle on Base only (noted above).
From the BlockRun ecosystem
BlockRun is agent-native AI infrastructure — one wallet, x402 USDC micropayments, across every surface:
- ⚡ ClawRouter — the agent-native LLM router for OpenClaw. 71 models, <1ms local routing, USDC on Base & Solana.
- 🤖 BRCC — BlockRun for Claude Code: smart routing + x402 payments, purpose-built for Claude Code.
- 🐍 ClawRouter-Hermes — Python plugin wiring NousResearch Hermes into the ClawRouter proxy.
- 📚 Docs · Models & pricing — full SDKs, APIs, and the model catalogue.
Support & community
| 💬 Community Telegram | t.me/blockrunAI |
| 🐦 X / Twitter | @BlockRunAI |
| 📖 Documentation | blockrun.ai/docs |
| 🐛 Issues | github.com/BlockRunAI/blockrun-mcp/issues |
Contributing
PRs welcome. See CONTRIBUTING.md for setup, the tool-vs-skill design rule, and how to add a new partner API.
MIT License · blockrun.ai — Agent-native AI infrastructure
Website · npm · Docs · @BlockRunAI
Featured
belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →Plug Mailtrap into your AI workflow and let it handle the email.
Connect Mailtrap MCP →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →Make coding agent sessions - Searchable, Shareable, Vendor-neutral & Scored.
Try For Free →Your agent targets a perfect 10 Code Health score. Deterministic. Every commit.
Try For Free →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Configuration
BLOCKRUN_WALLET_KEYsecretOptional: Your wallet private key for USDC payments (hex for Base, bs58 for Solana). If not set, a wallet is auto-generated.
Registryactive
Package@blockrun/mcp
TransportSTDIO
AuthRequired
Resources2
Tools verifiedJun 11, 2026
UpdatedApr 7, 2026
