@blockrun/mcp

claude mcp add blockrun -s user -- npx -y @blockrun/mcp@latest

BlockRun MCP é um servidor de Model Context Protocol de código aberto que dá ao Claude — e a qualquer agente compatível com MCP — 19 ferramentas para dados em tempo real e ações reais: 79 LLMs, geração de imagens e vídeo, dados de mercados de previsão, busca ao vivo na web/X, consultas on-chain em 40 blockchains, e a capacidade de fazer apostas reais, liquidadas em USDC, na Polymarket.

Você paga por chamada e escolhe como. Modo carteira autentica com uma assinatura e liquida cada chamada em USDC via protocolo x402 — sem conta, sem cartão de crédito, sem assinatura, na Solana ou Base. Modo conta autentica com uma chave de API BlockRun (brk_live_…) de user.blockrun.ai, roteia chamadas de serviço através de api.blockrun.ai e consome crédito da conta financiado por cartão ou transferência no uso exato. As mesmas 19 ferramentas de qualquer forma. Licença MIT.

🏆 Primeiro do tipo — o loop sinal → negociação no Claude Code

Leia as probabilidades ao vivo da Polymarket e faça a aposta, a partir de uma única carteira de autocustódia, pagando por chamada. Ir para negociação na Polymarket →

Por que o BlockRun MCP existe

Toda outra integração de dados foi construída para desenvolvedores humanos — crie uma conta, copie uma chave de API em .env, adicione um cartão de crédito, repita para cada fornecedor.

BlockRun dá a você ambos os trilhos de pagamento sem reconstruir a integração. Use uma carteira quando o agente deve ter autocustódia dos fundos, ou use uma chave de conta quando uma equipe quer créditos financiados por cartão e um painel.

• Uma carteira, todas as fontes — 19 ferramentas atrás de uma única carteira de autocustódia. Sem cadastros por fornecedor.
• Uma chave de conta, todas as fontes — crie uma chave em user.blockrun.ai, recarregue por cartão ou transferência, e o MCP chama api.blockrun.ai com essa chave.
• Sem chave de API necessária no modo carteira — sua assinatura de carteira é a autenticação.
• Sem cartão de crédito necessário no modo carteira — pague por requisição em USDC via x402, frações de centavo cada.
• Começa grátis — o nível gratuito (blockrun_chat mode:"free", blockrun_dex, crypto blockrun_price, blockrun_models) custa $0.
• Lê e age — a maioria das ferramentas entrega dados; blockrun_polymarket faz negociações reais, com confirmação obrigatória.
• Pagamentos com humano no circuito — ative BLOCKRUN_CONFIRM_SPEND=on e o agente pausa antes de qualquer chamada paga acima do seu limite; nada é assinado até você aprovar. Detalhes ↓
• UI generativa — no Claude Desktop, claude.ai, VS Code e Cursor, a prévia da Polymarket é um cartão de ordem ao vivo com um botão de Colocar, e a carteira é um painel com saldos, QR e recarga por cartão. Apps MCP ↓
• Autocustódia — sua chave nunca sai da sua máquina (~/.blockrun/.session, 0600 — ou o chaveiro do sistema operacional quando você optar por BLOCKRUN_KEYCHAIN=strict). BlockRun não pode mover seus fundos.

Como se compara

✓ Uma carteira ou uma chave de conta · ✓ Pague por chamada · ✓ Lê e negocia · ✓ Multi-blockchain · ✓ Pronto para agentes · ✓ Código aberto

O que muda

Antes do BlockRun, Claude não consegue responder:

• "Qual é a probabilidade atual na Polymarket de o Bitcoin atingir $100k este ano?"
• "Encontre os 5 principais artigos sobre RAG publicados nos últimos 30 dias."
• "O que as pessoas estão dizendo sobre @sama no X agora?"
• "Qual é o volume de 24h no par PEPE/ETH na Uniswap?"
• "A Polymarket tem o Fed mantendo as taxas em 73% — coloque $2 nisso." ← e agora ele pode fazer a negociação, não apenas ler as probabilidades.

Depois do BlockRun, ele consegue. Cada consulta custa frações de centavo — cobradas de uma carteira USDC local, ou de crédito financiado por cartão em uma conta BlockRun através de api.blockrun.ai. Sem assinaturas, sem cadastros por fornecedor.

Início Rápido

0. Escolha como você paga

