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

BlockRun MCP is an open-source Model Context Protocol server that gives Claude — and any MCP-compatible agent — 19 tools for real-time data and real actions: 55+ 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 — 19 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, crypto blockrun_price, blockrun_models) costs $0.
• Reads and acts — most tools deliver data; blockrun_polymarket places real, confirm-gated trades.
• Self-custody — your key never leaves your machine (~/.blockrun/.session, 0600). BlockRun can't move your funds.

How it compares

✓ 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/npx on its launcher PATH. Pass your shell PATH through — works on CLI and desktop:

bash

claude mcp add blockrun -s user -e PATH="$PATH" -- npx -y @blockrun/mcp@latest

See Troubleshooting if it persists.

{
  "mcpServers": {
    "blockrun": { "command": "npx", "args": ["-y", "@blockrun/mcp"] }
  }
}

{
  "mcpServers": {
    "blockrun": { "command": "npx", "args": ["-y", "@blockrun/mcp@latest"] }
  }
}

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.

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

An unknown profile name falls back to full. modal and phone are full-profile only.

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 ~5,000 market queries · ~500 Exa searches · ~250 image generations · ~10 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.001)

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 via blockrun_polymarket — one self-custody wallet, gasless · on-chain tx 0x7ca8…)

Tools

Key use cases

1. Prediction-market consensus → "Polymarket's odds for the next Fed decision?" — blockrun_markets
2. Signal → trade (the full loop, self-custody) → "If 'hold' is under 30%, put $2 on Yes." — blockrun_markets reads, blockrun_polymarket action:"buy" places. Gasless, confirm-gated.
3. On-chain forensics → "This wallet — what's it labeled, what does it hold, when did it whale up?" — blockrun_surf
4. Cited research → "5 most-cited papers on speculative decoding, last 90 days." — blockrun_exa
5. Image generation with on-image text → "Poster announcing GPT-5.5, retro-futuristic, headline 'NOW LIVE'." — blockrun_image
6. Give your agent a voice → "Speak this with the sarah voice." — blockrun_speech
7. Voice phone-out → "Call +1-415-… and confirm Friday at 3pm." — blockrun_phone
8. Multi-agent research, capped → "Spawn 3 agents on competing L1 narratives. Cap each at $0.50." — blockrun_wallet delegate × 3
9. Cross-chain SQL → "Top 10 tokens by DEX volume on Base, last 24h." — blockrun_surf onchain/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 with blockrun_markets, then place (dry-run without confirm)
blockrun_polymarket action:"buy" token_id:"<id>" amount_usd:2 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 (HTTPS_PROXY / POLYMARKET_CLOB_PROXY). Complying with Polymarket's terms for your jurisdiction is your responsibility.

⚠️ Back up ~/.blockrun/.session. 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.

$5 covers ~5,000 market queries, ~500 Exa searches, ~250 image generations, or ~10 Seedance 1.5-pro clips (5s @ 720p+audio, ~$0.46 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, paid blockrun_realface, paid stock blockrun_price, blockrun_chat routing:"smart" (ClawRouter), 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_wallet first to check status, then action:"setup" for funding. Don't retry the failing tool blindly — the wallet is empty.
• CRITICAL: blockrun_polymarket moves REAL user funds (pUSD on Polygon), separate from the x402 API budget. Never buy/sell/redeem with confirm:true unless the user explicitly approved that exact trade; without confirm you get a safe dry-run. Discover markets/token IDs with blockrun_markets first.
• CRITICAL: blockrun_surf's 84-endpoint catalog is in skills/surf/SKILL.md; blockrun_markets' full endpoint list is in its tool description (worked examples in skills/prediction-markets/SKILL.md). Browse those before guessing paths.
• CRITICAL: blockrun_chat routing:"smart" (ClawRouter) only works on Base wallets. On Solana, pass mode: or model: directly.
• CRITICAL: blockrun_music and blockrun_video are 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 pass agent_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), and blockrun_models are $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.

BlockRun at the Cornell Blockchain Conference 2026, packed booth	BlockRun at the Cornell Blockchain Conference 2026
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?

One wallet. All sources. No dashboards.

Configuration

Troubleshooting

• Insufficient balance / HTTP 402 after retry → Run blockrun_wallet action:"setup", send USDC on Base (or Solana).
• blockrun doesn't connect / "MCP server failed" / spawn npx ENOENT → Almost always a PATH issue: Claude Code can't find node/npx on its launcher PATH (common with Homebrew / nvm, on CLI and desktop). Fix by passing your shell PATH at install:
  bash

  claude mcp remove blockrun -s user
  claude mcp add blockrun -s user -e PATH="$PATH" -- npx -y @blockrun/mcp@latest
  

  Then restart Claude Code. Or pin absolute paths (which npx).
• claude mcp list doesn't show blockrun → Check node -v (≥20.19). Clear the npx cache: rm -rf ~/.npm/_npx. Re-run the install.
• Smart routing (ClawRouter) not available on Solana → Pass model: or mode: to blockrun_chat, or echo base > ~/.blockrun/.chain.
• 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 though setup shows ready → Re-run action:"setup" confirm:true once (grants the on-chain approval a pre-upgrade deposit wallet may lack). See the setup guide.

FAQ

What is BlockRun MCP? An open-source MCP server that gives Claude and other agents 19 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, 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. 55+ 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

Contributing

PRs welcome. See CONTRIBUTING.md for setup, the tool-vs-skill design rule, and how to add a new partner API.