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 -->8<!-- /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.
3. Or send USDC to the address on Base, Solana or Arc (Arc uses the Base address).

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