Ambos os modos alcançam as mesmas 19 ferramentas. O modo conta envia chamadas de serviço para https://api.blockrun.ai por padrão. Você pode alternar a qualquer momento; definir BLOCKRUN_API_KEY tem prioridade sobre uma carteira, e remover a definição devolve a carteira.

1. Instalação

Claude Code (recomendado)

claude mcp add blockrun -s user -- npx -y @blockrun/mcp@latest

-s user instala globalmente (disponível em todos os projetos). O separador -- garante que -y seja passado para npx, não interpretado por claude mcp add.

💡 Usuários de Homebrew / nvm: se o servidor não conectar, o Claude Code provavelmente não consegue encontrar node/npx no PATH do launcher. Passe o PATH do seu shell — funciona na CLI e no desktop:

claude mcp add blockrun -s user -e PATH="$PATH" -- npx -y @blockrun/mcp@latest

Veja Solução de problemas se persistir.

Todo cliente MCP — um comando ou um bloco JSON. Verificado = executamos o pacote publicado nesse cliente e vimos as ferramentas listadas (versão do cliente · data). Documentado = caminho de instalação da própria documentação do cliente; ainda não executado por nós — nos diga se funciona. A coluna Diálogo de gastos indica se o cliente renderiza o prompt de pagamento com humano no circuito; em clientes ❌, chamadas pagas prosseguem sem perguntar e BLOCKRUN_BUDGET_LIMIT é a proteção.

Qualquer outro cliente MCP que possa iniciar um servidor stdio funciona da mesma forma: command: npx, args: ["-y", "@blockrun/mcp@latest"]. Com Node via nvm/Homebrew em um cliente configurado por JSON, coloque o caminho absoluto de which npx em command. Fontes do diálogo de gastos e o que "prosseguir sem perguntar" significa: docs/spend-confirmation.md.

Grok — aumente o timeout de inicialização antes de instalar, ou a primeira execução parecerá quebrada. Grok espera startup_timeout_sec para um servidor MCP responder, e o padrão é 30 (documentação MCP da xAI). Uma primeira execução de npx -y precisa baixar este pacote e sua árvore de dependências antes que o servidor possa dizer qualquer coisa, e isso é uma corrida: medido a frio, com cache npm vazio, levou 17s em uma conexão rápida e 42-46s em uma máquina compartilhada mais lenta. Perdeu a corrida e grok mcp doctor blockrun diz server timed out (no response within 30s) e a UI mostra blockrun [unavailable] — uma instalação que está funcionando, expirando o tempo, e indistinguível de quebrada.

Dê espaço em ~/.grok/config.toml (ou .grok/config.toml para um projeto):

[mcp_servers.blockrun]
command = "npx"
args = ["-y", "@blockrun/mcp@latest"]
enabled = true
startup_timeout_sec = 120

Ou pule o download a frio completamente, o que é mais rápido em toda execução após a primeira:

npm install -g @blockrun/mcp@latest
grok mcp add blockrun -- blockrun-mcp

Somente a PRIMEIRA execução paga isso: o npx armazena em cache pela especificação exata, então a próxima inicialização é rápida (~9s aqui). A mesma armadilha existe em qualquer cliente com timeout de inicialização — se uma instalação nova aparecer como indisponível e npx -y @blockrun/mcp@latest funcionar normalmente em um terminal, aumente o timeout do cliente ou instale globalmente antes de procurar qualquer outra coisa. Agradecimentos a @0xCheetah1 pelo relato.

OpenClaw: o pacote npx publicado foi verificado de ponta a ponta em 2026.8.2: todas as 20 ferramentas foram projetadas (19 desde a remoção do Surf), chamadas gratuitas funcionaram e chamadas pagas x402 foram liquidadas. Adicione um limite rígido de sessão durante a instalação:

openclaw mcp set blockrun '{"command":"npx","args":["-y","@blockrun/mcp@latest"],"env":{"BLOCKRUN_BUDGET_LIMIT":"2"}}'
openclaw mcp doctor blockrun --probe

A confirmação de gasto depende do runtime do OpenClaw e da superfície de chat. Seu harness Codex suporta elicitação de formulário MCP, mas um prompt não mapeável é retornado como uma recusa explícita; na rota WebChat → Codex testada aqui, BLOCKRUN_CONFIRM_SPEND=on recusou chamadas pagas sem apresentar um diálogo acionável. Mantenha a confirmação desativada nessa rota e confie em BLOCKRUN_BUDGET_LIMIT além do próprio modo de aprovação de ferramentas do OpenClaw.

