# blockrunai/blockrun-mcp [Health: Active]

**Category:** 🔗 Aggregators  
**Repository:** https://github.com/blockrunai/blockrun-mcp  
**GitHub Stars:** 392  
**npm Downloads (last month):** 3589  
**Views:** 7  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/blockrunai-blockrun-mcp

## Description
Access 30+ AI models (GPT-5, Claude, Gemini, Grok, DeepSeek) without API keys. Pay-per-use via x402 micropayments with USDC on Base.

## Tools
Capabilities this server exposes over MCP:

- **blockrun_wallet** — 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 before spawning child agents.

If this server is running on a BlockRun API key (BLOCKRUN_API_KEY), there is no
wallet and no chain: status reports the account, and setup/qr/deposit/chain do
not apply. Credit is managed at https://user.blockrun.ai/dashboard/credits.

In wallet mode the server holds TWO wallets — one on Solana, one on Base — but
pays on ONE active chain at a time. status shows both addresses/balances and
which is active. New installs default to Solana; an existing Base wallet keeps
Base until you switch.

To switch chain (no env vars, no file editing, no restart):
  1. action:"chain" chain:"solana"   → provisions + activates the Solana wallet
  2. action:"setup"                   → address + funding QR for the active chain
Switch back with action:"chain" chain:"base". Almost everything now settles on
either chain; only blockrun_defi (DefiLlama) and blockrun_modal are Base-only,
plus native Anthropic (claude-*) in blockrun_chat.

Actions:
- status (default): Both wallet addresses + USDC balances, active chain, session spending
- deposit: Buy USDC with a card — mints a one-time Coinbase Onramp link and opens it in the browser (Base only; funds settle into your own wallet). Paid tools auto-open this on an out-of-funds failure; call it directly to fund up front.
- setup: Get funding instructions + QR code for the ACTIVE chain (call this when balance is 0)
- qr: Open QR code (active chain) in system viewer
- chain + chain:"base"|"solana": Switch the active payment chain (omit chain: to just see the current one)

Budget controls:
- budget + budget_action:"set" + budget_amount:1.00 → Set global spend cap
- budget + budget_action:"check" (the default) → Report the cap, spend and remaining
- budget + budget_action:"clear" → Remove a cap set here
If the operator started the server with BLOCKRUN_BUDGET_LIMIT, that value is a
ceiling this tool can only lower: set above it is clamped, clear restores it,
and agent_limit is clamped to it. Only a restart with a new env raises it.

Multi-agent orchestration:
- delegate + agent_id:"research" + agent_limit:2.00 → Allocate $2 to a child agent
- revoke + agent_id:"research" → Remove a child agent's cap (its spend is kept; re-delegating the id carries it)
- report → See per-agent spending breakdown

Usage pattern for multi-agent systems:
  1. blockrun_wallet action:"delegate" agent_id:"worker-1" agent_limit:1.00
  2. Pass agent_id:"worker-1" to all blockrun_chat/search/etc calls for that agent
  3. blockrun_wallet action:"report" to audit spending

Do NOT call this for actual AI queries — use blockrun_chat for that.
- **blockrun_chat** — Get a second opinion from another AI model, or use a specialized model for a specific task.

Notable modes:
- mode:"powerful" → Claude Opus 5, Claude Opus 4.8, GPT-5.6-sol, Claude Fable 5 (frontier, 1M context)
- mode:"reasoning" → Claude Opus 5, GPT-5.6-sol, Kimi K3, Grok 4.3, deepseek-v4-pro
- mode:"coding" → Claude Opus 5, GPT-5.3-codex, Kimi K3, Grok Build, GLM-5.2
- mode:"cheap" → deepseek-v4-pro, Qwen3.7 Flash, MiniMax M3, Tencent Hy3
- mode:"glm" → Zhipu GLM-5 / 5.2 / 5.1 / 5-Turbo (strong at coding)
- mode:"free" → free models (no cost)

Pick directly: model:"anthropic/claude-opus-5", model:"moonshot/kimi-k3", model:"openai/gpt-5.6-sol", model:"xai/grok-4.5", model:"nvidia/gpt-oss-120b" (free).

