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.

The server holds TWO wallets — one on Base, one on Solana — but pays on ONE active chain at a time. status shows both addresses/balances and which is active. Default chain is Base.

To pay on Solana (no env vars, no file editing, no restart):

1. action:"chain" chain:"solana" → provisions + activates the Solana wallet

2. action:"setup" → Solana address + funding QR (send USDC SPL on Solana) Switch back with action:"chain" chain:"base". Base-only — these ignore Solana and need Base: blockrun_music, blockrun_speech, blockrun_video, blockrun_realface, paid blockrun_price, blockrun_chat routing:"smart", and native Anthropic (claude-*). blockrun_image pays on either chain.

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:"clear" → Remove global spend cap

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 budget

• 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.

Get a second opinion from another AI model, or use a specialized model for a specific task.

Notable modes:

• mode:"powerful" → Claude Opus 4.8, GPT-5.6-sol, Claude Fable 5 (frontier, 1M context)

• mode:"reasoning" → Claude Opus 4.8, GPT-5.6-sol, Kimi K3, Grok 4.3, deepseek-v4-pro

• mode:"coding" → Claude Opus 4.8, GPT-5.3-codex, Kimi K3, Grok Build, GLM-5.2

• mode:"cheap" → deepseek-v4-pro, MiniMax M3, GLM-5, NVIDIA free

• mode:"glm" → Zhipu GLM-5 / 5.2 / 5.1 / 5-Turbo (cheap, strong at coding)

• mode:"free" → NVIDIA models (no cost)

Pick directly: model:"moonshot/kimi-k3", model:"openai/gpt-5.6-sol", model:"anthropic/claude-opus-4.8", model:"xai/grok-4.5", model:"nvidia/deepseek-v4-flash" (free).

Run blockrun_models to see all available models with pricing.

List available AI models with pricing. Use to discover models and compare costs.

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-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

Edit (img2img) models: openai/gpt-image-2 (default), openai/gpt-image-1, google/nano-banana, 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.

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; payment settles only when a finished track is returned — if it fails or times out, you are not charged.

Models: minimax/music-2.5+ ($0.1575), minimax/music-2.5 ($0.1575)

Returns a permanent BlockRun-hosted URL.

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 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)

Voice aliases: 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.

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 upstream returns a finished video — if the job fails or we give up, you are not charged.

Models (Seedance defaults bumped to 720p + synced audio on the gateway):

• azure/sora-2 ($0.10/sec, 720p + synced audio, text-to-video) — OpenAI Sora 2 via Azure AI Foundry. duration_seconds must be 4, 8, or 12 (4s default -> ~$0.40/clip). No image_url / RealFace.

• xai/grok-imagine-video ($0.05/sec, 8s default -> $0.40/clip) — stylized, fast

• bytedance/seedance-1.5-pro (~$0.092/sec, 720p + audio t2v, 5s default up to 10s) — cheapest Seedance, token-priced upstream

• bytedance/seedance-2.0-fast (~$0.238/sec text · ~$0.140/sec image-to-video, 720p + audio, ~60-80s gen) — sweet-spot price/quality; supports BytePlus RealFace assets

• bytedance/seedance-2.0 (~$0.298/sec text · ~$0.183/sec image-to-video, 720p + audio Pro) — highest quality; supports BytePlus RealFace assets

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 a Seedance 2.0 model. Mutually exclusive with image_url.

Returns a permanent blockrun-hosted MP4 URL (the gateway mirrors the asset to GCS so URLs don't expire).

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 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 USDC, Base only). 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 USDC, Base only). 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. 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.

Grok Live Search — real-time web + X/Twitter + 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","x","news"], max_results: 10, from_date: "YYYY-MM-DD", to_date: "YYYY-MM-DD" }

sources accepts any subset of ["web","x","news"] (defaults to all three). For tweet-only searches, use ["x"]. 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).

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.012/call charged)

• answer — body: { query } ($0.012/call charged)

• contents — body: { urls: [...] } ($0.002/URL + $0.002 fee, up to 100)