{
  "mcpServers": {
    "blockrun": { "command": "npx", "args": ["-y", "@blockrun/mcp@latest"] }
  }
}

2. Escolha um perfil de ferramentas (opcional)

Exponha um conjunto de ferramentas reduzido para que o cliente carregue menos esquemas no contexto. Passe --profile <name> (ou defina BLOCKRUN_MCP_PROFILE); omita para o conjunto completo.

blockrun_surf foi removido na versão 0.49.0: o gateway respondeu a todos os caminhos do Surf (asksurf.ai) com 410 desde 2026-09-06, então a ferramenta só poderia retornar um erro, e seu esquema custava contexto de agente em cada turno. Essas perguntas vão para blockrun_price, blockrun_defi, blockrun_markets e blockrun_dex; a habilidade surf mapeia cada endpoint antigo para seu substituto.

claude mcp add blockrun-trading -s user -- npx -y @blockrun/mcp@latest --profile trading

# Codex CLI
codex mcp add blockrun-trading -- npx -y @blockrun/mcp@latest --profile trading

Um nome de perfil desconhecido cai para full. modal e phone são exclusivos do perfil full.

O que cada perfil custa ao seu contexto

Instalar um servidor MCP gasta contexto em cada turno, quer você chame as ferramentas ou não — o cliente carrega o esquema de cada ferramenta no prompt do modelo e o reenvia durante toda a sessão. Gerenciadores de pacotes mostram o tamanho da instalação há décadas. Quase nenhum servidor MCP mostra isso. O nosso:

Executar --profile trading em vez do padrão custa 59% menos contexto para o mesmo fluxo de trabalho de trading. Se você só pergunta sobre mercados, essa é a mudança mais barata que você pode fazer.

Meça você mesmo — contra nós, ou contra qualquer outro servidor MCP stdio:

npm i gpt-tokenizer
node scripts/measure-tool-schema.mjs                     # this server, every profile
node scripts/measure-tool-schema.mjs -- npx -y @some/other-mcp-server

3. Adicione fundos

Opção A — chave de API + crédito na conta (sem carteira). Entre em user.blockrun.ai com o Google. Este é o painel para chaves, créditos e atividade; o MCP usa a chave para chamar api.blockrun.ai para os serviços reais.

1. Painel → Chaves — crie uma chave. Ela se parece com brk_live_… e é mostrada uma única vez.
2. Painel → Créditos — recarregue com cartão de crédito ou transferência bancária.
3. Aponte o servidor para ela. Por padrão, chamadas em modo de conta vão para https://api.blockrun.ai:

claude mcp add blockrun -s user -e BLOCKRUN_API_KEY=brk_live_… -- npx -y @blockrun/mcp@latest

Ou export BLOCKRUN_API_KEY=brk_live_… no ambiente a partir do qual o cliente é iniciado.

Se o seu cliente tornar variáveis de ambiente complicadas, escreva a chave em ~/.blockrun/.api-key (chmod 600) — o mesmo diretório de arquivos que a carteira usa. A variável de ambiente vence quando ambas estão presentes. 4. Painel → Atividade — cada chamada, precificada pelo uso exato.

Verifique com blockrun_wallet action:"status" — ele informa a conta, o saldo real e o que esta sessão gastou:

Paying with: BlockRun account API key (no wallet, no chain)

  Account:  acme (gated)
  Credit remaining: $12.5000 of $50.00 granted
  Top up:   https://user.blockrun.ai/dashboard/credits

Contas com faturamento mostram Spent to date: $4.5239 (invoiced account — no prepaid ceiling) em vez disso. Se a conta estiver bloqueada, o status diz isso e o motivo antes de você gastar uma chamada para descobrir.

Opção B — carteira (sem conta). Execute blockrun_wallet para ver seus endereços. Novas instalações usam Solana por padrão; envie USDC (SPL) na Solana pela Coinbase (escolha "Solana"), Phantom, Solflare ou Backpack. Para pagar na Base em vez disso: blockrun_wallet action:"chain" chain:"base", depois envie USDC na Base. Instruções completas: Financie sua carteira.

$5 cobre ~525 consultas de mercado · ~500 buscas Exa · ~250 gerações de imagem · ~14 clipes Seedance 1.5-pro.

4. Pergunte qualquer coisa ao Claude

"O que a Polymarket está dizendo sobre a próxima decisão do Fed? Se 'manter' estiver acima de 70%, coloque $2 nisso."