Run blockrun_models to see all available models with pricing.
- **blockrun_models** — List available AI models with pricing. Use to discover models and compare costs.
- **blockrun_image** — Generate or edit images via BlockRun. Pays with USDC on the ACTIVE chain — Base or Solana (see blockrun_wallet) — 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-*):
- openai/gpt-image-2 ($0.06–0.12) — flagship, reasoning-driven, multilingual on-image text + character consistency (default)
- openai/gpt-image-1 ($0.02–0.04) — GPT native image generation
- google/nano-banana ($0.05) — Gemini-family image model
- google/nano-banana-2 ($0.09) — Gemini 3.1 Flash, pro-level quality at Flash speed (1024x1024 only)
- google/nano-banana-pro ($0.10; $0.15 at 4096px) — up to 4K, strongest photorealism
- xai/grok-imagine-image ($0.02) — stylized, fast
- xai/grok-imagine-image-pro ($0.07) — higher quality Grok Imagine
- zai/cogview-4 ($0.015) — cheapest, photorealistic detailed scenes
- bytedance/seedream-5-pro ($0.045; $0.09 when both dimensions exceed 1024) — Seedream 5.0 Pro; cheap widescreen at 1280x720 / 2048x1024, large formats up to 2848x1600

Edit (img2img) models: openai/gpt-image-2 (default), openai/gpt-image-1, google/nano-banana, google/nano-banana-2, google/nano-banana-pro
Multi-image edit: pass an array of 2–4 source images to "image" to fuse them in one render (openai/* up to 4, google/* up to 3) — e.g. a subject plus a sprite layout guide, or a reference plus a brand logo.
Source images and masks accept a base64 data URI, an http(s) URL, or a local file path (auto-encoded). Inpaint mask (openai/gpt-image-* only) via "mask"; not combinable with multiple source images.
- **blockrun_music** — Generate music tracks via BlockRun x402 (async, client-polled).

Generates a full-length ~3 minute MP3 track. Takes 1-3 minutes to complete. The
tool submits the job and, for slower tracks, polls until it is ready. On the
Base wallet payment settles only when a finished track is returned — if the
job fails you are not charged; if this client gives up while a paid request is
still in flight the gateway may still settle, and the error text says so. On
Solana and on the account rail the job is billed when the gateway ACCEPTS it,
so a job that later fails or outlives the poll budget is still charged — the
error text says so and names the job, which stays claimable for ~48h.

Model: minimax/music-2.5+ ($0.1575/track, up to ~4 min)

Returns a permanent BlockRun-hosted URL.
- **blockrun_speech** — AI voice via BlockRun x402 — speak text aloud (ElevenLabs or ByteDance Seed Audio), 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 effects from a text prompt, up to 22s ($0.0525/clip)
- voices: list available voices (free)

Models (speak): elevenlabs/flash-v2.5 ($0.05/1k chars, ~75ms, default), elevenlabs/turbo-v2.5 ($0.05/1k), elevenlabs/multilingual-v2 ($0.10/1k, narration), elevenlabs/v3 ($0.10/1k, most expressive), bytedance/seed-audio-1.0 (~$0.003/sec of output, est. from input length; max 3k chars in / 120s out) — prompt-DIRECTED audio: describe the voice, emotion, and sound staging in the input text itself ("a tired detective mutters, rain in the background: ..."); the voice parameter is ignored.

Voice aliases (ElevenLabs models only): sarah (default), george, laura, charlie, river, roger, callum, harry — or any raw ElevenLabs voice_id.

Returns a hosted audio URL — download immediately if you need to keep the file.
- **blockrun_video** — Generate short AI videos via BlockRun x402 on the active Base or Solana chain (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; 9 min Base / 15 min Solana hard cap). On the wallet rails payment settles only when upstream returns a finished video — if the job fails you are not charged; if this client gives up while a paid poll is still in flight the gateway may still settle, and the error text says so. On the account rail the job is billed when the gateway accepts it, so a job that fails or outlives the poll budget is still charged — the error names it.

Models. Every rate below is what you are CHARGED (margin and transaction fee included), at the 720p baseline Seedance renders by default with synced audio:
- azure/sora-2 (~$0.105/sec, 720p + synced audio, text- or image-to-video) — OpenAI Sora 2 via Azure AI Foundry. duration_seconds must be 4, 8, or 12 (4s default -> ~$0.42/clip). image_url takes a NON-HUMAN reference image (faces are rejected upstream by moderation — use Seedance + RealFace for real people); same price as text-to-video. No RealFace, no last_frame_url. Base only for now: the Solana gateway quotes it as Seedance 2.0 at $1.135 and the tool refuses that quote unsigned.
- xai/grok-imagine-video ($0.05/sec at 480p default, $0.07/sec at 720p; 8s default -> $0.401/clip, 1-15s) — stylized, fast. 480p/720p only.
- bytedance/seedance-1.5-pro (~$0.071/sec, 4-12s, 5s default -> ~$0.35/clip) — cheapest Seedance, token-priced upstream
- bytedance/seedance-2.0-mini (~$0.080/sec, 4-15s, 5s default) — 2.0-generation quality at roughly half the 2.0-fast rate; 720p ceiling; supports RealFace and first/last-frame
- bytedance/seedance-2.0-fast (~$0.165/sec, 4-15s, ~60-80s gen) — sweet-spot price/quality; supports BytePlus RealFace assets
- bytedance/seedance-2.0 (~$0.227/sec, 4-15s, up to 4K) — highest quality, and the ONLY model that renders true 4K; supports RealFace, first/last-frame and reference media
- bytedance/seedance-2.5 (~$0.315/sec, 4-30s, 5s default) — long-form: double 2.0's length ceiling, multilingual. NOT a strict upgrade — it caps at 720p and does NOT support RealFace or first/last-frame. Use 2.0 for 1080p/4K or real-person video.

Image-to-video is NOT cheaper than text-to-video on Seedance — same per-second rate. Higher resolutions ARE more expensive (token-priced: 1080p ~2.25x, 4K ~9x the 720p rate); the 402 quote is authoritative and is what gets charged.

RealFace: to generate video of a SPECIFIC real person, first enroll them with blockrun_realface (returns a ta_xxxx asset id), then pass real_face_asset_id here with seedance-2.0, seedance-2.0-fast, or seedance-2.0-mini. Mutually exclusive with image_url.

Returns a permanent blockrun-hosted MP4 URL (the gateway mirrors the asset to GCS so URLs don't expire).
- **blockrun_realface** — 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 / 2.0-mini generate video of a SPECIFIC real person — not a generic seed image. Only those three models: seedance-2.5 is numerically newer but does NOT accept ta_ assets, and seedance-1.5-pro never did. Enrollment is a multi-step flow because BytePlus requires a live phone liveness check (the real person nods + blinks on camera) before a face photo can be uploaded.

Actions:
- init: FREE. Create an asset group + a phone H5 link. The tool renders the link as a QR code and opens it; the real person scans it on their phone and completes the ~1 min liveness check. Pass group_id to refresh an expired link.
- status: FREE. Poll a group until status:"active" (ready_to_finalize:true). The H5 link is valid ~120s — re-init if it expires.
- enroll: PAID ($0.01). Settles on Solana or Base from a wallet, or against your BlockRun account key. After the group is active, upload a clear front-facing photo (image_url) of the SAME person. Returns the ta_xxxx asset id.
- portrait: PAID ($0.01). Settles on Solana or Base from a wallet, or against your BlockRun account key. Virtual Portrait — enroll an AI-GENERATED character from an image URL directly, NO liveness needed (one step: name + image_url → ta_xxxx). For fictional/AI characters only; for a real person use the init→status→enroll liveness flow.
- list: FREE, WALLET MODE ONLY (assets are indexed by wallet address). List the RealFace + Virtual Portrait assets enrolled by this wallet (their ta_xxxx ids + names) so you can pick one for blockrun_video.

Typical flow:
  1. blockrun_realface action:"init" name:"Alice"          → scan QR on phone, do liveness
  2. blockrun_realface action:"status" group_id:"legacy_rf_…"  → repeat until ready_to_finalize:true
  3. blockrun_realface action:"enroll" name:"Alice" group_id:"legacy_rf_…" image_url:"https://…/alice.jpg"  → ta_xxxx
  4. blockrun_video model:"bytedance/seedance-2.0" real_face_asset_id:"ta_xxxx" prompt:"…"

Privacy: BlockRun does not store face/liveness data — only the asset id, name, and the photo URL you supply.
- **blockrun_search** — Grok Live Search — real-time web + news with AI-summarized results and citations. PRICED PER SOURCE and expensive by default: $0.025 × max_results, +5% gateway buffer — default max_results=10 settles ~$0.26 (max_results=50 → ~$1.31). Pass a smaller max_results to cap spend; for a plain fact, 3 sources (~$0.08) is usually enough.

Common shape:
- body: { query: "...", sources: ["web","news"], max_results: 10, from_date: "YYYY-MM-DD", to_date: "YYYY-MM-DD" }

`sources` accepts any subset of ["web","news"] (default ["web"] — pass both for news coverage). There is no X/Twitter source (removed upstream 2026-07-05; asking for it is refused before payment). `max_results` is 1–50 (default 10) and drives the price — pass a smaller value if you want to cap spend.

Full request shape + worked examples in the `search` skill (`skills/search/SKILL.md`).
- **blockrun_exa** — 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.010 base + tx fee)
- answer       — body: { query }                                                              ($0.010 base + tx fee)
- contents     — body: { urls: [...] }                                                        ($0.002/URL + ONE tx fee, up to 100)
- find-similar — body: { url, numResults? }                                                   ($0.010 base + tx fee)
Tx fee = the gateway's flat network fee, $0.001 today (we reserve $0.002); the 402 header carries the exact charge.

Categories for search: "news", "research paper", "company", "tweet", "github", "pdf".

Full request/response shapes + worked research workflows in the `exa-research` skill.
- **blockrun_markets** — Prediction market + derivatives data via Predexon aggregator. Flat $0.0075 base per call (every endpoint) plus the gateway's network fee — $0.001 on Base today, none quoted on Solana; the 402 header carries the exact charge (we reserve $0.0095).

POLYMARKET (Tier 1):
- polymarket/events, polymarket/markets — list events/markets (filter, sort, paginate)
- polymarket/markets/keyset, polymarket/events/keyset — same data, cursor-based keyset pagination (params: { pagination_key })
- polymarket/crypto-updown — crypto up/down markets
- polymarket/market-price/:token_id — current/historical price
- polymarket/candlesticks/:condition_id — OHLCV by market
- polymarket/candlesticks/token/:token_id — OHLCV by single outcome token
- polymarket/volume-chart/:condition_id — volume w/ YES/NO split
- polymarket/orderbooks, polymarket/trades, polymarket/activity
- polymarket/markets/:token_id/volume, polymarket/markets/:condition_id/open_interest
- polymarket/positions — user positions
- polymarket/leaderboard, polymarket/leaderboard/market/:condition_id
- polymarket/cohorts/stats, polymarket/market/:condition_id/top-holders
- polymarket/uma/markets, polymarket/uma/market/:condition_id — UMA oracle questions/timeline

POLYMARKET (Tier 2 — wallet/smart-money analytics):
- polymarket/wallet/:wallet — full smart-wallet profile
- polymarket/wallet/:wallet/markets, .../similar
- polymarket/wallet/pnl/:wallet, .../positions/:wallet, .../volume-chart/:wallet
- polymarket/wallets/profiles — batch profiles, GET with params: { addresses } (POST 404s); polymarket/wallets/filter — AND/OR filter
- polymarket/market/:condition_id/smart-money, polymarket/markets/smart-activity

WALLET IDENTITY & CLUSTERING (Tier 2) — cross-context labels + on-chain relationship graph:
- polymarket/wallet/identity/:wallet — fetch identity + profile metadata for one wallet
- polymarket/wallet/identities — POST { addresses: [...] } for bulk lookup (up to 200 wallets)
- polymarket/wallet/:address/cluster — discover wallets connected via on-chain transfers + identity proofs

SPORTS — sports/* (categories, markets, markets/:game_id, outcomes/:predexon_id) DEGRADED, do not call: Predexon 500 on every call since 2026-08-04; the gateway releases the payment on that upstream 500. Use markets/search { q: "NBA" } or polymarket/events { search: "NBA" } instead — no live route takes a "league" param.

KALSHI: kalshi/markets, kalshi/trades, kalshi/orderbooks
LIMITLESS / OPINION / PREDICT.FUN: {platform}/markets, {platform}/orderbooks
BINANCE FUTURES: binance/candles/:symbol, binance/ticks/:symbol

CROSS-PLATFORM:
- markets/search — search every venue in one call (search term is "q"). The only canonical-layer route left: markets, markets/listings, outcomes/:id and matching-markets(/pairs) were removed upstream 2026-08-04 and 404 before payment.

REQUEST CONTRACTS:
- Discover current markets with markets/search (its search term is "q"), then resolve the chosen Polymarket market with polymarket/markets/keyset and condition_id.
- On polymarket/markets{,/keyset} the free-text filter is "search" (NOT "q"), and status:"open"/"closed" replaces Gamma's active/closed. "sort", "end_after", and "end_before" are supported; "order"/"ascending" are not.
- Candlesticks interval is integer minutes ("1440", not "1h"); it is OPTIONAL (the server defaults). Which intervals a market serves varies — 1440 may work where 60 does not. start_time/end_time are Unix seconds.
- polymarket/orderbooks requires token_id plus start_time/end_time in Unix milliseconds.
- Smart-money needs a smart-wallet CRITERION (min_trades, min_volume, min_roi, min_*_pnl, min_win_rate, min_profit_factor). "window" only scopes time and is NOT sufficient on its own. Default: { window: "30d", min_trades: "100" }.

Pass query params via 'params' (GET) — a '?' in 'path' is refused before payment, because path-carried values bypass the pre-payment checks above. Use 'body' only for POST endpoints (e.g. polymarket/wallet/identities).
- **blockrun_price** — Realtime quotes and OHLC history for crypto, FX and commodities (Pyth-backed), plus the ticker catalog for 12 stock markets.

- action="price" — realtime quote for a symbol
- action="history" — OHLC bars between from/to (unix seconds)
- action="list" — discovery: list available symbols (free)

Pricing:
- crypto / fx / commodity: FREE across price, history and list
- stocks / usstock: list (ticker catalog) FREE; price/history NOT SERVED — gateway 501 before payment since 2026-09-05, nothing charged, do not retry

Stocks markets: us, hk, jp, kr, gb, de, fr, nl, ie, lu, cn, ca (required when category="stocks").

Examples:
- { action: "price", category: "crypto", symbol: "BTC-USD" }
- { action: "price", category: "fx", symbol: "EUR-USD" }
- { action: "history", category: "crypto", symbol: "ETH-USD", resolution: "D", from: 1700000000, to: 1710000000 }
- { action: "list", category: "crypto", query: "sol" }
- **blockrun_dex** — 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: "So11...xxx" })    -> Get specific token data
  blockrun_dex({ symbol: "PEPE" })         -> Search by symbol
- **blockrun_modal** — 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/H100 — those five only), or a safer place for untrusted code. Prefer local tools for normal repo work.

⚠️ `timeout` IS THE BILLED LIFETIME — charged upfront in full, NEVER refunded. It is not an idle timeout: you pay for the time you ASK for, not the time you use, and terminating early refunds nothing. Ask for what you need, not a safe-looking ceiling.
- timeout ≤ 300s → flat: $0.0120 CPU · $0.0520 T4 · $0.0820 L4 · $0.1020 A10G · $0.2020 A100 · $0.4020 H100
- timeout > 300s → PER-HOUR × the full requested lifetime: $0.10/h CPU · $1.50 T4 · $2.00 L4 · $2.50 A10G · $4.00 A100 · $8.00/h H100
  e.g. { timeout: 600, gpu: "A100" } = $0.6687 · { timeout: 86400, gpu: "H100" } = $192.00

Common paths (all POST):
- sandbox/create     — body: { image?, timeout?, cpu?, memory?, gpu?, setup_commands? }    (see above — $0.0120 to $192.00)
- sandbox/exec       — body: { sandbox_id, command: ["python","-c","..."], timeout? }      ($0.0030)
- sandbox/status     — body: { sandbox_id }                                                ($0.0030)
- sandbox/terminate  — body: { sandbox_id }                                                ($0.0030)

Full pricing tables + GPU details in the `modal` skill.
- **blockrun_phone** — 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)
- phone/numbers/buy          POST body: { country?: "US"|"CA", areaCode? } — 30-day lease       ($5.00)
- phone/numbers/renew        POST body: { phoneNumber } — extend 30 days                        ($5.00)
- phone/numbers/list         POST body: {} — your wallet-owned numbers                          ($0.001)
- phone/numbers/release      POST body: { phoneNumber } — release back to pool                  (free)
- voice/call                 POST body: { to, task, from, voice?, max_duration?, ... }          ($0.54 flat)
- voice/call/{call_id}       GET (no body) — poll status + transcript                           (free)

REQUIRED for voice/call: `from` must be a number your wallet owns. Provision one with `phone/numbers/buy` first ($5, 30-day lease).

Voice presets: nat, josh, maya, june, paige, derek, florian. Phone numbers use E.164 format (e.g. +1 followed by 10 US digits, or +<country-code><number>).

Voice call flow + voice preset details + full body shapes in the `phone` skill.
- **blockrun_rpc** — Raw JSON-RPC against 40+ blockchains — one endpoint, no node, no API key. $0.002 base per call plus the gateway's flat tx fee ($0.001 today; we reserve $0.002, so budget/confirm show $0.004 per single call). A JSON-RPC batch charges $0.002 per element plus ONE fee — batch when you can.

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.

Networks (full catalog in the rpc skill): ethereum, base, arbitrum, optimism, polygon, bsc, avalanche, solana, bitcoin, sui, near, ripple, polkadot, dogecoin, litecoin, monad, berachain, unichain, hyperevm, sonic, and 20+ more.

Examples:
  blockrun_rpc({ network: "ethereum", method: "eth_blockNumber" })
  blockrun_rpc({ network: "base", method: "eth_getBalance", params: ["0xabc...", "latest"] })
  blockrun_rpc({ network: "solana", method: "getSlot" })
  blockrun_rpc({ network: "bitcoin", method: "getblockchaininfo" })
  blockrun_rpc({ network: "ethereum", body: [{jsonrpc:"2.0",id:1,method:"eth_blockNumber"},{...}] })  // batch

Prefer blockrun_price (free quotes) or blockrun_dex (free DEX data) when they cover the question — this tool is for raw chain access.
- **blockrun_defi** — DeFi fundamentals via DefiLlama — protocol TVL, chain TVL, yield pools (APY), token prices. Pays per call in USDC, no API key.

Paths (GET only; price = base + the gateway's flat tx fee, $0.001 today — we reserve $0.002; the 402 header carries the exact charge):
- protocols                      ($0.005 base) — all DeFi protocols ranked by TVL
- protocol/{slug}                ($0.005 base) — one protocol's TVL history + chain breakdown, e.g. protocol/aave-v3
- chains                         ($0.005 base) — TVL by chain
- yields                         ($0.005 base) — yield pools with APY + TVL (large; filter client-side)
- prices/{coins}                 ($0.001 base) — token prices, coins like 'base:0x833589...,coingecko:ethereum'

Examples:
  blockrun_defi({ path: "protocol/uniswap-v3" })
  blockrun_defi({ path: "prices/coingecko:bitcoin,coingecko:ethereum" })
  blockrun_defi({ path: "chains" })

Use blockrun_price (free) for plain spot quotes, blockrun_dex (free) for DEX pairs — this tool is for protocol/TVL/yield fundamentals.
- **blockrun_polymarket_read** — Read or preview Polymarket state without signing or changing anything.

Actions:
- positions — holdings, current value, PnL, and redeemable status (free Data API)
- orders — open CLOB orders, optionally filtered by condition_id
- preview — build a live buy/sell order preview from the CLOB book. side plus token_id (or condition_id+outcome) are required. Market buys use amount_usd; limit orders use price+size. This action never accepts confirm and never signs or submits an order.

Use blockrun_polymarket only for setup and funds-affecting operations: confirmed buy/sell, cancel, redeem, fund, or withdraw.
- **blockrun_polymarket** — Trade on Polymarket prediction markets (CLOB V2, Polygon). REAL MONEY — orders spend pUSD held in your Polymarket deposit wallet, signed locally by your BlockRun key. Free tool (no BlockRun API charge); discover markets/prices/token IDs with blockrun_markets first.

Run action:"setup" FIRST (and again after funding). It creates a gasless deposit wallet owned by your key, checks pUSD balance + exchange approvals, and prints funding instructions. Zero config — no Polymarket account or API keys; setup bootstraps its credentials from your wallet key.

Actions:
- setup — create/inspect deposit wallet, funding, approvals (confirm:true to sign the approval batch), region check. Idempotent.
- fund — top up the deposit wallet from your OWN Base USDC, gasless (confirm:true). amount_usd required. BlockRun pays the gas + charges $0.01; you need no ETH. Non-custodial (USDC → Polymarket bridge → your vault).
- buy / sell — token_id (or condition_id+outcome) + either price+size (limit) or amount_usd (market buy) / size (market sell). confirm:true REQUIRED to place; omitting it returns a dry-run preview. Per-order cap: POLYMARKET_MAX_BET_USD (default $25).
- orders — list open orders (optional condition_id filter)
- cancel — order_id:"…" or all:true
- positions — holdings incl. redeemable winnings (free Data-API)
- redeem — claim resolved winnings for condition_id (confirm:true; gasless)
- withdraw — cash out pUSD → native USDC on Base to your agent wallet (confirm:true). amount_usd optional (default: full balance); to_address optional (default: your wallet).

Prices are probabilities 0–1 on the market's tick grid. token_id comes from blockrun_markets Polymarket data. Geoblock is handled by default (CLOB traffic routes through BlockRun's Finland egress) — setup reports your region status. Complying with Polymarket's terms for the user's jurisdiction is the user's responsibility.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "blockrun-mcp": {
    "command": "npx",
    "args": ["-y","@blockrun/mcp@latest"],
    "env": {
      "BLOCKRUN_API_KEY": "",
      "BLOCKRUN_BUDGET_LIMIT": "",
      "BLOCKRUN_CONFIRM_SPEND": "",
      "BLOCKRUN_KEYCHAIN": "",
      "POLYMARKET_MAX_BET_USD": ""
    }
  }
}
```

**Requires environment variables:** `BLOCKRUN_API_KEY`, `BLOCKRUN_BUDGET_LIMIT`, `BLOCKRUN_CONFIRM_SPEND`, `BLOCKRUN_KEYCHAIN`, `POLYMARKET_MAX_BET_USD` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What blockrunai/blockrun-mcp does

blockrunai/blockrun-mcp gives MCP clients a single interface to a broad set of paid and free services. Its tools cover AI model access, model discovery, web search, neural research, image generation and editing, music, speech, video, real-face enrollment, market and price data, DEX data, DeFi fundamentals, blockchain RPC, remote code execution, phone operations, and Polymarket read and trading workflows.

The server supports two payment paths. In wallet mode, it creates or uses local wallets and settles eligible calls in USDC through x402. Solana and Base are supported, with one active payment chain at a time. In account mode, `BLOCKRUN_API_KEY` routes calls through BlockRun account credit instead of a local wallet or blockchain payment.

## How it works

Install the npm package as an MCP process and connect it to an MCP client. Paid calls are charged per request, while selected capabilities such as free chat models, model listings, DEX data, and some price queries can be used without payment. `blockrun_wallet` reports balances, active-chain status, budgets, and agent spending allocations.

For multi-agent workflows, allocate a limit with `delegate`, pass the corresponding `agent_id` to that agent’s BlockRun calls, and use `report` to review spending. The wallet tool should also be used first when another BlockRun tool reports a payment or balance error.

Polymarket workflows separate discovery, read-only inspection, and trading. Use market data to find instruments, `blockrun_polymarket_read` for positions, orders, and previews, and `blockrun_polymarket` for confirmed operations such as buying, selling, redeeming, funding, or withdrawing.

## Setup and configuration

The repository publishes an npm package and requires Node.js 20.19 or newer. A Claude Code installation command is:

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

Wallet mode creates a wallet on first use. `blockrun_wallet` can show funding instructions or produce a card-funded Coinbase Onramp link on Base. The active chain can be switched without editing environment variables or restarting.

Account mode uses `BLOCKRUN_API_KEY` and account credit managed through BlockRun. Optional controls include `BLOCKRUN_BUDGET_LIMIT`, `BLOCKRUN_CONFIRM_SPEND`, `BLOCKRUN_KEYCHAIN`, and `POLYMARKET_MAX_BET_USD`.

## Tools and capabilities

- Call categorized LLMs through `blockrun_chat`, including direct model selection and free models.
- Compare available models and pricing with `blockrun_models`.
- Search the live web with Grok or perform neural research through Exa.
- Generate or edit images, music, speech, sound effects, and short videos.
- Enroll real-face or virtual-portrait assets for supported video models.
- Query prediction markets, crypto and other supported prices, DEX data, DeFi metrics, and raw blockchain RPC endpoints.
- Run disposable BlockRun-hosted sandboxes with optional GPUs.
- Provision phone numbers, inspect numbers, and place AI voice calls.
- Read and trade Polymarket positions and orders, with confirmation required for funds-affecting actions.

## Limitations and notes

Paid media and data calls consume wallet funds or account credit. Video and music operations are asynchronous and may take several minutes. Modal billing is based on the requested sandbox lifetime, including time not used. Polymarket trading uses real funds, and geographic or jurisdictional requirements remain the operator’s responsibility. Some capabilities are chain-specific: DefiLlama and Modal use Base, while native Anthropic chat models are Base-only. The project is MIT licensed.

_Full upstream README: https://allmcps.com/mcp/blockrunai-blockrun-mcp/readme_