• find-similar — body: { url, numResults? } ($0.012/call charged)

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

Full request/response shapes + worked research workflows in the exa-research skill.

Prediction market + derivatives data via Predexon aggregator. Flat $0.0095/call (every endpoint) — $0.0075 base + $0.002 tx fee.

CANONICAL CROSS-VENUE (Tier 1) — Predexon v2 unified data layer:

• markets — list canonical market/question containers with cross-venue Predexon IDs

• markets/listings — venue-native executable listings flattened across canonical markets

• outcomes/:predexon_id — resolve a canonical outcome ID to its market context + venue listings Filter with ?venue=polymarket|kalshi|limitless|opinion|predictfun, ?status=, ?category=, ?league=, ?event_id=, ?pagination_key=

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 (use ?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, polymarket/wallets/filter — batch + 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 (Tier 1):

• sports/categories — list available sports categories

• sports/markets — list sports markets grouped by game (filter ?league=, ?sport_type=, ?status=, ?venue=)

• sports/markets/:game_id — single sports game with all venue outcomes

• sports/outcomes/:predexon_id — equivalent sports outcomes across venues for a Predexon ID

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

CROSS-PLATFORM:

• matching-markets, matching-markets/pairs — equivalent markets across Polymarket+Kalshi

• markets/search — search across all platforms in one call

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: 0|1|5|15|60|1440 (use "60", not "1h"); start_time/end_time are Unix seconds.

• polymarket/orderbooks requires token_id plus start_time/end_time in Unix milliseconds.

• Smart-money calls need at least one cohort filter (window, min_trades, min_volume, min_roi, min_*_pnl, min_win_rate, min_profit_factor); a good default is { window: "30d", min_trades: "100" }.

• Issue paid calls sequentially. The MCP also serializes them to protect one wallet from concurrent x402 payment races.

Pass query params via 'params' (GET). Use 'body' only for POST endpoints (e.g. polymarket/wallet/identities).

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)

Pricing:

• crypto / fx / commodity: FREE across price, history and list

• stocks / usstock: $0.001 per price or history call (list free)

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: "stocks", symbol: "AAPL", market: "us" }

• { action: "history", category: "crypto", symbol: "ETH-USD", resolution: "D", from: 1700000000, to: 1710000000 }

• { action: "list", category: "crypto", query: "sol" }

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

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.

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 +).

Voice call flow + voice preset details + full body shapes in the phone skill.

Unified crypto data via Surf (asksurf.ai) — 83 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, and unified search.

Pricing (settled in USDC to Surf's Base treasury):

• Flat $0.0095/call — every endpoint, including raw on-chain SQL. No tiers. ($0.0075 base + $0.002 tx fee.)

Common paths (full 83-endpoint catalog in the surf skill):

• market/price?symbol=BTC

• exchange/price?pair=BTC-USDT

• prediction-market/polymarket/ranking

• search/web?q=ethereum+pectra+upgrade

• wallet/detail?address=0x...

• social/mindshare?q=ethereum&interval=1d

• onchain/sql + body:{ sql: "SELECT ..." }

Method is auto-routed: pass 'body' for POST endpoints; otherwise GET with 'params'. Each Surf endpoint pre-validates required params before settling — you get a 400 (not a charge) if a required field is missing. Browse the full catalog: https://blockrun.ai/marketplace/surf

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.

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), blockrun_dex (free DEX data), or blockrun_surf (labeled/aggregated data) when they cover the question — this tool is for raw chain access.

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.007 charged) — all DeFi protocols ranked by TVL

• protocol/{slug} ($0.007 charged) — one protocol's TVL history + chain breakdown, e.g. protocol/aave-v3

• chains ($0.007 charged) — TVL by chain

• yields ($0.007 charged) — yield pools with APY + TVL (large; filter client-side)

• prices/{coins} ($0.003 charged) — 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, blockrun_surf for labeled on-chain data — this tool is for protocol/TVL/yield fundamentals.

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.

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.