O Claude lê as probabilidades com blockrun_markets. No modo carteira, e somente após sua confirmação, ele também pode colocar a aposta com blockrun_polymarket. No modo chave de API, as chamadas de dados/mídia/pesquisa passam por api.blockrun.ai; trading na Polymarket ainda exige um par de chaves local para assinar.

5. Instale as habilidades do agente (opcional)

O pacote inclui 17 habilidades — qual ferramenta responde o quê, exemplos práticos e um trio de configuração / depuração / atualização para que o agente possa instalar, solucionar problemas e atualizar o servidor por conta própria.

/plugin marketplace add BlockRunAI/blockrun-mcp            # Claude Code
npx -y @blockrun/mcp@latest skills install                 # any project → ./.claude/skills
npx -y @blockrun/mcp@latest skills install --global        # ~/.claude/skills
npx -y @blockrun/mcp@latest skills install --to ~/.codex/skills

skills list mostra o que acompanha; --only a,b seleciona; --force atualiza as cópias após uma atualização.

Demonstração

Usuário: O que a Polymarket está dizendo sobre a decisão de taxa do Fed no próximo mês?

Claude: De acordo com a Polymarket, o mercado coloca uma probabilidade de 73% no Fed mantendo as taxas estáveis, 24% em um corte de 25 pontos-base, 3% em um aumento. Volume em 24h: $2,1M. O contrato "Hold" foi negociado pela última vez a $0,73.

(via blockrun_markets · custo: $0,0085 na Base — $0,0075 + a taxa de rede de $0,001)

Usuário: A Polymarket tem Hawley em ~13% para anunciar uma candidatura presidencial em 2026 — coloque $1 em Sim.

Claude: Feito — comprei 7,63 ações de Sim a $0,131 ($1,00, mercado FOK). Ordem real on-chain, liquidada em pUSD da sua carteira de depósito sem gás da Polymarket; estou acompanhando a posição agora.

(sinal via blockrun_markets, trade via blockrun_polymarket — uma carteira de autocustódia, sem gás · tx on-chain 0x7ca8…)

Ferramentas

Preços de dados fixos são a base. No modo carteira, o gateway adiciona sua taxa de rede fixa por cima — $0,001 por chamada na Base hoje, e o gateway Solana cotiza apenas a base; o trilho de conta não cobra taxa. O valor exato está no cabeçalho payment-required de qualquer solicitação não paga, que é grátis de pedir. O servidor reserva $0,002 para a taxa contra o limite de orçamento, então blockrun_wallet action:"report" e o diálogo de confirmação de gasto rodam $0,001 acima por chamada por design.

Casos de uso principais

1. Consenso de mercado de previsão → "Probabilidades da Polymarket para a próxima decisão do Fed?" — blockrun_markets
2. Sinal → trade (o loop completo, autocustódia) → "Se 'manter' estiver abaixo de 30%, coloque $2 em Sim." — blockrun_markets lê, blockrun_polymarket action:"buy" executa. Sem gas, com confirmação.
3. Análise forense de dinheiro inteligente → "Esta baleia da Polymarket — quem é, quais carteiras são dela, qual é o P&L?" — blockrun_markets polymarket/wallet/identity/:wallet + .../cluster
4. Pesquisa citada → "Os 5 artigos mais citados sobre decodificação especulativa, últimos 90 dias." — blockrun_exa
5. Geração de imagens com texto na imagem → "Pôster anunciando GPT-5.5, retrofuturista, manchete 'AGORA NO AR'." — blockrun_image
6. Dê voz ao seu agente → "Fale isto com a voz sarah." — blockrun_speech
7. Chamada de voz para telefone → "Ligue para +1-415-… e confirme sexta às 15h." — blockrun_phone
8. Pesquisa multiagente, com limite → "Gere 3 agentes sobre narrativas concorrentes de L1. Limite de $0,50 para cada." — blockrun_wallet delegate × 3
9. Leituras brutas de blockchain, 40 redes → "Último bloco da Base e o saldo de USDC deste contrato." — blockrun_rpc

📈 Negociação na Polymarket

blockrun_polymarket permite que um agente faça apostas reais na Polymarket (CLOB V2, Polygon). É não custodial: cada ordem e aprovação é assinada localmente via EIP-712 pela sua chave da carteira BlockRun — a mesma chave de autocustódia que paga taxas de API x402 na Base também autoriza apostas na Polygon. Nem a BlockRun nem o relayer da Polymarket podem mover fundos; eles apenas encaminham payloads que você assinou.

