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.
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.
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-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.
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.
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.
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).
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.
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`).
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.
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).
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" }
+7 more tools listed on main page