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_image, blockrun_music, blockrun_speech, blockrun_video, paid blockrun_price, blockrun_chat routing:"smart", and native Anthropic (claude-*).

Actions:

• status (default): Both wallet addresses + USDC balances, active chain, session spending

• 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:"glm" → Zhipu GLM-5 / GLM-5-Turbo ($0.001/call, excellent for coding tasks, pays via USDC on BlockRun)

• mode:"coding" → GLM-5 first, then code-specialized models

• mode:"cheap" → GLM-5, NVIDIA free, DeepSeek

• mode:"reasoning" → o3, o1, DeepSeek-R1

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

• routing:"smart" → auto-select via ClawRouter

Pick directly: model:"zai/glm-5", model:"openai/o3", model:"nvidia/deepseek-v4-flash" (free).

Run blockrun_models to see all 41+ 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 — 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

Generate music tracks via BlockRun x402.

Generates a full-length ~3 minute MP3 track. Takes 1-3 minutes to complete.

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

Returns a time-limited CDN URL — download immediately if you need to keep the file.

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.42/clip). No image_url / RealFace.

• xai/grok-imagine-video ($0.05/sec, 8s default -> $0.42/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. $0.025 per returned source (max_results × $0.025; default max_results=10 → $0.25).

Common shape:

• body: { query: "...", sources: ["web","x","news"], max_results: 10, from_date: "YYYY-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.01/call)

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

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

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

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. Tier 1 = $0.001/call, Tier 2 = $0.005/call.

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

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

• markets/listings — 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 (Tier 1): kalshi/markets, kalshi/trades, kalshi/orderbooks LIMITLESS / OPINION / PREDICT.FUN (Tier 1): {platform}/markets, {platform}/orderbooks DFLOW: dflow/trades (T1), dflow/wallet/positions/:wallet (T2), dflow/wallet/pnl/:wallet (T2) BINANCE FUTURES (Tier 2): binance/candles/:symbol, binance/ticks/:symbol

CROSS-PLATFORM:

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

• markets/search — search across all platforms in one call (T2)

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/A100-80GB/H100), or a safer place for untrusted code. Prefer local tools for normal repo work.

Common paths (all POST):

• sandbox/create — body: { image?, timeout?, cpu?, memory?, gpu?, setup_commands? } ($0.01)

• sandbox/exec — body: { sandbox_id, command: ["python","-c","..."], timeout? } ($0.001)

• sandbox/status — body: { sandbox_id } ($0.001)

• sandbox/terminate — body: { sandbox_id } ($0.001)

Full action shapes + GPU type 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) — 84 endpoints, one API.

Coverage: CEX market data (16 exchanges), on-chain SQL across 13 chains, 100M+ labeled wallets, prediction markets (Polymarket + Kalshi), social mindshare / CT intelligence, news, unified search, and Surf-1.5 chat with citations.

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

• Tier 1 $0.001 — prices, rankings, lists, news, profiles, simple reads

• Tier 2 $0.005 — order books, candles, search, wallet detail, social aggregates

• Tier 3 $0.020 — raw on-chain SQL, structured queries, surf-1.5 chat

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

• market/price?symbol=BTC (T1)

• exchange/price?pair=BTC-USDT (T1)

• prediction-market/polymarket/ranking (T1)

• search/web?q=ethereum+pectra+upgrade (T2)

• wallet/detail?address=0x... (T2)

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

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

• chat/completions + body:{ model:"surf/surf-1.5", messages:[]} (T3, $0.02 flat)

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

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

• chains ($0.005) — TVL by chain

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

• prices/{coins} ($0.001) — 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.