Web search, deep research, prediction markets & crypto data for AI agents. Pay per call via x402.
BlockRun MCP (io.github.BlockRunAI/blockrun-mcp)
BlockRun MCP is an MCP server that provides real-time data and live market access for Claude and other AI agents. It supports web search, deep research, prediction markets, and crypto data, with usage paid per call via x402.
π οΈ Key Features
Web search and deep research for AI agents
Prediction markets & crypto data
Live Polymarket trading
20 tools referenced in the server excerpt
Paid per call via x402
π Use Cases
Fetch real-time information for agent workflows
Perform research and web search during reasoning
Query prediction markets and crypto-related data
Enable live trading actions via Polymarket
β‘ Developer Benefits
Agent-friendly integration (agents can only sign transactions, per excerpt)
No account or credit-card signup for agents, per excerpt
Tool-based access to markets, research, web search, and additional media/on-chain categories (as stated)
β οΈ Limitations
Billing is pay-per-call via x402, per excerpt
Payment methods mentioned in the excerpt include a self-custody wallet (USDC on Solana or Base) and a Bloc⦠(truncated)
web searchcrypto dataprediction marketsai agentspay-per-call
Real-time data β and real trades β for Claude and any AI agent.
Agents can pay like agents: sign transactions from a wallet.
Teams can pay like teams: get a BlockRun API key at user.blockrun.ai, add credit by card or wire, and let the MCP call api.blockrun.ai.
BlockRun MCP gives your agent 19 tools β markets, research, web search, images, video, on-chain data, and live Polymarket trading β paid per call.
Two ways to pay, same tools: a self-custody wallet (USDC on Solana, Base or Arc, no account needed) β or a BlockRun API key backed by account credit. Sign up at user.blockrun.ai β
Read the odds and place the bet, from one self-custody wallet.
Β
Β
Β
Β
Β
bash
claude mcp add blockrun -s user -- npx -y @blockrun/mcp@latest
Wallet auto-created on first run. Fund with $5 USDC β or get a key at user.blockrun.ai, top up by card, and call through api.blockrun.ai. Ask Claude anything.
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: 91 LLMs, image & video generation, prediction-market data, live web + news search, on-chain queries across 40 chains, and the ability to place real, USDC-settled bets on Polymarket.
You pay per call, and you choose how. Wallet mode authenticates with a signature and settles each call in USDC via the x402 protocol β no account, no credit card, no subscription, on Solana, Base or Arc. Account mode authenticates with a BlockRun API key (brk_live_β¦) from user.blockrun.ai, routes service calls through api.blockrun.ai, and draws down card- or wire-funded account credit at exact usage. Same 19 tools either way. MIT licensed.
π First of its kind β the signal β trade loop in Claude Code
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.
BlockRun gives you both payment rails without rebuilding the integration. Use a wallet when the agent should self-custody funds, or use an account key when a team wants card-funded credits and a dashboard.
One wallet, every source β 19 tools behind a single self-custody wallet. No per-vendor signups.
One account key, every source β mint a key at user.blockrun.ai, top up by card or wire, then the MCP calls api.blockrun.ai with that key.
No API key required in wallet mode β your wallet signature is authentication.
No credit card required in wallet mode β pay per request in USDC via x402, fractions of a cent each.
Reads and acts β most tools deliver data; blockrun_polymarket places real, confirm-gated trades.
Human-in-the-loop payments β turn on BLOCKRUN_CONFIRM_SPEND=on and the agent pauses before any paid call above your threshold; nothing is signed until you approve. Details β
Generative UI β on Claude Desktop, claude.ai, VS Code and Cursor the Polymarket preview is a live order card with a Place button, and the wallet is a panel with balances, QR and card top-up. MCP Apps β
Self-custody β your key never leaves your machine (~/.blockrun/.session, 0600 β or the OS keychain once you opt into BLOCKRUN_KEYCHAIN=strict). 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 β or one BlockRun key for everything
Payment
Credit card, monthly minimums
Credit card / vendor plan
USDC per-call via x402, or card/wire-funded account credit
Data sources
One per integration
One vendor
19 tools β LLMs, media, markets, chain
Place real bets
Build it yourself
Rare
Yes β Polymarket CLOB, confirm-gated
Pay-chain
β
β
Solana + Base, or api.blockrun.ai with no chain at all
Agent budgets
Manual
β
Built-in per-agent delegation
Spend approval
β
β
Ask-before-pay dialog (MCP elicitation)
Generative UI
β
Rare
Order card + wallet panel (MCP Apps)
Open source
Varies
Varies
Yes (MIT)
β One wallet or one account key Β· β 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, or from card-funded credit on a BlockRun account through api.blockrun.ai. No subscriptions, no per-vendor signups.
Exact-usage account credit, no per-call network fee, no minimum
Identity
A keypair on your machine
An account with members, credits, and a usage ledger
Best for
Agents, solo devs, anything self-custody
Teams, companies, anyone who can't run a wallet
Trade on Polymarket
β
β β needs a keypair to sign
Both modes reach the same 19 tools. Account mode sends service calls to https://api.blockrun.ai by default. You can switch at any time; setting BLOCKRUN_API_KEY takes priority over a wallet, and unsetting it hands the wallet back.
1. Install
Claude Code (recommended)
bash
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
Every MCP client β one command or one JSON block. Verified = we ran the published package on that client and saw the tools listed (client version Β· date). Documented = install path from the client's own docs; not run by us yet β tell us if it works. The Spend dialog column is whether the client renders the human-in-the-loop payment prompt; on β clients paid calls proceed without asking and BLOCKRUN_BUDGET_LIMIT is the guard.
Client
Status
Spend dialog
Install
Claude Code
β Verified Β· 2.1.251 Β· 2026-08-30
β
claude mcp add blockrun -s user -- npx -y @blockrun/mcp@latest
Any other MCP client that can spawn a stdio server works the same way: command: npx, args: ["-y", "@blockrun/mcp@latest"]. With nvm/Homebrew Node on a JSON-configured client, put the absolute path from which npx in command. Spend-dialog sources and what "proceeds without asking" means: docs/spend-confirmation.md.
Grok β raise the startup timeout before you install, or the first run looks broken.
Grok waits startup_timeout_sec for an MCP server to answer, and it defaults to 30
(xAI's MCP docs). A first npx -y run has
to download this package and its dependency tree before the server can say anything, and
that is a race: measured cold, with an empty npm cache, it took 17s on a fast connection
and 42-46s on a slower shared box. Lose the race and grok mcp doctor blockrun says
server timed out (no response within 30s) and the UI shows blockrun [unavailable] β an
install that is working, timing out, and indistinguishable from broken.
Give it room in ~/.grok/config.toml (or .grok/config.toml for one project):
Only the FIRST run pays this: npx caches by exact spec, so the next start is warm (~9s
here). The same trap exists on any client with a startup timeout β if a fresh install
shows as unavailable and npx -y @blockrun/mcp@latest runs fine in a terminal, raise the
client's timeout or install globally before looking for anything else. Thanks to
@0xCheetah1 for the report.
OpenClaw: the published npx package was verified end-to-end on 2026.8.2: all 20 tools were projected (19 since the Surf delisting), free calls worked, and paid x402 calls settled. Add a hard session cap while installing:
bash
openclaw mcp set blockrun '{"command":"npx","args":["-y","@blockrun/mcp@latest"],"env":{"BLOCKRUN_BUDGET_LIMIT":"2"}}'
openclaw mcp doctor blockrun --probe
Spend confirmation depends on the OpenClaw runtime and chat surface. Its Codex harness supports MCP form elicitation, but an unmappable prompt is returned as an explicit decline; in the WebChat β Codex route tested here, BLOCKRUN_CONFIRM_SPEND=on declined paid calls without presenting an actionable dialog. Keep confirmation off on that route and rely on BLOCKRUN_BUDGET_LIMIT plus OpenClaw's own tool-approval mode.
blockrun_surf was removed in 0.49.0: the gateway has answered every Surf (asksurf.ai) path with 410 since 2026-09-06, so the tool could only ever return an error, and its schema cost every agent context on every turn. Those questions go to blockrun_price, blockrun_defi, blockrun_markets and blockrun_dex; the surf skill maps each former endpoint to its replacement.
An unknown profile name falls back to full. modal and phone are full-profile only.
What each profile costs your context
Installing an MCP server spends context on every turn, whether or not you call the tools β
the client loads each tool's schema into the model's prompt and re-sends it for the whole session.
Package managers have shown install size for decades. Almost no MCP server shows this. Ours:
Profile
Tools
Context
full(default)
19
14,265
trading
8
5,471
media
7
7,016
research
5
2,807
chat
3
2,155
Running --profile trading instead of the default costs 62% less context for the same trading
workflow. If you only ever ask about markets, that is the single cheapest change you can make.
Measure it yourself β against us, or against any other stdio MCP server:
bash
npm i gpt-tokenizer
node scripts/measure-tool-schema.mjs # this server, every profile
node scripts/measure-tool-schema.mjs -- npx -y @some/other-mcp-server
How the number is computed, and why it is a slight under-count
It counts the model-visible projection β {name, description, input_schema} per tool, with the
mcp__blockrun__ prefix the host prepends β because that is what lands in the API tools array.
It excludes annotations, _meta and outputSchema, which the host consumes and never forwards
to the model (a further ~3.7% on the wire).
The tokenizer is o200k_base. Claude's tokenizer is not public and runs a few percent higher on
JSON, so every figure here is a slight under-count, never an over-count.
Two caveats worth stating plainly. Tool schemas sit at the front of the prompt and are covered by
prompt caching, so after the first turn they re-send at cache-read rates β the context-window
cost is 100% every turn, the dollar cost is roughly a tenth of that. And 54% of our own cost is
tool descriptions, not schemas, which is where the remaining work is.
For a complete live signal β order-preview presentation, use
[`skills/signal-to-trade-demo/SKILL.md`](skills/signal-to-trade-demo/SKILL.md)
with the [Stanford runbook](docs/stanford-trading-demo.md).
3. Add funds
Option A β API key + account credit (no wallet). Sign in at user.blockrun.ai with Google. This is the dashboard for keys, credits, and activity; the MCP uses the key to call api.blockrun.ai for the actual services.
Dashboard β Keys β mint a key. It looks like brk_live_β¦ and is shown once.
Point the server at it. By default, account-mode calls go to https://api.blockrun.ai:
bash
claude mcp add blockrun -s user -e BLOCKRUN_API_KEY=brk_live_β¦ -- npx -y @blockrun/mcp@latest
Or export BLOCKRUN_API_KEY=brk_live_β¦ in the environment the client launches from.
If your client makes environment variables awkward, write the key to
~/.blockrun/.api-key instead (chmod 600) β same file directory the
wallet uses. The environment variable wins when both are present.
4. Dashboard β Activity β every call, priced at exact usage.
Verify with blockrun_wallet action:"status" β it reports the account, its real
balance, and what this session has spent:
code
Paying with: BlockRun account API key (no wallet, no chain)
Account: acme (gated)
Credit remaining: $12.5000 of $50.00 granted
Top up: https://user.blockrun.ai/dashboard/credits
Invoiced accounts show Spent to date: $4.5239 (invoiced account β no prepaid ceiling) instead. If the account is blocked, status says so and why before you spend a call finding out.
Option B β wallet (no account). Run blockrun_wallet to see your addresses. New installs default to Solana; send USDC (SPL) on Solana from Coinbase (pick "Solana"), Phantom, Solflare, or Backpack. To pay on Base instead: blockrun_wallet action:"chain" chain:"base", then send USDC on Base. Full instructions: Fund your wallet.
"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. In wallet mode, and only after your confirmation, it can also place the trade with blockrun_polymarket. In API-key mode, the data/media/research calls run through api.blockrun.ai; Polymarket trading still requires a local keypair to sign.
5. Install the agent skills (optional)
The package ships 17 skills β which tool answers what, worked examples, and a setup / debug / upgrade trio so the agent can install, troubleshoot and update the server on its own.
skills list shows what ships; --only a,b picks; --force refreshes copies after an upgrade.
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.0085 on Base β $0.0075 + the $0.001 network fee)
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
Tool
Data source
Cost
blockrun_chat
91 LLMs (GPT, Claude, Gemini, DeepSeek, Kimi K3, GLM, NVIDIA free tier, β¦) with mode tier routing
xAI Grok Imagine Video 1.0/1.5 + 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; reference images, video and audio on the account rail
$0.053β0.32/sec charged; reference clips billed at the model's ceiling (15.2s on 2.0, 30.2s on 2.5)
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)
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_exa
Neural web search (Exa) β research, competitors, papers, URL content
$0.01 + fee/query
blockrun_search
Grok Live Search β web + news with citations
$0.08 flat + network fee
blockrun_dex
Live DEX prices via DexScreener
free
blockrun_rpc
Raw JSON-RPC on 40 chains (Ethereum, Base, Solana, Bitcoin, Sui, NEAR, β¦) via Tatum
Flat data prices are the base. In wallet mode the gateway adds its flat network fee on top β $0.001 per call on Base today, and the Solana gateway quotes the base alone; the account rail charges no fee. The exact figure is in the payment-required header of any unpaid request, which is free to ask for. The server reserves $0.002 for the fee against the budget cap, so the spend-confirmation dialog and the cap reservation run $0.001 high per call by design. The blockrun_wallet action:"report" ledger books the observed fee instead ($0.001 on Base, none on Solana or the account rail), or the settled amount when the account rail reports one.
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_markets reads, blockrun_polymarket action:"buy" places. Gasless, confirm-gated.
Smart-money forensics β "This Polymarket whale β who are they, which wallets are theirs, what's their P&L?" β blockrun_marketspolymarket/wallet/identity/:wallet + .../cluster
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
Raw chain reads, 40 chains β "Latest Base block, and this contract's USDC balance." β blockrun_rpc
π 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.
# 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/.session by default; a BLOCKRUN_WALLET_KEY env var or an existing agent wallet.json takes precedence β setup prints the actual signer address). It is the only key to both the payment wallet and the Polymarket deposit wallet.
π‘οΈ Human-in-the-loop payments
Turn on BLOCKRUN_CONFIRM_SPEND=on and every paid tool pauses before it signs. The server sends an MCP elicitation; your client renders it as a dialog with the estimated charge:
code
πΈ BlockRun charge β video Β· bytedance/seedance-2.5 Β· 10s
Estimated: $2.6500
Approve this spend? (USDC is debited per call.)
To stop the charge, choose Decline β Cancel/ESC lets it proceed.
[ ] Approve all BlockRun charges for the rest of this session (don't ask again)
[ Decline ] [ Approve ]
Decline β nothing is sent, nothing is charged, the tool reports "Charge declined". Approve β the call proceeds. Tick the box and you're not asked again for the session. Free calls never prompt. Set BLOCKRUN_CONFIRM_THRESHOLD=0.05 to only be asked above $0.05.
bash
claude mcp add blockrun -s user -e BLOCKRUN_CONFIRM_SPEND=on -e BLOCKRUN_CONFIRM_THRESHOLD=0.05 -- npx -y @blockrun/mcp@latest
Client
Dialog
Client
Dialog
Claude Code
β
Claude Desktop
β οΈ renders; OK reports cancel β proceeds
Cursor
β
Windsurf
β proceeds without asking
VS Code Copilot
β
Codex CLI Β· Gemini CLI
β proceeds without asking
On a client that can't ask, the gate fails open β the call proceeds and the cost footer reports the charge. The hard stop on every client is the budget: BLOCKRUN_BUDGET_LIMIT for the process, blockrun_wallet action:"delegate" per sub-agent. blockrun_polymarket keeps its own, stronger per-order confirm:true.
On hosts that support the MCP Apps extension β Claude Desktop, claude.ai, VS Code, Cursor, ChatGPT β two tools render as interactive cards instead of text. Everywhere else (Claude Code, Codex, terminals) nothing changes.
Β Β Β
Order card on blockrun_polymarket_read action:"preview" β question, outcome, side, best quote, est. shares, notional, cap meter, session ledger. Edit the amount β Re-quote. Place order is arm-then-confirm and asks the host to call blockrun_polymarket β¦ confirm:true, so the host's consent prompt and every server cap (POLYMARKET_MAX_BET_USD, session cap) still apply.
Wallet panel on blockrun_wallet β both chains' balances, switch chain, copy address, EIP-681 / Solana Pay QR, explorer, Buy USDC with card.
Paying with an API key instead? There is no wallet to fund β top up credit by card or wire at user.blockrun.ai/dashboard/credits. The MCP will use that key against api.blockrun.ai and skip the wallet rail entirely.
The server keeps two wallets β one on Solana, one on Base β and pays from one at a time. Run blockrun_wallet to see both addresses, balances, and which is active.
blockrun_wallet action:"setup" # shows the Solana address + funding QR
Send USDC (SPL) on the Solana network β from Coinbase (pick "Solana"), Phantom, Solflare, or Backpack.
Pay on Base
One tool call β no env vars, no file editing, no restart:
code
blockrun_wallet action:"chain" chain:"base" # provisions + activates the Base wallet
blockrun_wallet action:"setup" # shows the Base address + funding QR
blockrun_wallet action:"deposit" β Coinbase Onramp, Base only
Switch back with blockrun_wallet action:"chain" chain:"solana". Switching only changes which wallet pays; both keep their balances.
Upgrading from an older version? Nothing moves. The Solana-first default applies only to installs with no wallet and no saved chain preference β if you already have a Base wallet, you stay on Base until you switch.
What each mode reaches
Almost everything now settles on either chain. The exceptions:
Capability
API key
Solana wallet
Base wallet
Chat, image, video, music, speech, RealFace
β
β
β
Search, Exa, markets, RPC, DEX, phone
β
β
β
blockrun_defi (DefiLlama)
β
β not served on the Solana gateway
β
blockrun_modal (sandboxes)
β
β not configured on the Solana gateway
β
Native Anthropic claude-* passthrough
β
β the SDK signs EIP-3009 only
β
Polymarket trading
β needs a keypair
β
β
blockrun_wallet balance / deposit / QR
β no wallet
β
β
blockrun_realface action:"list"
β indexed by wallet address
β
β
A blocked capability returns a message naming the fix, not a raw error.
What a call costs, and how sure we are
Mode
Reported cost
API key β most tools
The amount actually settled, read from the account API's per-call response
API key β blockrun_chat
An estimate. Chat settles after the response by design, so no figure exists when the answer is sent
API key β blockrun_image
The amount actually settled (since 0.49.0); only when the account API returns no figure does it fall back to the catalog estimate, marked ~
Wallet
The amount signed and settled on-chain, from the 402 quote
Anything estimated is printed with a ~ and says so. Estimates run high on
the account rail β they add a transaction fee it does not charge β so a budget
cap trips early rather than late. The source of truth is always
Dashboard β Activity.
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, 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_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.
A declined spend confirmation is the user's decision. Report it and stop β never re-issue the call with a cheaper model, smaller parameters, or split requests to get under their threshold.
Showcase
Posters generated through blockrun_image with openai/gpt-image-2 β each a single API call routed through BlockRun, paid from either account credit or a USDC wallet.
BlockRun at the Cornell Blockchain Conference 2026, packed booth
BlockRun at the Cornell Blockchain Conference 2026
$0.011/call on Base ($0.01 + fee), or exact account usage via api.blockrun.ai
Polymarket
Undocumented, rate-limited
$0.0085/call on Base ($0.0075 + fee), or exact account usage for reads β plus wallet mode can trade
DefiLlama
Free tier, rate-limited, no SLA
$0.006/call on Base ($0.005 + fee), or exact account usage via api.blockrun.ai
Multiple sources
3 accounts, 3 API keys, 3 billing pages
1 wallet, or 1 BlockRun account key
One wallet, or one dashboard-backed API key. All sources.
Configuration
Environment variables & files
Variable / File
Default
Effect
BLOCKRUN_API_KEY
unset
A BlockRun account key (brk_live_β¦) from user.blockrun.ai/dashboard/keys. Set β account billing through api.blockrun.ai: no wallet is created, read or used, and no chain applies. Takes priority over every wallet setting below. A malformed value is a startup error, never a silent fall back to the wallet.
~/.blockrun/.api-key
not created
The same key on disk, for clients that make env vars awkward. Read only when BLOCKRUN_API_KEY is unset; an empty or unreadable file falls through to wallet mode.
BLOCKRUN_API_BASE_URL
https://api.blockrun.ai
Account API service endpoint used after you get a key at user.blockrun.ai. Override only for staging. Accepts the OpenAI-style β¦/v1 form too.
~/.blockrun/.session
created on the first blockrun_wallet call (with .solana-session)
EVM private key (0xβ¦). Which chain pays is the priority list below, not this file's existence. 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
created on the first blockrun_wallet call (with .session)
Solana private key β the funded wallet on a new install. Which chain pays is the priority list below.
SOLANA_WALLET_KEY
unset
Env override of .solana-session. Set β use Solana.
BLOCKRUN_KEYCHAIN
auto
Key storage. auto β mirror the key into the OS keychain (macOS Keychain / Linux secret-tool) and keep the plaintext file, which stays authoritative so other BlockRun tools keep working and so replacing it still rotates your wallet. off β file only. strict β also delete ~/.blockrun/.session once a read-back proves the keychain holds the same key; this breaks other tools that read that file directly.
BLOCKRUN_MCP_PROFILE
full
Tool profile (media / trading / research / chat).
BLOCKRUN_BUDGET_LIMIT
unset (unlimited)
Hard USD cap on spend for this server process (both rails). In-memory; resets on restart. Per-agent caps via blockrun_wallet action:"delegate".
BLOCKRUN_CONFIRM_SPEND
off
on β ask before every paid call via MCP elicitation. Details. Fails open on clients without elicitation.
BLOCKRUN_CONFIRM_THRESHOLD
0
Only ask for calls estimated above this many USD. Malformed values fall back to 0 (ask for everything), never to "off".
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.
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), highest first: .chain preference β SOLANA_WALLET_KEY β .chain-auto pin β non-empty .solana-session β Solana key in the OS keychain β an existing Base wallet keeps Base β otherwise Solana (a fresh install with no wallet at all).
That second-to-last step is the upgrade guard: without it, flipping the default to Solana would move every existing Base-only user onto an empty wallet, and their next paid call would fail on a zero balance with nothing on screen explaining why. None of this applies in account mode β BLOCKRUN_API_KEY has no chain.
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
π€ Hand this to the agent: the blockrun-debug skill carries every row below as symptom β cause β fix, plus the diagnostics it can run itself. blockrun-setup and blockrun-upgrade cover the other two halves. Install: npx -y @blockrun/mcp@latest skills install.
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.
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. Whether it cost anything depends on the rail, and the error says which: on the Base wallet payment settles on completion, so it is not charged and a retry is safe; on Solana music and every account-rail media job the gateway bills at submit, so the job is charged, the error names it, and re-running bills a second one β check blockrun_wallet action:"report" instead.
blockrun_price says Equity quotes are not served (gateway 501 β¦) β Equity price/history were withdrawn on 2026-09-05; not an outage, and nothing was charged (the wallet is never asked to sign). The ticker catalog (action:"list" category:"stocks") is still free. Equity coverage: hello@blockrun.ai.
blockrun_markets on sports/* fails β before 0.49.0 as API error after payment: 502 with no balance change β Predexon's sports/* routes have been down upstream since 2026-08-04; the gateway releases the payment on that upstream 500, so the call is not charged (the error says so when the gateway's "payment NOT charged" confirmation is in the response; otherwise it tells you to check blockrun_wallet action:"report"). For sports odds use path:"markets/search" with params:{ q: "NBA" }, or polymarket/events with params:{ search: "NBA" } β the bare markets route and its league filter were removed upstream on 2026-08-04 and 404 before payment. Upgrade to β₯ 0.49.0 so the error says all of this itself.
No spend-confirmation dialog although BLOCKRUN_CONFIRM_SPEND=on β Your client doesn't support MCP elicitation (Windsurf, Codex, Gemini CLI); the server proceeds without asking by design. Use BLOCKRUN_BUDGET_LIMIT as the guard, or a client from the support table.
Polymarket: neg-risk ("winner") market buy fails, or redeem reverts, though setup shows ready β Re-run action:"setup" confirm:true once (grants the on-chain approvals a pre-upgrade deposit wallet may lack β including the collateral-adapter approvals redeem needs). 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 β from a self-custody wallet or a BlockRun account key.
Do I need an API key or an account?
No. A wallet is auto-created locally on first run; you fund it with USDC and there are no signups, dashboards or keys to rotate.
But you can have one. If your team can't hand a wallet to an agent, sign in at user.blockrun.ai, mint a key at Dashboard β Keys, top up account credit by card or wire at Dashboard β Credits, and set BLOCKRUN_API_KEY. The MCP then sends paid service calls to api.blockrun.ai and bills exact usage against that account credit β no $0.001 per-call network fee, no per-call minimum β with a ledger at Dashboard β Activity. Everything works except the parts that genuinely need a keypair: Polymarket trading, wallet balances/top-ups, and the wallet-indexed blockrun_realface action:"list".
Which is cheaper?
Account billing, slightly β it charges exact metered usage with no per-call minimum and no $0.001 transaction fee. Wallet mode buys you self-custody and Polymarket trading instead.
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 or account credit 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?
Any MCP client that can spawn a stdio server. Verified on Claude Code and Codex CLI, in daily use on OpenClaw; install paths documented for Claude Desktop, Cursor, VS Code, Gemini CLI and Windsurf β see the client table. The spend-confirmation dialog additionally needs MCP elicitation (Claude Code, Cursor, VS Code).
Does it have a UI?
On MCP-Apps hosts (Claude Desktop, claude.ai, VS Code, Cursor) the Polymarket preview is a live order card and the wallet is a panel β see MCP Apps β. Terminal clients get the same information as text.
Can I make the agent ask before it spends?
Yes β BLOCKRUN_CONFIRM_SPEND=on. Every paid tool pauses with the estimated charge and nothing is signed until you approve. Human-in-the-loop payments β
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, Solana or Arc?
All three. Switch instantly with blockrun_wallet action:"chain". Arc (Circle's chain) pays from the same address as Base, funded with USDC on Arc, and serves everything Base does. Three things are Base-only, and each says so when you call them on Solana: blockrun_defi (DefiLlama) and blockrun_modal, which the Solana gateway does not serve, and claude-* chat with thinking (the native /v1/messages path pays on Base; a plain claude-* call takes the compat path on Solana). Media generation, markets, search and Polymarket all settle on either chain.
From the BlockRun ecosystem
BlockRun is agent-native AI infrastructure β one wallet with x402 USDC micropayments, or one account API key with card-funded credit, across every surface:
β‘ ClawRouter β the agent-native LLM router for OpenClaw. 91 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.