blockrunai/blockrun-mcp/blockrun

BlockRun

One wallet, pay-per-call, no API keys. Every paid tool below settles in USDC over x402 at the moment of the call.

Never quote a price from memory

There is no price table in this skill, and that is deliberate. Every flat per-call price published in this repo drifted by exactly the per-transaction fee the last time that fee changed, because each one was a typed copy. Read prices from a live source instead:

The tool descriptions in the MCP server carry the published base prices too; they are typed by hand and verified against live 402 quotes by npm run verify:prices, and the 402 header is what actually gets charged.

The two chains are not the same gateway

blockrun.ai and sol.blockrun.ai are separate deployments, and blockrun_wallet action: "chain" switches between them mid-session. Two consequences, both easy to miss because nothing announces the switch:

Prices differ, on purpose. Every figure in these skills is the Base price. Base adds a flat per-transaction fee; Solana deliberately adds none — the ~$0.001-per-call gap is pricing policy (an incentive to settle on Solana), not drift, so do not expect it to be "fixed". Each gateway's own llms.txt quotes its own convention — read the one for the chain you are on, or just read the 402.

Some tools do not exist on Solana at all. Verified against both gateways 2026-08-07:

Both tools now refuse before the round trip and tell you to switch, so you should never see the raw 404/503 through the MCP. If you are calling the HTTP API directly you will, and neither status says "wrong chain" — check the chain first.

The same applies to counts. Where a number has a canonical source it is wrapped in a br: HTML-comment marker in this file, regenerated from brand-numbers.json by scripts/sync-brand-numbers.mjs and enforced in CI by --check. Add the marker rather than the digits — an unmarked number is invisible to that check, which is exactly how the prices drifted.

Getting a first call working

Free, no wallet, no key. <!-- br:models.free -->7<!-- /br:models.free --> open-weight chat models cost nothing. Use blockrun_chat with mode: "free" — the parameter is mode, not routing, and an unrecognised key is silently dropped, which lands you on the paid balanced tier instead. Calling the HTTP API directly, a free model needs no wallet and no X-PAYMENT header at all; it returns 200 on the first request rather than a 402.

Do this first whenever a language model is all the task needs — it is the shortest path to something working, and it costs nothing if it turns out to be the wrong approach.

When you need the paid catalog, check the balance with blockrun_wallet (action: "status"). If it is zero:

1. blockrun_wallet action: "setup" prints the address and a funding QR.
2. To fund with a card, blockrun_wallet action: "deposit" mints a one-time Coinbase Onramp

link and opens it. The call itself is free. Base only — on Solana it returns address and QR guidance instead, so fund Solana by transfer.

1. Or send USDC to the address on Base or Solana.

Do not fund a wallet inside an ephemeral sandbox (Claude Cowork / Desktop / Web). The key lives in ~/.blockrun/ on whatever filesystem you are on, and if that is a throwaway VM the USDC goes with it. In a sandbox, use the free models or hand the user the command to run locally.

Deeper wallet, budget and x402 mechanics — including calling the HTTP API directly — are in rules/wallet-and-payment.md.

Which tool

The crypto tools overlap heavily. Prefer the free ones (blockrun_price, blockrun_dex) when they already answer the question, and reach for blockrun_defi or blockrun_markets only when they do not. On-chain SQL, wallet labels and social mindshare came from blockrun_surf, which was removed in 0.49.0 — the gateway retired Surf on 2026-09-06 and there is no replacement yet.

Picking a chat model

blockrun_chat takes a mode instead of a model id. Default to `balanced` — it is what an omitted mode resolves to anyway, and it is the right answer for most requests.

Two things to know about free: it routes to the open-weight tier only, and that path caps very long inputs. Through the MCP the truncation is reported — the response carries a note saying roughly what fraction of the prompt never reached the model — but a direct HTTP call gets no such warning, so do not send a large document over the free tier and assume the answer covered all of it. mode is ignored entirely when you pass an explicit model.

Name a specific model only when the user names one, or when a task genuinely needs that model's quirk. Otherwise a mode is both cheaper and more robust to the catalog moving.

For media, the picking advice lives with the generation tools, and `blockrun_models` is authoritative — this list would go stale within a release.

Cost discipline

• Failed requests are not charged. Settlement happens on success only, so a non-2xx costs

nothing and retrying after an upstream error is free. Do not let a failure stop you retrying.

• Check the balance before an expensive call. Video generation is the priciest category by

a wide margin — a single call can cost more than a thousand chat calls.

• Free before paid. blockrun_price (crypto/FX/commodities), blockrun_dex, and the free

chat tier cost nothing. Reach for them before their paid equivalents.

• Set a cap for unattended work. blockrun_wallet action: "budget" sets a session spend

ceiling; action: "delegate" gives a sub-agent its own allowance.

Troubleshooting

Related skills

Install from the same marketplace for depth on one area: search, exa-research, crypto-data, surf, rpc, prediction-markets, polymarket-trading, image-prompting, phone, modal, decide.

/plugin marketplace add BlockRunAI/blockrun-mcp