Arquitetura — o caminho oficial da "carteira de depósito" (tipo de assinatura POLY_1271): um vault de contrato inteligente na Polygon, derivado via CREATE2 da sua chave (somente sua chave pode autorizá-lo), mantém fundos de aposta em pUSD (wrapper de garantia 1:1 da Polymarket). Implantação, aprovações e resgates rodam todos sem gas pelo relayer da Polymarket — você nunca precisa de POL.

📖 Guia completo passo a passo: docs/polymarket-trading-setup.md

# 1. Provision your deposit wallet (idempotent, gasless)
blockrun_polymarket action:"setup"

# 2. Fund it from your Base USDC in one call (gasless; $0.01 fee, non-custodial)
blockrun_polymarket action:"fund" amount_usd:5 confirm:true

# 3. Sign the one-time gasless approval batch
blockrun_polymarket action:"setup" confirm:true

# 4. Find a market, preview safely, then place only after exact user approval
blockrun_polymarket_read action:"preview" side:"buy" token_id:"<id>" amount_usd:5 order_type:"FOK"
blockrun_polymarket action:"buy" token_id:"<id>" amount_usd:5 order_type:"FOK" confirm:true

# 5. Manage → positions · orders · cancel · sell · redeem · withdraw

Travas de segurança (no lado do servidor; um agente não pode contorná-las): confirm:true exigida para cada ordem/aprovação/resgate, POLYMARKET_MAX_BET_USD limite por ordem (padrão $25), POLYMARKET_MAX_SESSION_USD opcional limite por sessão, e apostas nunca usam o orçamento de API x402.

Regiões: a Polymarket bloqueia geograficamente a colocação de ordens por IP (EUA/Reino Unido + muitas regiões). Tratado por padrão — o MCP roteia o tráfego CLOB pelo egresso hospedado da BlockRun na Finlândia (uma região totalmente desbloqueada pela política da Polymarket), então a negociação funciona de imediato; setup informa seu status. Substitua POLYMARKET_CLOB_HOST para ir direto ou usar seu próprio egresso, opcionalmente alcançado via HTTPS_PROXY / POLYMARKET_CLOB_PROXY (um proxy sozinho não muda o egresso voltado à Polymarket). Cumprir os termos da Polymarket para sua jurisdição é sua responsabilidade.

⚠️ Faça backup da sua chave de assinatura (~/.blockrun/.session por padrão; uma variável de ambiente BLOCKRUN_WALLET_KEY ou um agente existente wallet.json tem precedência — setup imprime o endereço real do assinante). É a única chave tanto para a carteira de pagamento quanto para a carteira de depósito da Polymarket.

🛡️ Pagamentos com intervenção humana

Ative BLOCKRUN_CONFIRM_SPEND=on e toda ferramenta paga pausa antes de assinar. O servidor envia uma elicitação MCP; seu cliente a renderiza como um diálogo com a cobrança estimada:

💸 BlockRun charge — video · bytedance/seedance-2.5 · 10s
Estimated: $2.6500
Approve this spend? (USDC is debited per call.)
To stop the charge, choose Decline — Cancel/ESC lets it proceed.

[ ] Approve all BlockRun charges for the rest of this session (don't ask again)

                                          [ Decline ]  [ Approve ]

Recusar → nada é enviado, nada é cobrado, a ferramenta reporta "Cobrança recusada". Aprovar → a chamada prossegue. Marque a caixa e você não será perguntado novamente na sessão. Chamadas gratuitas nunca perguntam. Defina BLOCKRUN_CONFIRM_THRESHOLD=0.05 para só ser perguntado acima de $0,05.

claude mcp add blockrun -s user -e BLOCKRUN_CONFIRM_SPEND=on -e BLOCKRUN_CONFIRM_THRESHOLD=0.05 -- npx -y @blockrun/mcp@latest

Em um cliente que não pode perguntar, a trava falha aberta — a chamada prossegue e o rodapé de custo reporta a cobrança. A parada rígida em todo cliente é o orçamento: BLOCKRUN_BUDGET_LIMIT para o processo, blockrun_wallet action:"delegate" por subagente. blockrun_polymarket mantém seu próprio limite por ordem, mais forte, confirm:true.

📖 Quando usar, fontes da matriz, limitações: docs/spend-confirmation.md

🧩 MCP Apps — cartão de ordem e painel de carteira

Em hosts que suportam a extensão MCP Apps — Claude Desktop, claude.ai, VS Code, Cursor, ChatGPT — duas ferramentas renderizam como cartões interativos em vez de texto. Em qualquer outro lugar (Claude Code, Codex, terminais) nada muda.

• Cartão de ordem em blockrun_polymarket_read action:"preview" — pergunta, resultado, lado, melhor cotação, ações estimadas, nocional, medidor de limite, registro da sessão. Edite o valor → Re-cotar. Colocar ordem é armar-depois-confirmar e pede ao host para chamar blockrun_polymarket … confirm:true, então o prompt de consentimento do host e todos os limites do servidor (POLYMARKET_MAX_BET_USD, limite de sessão) ainda se aplicam.
• Painel de carteira em blockrun_wallet — saldos de ambas as redes, trocar de rede, copiar endereço, QR EIP-681 / Solana Pay, explorador, Comprar USDC com cartão.

📖 Hosts, caminho do dinheiro, teste local: docs/mcp-apps.md

Financie sua carteira

Pagando com chave de API? Não há carteira para financiar — adicione crédito por cartão ou transferência em user.blockrun.ai/dashboard/credits. O MCP usará essa chave contra api.blockrun.ai e pulará o trilho da carteira completamente.

O servidor mantém duas carteiras — uma na Solana, uma na Base — e paga de uma por vez. Execute blockrun_wallet para ver ambos os endereços, saldos e qual está ativa.

$5 cobre ~525 consultas de mercado, ~500 buscas Exa, ~250 gerações de imagem, ou ~14 clipes Seedance 1.5-pro (5s @ 720p+áudio, ~$0,35 cada).

Pagar na Solana (padrão para novas instalações)

blockrun_wallet action:"setup"    # shows the Solana address + funding QR

Envie USDC (SPL) na rede Solana — da Coinbase (escolha "Solana"), Phantom, Solflare ou Backpack.

Pagar na Base

Uma chamada de ferramenta — sem variáveis de ambiente, sem editar arquivos, sem reiniciar:

blockrun_wallet action:"chain" chain:"base"   # provisions + activates the Base wallet
blockrun_wallet action:"setup"                # shows the Base address + funding QR

Volte com blockrun_wallet action:"chain" chain:"solana". Trocar apenas muda qual carteira paga; ambas mantêm seus saldos.

Atualizando de uma versão antiga? Nada se move. O padrão Solana-primeiro se aplica apenas a instalações sem carteira e sem preferência de rede salva — se você já tem uma carteira Base, permanece na Base até trocar.

O que cada modo alcança

Quase tudo agora liquida em qualquer uma das redes. As exceções:

Uma capacidade bloqueada retorna uma mensagem nomeando a correção, não um erro bruto.

Quanto custa uma chamada e quão certos estamos

Qualquer coisa estimada é impressa com um ~ e diz isso. Estimativas ficam altas no trilho da conta — elas adicionam uma taxa de transação que não é cobrada — então um limite de orçamento dispara cedo em vez de tarde. A fonte da verdade é sempre Dashboard → Atividade.

Para agentes e LLMs

Se você é um LLM invocando ferramentas MCP da BlockRun, leia isto primeiro:

• CRÍTICO: Em qualquer erro de pagamento / saldo / 402, chame blockrun_wallet primeiro para verificar o status, depois action:"setup" para financiamento. Não tente novamente a ferramenta com falha às cegas — a carteira está vazia.
• CRÍTICO: blockrun_polymarket move fundos REAIS do usuário (pUSD na Polygon), separado do orçamento de API x402. Nunca buy/sell/redeem com confirm:true a menos que o usuário tenha aprovado explicitamente aquela negociação exata; sem confirm você obtém um dry-run seguro. Descubra mercados/IDs de token com blockrun_markets primeiro.
• CRÍTICO: blockrun_music e blockrun_video são assíncronos com pagamento na conclusão. Falhas / timeouts do cliente NÃO cobram. Não faça loop de tentativas — podem levar 60–180s.
• CRÍTICO: Antes de gerar agentes filhos, aloque orçamento por agente: blockrun_wallet action:"delegate" agent_id:"X" agent_limit:1.00, depois passe agent_id:"X" para toda chamada downstream. O filho é bloqueado automaticamente em zero.
• Camada gratuita primeiro para rascunhos: blockrun_chat mode:"free" (NVIDIA), blockrun_dex, blockrun_price (cripto/FX/commodity) e blockrun_models são $0.
• Uma confirmação de gasto recusada é a decisão do usuário. Reporte e pare — nunca re-emita a chamada com um modelo mais barato, parâmetros menores ou solicitações divididas para ficar abaixo do limite deles.

Vitrine

Pôsteres gerados via blockrun_image com openai/gpt-image-2 — cada um uma única chamada de API roteada pela BlockRun, paga com crédito da conta ou carteira USDC.

Conferência Blockchain Cornell 2026	Conferência Blockchain Cornell 2026	100 Trilhões de Tokens marco

Prompts e um exemplo trabalhado estão em skills/image-prompting/SKILL.md.

Por que não usar apenas as APIs diretamente?

Uma carteira, ou uma chave de API com dashboard. Todas as fontes.

Configuração

Solução de problemas

🤖 Entregue isto ao agente: a habilidade blockrun-debug carrega cada linha abaixo como sintoma → causa → correção, além dos diagnósticos que ela pode executar sozinha. blockrun-setup e blockrun-upgrade cobrem as outras duas metades. Instalação: npx -y @blockrun/mcp@latest skills install.

• Insufficient balance / HTTP 402 após nova tentativa → Execute blockrun_wallet action:"setup", envie USDC na Base (ou Solana).
• blockrun não conecta / "MCP server failed" / spawn npx ENOENT → Quase sempre um problema de PATH: o Claude Code não consegue encontrar node/npx no PATH do seu lançador (comum com Homebrew / nvm, na CLI e no desktop). Corrija passando o PATH do seu shell na instalação:

  claude mcp remove blockrun -s user
  claude mcp add blockrun -s user -e PATH="$PATH" -- npx -y @blockrun/mcp@latest
  

  Em seguida, reinicie o Claude Code. Ou fixe caminhos absolutos (which npx).
• claude mcp list não mostra blockrun → Verifique node -v (≥20.19). Limpe o cache do npx: rm -rf ~/.npm/_npx. Execute novamente a instalação.
• fetch failed / timeout na verificação de saldo → Interrupção transitória do RPC da Base. A ferramenta tenta 3 RPCs públicos; tente novamente após 30s. Persistente = proxy local / firewall bloqueando RPC de saída.
• Video/Music generation timed out → Congestionamento da fila upstream. Se custou algo depende do trilho, e o erro diz qual: na carteira Base o pagamento é liquidado na conclusão, então não é cobrado e uma nova tentativa é segura; na música Solana e em todo trabalho de mídia no trilho de conta o gateway cobra no envio, então o trabalho é cobrado, o erro o nomeia, e executar novamente cobra um segundo — verifique blockrun_wallet action:"report" em vez disso.
• blockrun_price diz Equity quotes are not served (gateway 501 …) → Preços/histórico de ações foram retirados em 2026-09-05; não é uma interrupção, e nada foi cobrado (a carteira nunca é solicitada a assinar). O catálogo de tickers (action:"list" category:"stocks") ainda é gratuito. Cobertura de ações: hello@blockrun.ai.
• blockrun_markets em sports/* falha — antes de 0.49.0 como API error after payment: 502 sem mudança de saldo → As rotas sports/* da Predexon estão fora do ar upstream desde 2026-08-04; o gateway libera o pagamento nesse 500 upstream, então a chamada não é cobrada (o erro diz isso quando a confirmação "payment NOT charged" do gateway está na resposta; caso contrário, ele diz para você verificar blockrun_wallet action:"report"). Para odds esportivas use path:"markets/search" com params:{ q: "NBA" }, ou polymarket/events com params:{ search: "NBA" } — a rota markets simples e seu filtro league foram removidos upstream em 2026-08-04 e retornam 404 antes do pagamento. Atualize para ≥ 0.49.0 para que o erro diga tudo isso por si só.
• Nenhum diálogo de confirmação de gasto embora BLOCKRUN_CONFIRM_SPEND=on → Seu cliente não suporta elicitação MCP (Windsurf, Codex, Gemini CLI); o servidor prossegue sem perguntar por design. Use BLOCKRUN_BUDGET_LIMIT como proteção, ou um cliente da tabela de suporte.
• Polymarket: compra em mercado de risco negativo ("winner") falha, ou redeem reverte, embora a configuração mostre pronta → Execute action:"setup" confirm:true novamente uma vez (concede as aprovações on-chain que uma carteira de depósito pré-upgrade pode não ter — incluindo as aprovações do adaptador de colateral que redeem precisa). Veja o guia de configuração.

FAQ

O que é o BlockRun MCP? Um servidor MCP de código aberto que dá ao Claude e outros agentes 19 ferramentas para dados em tempo real e ações reais (trading, mídia, on-chain), pagas por chamada — de uma carteira de autocustódia ou uma chave de conta BlockRun.

Preciso de uma chave de API ou uma conta? Não. Uma carteira é criada automaticamente localmente na primeira execução; você a financia com USDC e não há cadastros, dashboards ou chaves para rotacionar.

Mas você pode ter uma. Se sua equipe não pode entregar uma carteira a um agente, entre em user.blockrun.ai, crie uma chave em Dashboard → Keys, adicione crédito à conta por cartão ou transferência em Dashboard → Credits, e defina BLOCKRUN_API_KEY. O MCP então envia chamadas de serviço pagas para api.blockrun.ai e cobra o uso exato contra esse crédito da conta — sem taxa de rede de $0.001 por chamada, sem mínimo por chamada — com um livro-razão em Dashboard → Activity. Tudo funciona exceto as partes que realmente precisam de um par de chaves: trading na Polymarket, saldos/recargas de carteira, e o blockrun_realface action:"list" indexado por carteira.

Qual é mais barato? Cobrança de conta, ligeiramente — ela cobra uso medido exato sem mínimo por chamada e sem taxa de transação de $0.001. O modo de carteira compra autocustódia e trading na Polymarket em vez disso.

Quanto custa? Pague por chamada — frações de centavo a alguns centavos. O nível gratuito (blockrun_chat mode:"free", blockrun_dex, cripto blockrun_price, blockrun_models) é $0. $5 de USDC ou crédito de conta cobre milhares de consultas.

É seguro / não custodial? Sim. Sua chave privada nunca sai da sua máquina (~/.blockrun/.session por padrão, 0600). Pagamentos x402 e pedidos da Polymarket são assinados localmente — a BlockRun encaminha payloads assinados e não pode mover seus fundos.

Quais clientes funcionam? Qualquer cliente MCP que possa iniciar um servidor stdio. Verificado no Claude Code e Codex CLI, em uso diário no OpenClaw; caminhos de instalação documentados para Claude Desktop, Cursor, VS Code, Gemini CLI e Windsurf — veja a tabela de clientes. O diálogo de confirmação de gasto adicionalmente precisa de elicitação MCP (Claude Code, Cursor, VS Code).

Tem uma interface? Em hosts MCP-Apps (Claude Desktop, claude.ai, VS Code, Cursor) a prévia da Polymarket é um cartão de pedido ao vivo e a carteira é um painel — veja MCP Apps ↑. Clientes de terminal recebem as mesmas informações como texto.

Posso fazer o agente perguntar antes de gastar? Sim — BLOCKRUN_CONFIRM_SPEND=on. Cada ferramenta paga pausa com a cobrança estimada e nada é assinado até você aprovar. Pagamentos com humano no loop ↑

Ele realmente pode fazer apostas reais? Sim. blockrun_polymarket coloca pedidos reais, liquidados em USDC, no CLOB da Polymarket — com confirmação e limite. Leia as odds com blockrun_markets, coloque com blockrun_polymarket.

Base ou Solana? Ambas. Alterne instantaneamente com blockrun_wallet action:"chain". Três coisas são exclusivas da Base, e cada uma diz isso quando você as chama na Solana: blockrun_defi (DefiLlama) e blockrun_modal, que o gateway Solana não serve, e chat claude-* com thinking (o caminho nativo /v1/messages paga na Base; uma chamada claude-* simples usa o caminho de compatibilidade na Solana). Geração de mídia, mercados, busca e Polymarket liquidam em qualquer uma das chains.

Do ecossistema BlockRun

A BlockRun é infraestrutura de IA nativa para agentes — uma carteira com micropagamentos x402 em USDC, ou uma chave de API de conta com crédito financiado por cartão, em todas as superfícies:

• ⚡ ClawRouter — o roteador de LLM nativo para agentes do OpenClaw. 79 modelos, roteamento local <1ms, USDC na Base & Solana.
• 🤖 BRCC — BlockRun para Claude Code: roteamento inteligente + pagamentos x402, feito sob medida para Claude Code.
• 🐍 ClawRouter-Hermes — plugin Python conectando NousResearch Hermes ao proxy ClawRouter.
• 📚 Docs · Modelos & preços — SDKs completos, APIs e o catálogo de modelos.

Suporte & comunidade

Contribuindo

PRs são bem-vindos. Veja CONTRIBUTING.md para configuração, a regra de design ferramenta-vs-habilidade e como adicionar uma nova API parceira.